Skip to main content

MQTT API

Message Queuing Telemetry Transport (MQTT) is a lightweight publish-subscribe protocol for exchanging messages. nRF Cloud is built on AWS and uses the MQTT broker in AWS IoT Core to process MQTT messages sent and received over MQTT topics.

The publish-subscribe process over MQTT is as follows:

  1. A device, or the MQTT client running in the modem, connects to the nRF Cloud MQTT endpoint.
  2. The device publishes a JSON message on a topic.
  3. The MQTT broker receives the message. If a rule is specified, the rule is run, and if the rule's criteria are met, it triggers an action. Typical actions might include storing a message in a database or republishing a subset of the data to another topic.

MQTT connection information

Acquire the MQTT broker hostname by calling the FetchAccountInfo endpoint. This method requires you to use the REST API. The JSON response includes two fields, the mqttEndpoint and mqttTopicPrefix. The endpoint is always the same for nRF Cloud operations. The topic prefix is unique to your team, as in the following example:

"mqttEndpoint": "a2n7tk1kp18wix-ats.iot.us-east-1.amazonaws.com"
"mqttTopicPrefix": "prod/762bfc32-d338-4d5a-bd03-1e504e013846/"

If you do not want to use the REST API to get this information, you can also form the mqttTopicPrefix using your Team ID:

  1. Log in to the nRF Cloud portal.
  2. Click the drop-down menu in the top right corner.
  3. Click Teams.
  4. Find the Team ID under the team name.
  5. The value of mqttTopicPrefix is prod/<teamID>.
  6. Use this value when calling the MQTT API.

Authentication

All connections to the AWS IoT MQTT broker must connect using Mutual TLS on port 8883. This means that devices using MQTT must have an X.509 device certificate and be cloud provisioned.

nRF Cloud MQTT API

As with the REST API, the MQTT API has endpoints. These endpoints are MQTT message topics. Topics that begin with $aws are called AWS Reserved Topics. All other topics are custom-defined by nRF Cloud.

In the following sections, ${mqttTopicPrefix} is the value of the mqttTopicPrefix JSON field in the response to the FetchAccountInfo endpoint.

Permissions to access these topics are managed by IoT security policies. See Device security for more information.

Topics used by devices running the nRF Cloud library

Devices running the nRF Cloud library, whether through Asset Tracker or a custom application, use the topics in this section.

Shadow topics

The nRF Cloud library supports the following MQTT topics for retrieving and managing device state through the shadow. See also the AWS documentation regarding MQTT topics reserved for shadows.

TopicPublishSubscribePurpose
${device_id}/shadow/get/accepted-XReceive a trimmed shadow that contains only essential shadow data
$aws/things/${deviceId}/shadow/get/rejected-XReceive info about a rejected shadow request
$aws/things/${deviceId}/shadow/update/delta-XReceive info about changes in the shadow request
$aws/things/${deviceId}/shadow/getX-Request the device's shadow
$aws/things/${deviceId}/shadow/updateX-Update the device shadow

After connecting and getting the shadow contents, the device looks for {"pairing":{"state":"paired"}}. If instead it finds {"state":"not_associated"}, the device waits for association. If found, the device derives and stores the c2d and d2c topics.

Message and Location Services topics

Preface each of these topics with mqttTopicPrefix. nRF Cloud supports messages sent to any topic prefixed with ${mqttTopicPrefix}/m. The nRF Cloud web portal, nRF Cloud library, and Asset Tracker application all use /d2c, /d2c/bulk and /c2d. If you want the nRF Cloud web portal to work with and properly display these messages, send the data formatted according to /d2c schemas.

The following table shows supported topics.

TopicPublishSubscribePurpose
m/d/${deviceId}/c2d-XReceive messages from nRF Cloud (c2d = cloud to device), such as Location Services data
m/d/${deviceId}/d2cX-Publish messages to nRF Cloud (d2c = device to cloud), such as a request for Location Services data
m/d/${deviceId}/d2c/bulkX-Publish a batch of messages to nRF Cloud as an array, which republishes each message in the array to the /d2c topic as if each message were published individually. Messages sent to /d2c/bulk are not stored. Useful for ultra-low power (ULP) scenarios. This is currently the only supported bulk processing topic.
gateways/${gatewayId}/c2g-XReceive messages from nRF Cloud (c2g = cloud to gateway) Applies to LTE gateways only.
gateways/${gatewayId}/g2cX-Publish messages to nRF Cloud (g2c = gateway to cloud). Applies to LTE gateways only.

FOTA topics

These topics relate to the firmware over-the-air (FOTA) update service, which sends an update job that the target device can execute to update its firmware.

Preface each of these topics with mqttTopicPrefix.

TopicPublishSubscribePurpose
${deviceId}/jobs/rcv-XReceive a FOTA job execution for an IP-based device
${deviceId}/jobs/rcv-XReceive a FOTA job execution for a Bluetooth LE device. Applies to LTE gateways only.
${deviceId}/jobs/reqX-Request the current pending job execution for an IP-based device
${deviceId}/jobs/updateX-Update the status of a job execution for an IP-based device
${gatewayId}/jobs/ble/reqX-Request the current pending job execution for a Bluetooth LE device. Applies to LTE gateways only.
${gatewayId}/jobs/ble/updateX-Update the status of a job execution for a Bluetooth LE device. Applies to LTE gateways only.

Additional topics supported by nRF Cloud

The following topics are not directly supported by the nRF Cloud library.

Preface each of these topics with mqttTopicPrefix.

TopicPublishSubscribePurpose
m/#XXSend and receive device messages, and have them automatically stored in the cloud for later retrieval. The nRF Cloud library uses the m/# topic fragment on /d2c and /c2d. nRF Cloud processes and stores any device messages sent over topics that start with the m topic fragment, for example, m/sensor/temperature/room2.
a/connections-XReceive connection events from your devices, informing you when they connected and disconnected