Skip to content

nRF Cloud CoAP API

This page provides an overview of the nRF Cloud CoAP API.

Constrained Application Protocol (CoAP) is a specialized protocol designed for communication between devices with constrained resources. CoAP enables devices to communicate over constrained networks with minimal data traffic usage.

CoAP reduces network traffic by sending fewer and smaller messages, using CBOR message formatting instead of JSON. CoAP saves power by enabling the device to sleep and communicate with the cloud only when needed. By using a connection ID (CID) instead of repeating the handshake, a constrained device using CoAP can more efficiently re-establish a connection upon waking. This reduced network load, in turn, saves power by reducing modem usage. The protocol allows you to send information to the device asynchronously by updating the device shadow using the REST API.

CoAP uses a client-server model based on the REST architectural style. It provides a set of methods similar to those in HTTP, such as GET, POST, PUT, and DELETE, allowing devices to interact with resources in the cloud.

CoAP uses UDP as its underlying transport protocol instead of TCP, which reduces the overhead and complexity associated with TCP's reliability mechanisms. CoAP also includes its own reliability features based on retransmissions.

nRF Cloud CoAP services and features

nRF Cloud supports the following services through CoAP:

  • Location Services:
    • Assisted GPS (A-GPS)
    • Predicted GPS (P-GPS)
    • Ground fix
  • FOTA:
    • Fetch current pending FOTA job execution. The firmware image is downloaded through the HTTP client, as it is when connecting to nRF Cloud through MQTT.
    • Update FOTA job execution status
  • Messaging:
    • Publish messages
    • Fetch device state
    • Update device state
    • Read device state (delta)

Device requirements

To use the nRF Cloud CoAP API, your setup must meet the following requirements:

Samples and libraries

The following samples and libraries support CoAP:

  • nRF Cloud CoAP library. See the library for more information on specific endpoints, operations, and configurations.
  • nRF Cloud multi-service sample. This sample supports either CoAP or MQTT, depending on your chosen configuration.

For more general information on CoAP, see the Zephyr overview.

Message formatting

Concise Binary Object Representation (CBOR) is a compact binary data serialization format designed to efficiently represent data structures. It is similar in purpose to JSON but provides a more concise binary representation.

Every CoAP endpoint supports CBOR to optimize data traffic by minimizing or compressing data payloads. The protocol also supports JSON. Using CoAP with CBOR can reduce data usage by up to 75%.

Example:

Calling POST /v1/location/ground-fix over HTTP with JSON can use approximately 1.2 kB of data. The same message over CoAP with CBOR is approximately 0.3 kB. These calculations include TLS over HTTP and DTLS over CoAP headers, assuming that a secure connection is established and no handshake is done.

Supported transport features

CoAP supports the following transport features:

  • IPv4 or IPv6.
  • Blockwise transfer: Larger messages are split so they fit into the maximum transmission unit (MTU) limit. These messages fit into smaller UDP frames and are suitable for constrained networks.
  • DTLS with connection ID (CID), which allows for a long-lived secure connection and eliminates the need to repeat the DTLS handshake.

Authentication

All CoAP communication with nRF Cloud must use DTLS on port 5684 for server-side authentication.

The server must present its X509 certificate, but the device does not. The device must verify the server certificate. After a secure connection is established, the device sends its JWT to authenticate itself. Once authenticated, the device and server are open for further communication.

Since the device uses a JWT for authentication, it must be cloud provisioned.

JWTs

nRF Cloud CoAP supports two types of JWT:

  • REST API JWT: This is the same type of JWT used to authenticate REST API requests. Requires cloud provisioning.
  • Identity JWT: The identity JWT is signed with an identity key that resides on the device. This token is generated through the nRF Cloud Identity Service. Requires cloud provisioning.

Secure connection

nRF Cloud supports DTLS 1.2 with CID extension (RFC 9146), which reduces the need to handshake with the server. The server uses a connection identifier to identify the device's secure connection, instead of an IP address, which can change often. This enables the device to use long-lasting, secure connections, even when connecting from behind NAT or after a long period of inactivity.

Example:

In this example, a device sends 100 bytes of sensor data. Every five minutes of activity results in a traffic decrease of 89% over DTLS 1.2 without a CID extension. The time spent online by the device is also reduced.

Characteristics DTLS 1.2 DTLS 1.2 with CID
Number of handshakes 288 1 or 0
Data transferred ~606 kB ~62 kB

See next