TODO: Provide a short overview of the document and the protocol binding features.

Introduction

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

Protocol Overview

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": ...

URI Schemes

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.

CoAP Vocabulary

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.

Form terms

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

BlockWiseTransferParameters

Vocabulary term Description Assignment Type
coap:block2SZX Indicates the largest block size that may be used in a Block2 Option optional unsignedShort

(one of 16, 32, 64, 128, 256, 512, 1024)

coap:block1SZX Indicates the largest block size that may be used in a Block1 Option optional unsignedShort

(one of 16, 32, 64, 128, 256, 512, 1024)

QBlockWiseTransferParameters

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 16, 32, 64, 128, 256, 512, 1024)

coap:qblock1SZX Indicates the largest block size that may be used in a Q-Block1 Option optional unsignedShort

(one of 16, 32, 64, 128, 256, 512, 1024)

Mappings

This section describes the strategies and default values to use protocol specific concepts within the WoT Interaction model.

Default mappings

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"

Possible mappings

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.

Examples

TODO: Provide a compressive list of examples about how this binding template can be used within forms or Thing Descriptions