CoAP adapter
The CoAP protocol adapter exposes CoAP based endpoints for the Telemetry, Event and Command&Control APIs of the device connectivity layer.
The CoAP adapter requires clients to authenticate during connection establishment. The adapter currently supports PSK as part of a DTLS handshake for that purpose. In order to do so, clients need to provide a PSK-Identity during the handshake. The PSK-Identity must have the format auth-id@tenant-id.
The details regarding device provisioning with PSK are provided in the chapter Device authentication.
For the examples below the coap-client command line tool of libcoap project is used. To build the client please follow the steps of this manual. For PSK based device authentication the exchange of certificates is not necessary and therefore it is not required to download the server certificate of the device connectivity layer.
Table of contents
Communication patterns
Publishing telemetry data
The CoAP adapter supports publishing of telemetry data by means of request with method POST for devices and PUT for gateways using CON (at least once QoS 1) or NON (at most once QoS 0) delivery semantics.
Publishing events
The CoAP adapter supports publishing of events by means of request with method POST for devices and PUT for gateways using CON (at least once QoS 1) delivery semantic only. The adapter will send a status code to the client once the event has been accepted for processing.
Command & control
The CoAP adapter supports receiving commands by means of request with method POST for devices and PUT for gateways. The responses to the commands are sent using only CON (QoS 1) delivery semantic.
All above mentioned communication patterns can be used by devices connecting directly to CoAP protocol adapter or by gateways connecting to CoAP protocol adapter and acting on behalf of the actual devices.
Devices connected directly to CoAP adapter
Publishing telemetry data
URI: /telemetry
Method: POST
Type:
CON: at least once QoS 1 delivery semantic
NON: at most once QoS 0 delivery semantic
Request Options:
(optional) content-format: The type of payload contained in the request body. Required, if request contains payload.
Query Parameters:
(optional) hono-ttd: The number of seconds the device will wait for the response.
(optional) empty: Marks the request as an empty-notification
Request Body:
(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if URI-query: empty is provided.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
If the hono-ttd query-parameter is set in order to receive a command and if the authenticated device is actually a gateway, the returned command will be the first command that the northbound application has sent either to the gateway itself or to any device that has last sent a telemetry or event message via this gateway.
Example:
Publish some JSON data with default delivery semantic CON (QoS 1):
coap-client -u auth-id@tenant-id -k psk-secret -m POST coaps://coap.bosch-iot-hub.com/telemetry -t application/json -e '{"temp": 5}'Publish some JSON data with delivery semantic NON (QoS 0):
coap-client -u auth-id@tenant-id -k psk-secret -N -m POST coaps://coap.bosch-iot-hub.com/telemetry -t application/json -e '{"temp": 5}'Publishing events
URI: /event
Method: POST
Type:
CON: at least once QoS 1 delivery semantic
Request Options:
(optional) content-format: The type of payload contained in the request body. Required, if request contains payload.
Query Parameters:
(optional) hono-ttd: The number of seconds the device will wait for the response.
(optional) empty: Marks the request as an empty-notification
Request Body:
(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if URI-query: empty is provided.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
If the hono-ttd query-parameter is set in order to receive a command and if the authenticated device is actually a gateway, the returned command will be the first command that the application has sent either to the gateway itself or to any device that has last sent a telemetry or event message via this gateway.
Example:
Publish some JSON data for device:
coap-client -u auth-id@tenant-id -k psk-secret -N -m POST coaps://coap.bosch-iot-hub.com/telemetry -t application/json -e '{"temp": 5}'Sending a response to a command
After a connected business application has sent a command to a connected device, the device may send a response to this command.
URI: /command_response/${commandRequestId}
Method: POST
Type:
CON: at least once QoS 1 delivery semantic
Request Options:
(optional) content-format: A media type describing the semantics and format of the payload contained in the request body. This option must be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body.
Query Parameters:
(required) hono-cmd-status: An HTTP status code indicating the outcome of processing the command.
Request Body:
(optional) Arbitrary data representing the result of processing the command on the device.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
Example:
Send a response to a previously received command with the command-request-id req-id-uuid:
coap-client -u auth-id@tenant-id -k psk-secret coaps://coap.bosch-iot-hub.com/command_response/req-id-uuid?hono-cmd-status=200Devices connected via gateway to CoAP adapter
Gateways publish data on behalf of other devices which do not connect to a protocol adapter directly but instead are connected to the gateway. In this case the credentials provided by the gateway during connection establishment with the protocol adapter are used to authenticate the gateway whereas the parameters from the URI are used to identify the device that the gateway publishes data for.
Publishing telemetry data
URI: /telemetry/${tenantId}/${deviceId}
Method: PUT
Type:
CON: at least once QoS 1 delivery semantic
NON: at most once QoS 0 delivery semantic
Request Options:
(optional) content-format: The type of payload contained in the request body. Required, if request contains payload.
Query Parameters:
(optional) hono-ttd: The number of seconds the device will wait for the response.
(optional) empty: Marks the request as an empty-notification
Request Body:
(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if URI-query: empty is provided.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
Example:
Publish some JSON data for a device through gateway:
coap-client -u auth-id-gateway@tenant-id -k gateway-psk-secret -m PUT coaps://coap.bosch-iot-hub.com/telemetry/tenant-id/device-id -t application/json -e '{"temp": 5}'Publishing events
URI: /event/${tenantId}/${deviceId}
Method: PUT
Type:CON
Request Options:
(optional) content-format: The type of payload contained in the request body. Required, if request contains payload.
Query Parameters:
(optional) hono-ttd: The number of seconds the device will wait for the response.
(optional) empty: Marks the request as an empty-notification
Request Body:
(optional) Arbitrary payload encoded according to the given content type. Maybe empty, if URI-query: empty is provided.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
Example:
Publish some JSON data for a device through gateway, indicating that the gateway will wait for 10 seconds to receive the response:
coap-client -u auth-id-gateway@tenant-id -k gateway-psk-secret -m PUT coaps://coap.bosch-iot-hub.com/event/tenant-id/device-id?hono-ttd=10 -t application/json -e '{"temp": 5}'Sending a response to a command
After a connected business application sent a command to a device connected via a gateway, the device may send a response to this command via the gateway.
URI: /command_response/${tenantId}/${deviceId}/${commandRequestId}
Method: PUT
Type: CON
Request Options:
(optional) content-type: A media type describing the semantics and format of the payload contained in the request body. This option must be set if the result of processing the command on the device is non-empty. In this case the result data is contained in the request body.
Query Parameters:
(required) hono-cmd-status: An HTTP status code indicating the outcome of processing the command.
Request Body:
(optional) Arbitrary data representing the result of processing the command on the device.
The details concerning the Response to the Request via the CoAP adapter can be found in the Hono Documentation.
Example:
Send a response to a previously received command with the command-request-id req-id-uuid for a device:
coap-client -u gateway-auth-id@tenant-id -k gateway-psk-secret coaps://coap.bosch-iot-hub.com/command_response/tenant-id/device-id/req-id-uuid?hono-cmd-status=200 -e '{"brightness-changed": true}'