CoAP adapter

The CoAP protocol adapter exposes CoAP based endpoints for Bosch IoT Hub’s Telemetry, Event and Command&Control APIs.

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 Bosch IoT Hub.

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. See Gateway mode for a more detailed description.

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 -m POST coaps://coap.bosch-iot-hub.com/event -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=200

Devices 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}'
Corporate information Data protection notice Legal information Support Free plans