RFC 7390
Group Communication for the Constrained Application Protocol (CoAP)
Pages: 46
Experimental
Experimental
Part 1 of 3 – Pages 1 to 17
Internet Engineering Task Force (IETF) A. Rahman, Ed. Request for Comments: 7390 InterDigital Communications, LLC Category: Experimental E. Dijk, Ed. ISSN: 2070-1721 Philips Research October 2014 Group Communication for the Constrained Application Protocol (CoAP)Abstract
The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for constrained devices and constrained networks. It is anticipated that constrained devices will often naturally operate in groups (e.g., in a building automation scenario, all lights in a given room may need to be switched on/off as a group). This specification defines how CoAP should be used in a group communication context. An approach for using CoAP on top of IP multicast is detailed based on existing CoAP functionality as well as new features introduced in this specification. Also, various use cases and corresponding protocol flows are provided to illustrate important concepts. Finally, guidance is provided for deployment in various network topologies. Status of This Memo This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation. This document defines an Experimental Protocol for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7390.
Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Conventions and Terminology . . . . . . . . . . . . . . . 4 2. Protocol Considerations . . . . . . . . . . . . . . . . . . . 5 2.1. IP Multicast Background . . . . . . . . . . . . . . . . . 5 2.2. Group Definition and Naming . . . . . . . . . . . . . . . 6 2.3. Port and URI Configuration . . . . . . . . . . . . . . . 7 2.4. RESTful Methods . . . . . . . . . . . . . . . . . . . . . 9 2.5. Request and Response Model . . . . . . . . . . . . . . . 9 2.6. Membership Configuration . . . . . . . . . . . . . . . . 10 2.6.1. Background . . . . . . . . . . . . . . . . . . . . . 10 2.6.2. Membership Configuration RESTful Interface . . . . . 11 2.7. Request Acceptance and Response Suppression Rules . . . . 17 2.8. Congestion Control . . . . . . . . . . . . . . . . . . . 19 2.9. Proxy Operation . . . . . . . . . . . . . . . . . . . . . 20 2.10. Exceptions . . . . . . . . . . . . . . . . . . . . . . . 21 3. Use Cases and Corresponding Protocol Flows . . . . . . . . . 22 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 22 3.2. Network Configuration . . . . . . . . . . . . . . . . . . 22 3.3. Discovery of Resource Directory . . . . . . . . . . . . . 25 3.4. Lighting Control . . . . . . . . . . . . . . . . . . . . 26 3.5. Lighting Control in MLD-Enabled Network . . . . . . . . . 30 3.6. Commissioning the Network Based on Resource Directory . . 31 4. Deployment Guidelines . . . . . . . . . . . . . . . . . . . . 32 4.1. Target Network Topologies . . . . . . . . . . . . . . . . 32 4.2. Networks Using the MLD Protocol . . . . . . . . . . . . . 33 4.3. Networks Using RPL Multicast without MLD . . . . . . . . 33 4.4. Networks Using MPL Forwarding without MLD . . . . . . . . 34 4.5. 6LoWPAN Specific Guidelines for the 6LBR . . . . . . . . 35 5. Security Considerations . . . . . . . . . . . . . . . . . . . 35 5.1. Security Configuration . . . . . . . . . . . . . . . . . 35 5.2. Threats . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 36
5.3.1. WiFi Scenario . . . . . . . . . . . . . . . . . . . . 37
5.3.2. 6LoWPAN Scenario . . . . . . . . . . . . . . . . . . 37
5.3.3. Future Evolution . . . . . . . . . . . . . . . . . . 37
5.4. Monitoring Considerations . . . . . . . . . . . . . . . . 38
5.4.1. General Monitoring . . . . . . . . . . . . . . . . . 38
5.4.2. Pervasive Monitoring . . . . . . . . . . . . . . . . 38
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39
6.1. New 'core.gp' Resource Type . . . . . . . . . . . . . . . 39
6.2. New 'coap-group+json' Internet Media Type . . . . . . . . 39
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1. Normative References . . . . . . . . . . . . . . . . . . 41
7.2. Informative References . . . . . . . . . . . . . . . . . 43
Appendix A. Multicast Listener Discovery (MLD) . . . . . . . . . 45
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 45
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46
1. Introduction
1.1. Background
CoAP is a web transfer protocol based on Representational State
Transfer (REST) for resource constrained devices operating in an IP
network [RFC7252]. CoAP has many similarities to HTTP [RFC7230] but
also some key differences. Constrained devices can be large in
numbers but are often related to each other in function or by
location. For example, all the light switches in a building may
belong to one group, and all the thermostats may belong to another
group. Groups may be preconfigured before deployment or dynamically
formed during operation. If information needs to be sent to or
received from a group of devices, group communication mechanisms can
improve efficiency and latency of communication and reduce bandwidth
requirements for a given application. HTTP does not support any
equivalent functionality to CoAP group communication.
1.2. Scope
Group communication involves a one-to-many relationship between CoAP
endpoints. Specifically, a single CoAP client can simultaneously get
(or set) resources from multiple CoAP servers using CoAP over IP
multicast. An example would be a CoAP light switch turning on/off
multiple lights in a room with a single CoAP group communication PUT
request and handling the potential multitude of (unicast) responses.
The base protocol aspects of sending CoAP requests on top of IP
multicast and processing the (unicast IP) responses are given in
Section 8 of [RFC7252]. To provide a more complete CoAP group
communication functionality, this specification introduces new CoAP
processing functionality (e.g., new rules for reuse of Token values, request suppression, and proxy operation) and a new management interface for RESTful group membership configuration. CoAP group communication will run in the Any Source Multicast (ASM) mode [RFC5110] of IP multicast operation. This means that there is no restriction on the source node that sends (originates) the CoAP messages to the IP multicast group. For example, the source node may or may not be part of the IP multicast group. Also, there is no restriction on the number of source nodes. While Section 9.1 of [RFC7252] supports various modes of security based on Datagram Transport Layer Security (DTLS) for CoAP over unicast IP, it does not specify any security modes for CoAP over IP multicast. That is, it is assumed per [RFC7252] that CoAP over IP multicast is not encrypted, nor authenticated, nor access controlled. This document assumes the same security model (see Section 5.1). However, there are several promising security approaches being developed that should be considered in the future for protecting CoAP group communications (see Section 5.3.3).1.3. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] when they appear in ALL CAPS. When these words are not in ALL CAPS (such as "should" or "Should"), they have their usual English meanings and are not to be interpreted as [RFC2119] key words. Note that this document refers back to other RFCs, and especially [RFC7252], to help explain overall CoAP group communication features. However, use of [RFC2119] key words is reserved for new CoAP functionality introduced by this specification. This document assumes readers are familiar with the terms and concepts that are used in [RFC7252]. In addition, this document defines the following terminology: Group Communication: A source node sends a single application-layer (e.g., CoAP) message that is delivered to multiple destination nodes, where all destinations are identified to belong to a specific group. The source node itself may be part of the group. The underlying mechanisms for CoAP group communication are UDP/IP multicast for
the requests and unicast UDP/IP for the responses. The network
involved may be a constrained network such as a low-power, lossy
network.
Reliable Group Communication:
A special case of group communication where for each destination
node, it is guaranteed that the node either 1) eventually receives
the message sent by the source node or 2) does not receive the
message and the source node is notified of the non-reception
event. An example of a reliable group communication protocol is
[RFC5740].
Multicast:
Sending a message to multiple destination nodes with one network
invocation. There are various options to implement multicast,
including layer 2 (Media Access Control) and layer 3 (IP)
mechanisms.
IP Multicast:
A specific multicast approach based on the use of IP multicast
addresses as defined in "IANA Guidelines for IPv4 Multicast
Address Assignments" [RFC5771] and "IP Version 6 Addressing
Architecture" [RFC4291]. A complete IP multicast solution may
include support for managing group memberships and IP multicast
routing/forwarding (see Section 2.1).
Low-Power and Lossy Network (LLN):
A type of constrained IP network where devices are interconnected
by low-power and lossy links. The links may be composed of one or
more technologies such as IEEE 802.15.4, Bluetooth Low Energy
(BLE), Digital Enhanced Cordless Telecommunication (DECT), and
IEEE P1901.2 power-line communication.
2. Protocol Considerations
2.1. IP Multicast Background
IP multicast protocols have been evolving for decades, resulting in
standards such as Protocol Independent Multicast - Sparse Mode (PIM-
SM) [RFC4601]. IP multicast is very popular in specific deployments
such as in enterprise networks (e.g., for video conferencing), smart
home networks (e.g., Universal Plug and Play (UPnP)), and carrier
IPTV deployments. The packet economy and minimal host complexity of
IP multicast make it attractive for group communication in
constrained environments.
To achieve IP multicast beyond link-local (LL) scope, an IP multicast routing or forwarding protocol needs to be active on IP routers. An example of a routing protocol specifically for LLNs is the IPv6 Routing Protocol for Low-Power and Lossy Networks (RPL) (Section 12 of [RFC6550]), and an example of a forwarding protocol for LLNs is the Multicast Protocol for Low-Power and Lossy Networks (MPL) [MCAST-MPL]. RPL and MPL do not depend on each other; each can be used in isolation, and both can be used in combination in a network. Finally, PIM-SM [RFC4601] is often used for multicast routing in traditional IP networks (i.e., networks that are not constrained). IP multicast can also be run in an LL scope. This means that there is no routing involved, and an IP multicast message is only received over the link on which it was sent. For a complete IP multicast solution, in addition to a routing/ forwarding protocol, a "listener" protocol may be needed for the devices to subscribe to groups (see Section 4.2). Also, a multicast forwarding proxy node [RFC4605] may be required. IP multicast is generally classified as an unreliable service in that packets are not guaranteed to be delivered to each and every member of the group. In other words, it cannot be directly used as a basis for "reliable group communication" as defined in Section 1.3. However, the level of reliability can be increased by employing a multicast protocol that performs periodic retransmissions as is done, for example, in MPL.2.2. Group Definition and Naming
A CoAP group is defined as a set of CoAP endpoints, where each endpoint is configured to receive CoAP group communication requests that are sent to the group's associated IP multicast address. The individual response by each endpoint receiver to a CoAP group communication request is always sent back as unicast. An endpoint may be a member of multiple groups. Group membership of an endpoint may dynamically change over time. All CoAP server nodes SHOULD join the "All CoAP Nodes" multicast group (Section 12.8 of [RFC7252]) by default to enable CoAP discovery. For IPv4, the address is 224.0.1.187, and for IPv6, a server node joins at least both the link-local scoped address ff02::fd and the site-local scoped address ff05::fd. IPv6 addresses of other scopes MAY be enabled. A CoAP group URI has the scheme 'coap' and includes in the authority part either a group IP multicast address or a hostname (e.g., Group Fully Qualified Domain Name (FQDN)) that can be resolved to the group
IP multicast address. A group URI also contains an optional CoAP port number in the authority part. Group URIs follow the regular CoAP URI syntax (Section 6 of [RFC7252]). Note: A group URI is needed to initiate CoAP group communications. For CoAP client implementations, it is recommended to use the URI decomposition method of Section 6.4 of [RFC7252] in such a way that, from a group URI, a CoAP group communication request is generated. For sending nodes, it is recommended to use the IP multicast address literal in a group URI. (This is because DNS infrastructure may not be deployed in many constrained network deployments.) However, in case a group hostname is used, it can be uniquely mapped to an IP multicast address via DNS resolution (if supported). Some examples of hierarchical group FQDN naming (and scoping) for a building control application are shown below: URI authority Targeted group of nodes --------------------------------------- -------------------------- all.bldg6.example.com "all nodes in building 6" all.west.bldg6.example.com "all nodes in west wing, building 6" all.floor1.west.bldg6.example.com "all nodes in floor 1, west wing, building 6" all.bu036.floor1.west.bldg6.example.com "all nodes in office bu036, floor 1, west wing, building 6" Similarly, if supported, reverse mapping (from IP multicast address to Group FQDN) is possible using the reverse DNS resolution technique ([RFC1033]). Reverse mapping is important, for example, in troubleshooting to translate IP multicast addresses back to human- readable hostnames to show in a diagnostics user interface.2.3. Port and URI Configuration
A CoAP server that is a member of a group listens for CoAP messages on the group's IP multicast address, usually on the CoAP default UDP port, 5683. If the group uses a specified non-default UDP port, be careful to ensure that all group members are configured to use that same port. Different ports for the same IP multicast address are preferably not used to specify different CoAP groups. If disjoint groups share the same IP multicast address, then all the devices interested in one group will accept IP traffic also for the other disjoint groups, only to ultimately discard the traffic higher in their IP stack (based on UDP port discrimination).
CoAP group communication will not work if there is diversity in the
authority port (e.g., different dynamic port addresses across the
group) or if other parts of the group URI such as the path, or the
query, differ on different endpoints. Therefore, some measures must
be present to ensure uniformity in port number and resource names/
locations within a group. All CoAP group communication requests MUST
be sent using a port number according to one of the below options:
1. A preconfigured port number.
2. If the client is configured to use service discovery including
URI and port discovery, it uses the port number obtained via a
service discovery lookup operation for the targeted CoAP group.
3. Use the default CoAP UDP port (5683).
For a CoAP server node that supports resource discovery, the default
port 5683 must be supported (Section 7.1 of [RFC7252]) for the "All
CoAP Nodes" group. Regardless of the method of selecting the port
number, the same port MUST be used across all CoAP servers in a group
and across all CoAP clients performing the group requests.
All CoAP group communication requests SHOULD operate on group URI
paths in one of the following ways:
1. Preconfigured group URI paths, if available. Implementers are
free to define the paths as they see fit. However, note that
[RFC7320] prescribes that a specification must not constrain or
define the structure or semantics for any path component. So for
this reason, a predefined URI path is not specified in this
document and also must not be provided in other specifications.
2. If the client is configured to use default Constrained RESTful
Environments (CoRE) resource discovery, it uses URI paths
retrieved from a "/.well-known/core" lookup on a group member.
The URI paths the client will use MUST be known to be available
also in all other endpoints in the group. The URI path
configuration mechanism on servers MUST ensure that these URIs
(identified as being supported by the group) are configured on
all group endpoints.
3. If the client is configured to use another form of service
discovery, it uses group URI paths from an equivalent service
discovery lookup that returns the resources supported by all
group members.
4. If the client has received a group URI through a previous RESTful
interaction with a trusted server, it can use this URI in a CoAP
group communication request. For example, a commissioning tool
may instruct a sensor device in this way to which target group
(group URI) it should report sensor events.
However, when the URI path is selected, the same path MUST be used
across all CoAP servers in a group and all CoAP clients performing
the group requests.
2.4. RESTful Methods
Group communication most often uses the idempotent CoAP methods GET
and PUT. The idempotent method DELETE can also be used. The non-
idempotent CoAP method POST may only be used for group communication
if the resource being POSTed to has been designed to cope with the
unreliable and lossy nature of IP multicast. For example, a client
may resend a multicast POST request for additional reliability. Some
servers will receive the request two times while others may receive
it only once. For idempotent methods, all these servers will be in
the same state while for POST, this is not guaranteed; so, the
resource POST operation must be specifically designed to take message
loss into account.
2.5. Request and Response Model
All CoAP requests that are sent via IP multicast must be Non-
confirmable (Section 8.1 of [RFC7252]). The Message ID in an IP
multicast CoAP message is used for optional message deduplication as
detailed in Section 4.5 of [RFC7252].
A server optionally sends back a unicast response to the CoAP group
communication request (e.g., response "2.05 Content" to a group GET
request). The unicast responses received by the CoAP client may be a
mixture of success (e.g., 2.05 Content) and failure (e.g., 4.04 Not
Found) codes depending on the individual server processing results.
Detailed processing rules for IP multicast request acceptance and
unicast response suppression are given in Section 2.7.
A CoAP request sent over IP multicast and any unicast response it
causes must take into account the congestion control rules defined in
Section 2.8.
The CoAP client can distinguish the origin of multiple server
responses by the source IP address of the UDP message containing the
CoAP response or any other available unique identifier (e.g.,
contained in the CoAP payload). In case a CoAP client sent multiple group requests, the responses are as usual matched to a request using the CoAP Token. For multicast CoAP requests, there are additional constraints on the reuse of Token values, compared to the unicast case. In the unicast case, receiving a response effectively frees up its Token value for reuse since no more responses will follow. However, for multicast CoAP, the number of responses is not bounded a priori. Therefore, the reception of a response cannot be used as a trigger to "free up" a Token value for reuse. Reusing a Token value too early could lead to incorrect response/request matching in the client and would be a protocol error. Therefore, the time between reuse of Token values used in multicast requests MUST be greater than: NON_LIFETIME + MAX_LATENCY + MAX_SERVER_RESPONSE_DELAY where NON_LIFETIME and MAX_LATENCY are defined in Section 4.8 of [RFC7252]. MAX_SERVER_RESPONSE_DELAY is defined here as the expected maximum response delay over all servers that the client can send a multicast request to. This delay includes the maximum Leisure time period as defined in Section 8.2 of [RFC7252]. CoAP does not define a time limit for the server response delay. Using the default CoAP parameters, the Token reuse time MUST be greater than 250 seconds plus MAX_SERVER_RESPONSE_DELAY. A preferred solution to meet this requirement is to generate a new unique Token for every multicast request, such that a Token value is never reused. If a client has to reuse Token values for some reason, and also MAX_SERVER_RESPONSE_DELAY is unknown, then using MAX_SERVER_RESPONSE_DELAY = 250 seconds is a reasonable guideline. The time between Token reuses is in that case set to a value greater than 500 seconds.2.6. Membership Configuration
2.6.1. Background
2.6.1.1. Member Discovery
CoAP groups, and the membership of these groups, can be discovered via the lookup interfaces in the Resource Directory (RD) defined in [CoRE-RD]. This discovery interface is not required to invoke CoAP group communications. However, it is a potential complementary interface useful for overall management of CoAP groups. Other methods to discover groups (e.g., proprietary management systems) can also be used. An example of doing some of the RD-based lookups is given in Section 3.6.
2.6.1.2. Configuring Members
The group membership of a CoAP endpoint may be configured in one of the following ways. First, the group membership may be preconfigured before node deployment. Second, a node may be programmed to discover (query) its group membership using a specific service discovery means. Third, it may be configured by another node (e.g., a commissioning device). In the first case, the preconfigured group information may be either an IP multicast address or a hostname (FQDN) that is resolved later (during operation) to an IP multicast address by the endpoint using DNS (if supported). For the second case, a CoAP endpoint may look up its group membership using techniques such as DNS-based Service Discovery (DNS-SD) and RD [CoRE-RD]. In the third case, typical in scenarios such as building control, a dynamic commissioning tool determines to which group(s) a sensor or actuator node belongs, and writes this information to the node, which can subsequently join the correct IP multicast group(s) on its network interface. The information written per group may again be an IP multicast address or a hostname.2.6.2. Membership Configuration RESTful Interface
To achieve better interoperability between endpoints from different manufacturers, an OPTIONAL CoAP membership configuration RESTful interface for configuring endpoints with relevant group information is described here. This interface provides a solution for the third case mentioned above. To access this interface, a client will use unicast CoAP methods (GET/PUT/POST/DELETE). This interface is a method of configuring group information in individual endpoints. Also, a form of authorization (preferably making use of unicast DTLS- secured CoAP per Section 9.1 of [RFC7252]) should be used such that only authorized controllers are allowed by an endpoint to configure its group membership. It is important to note that other approaches may be used to configure CoAP endpoints with relevant group information. These alternative approaches may support a subset or superset of the membership configuration RESTful interface described in this document. For example, a simple interface to just read the endpoint group information may be implemented via a classical Management Information Base (MIB) approach (e.g., following the approach of [RFC3433]).
2.6.2.1. CoAP-Group Resource Type and Media Type
CoAP endpoints implementing the membership configuration RESTful interface MUST support the CoAP group configuration Internet Media Type "application/coap-group+json" (Section 6.2). A resource offering this representation can be annotated for direct discovery [RFC6690] using the Resource Type (rt=) Link Target Attribute "core.gp", where "gp" is shorthand for "group" (Section 6.1). An authorized client uses this media type to query/ manage group membership of a CoAP endpoint as defined in the following subsections. The Group Configuration resource and its sub-resources have a content format based on JavaScript Object Notation (JSON) (as indicated by the "application/coap-group+json" media type). The resource includes zero or more group membership JSON objects [RFC7159] in a format as defined in Section 2.6.2.4. A group membership JSON object contains one or more key/value pairs as defined below, and represents a single IP multicast group membership for the CoAP endpoint. Each key/value pair is encoded as a member of the JSON object, where the key is the member name and the value is the member's value. Examples of four different group membership objects are as follows: { "n": "All-Devices.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:abcd]:4567" } { "n": "sensors.floor2.east.bldg6.example.com" } { "n": "coap-test", "a": "224.0.1.187:56789" } { "a": "[ff15::c0a7:15:c001]" } The OPTIONAL "n" key/value pair stands for "name" and identifies the group with a hostname (and optionally the port number), for example, an FQDN. The OPTIONAL "a" key/value pair specifies the IP multicast address (and optionally the port number) of the group. It contains an IPv4 address (in dotted-decimal notation) or an IPv6 address. The following ABNF rule can be used for parsing the address, referring to the definitions in Section 3.2.2 of [RFC3986] that are also used in the base CoAP (Section 6 of [RFC7252]. group-address = IPv4address [ ":" port ] / "[" IPv6address "]" [":" port ]
In any group membership object, if the IP address is known when the
object is created, it is included in the "a" key/value pair. If the
"a" value cannot be provided, the "n" value MUST be included,
containing a valid hostname with an optional port number that can be
translated to an IP multicast address via DNS.
group-name = host [ ":" port ]
If the port number is not provided, then the endpoint will attempt to
look up the port number from DNS if it supports a method to do this.
The possible DNS methods include DNS SRV [RFC2782] or DNS-SD
[RFC6763]. If port lookup is not supported or not provided by DNS,
the default CoAP port (5683) is assumed.
After any change on a Group Configuration resource, the endpoint MUST
effect registration/deregistration from the corresponding IP
multicast group(s) by making use of APIs such as IPV6_RECVPKTINFO
[RFC3542].
2.6.2.2. Creating a New Multicast Group Membership (POST)
Method: POST
URI Template: /{+gp}
Location-URI Template: /{+gp}/{index}
URI Template Variables:
gp - Group Configuration Function Set path (mandatory).
index - Group index. Index MUST be a string of maximum two (2)
alphanumeric ASCII characters (case insensitive). It MUST be
locally unique to the endpoint server. It indexes the particular
endpoint's list of group memberships.
Example:
Req: POST /coap-group
Content-Format: application/coap-group+json
{ "n": "All-Devices.floor1.west.bldg6.example.com",
"a": "[ff15::4200:f7fe:ed37:abcd]:4567" }
Res: 2.01 Created
Location-Path: /coap-group/12
For the 'gp' variable, it is recommended to use the path "coap-group"
by default. The "a" key/value pair is always used if it is given.
The "n" pair is only used when there is no "a" pair. If only the "n"
pair is given, the CoAP endpoint performs DNS resolution to obtain
the IP multicast address from the hostname in the "n" pair. If DNS
resolution is not successful, then the endpoint does not attempt
joining or listening to any multicast group for this case since the
IP multicast address is unknown.
After any change on a Group Configuration resource, the endpoint MUST effect registration/deregistration from the corresponding IP multicast group(s) by making use of APIs such as IPV6_RECVPKTINFO [RFC3542]. When a POST payload contains an "a", an IP multicast address to which the endpoint is already subscribed, no change to that subscription is needed.2.6.2.3. Deleting a Single Group Membership (DELETE)
Method: DELETE URI Template: {+location} URI Template Variables: location - The Location-Path returned by the CoAP server as a result of a successful group creation. Example: Req: DELETE /coap-group/12 Res: 2.02 Deleted2.6.2.4. Reading All Group Memberships at Once (GET)
A (unicast) GET on the CoAP-group resource returns a JSON object containing multiple keys and values. The keys (member names) are group indices, and the values (member values) are the corresponding group membership objects. Each group membership object describes one IP multicast group membership. If no group memberships are configured, then an empty JSON object is returned. Method: GET URI Template: /{+gp} URI Template Variables: gp - see Section 2.6.2.2 Example: Req: GET /coap-group Res: 2.05 Content Content-Format: application/coap-group+json { "8" :{ "a": "[ff15::4200:f7fe:ed37:14ca]" }, "11":{ "n": "sensors.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:25cb]" }, "12":{ "n": "All-Devices.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:abcd]:4567" } }
Note: the returned IPv6 address string will represent the same IPv6 address that was originally submitted in group membership creation, though it might be a different string because of different choices in IPv6 string representation formatting that may be allowed for the same address (see [RFC5952]).2.6.2.5. Reading a Single Group Membership (GET)
Similar to Section 2.6.2.4, but only a single group membership is read. If the requested group index does not exist, then a 4.04 Not Found response is returned. Method: GET URI Template 1: {+location} URI Template 2: /{+gp}/{index} URI Template Variables: location - see Section 2.6.2.3 gp, index - see Section 2.6.2.2 Example: Req: GET /coap-group/12 Res: 2.05 Content Content-Format: application/coap-group+json {"n": "All-Devices.floor1.west.bldg6.example.com", "a": "[ff15::4200:f7fe:ed37:abcd]:4567"}2.6.2.6. Creating/Updating All Group Memberships at Once (PUT)
A (unicast) PUT with a group configuration media type as payload will replace all current group memberships in the endpoint with the new ones defined in the PUT request. This operation MUST only be used to delete or update group membership objects for which the CoAP client, invoking this operation, is responsible. The responsibility is based on application-level knowledge. For example, a commissioning tool will be responsible for any group membership objects that it created. Method: PUT URI Template: /{+gp} URI Template Variables: gp - see Section 2.6.2.2
Example: (replacing all existing group memberships with two new
group memberships)
Req: PUT /coap-group
Content-Format: application/coap-group+json
{ "1":{ "a": "[ff15::4200:f7fe:ed37:1234]" },
"2":{ "a": "[ff15::4200:f7fe:ed37:5678]" }
}
Res: 2.04 Changed
Example: (clearing all group memberships at once)
Req: PUT /coap-group
Content-Format: application/coap-group+json
{}
Res: 2.04 Changed
After a successful PUT on the Group Configuration resource, the
endpoint MUST effect registration to any new IP multicast group(s)
and deregistration from any previous IP multicast group(s), i.e., not
any more present in the new memberships. An API such as
IPV6_RECVPKTINFO [RFC3542] should be used for this purpose. Also, it
MUST take into account the group indices present in the new resource
during the generation of any new unique group indices in the future.
2.6.2.7. Updating a Single Group Membership (PUT)
A (unicast) PUT with a group membership JSON object will replace an
existing group membership in the endpoint with the new one defined in
the PUT request. This can be used to update the group membership.
Method: PUT
URI Template 1: {+location}
URI Template 2: /{+gp}/{index}
URI Template Variables:
location - see Section 2.6.2.3
gp, index - see Section 2.6.2.2
Example: (group name and IP multicast port change)
Req: PUT /coap-group/12
Content-Format: application/coap-group+json
{"n": "All-My-Devices.floor1.west.bldg6.example.com",
"a": "[ff15::4200:f7fe:ed37:abcd]"}
Res: 2.04 Changed
After a successful PUT on the Group Configuration resource, the endpoint MUST effect registration to any new IP multicast group(s) and deregistration from any previous IP multicast group(s), i.e., not any more present in the new membership. An API such as IPV6_RECVPKTINFO [RFC3542] should be used for this purpose.
(page 17 continued on part 2)