CoAP protocol endpoint

The CoAP protocol endpoint is a device facing service offering connectivity using a CoAP based API. The CoAP endpoint supports encrypted sessions using DTLS.

What is CoAP?

CoAP (Constrained Application Protocol) is a specialized Internet application protocol for constrained devices. The protocol resembles HTTP, but with a smaller footprint, and typically uses UDP instead of TCP as the transport protocol. Encryption is supported when using DTLS.

Connecting

Before communicating with the endpoint, the respective device and application need to be registered with Drogue Cloud.

An example CoAP URI for Drogue Cloud looks like this:

coap[s]://<coap-endpoint-address>/v1/{channel}
The scheme coaps:// is used for encrypted DTLS sessions.

The /v1/{channel} path suffix is required when used with Drogue Cloud. The channel parameter determines the subject in the Cloud Event that gets forwarded to applications.

Optional parameters can also be passed, but they need to be URL encoded. The rules for encoding the Drogue IoT specific parameters can be viewed here.

The following optional parameters can be passed:

  • application: Application that device belongs to

  • device: The device ID

  • data_schema: Data schema of the payload

  • as: Allows the device to alias another ID, typically used by gateways.

  • ct: The amount of time the device will wait for incoming commands

    For a device to receive commands, it must set the ct parameter with a specified timeout.

The command will piggyback on the response—the responsibility to track when the device issues a request and promptly issue the command lies on the application.

Authentication

A device can authenticate itself using one of the following approaches:

  • Client certificate authentication, only supported when using DTLS. See Setting X.509 client certificate credentials for how to configure the application.

  • Pre-shared key authentication, only supported when using DTLS. See Setting TLS-PSK credentials for how to configure the device.

  • Setting CoAP option number 4209. It is carried out using a base64 string similar to HTTP basic authentication. We strongly support using DTLS to ensure the password stays encrypted.

Responses

There are two response types that a device can receive.

A device would receive a response with the 2.04(Changed) status code if the publish action were successful.

If the request passed the ct(command timeout) parameter and a command is sent to the device within this interval, the device will receive the 2.05(Content) response code. The contents of the command can then be read from the CoAP option 4210.

If a request fails, the device can receive responses with appropriate status codes. The payload in such cases will contain the reason for the error as well.

Examples

An example CoAP URI:

coaps://sandbox.drogue.cloud:5674/v1/<channel>?application=example-app&device=device1&data_schema=application%2Foctet-stream&as=device%232&ct=30
The Request URL must be URL-encoded.

Using the coap-client tool authenticating with CoAP option number 4209, representing auth information "device1@example-app:hey-rodney":

coap-client -m post coaps://sandbox.drogue.cloud:5684/v1/foo -O 4209,"Basic ZGV2aWNlMUBleGFtcGxlLWFwcDpoZXktcm9kbmV5"