Skip to main content

MQTT API

What is MQTT?#

MQTT stands for Message Queuing Telemetry Transport and is a lightweight pub/sub protocol for exchanging messages. nRF Cloud is built on AWS and thus uses the MQTT broker in AWS IoT Core to process MQTT messages sent and received over MQTT topics.

How It Works#

It's beyond scope of this document to explain how MQTT works in general. That information is easily found on the Web. But here we can share some high level information about how it works on nRF Cloud. A typical process is as follows:

  1. A device (or more accurately, a device's MQTT client running in the modem) connects to the nRF Cloud MQTT endpoint. See the section, below, for getting the endpoint for your account.
  2. The device publishes a JSON message on a custom-defined topic for monitoring a warehouse (prod/${teamId}/m/d/sensor/temperature/room2). The message contains a temperature sensor reading.
  3. The MQTT broker receives the message. If a rule is specified, it is run; and if the rule's criteria are met, it will trigger an action. Typical actions might include "store this message in a database" or "republish a subset of this data to another topic".

Getting Your MQTT Connection Information#

You can acquire the MQTT broker hostname by calling the FetchAccountInfo endpoint. The JSON response will include these two fields (shown with sample values). You can read about the purpose of each of these values, below.

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

Authentication#

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

The nRF Cloud MQTT API#

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

In what follows, ${mqttTopicPrefix} is the value of the mqttTopicPrefix JSON field in the response from the FetchAccountInfo endpoint (see above).

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

Topics Used by Devices Running the nRF Cloud Library#

Devices running the nRF Cloud Library, whether via the Asset Tracker applications or as the foundation of a custom application, use the following topics.

Shadow Topics#

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

TopicPublishSubscribePurpose
${device_id}/shadow/get/acceptedXReceive a trimmed shadow that contains only essential shadow data*
$aws/things/${deviceId}/shadow/get/rejectedXReceive info about a rejected shadow request.
$aws/things/${deviceId}/shadow/update/deltaXReceive info about changes in the shadow request
$aws/things/${deviceId}/shadow/getXRequest the device's shadow
$aws/things/${deviceId}/shadow/updateXUpdate 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 (below).

Message and Location Services Topics#

Each of the topics below should be prefaced with your mqttTopicPrefix (see above).

TopicPublishSubscribePurpose
m/d/${deviceId}/c2dXReceive messages from nRF Cloud (c2d = "cloud to device"), such as Location Services data.*
m/d/${deviceId}/d2cXPublish messages to nRF Cloud (d2c = "device to cloud"). An example might a request for Location Services data.*
m/d/${deviceId}/d2c/bulkXPublish a batch of messages to nRF Cloud as an array, which will republish each message in the array to the /d2c topic (above), as if each message was published as a single. Messages sent to /d2c/bulk are not stored. Useful for ultra-low power (ULP) scenarios. This is currently the only bulk processing topic we support.
gateways/${gatewayId}/c2gXReceive messages from nRF Cloud (c2g = "cloud to gateway")**.
gateways/${gatewayId}/g2cXPublish messages to nRF Cloud (g2c = "gateway to cloud")**.

* nRF Cloud actually supports messages sent to any topic prefixed with ${mqttTopicPrefix}/m. However, the nRF Cloud Web app and nRF Cloud nRF Connect SDK library, and the Asset Tracker applications specifically use /d2c, /d2c/bulk and /c2d. If you want the nRF Cloud Web UI to work with and properly display these messages, send the data formatted per these schemas.

** Applies to LTE Gateways only.

FOTA Topics#

These topics are relevant if your device is using the Firmware Over-the-Air (FOTA) Update service, which sends "update jobs" to devices that they execute in order to update their firmware.

Each of the topics below should be prefaced with your mqttTopicPrefix (see above).

TopicPublishSubscribePurpose
${deviceId}/jobs/rcvXReceive a FOTA job execution for an IP-based device
${deviceId}/jobs/rcvXReceive a FOTA job execution for a Bluetooth LE device*
${deviceId}/jobs/reqXRequest the current pending job execution for an IP-based device
${deviceId}/jobs/updateXUpdate the status of a job execution for an IP-based device
${gatewayId}/jobs/ble/reqXRequest the current pending job execution for a Bluetooth LE device*
${gatewayId}/jobs/ble/updateXUpdate 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, but are supported by the nRF Cloud back end, and could be useful when developing custom firmware applications.

Each of the topics below should be prefaced with your mqttTopicPrefix (see above).

TopicPublishSubscribePurpose
m/#XXSend and receive device messages, and have them automatically stored in the cloud for retrieval later.*
a/connectionsXReceive connection events from your devices, informing you when they connected and disconnected.**

* The nRF Cloud Library does use this topic fragment, but only on /d2c and /c2d (see above). nRF Cloud will process and store any device messages sent over topics that start with the m topic fragment, e.g., m/sensor/temperature/room2.

** This can be useful if building, say, a Web or mobile application for managing a fleet of devices.