nRF Cloud MQTT topics¶
The MQTT API uses topics to send or receive data. Topics that begin with $aws
are 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 the device state through the shadow. See also the AWS documentation regarding MQTT topics reserved for shadows.
Topic | Publish | Subscribe | Purpose |
---|---|---|---|
${deviceId}/shadow/get/accepted |
✔ | Receive a trimmed shadow that contains only essential shadow data, in response to a get request. |
|
${deviceId}/shadow/update/delta |
✔ | Receive the trimmed shadow changes made in response to an update request. Only changes of essential shadow data is provided. |
|
$aws/things/${deviceId}/shadow/get/rejected |
✔ | Receive information about a rejected shadow request. | |
$aws/things/${deviceId}/shadow/update/delta |
✔ | Receive all shadow changes made in response to an update request. |
|
$aws/things/${deviceId}/shadow/get |
✔ | Request the device's shadow. | |
$aws/things/${deviceId}/shadow/update |
✔ | 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 topics¶
Preface each of these topics with mqttTopicPrefix
. nRF Cloud supports messages sent to any topic prefixed with ${mqttTopicPrefix}/m
.
Schemas¶
The following table explains the message topic schemas used by nRF Cloud and devices.
Schema | Description |
---|---|
c2d |
Cloud-to-device |
d2c |
Device-to-cloud |
c2g |
Cloud-to-gateway |
g2c |
Gateway-to-cloud |
The nRF Cloud portal, nRF Cloud library, and Asset Tracker application all use /d2c
, /d2c/bulk
and /c2d
. If you want the nRF Cloud portal to work with and properly display these messages, send the data formatted according to /d2c
schemas.
Topics¶
The following table shows supported message topics.
Topic | Publish | Subscribe | Purpose |
---|---|---|---|
m/d/${deviceId}/c2d/r |
✔ | Receive messages from nRF Cloud not related to Location Services. | |
Deprecated m/d/${deviceId}/c2d |
✔ | This topic is deprecated. See /c2d/r . |
|
m/d/${deviceId}/d2c |
✔ | Publish messages to nRF Cloud. | |
m/d/${deviceId}/d2c/bin |
✔ | Publish binary logs to nRF Cloud. | |
m/d/${deviceId}/d2c/bulk |
✔ | 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 |
✔ | Receive messages from nRF Cloud. Applies to LTE gateways only. | |
gateways/${gatewayId}/g2c |
✔ | Publish messages to nRF Cloud. Applies to LTE gateways only. |
Location Services topics¶
The following tables show topics related to Location Services.
Preface each of these topics with mqttTopicPrefix
.
Subscribe topics (C2D) for Location Services¶
A device can subscribe to the following topics to receive location data from nRF Cloud.
Topic | Purpose |
---|---|
/m/d/${deviceId}/agnss/r |
Receive A-GNSS data from nRF Cloud. |
Deprecated /m/d/${deviceId}/agps/r |
This topic is deprecated. See /agnss/r . |
/m/d/${deviceId}/pgps/r |
Receive P-GNSS data from nRF Cloud. |
/m/d/${deviceId}/wifi/r |
Receive Wi-Fi data from nRF Cloud. |
/m/d/${deviceId}/cell_pos/r |
Receive cell data from nRF Cloud. |
/m/d/${deviceId}/ground_fix/r |
Receive ground fix data from nRF Cloud. |
Publish topics (D2C) for Location Services¶
A device can use the following topics to send location data to nRF Cloud. These are the same topics used for other messages, and include location data according to the app ID in the payload.
Topic | Purpose | Example |
---|---|---|
m/d/${deviceId}/d2c or m/d/${deviceId}/d2c/bulk |
Send the following types of location data to nRF Cloud, based on the app ID in the payload:
|
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
.
Topic | Publish | Subscribe | Purpose |
---|---|---|---|
${deviceId}/jobs/rcv |
✔ | Receive a FOTA job execution for an IP-based device. | |
${deviceId}/jobs/ble/rcv |
✔ | Receive a FOTA job execution for a Bluetooth® Low Energy (LE) device. Applies to LTE gateways only. | |
${deviceId}/jobs/req |
✔ | Request the current pending job execution for an IP-based device. | |
${gatewayId}/jobs/ble/req |
✔ | Request the current pending job execution for a Bluetooth LE device. Applies to LTE gateways only. | |
${deviceId}/jobs/update |
✔ | Update the status of a job execution for an IP-based device. | |
${gatewayId}/jobs/ble/update |
✔ | 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
.
You can use account devices to subscribe to any of the above topics and any of the topics below. You can substitute the MQTT wildcard +
character for device IDs to subscribe to events from all devices in the team. You can also use the MQTT wildcard #
character at the end of a topic to subscribe to any topic at that level or below, such as +/jobs/#
.
Any provisioned and associated device can access the following topics, but the device's firmware must subscribe or publish to the full topic name directly, since they are not supported by the nRF Cloud library.
Topic | Publish | Subscribe | Purpose |
---|---|---|---|
m/# |
✔ | ✔ | Send and receive custom device messages, and have them automatically stored in the cloud for later retrieval. The nRF Cloud library uses only the m/d/${deviceId}/# topics shown in the tables above. 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 |
✔ | Receive connection events from your devices, informing you when they connected and disconnected. |
The following republished shadow topics are only accessible by account devices, not any other devices. The topics allow account devices to subscribe to shadow updates for any device on the same team as the account device. An account device that subscribes to shadow topics will only receive shadow changes for the account device, not for any other devices.
Topic | Publish | Subscribe | Republished From | Purpose |
---|---|---|---|---|
${deviceId}/shadow/get/accepted |
✔ | $aws/things/${deviceId}/shadow/get/accepted |
Receive the entire shadow, in response to a get request. |
|
${deviceId}/shadow/update/delta |
✔ | $aws/things/${deviceId}/shadow/update/delta |
Receive all shadow changes made in response to an update request. |