CoAP protocol endpoint

The CoAP protocol endpoint is a device facing service offering connectivity using a CoAP based API.

Currently, the endpoint does not support DTLS. It is not recommended to use this in production or to transfer any sensitive data over public networks.

Requests:

Before communicating with the endpoint, the respective device and application need to be registered with drogue cloud. The coap requests made to the endpoint need to be of the following format:

coap://<coap-endpoint-address>/v1/{channel}/{subject(optional)}

The UriPath option should be set with v1, channel name and subject name(optional).

Optional parameters can also be passed, but they need to be URL encoded. The rules for encoding the device and application name can be viewed over here.

The following parameters can be passed as queries:

  • application: The specific application ID that the device is sending telemetry to

  • device: The device ID

  • data_schema: Data schema of the payload

  • as: Allows the device to alias another ID

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

For a device to receive commands, it must send a request 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 information is sent using the CoAP option number 4209. It is carried out using HTTP-like authentication headers. For example:

Basic ZGV2aWNlMUBhcHAxOmhleS1yb2RuZXk

Here, we use the HTTP Basic authentication scheme, along with the base64 encoded device authentication information. The format of the device authentication information is <device-id>@<application-id>:<password>.

A sample CoAP request would look something like the following:

  • The Request URL would be formatted like so, with the device name 'device#2' and 'device#4' percentage encoded:

coap://test-url/v1/sample_channel/sample_subject?application=app1&device=device%232&data_schema=application%2Foctet-stream&as=device%232&ct=30

  • The value of Option 4209, representing auth information "device1@app1:hey-rodney":

Basic ZGV2aWNlMUBhcHAxOmhleS1yb2RuZXk // present as bytes

  • Value of the UriPath Option(obtained from request URL):

v1, Rust, test // present as bytes

  • Value of the UriQuery Option(obtained from request URL):

// present as bytes
application=app1&device=device%232&data_schema=application%2Foctet-stream&as=device%234&ct=30

Response:

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.