nRF Cloud MQTT topics

The MQTT API uses topics to send or receive data.

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.

Attempting to subscribe to MQTT topics other than those listed here will cause the MQTT broker to disconnect the device.

Topics used by devices running the nRF Cloud library

Devices with firmware developed with the nRF Cloud library use the topics in this section. For an example of firmware that uses this library to access MQTT topics, see the nRF Cloud multi-service sample.

Shadow topics

The nRF Cloud library supports the following MQTT topics for retrieving and managing the device state through the shadow. See the list of library functions here.

In addition to these topics, you can use any AWS shadow topics described in MQTT topics reserved for shadows, but they are not provided by the nRF Cloud library. You must develop your own custom firmware to implement publishing and subscribing to the AWS topics.

To obtain more of the shadow than the trimmed version returned by {deviceId}/shadow/get/trim, use{deviceId}/shadow/get/tf with a transform definition to request only the sections you need. By default, the transformed response is limited to 1792 bytes (characters). Nordic devices have a TLS buffer limit of 2 KB in the modem, but the complete shadow of a device can exceed that size. If the payload of the returned shadow is greater than 2 KB, the modem will disconnect the MQTT connection. It must be reconnected by the firmware. For this reason, do not raise the limit for Nordic devices.

You can raise the limit for non-Nordic devices capable of receiving larger payloads using the l limit property of the transform request.

You must subscribe to the Subscribe topics on which you will receive data before publishing to the Publish topics.

Getting shadow data

The following table contains topics related to getting shadow data.

Topic	Publish	Subscribe	Purpose
`{deviceId}/shadow/get/accepted/trim`		✔	Receive the device's trimmed shadow, which contains only essential shadow data (response to `.../get/trim`). See (1).
`{deviceId}/shadow/get/accepted`		✔	Legacy topic, same as the preferred `.../get/accepted/trim`. See (1).
`{deviceId}/shadow/get/accepted/tf`		✔	Receive the transformed subset of the device's full shadow (response to `.../get/tf`). See (3).
`{deviceId}/shadow/get/rejected`		✔	Receive information about a rejected shadow request.
`{deviceId}/shadow/get/trim`	✔		Request the device's trimmed shadow, which contains only essential shadow data.
`{deviceId}/shadow/get/tf`	✔		Request a subset of the device's full shadow, defined by a transform. See (2).

Click to expand the following examples.

(1) Trimmed shadow

The trimmed shadow consists of the following elements and their child elements:

desired
  nrfcloud_mqtt_topic_prefix
  pairing
  control
reported
  control
  config

Example response:

{
    "desired": {
      "pairing": {
        "state": "paired",
        "topics": {
          "d2c": "prod/63ae73c3-9918-4b03-a1a8-132174824392/m/d/nrf-352656101397613/d2c",
          "c2d": "prod/63ae73c3-9918-4b03-a1a8-132174824392/m/d/nrf-352656101397613/c2d"
        }
      },
      "nrfcloud_mqtt_topic_prefix": "prod/63ae73c3-9918-4b03-a1a8-132174824392/"
    },
    "reported": {
      "control": {
        "alertsEn": true,
        "logLvl": 3
        },
      "config": {
        "GPS": {
          "enable": false
          }
      }
   }
}

(2) Full shadow

The full shadow consists of the following elements and their child elements. Refer to the shadow schema for full details.

state
  desired
    nrfcloud_mqtt_topic_prefix
    pairing
    config
    control
  reported
    nrfcloud_mqtt_topic_prefix
    pairing
    config
    control
    connection
    device

You can define a limit for the size of the JSON response payload. By default, the limit is 1792 bytes (characters). If the payload to be returned is greater than the limit, an error is returned. No partial payload is returned.

Example request contents follow. Note how quoting must be handled. Spaces and newlines are ignored.

Example 1:

The required 't' property defines the transform string or JSON object.

The optional 'l' property defines the payload size limit (500 bytes in this example):

{'t':'state.reported.device.networkInfo', 'l': 500}

Example 2:

The JSON response contains only the network and device info from the shadow. To minimize the size of the response output, the transform defines that the response JSON elements are named ni instead of state.reported.device.networkInfo, and di instead of state.reported.device.deviceInfo.

{ 't': '{ "ni": state.reported.device.networkInfo, "di": state.reported.device.deviceInfo }' }

For more details, see Transforming JSON responses.

Example 3:

