TODO: Provide a short overview of the document and the protocol binding features.
The Constrained Application Protocol (CoAP) [[RFC7252]] is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine-to-machine (M2M) applications such as smart energy and building automation.
This document describes how the Web of Things specification can be use to present devices that use the CoAP in a Thing Description. In particular, the document explain how to create valid Forms for the different operations that CoAP can perform.
This document is a work in progress
In contrast to HTTP, where header fields all follow the same key-value based structure, CoAP defines specific formats for its options, which all have to be registered with IANA, being the primary way for adding new features to the protocol.
Due to the highly standardized nature of CoAP options, mapping them to a vocabulary of features makes more sense than offering a generic format for defining them within a TD form, also considering that there options with binary, numeric or string-based values (see sections 3.1 and 3.2 of [[RFC7252]] for more details).
The table below gives an overview of how the features offered by the existing CoAP RFCs
are translated into vocabulary terms which can be used in a [[[WOT-THING-DESCRIPTION]]].
Observing resources as defined in [[RFC7641]], for example, can be enabled by including a
subprotocol value of coap:observe in a form.
Parameters for blockwise transfer (as defined in [[RFC7959]]) can be set in a
coap:blockwise member.
The vocabulary terms are defined in full detail in section [[[#vocabulary]]].
| Feature | Covered by |
|---|---|
| Request to Server | "href": ..., "coap:method": ... |
| Request to Forward Proxy | "href": ..., "coap:method": ..., "coap:proxy": ... |
| Caching: Validation | n/a |
| Conditional Requests | n/a |
| Content | "coap:format": ... |
| Content Negotiation | "coap:accept": ... |
| Observing Resources | "subprotocol": "coap:observe" |
| Block-Wise Transfer | "coap:blockwise": { ... } |
| Quick Block-Wise Transfer | "coap:qblockwise": { ... } |
| Hop Limit | "coap:hoplimit": ... |
CoAP uses the following Uniform Resource Identifier (URI) schemes for identifying CoAP resources and providing a means of locating the resource:
| URI Scheme | Reference |
|---|---|
| coap | [[RFC7252]] |
| coap+tcp | [[RFC8323]] |
| coap+ws | [[RFC8323]] |
| coaps | [[RFC7252]] |
| coaps+tcp | [[RFC8323]] |
| coaps+ws | [[RFC8323]] |
See the Uniform Resource Identifier (URI) Schemes registry for the complete list of CoAP URI schemes.
This section describes the vocabulary used in CoAP. A protocol binding implementation should use the vocabulary defined in this section to describe the different configuration that can be used to exchanged data between Web of Things.
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
coap:method |
Indicates the CoAP method to be used in the request | optional |
string
(see the CoAP Method Codes registry for the set of possible values) |
coap:format |
Indicates that a payload in one of the specified formats with a matching CoAP Content-Format option [[RFC7252]] be included in the request | optional |
unsignedShort
or array of
unsignedShort
(see the CoAP Content-Formats registry for the set of possible values) |
coap:accept |
Indicates that a CoAP Accept option [[RFC7252]] with one of the specified formats be included in the request | optional |
unsignedShort
or array of
unsignedShort
(see the CoAP Content-Formats registry for the set of possible values) |
coap:blockwise |
Indicates that a block-wise transfer [[RFC7959]] is supported | optional | BlockWiseTransferParameters |
coap:qblockwise |
Indicates that a quick block-wise transfer [[RFC9177]] is supported | optional | QBlockWiseTransferParameters |
coap:hopLimit |
Indicates that a CoAP Hop-Limit option [[RFC8768]] be included in the request | optional |
unsignedByte
|
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
coap:block2SZX |
Indicates the largest block size that may be used in a Block2 Option | optional |
unsignedShort
(one of |
coap:block1SZX |
Indicates the largest block size that may be used in a Block1 Option | optional |
unsignedShort
(one of |
| Vocabulary term | Description | Assignment | Type |
|---|---|---|---|
coap:qblock2SZX |
Indicates the largest block size that may be used in a Q-Block2 Option | optional |
unsignedShort
(one of |
coap:qblock1SZX |
Indicates the largest block size that may be used in a Q-Block1 Option | optional |
unsignedShort
(one of |
This section describes the strategies and default values to use protocol specific concepts within the WoT Interaction model.
| Operation | Default Binding |
|---|---|
readproperty |
"coap:method": "GET" |
writeproperty |
"coap:method": "PUT" |
observeproperty |
"coap:method": "GET", "subprotocol": "coap:observe" |
unobserveproperty |
"coap:method": "GET", "subprotocol": "coap:observe" |
readmultipleproperties |
"coap:method": "GET" |
writemultipleproperties |
"coap:method": "PUT" |
readallproperties |
"coap:method": "GET" |
writeallproperties |
"coap:method": "PUT" |
observeallproperties |
"coap:method": "GET", "subprotocol": "coap:observe" |
unobserveallproperties |
"coap:method": "GET", "subprotocol": "coap:observe" |
invokeaction |
"coap:method": "POST" |
queryaction |
"coap:method": "GET" |
cancelaction |
"coap:method": "POST" |
queryallactions |
"coap:method": "GET" |
subscribeevent |
"coap:method": "GET", "subprotocol": "coap:observe" |
unsubscribeevent |
"coap:method": "GET", "subprotocol": "coap:observe" |
subscribeallevents |
"coap:method": "GET", "subprotocol": "coap:observe" |
unsubscribeallevents |
"coap:method": "GET", "subprotocol": "coap:observe" |
TODO: This section should describe other mappings that can be used by TD designers. It is meant to be informative but it provides guidelines for implementers.
TODO: Provide a compressive list of examples about how this binding template can be used within forms or Thing Descriptions