This is not recommended due to the modem's TLS buffer limit of 2 KB. Request only the parts of the shadow your device needs. The default limit of 1792 bytes protects the modem from this buffer limit, allowing for the overhead of TLS messaging. The limit can be overridden by the 'l' property described above.

To receive the full shadow, request:

{'t':'state'}

(3) Transformed shadow response

The following examples are transformed shadow responses, matching the first two examples in (2).

Example 1:

{
  "tf": {
    "currentBand": 12,
    "networkMode": "LTE-M",
    (…etc…)
  }
}

Example 2:

{
  "tf": {
    "ni": {
      "currentBand": 12,
      "networkMode": "LTE-M",
    (…etc…)
    }
    "di": {
      "modemFirmware": "mfw_nrf9160_2.0.0",
      "board": "nrf9160_pca10090",
    (…etc…)
    }
  }
}

If nothing in the shadow matches the given transform, you will get an empty result:

{}

An error in the given transform pattern will return a 40006 error, such as:

{
    "err": 40006,
    "position": 25,
    "message": "Error in Jsonata transform expression: Expected \"}\" before end of expression"
}

If the response payload is larger than the requested or default limit, a 41300 error is returned, such as these examples:

Example 1:

{
    "err": 41300,
    "position": 1324,
    "message": "Response payload size 1324 is larger than the requested limit 1024"
}

Example 2:

{
    "err": 41300,
    "position": 2041,
    "message": "Response payload size 2041 is larger than the default limit 1792"
}

Updating shadow data

Topic	Publish	Subscribe	Purpose
`{deviceId}/shadow/update/delta/trim`		✔	Receive the parts of the `"desired"` state that differ from the `"reported"` state after applying the shadow updates. All other elements of the shadow are trimmed away.
`{deviceId}/shadow/update/delta`		✔	Legacy topic, same as the preferred `.../update/delta/trim`.
`{deviceId}/shadow/update/delta/full`		✔	Receive the parts of the `"desired"` state that differ from the `"reported"` state after applying the shadow updates. The shadow version and metadata timestamps are included.
`{deviceId}/shadow/update`	✔		Update the device shadow.

To publish an update, send a JSON message following the pattern of the following examples (whitespace is ignored):

{ "desired": { "config": { "locationTimeout": 600 } } }

{ "reported": { "connection": { "status": "connected", "keepalive": 2400 } } }

The device is responsible for maintaining and updating the "reported" section. Entities such as nRF Cloud, your own software, or external devices communicate desired changes to the device state by updating the "desired" section. When the device receives a delta with desired changes, it typically updates the "reported" section to match the corresponding "desired" section.

The device can modify the "desired" section if needed. For example, if the device receives a delta event containing an unwanted change, it can reject the change by writing directly to "desired" so that it matches "reported", undoing the desired change.

The returned delta contains only properties from the "desired" state. If a change is made to a property in the "reported" state, and the property does not exist in the "desired" state, a delta message is sent, but the changed property is not included because no such property exists in "desired".

Your application can update the config section of the shadow to store any key-value pairs relevant to your application.

Do not update the control section of the shadow. The nRF Cloud libraries manage the properties of this section, and they should not be changed by your application.

To remove a section of the shadow, set it to null. For example:

{ "reported": { "device": null } }

Message topics

Devices can send and receive messages over MQTT topics. The following sections describe the naming schema and the specific topics using those names.

For MQTT team devices, see the overview of device types for an overview of compatible topics.

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
`c2a`	Cloud-to-portal

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.

The c2a schema allows the nRF Cloud server to pass messages to the portal. The nRF Cloud portal displays only messages it has received on c2a. This includes most d2c, and c2d messages, with the exception of binary data. Binary data includes binary logs and A-GNSS assistance responses.

Expand the following section for more on viewing messages in the nRF Cloud portal.

Viewing messages in the nRF Cloud portal

To view a device's c2d, d2c, and c2a messages in the nRF Cloud portal:

Log in to the nRF Cloud portal.
Select Device Management in the left navigation bar.

A panel opens to the right.
Select Devices.
Click the ID of the desired device to open the device view.
Find the Terminal card.
Either click the vertical three-dot icon in the card header and select the desired topics, or click the arrow icon to expand the card. Expanding the card shows all three topics in separate terminals.

note
Selecting all topics without expanding the terminal card may cause duplicate messages to show in the terminal card. However, these messages are processed only once. Duplicates do not show in downloaded message data.
If the device is connected, the terminal shows the most recent messages for each topic.
If the device is not connected, you can view historical data:
1. Click the clock icon.
2. Select the desired time range from the drop-down menu.
3. Click Get Data.
The terminal now displays data for each topic from the selected time range.

Topics

The following table shows supported message topics.

nRF Cloud accepts and stores all messages sent to any topic prefixed with {mqttTopicPrefix}/m. The {mqttTopicPrefix} is the value of the mqttTopicPrefix JSON field in the response to the FetchAccountInfo endpoint.

Topic	Publish	Subscribe	Purpose
`{mqttTopicPrefix}/m/d/{deviceId}/c2d/r`		✔	Receive messages from nRF Cloud not related to Location Services.
Deprecated ~~`{mqttTopicPrefix}/m/d/{deviceId}/c2d`~~		✔	This topic is deprecated. See `/c2d/r`. ~~Receive messages from nRF Cloud.~~
`{mqttTopicPrefix}/m/d/{deviceId}/d2c`	✔		Publish messages to nRF Cloud.
`{mqttTopicPrefix}/m/d/{deviceId}/d2c/bin`	✔		Publish binary logs to nRF Cloud.
`{mqttTopicPrefix}/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.

Location Services topics

The following tables show topics related to Location Services.

A device can subscribe to the following topics to receive location data from nRF Cloud.

Topic	Purpose
`{mqttTopicPrefix}/m/d/{deviceId}/agnss/r`	Receive A-GNSS data from nRF Cloud.
Deprecated ~~`{mqttTopicPrefix}/m/d/{deviceId}/agps/r`~~	This topic is deprecated. See `/agnss/r`. ~~Receive A-GNSS data from nRF Cloud.~~
`{mqttTopicPrefix}/m/d/{deviceId}/pgps/r`	Receive P-GNSS data from nRF Cloud.
`{mqttTopicPrefix}/m/d/{deviceId}/wifi/r`	Receive Wi-Fi data from nRF Cloud.
`{mqttTopicPrefix}/m/d/{deviceId}/cell_pos/r`	Receive cell data from nRF Cloud.
`{mqttTopicPrefix}/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
`{mqttTopicPrefix}/m/d/{deviceId}/d2c` or `{mqttTopicPrefix}/m/d/{deviceId}/d2c/bulk`	Send the following types of location data to nRF Cloud, based on the app ID in the payload: A-GNSS P-GNSS Wi-Fi Cell Ground fix	Example for A-GNSS and A-GPS Example for P-GNSS and P-GPS Wi-Fi example Cell position example Ground fix example

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.

Topic	Publish	Subscribe	Purpose
`{mqttTopicPrefix}/{deviceId}/jobs/rcv`		✔	Receive a FOTA job execution for an IP-based device.
`{mqttTopicPrefix}/{deviceId}/jobs/req`	✔		Request the current pending job execution for an IP-based device.
`{mqttTopicPrefix}/{deviceId}/jobs/update`	✔		Update the status of a job execution for an IP-based device.

Additional topics supported by nRF Cloud

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

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
`{mqttTopicPrefix}/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 `{mqttTopicPrefix}/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, `{mqttTopicPrefix}/m/sensor/temperature/room2`.
`{mqttTopicPrefix}/a/connections`		✔	Receive connection events from your devices, informing you when they connected and disconnected.

Using tools to access MQTT messages

You can use third-party tools to subscribe or publish to MQTT topics for devices in your team. To do this with MQTT-Explorer, for example:

Create a Connection to simulate a device.
Enter the device's CA server certificate, client certificate, and client private key into the corresponding Certificates fields for that connection.

Note that the default MQTT topics defined by MQTT Explorer for a new connection are "$SYS/#" and "#". Delete these subscriptions for a device connection, as they are outside the allowed set of topics for a device.
Enter your desired subscription topics.

Attempts to subscribe to other MQTT topics will cause the MQTT broker to disconnect the device.

Topics used by devices running the nRF Cloud library​

Shadow topics​

Getting shadow data​

Updating shadow data​

Message topics​

Schemas​

Topics​

Location Services topics​

Subscribe topics (C2D) for Location Services​

Publish topics (D2C) for Location Services​

FOTA topics​

Additional topics supported by nRF Cloud​

Using tools to access MQTT messages​

Topics used by devices running the nRF Cloud library

Shadow topics

Getting shadow data

Updating shadow data

Message topics

Schemas

Topics

Location Services topics

Subscribe topics (C2D) for Location Services

Publish topics (D2C) for Location Services

FOTA topics

Additional topics supported by nRF Cloud

Using tools to access MQTT messages