Using the device shadow

This page explains operations with the device shadow.

Getting a device shadow

This section explains how to get data from the device shadow using REST or MQTT.

Through the REST APIThrough the MQTT API

You can retrieve a device shadow by calling the FetchDevice or ListDevices endpoints. If using ListDevices, set the includeState parameter to true.

A device can retrieve its own shadow by publishing any message to the /shadow/get topic. See the MQTT API for more information.

Updating a device shadow

This section explains how to update the device shadow.

Through the REST APIThrough the MQTT API

You can update a device shadow through the UpdateDeviceState endpoint.

Devices can retrieve their own shadows by publishing to the /shadow/update topic. See more about shadow topics in the MQTT API documentation.

Example: enabling FOTA

If you want to enable the nRF Cloud firmware over-the-air (FOTA) update service, you must configure your device for FOTA. For a non-gateway device, this means the device must contain a reported.device.serviceInfo.fota_v2 array in its shadow, for example:

  ...
  "reported": {
      "device": {
        "serviceInfo": {
          "fota_v2": [
            "APP",
            "MODEM",
            "BOOT"
          ]
        }
      }
    }

Gateway devices that support Bluetooth® Low Energy (LE) FOTA must also set a fota_v2_ble flag. This example snippet from a gateway shadow shows that it supports APP and MODEM (but not BOOT) FOTA for itself, as well as Bluetooth LE FOTA for its connected peripherals:

  ...
  "reported": {
      "device": {
        "serviceInfo": {
          "fota_v2": [
            "APP",
            "MODEM"
          ],
          "fota_v2_ble": true
        },
      }
    }

See the REST preparations section of the FOTA documentation for REST API instructions.

To do this over MQTT, send the following message to the /shadow/update topic (include the state field):

{
  "state": {
    "reported": {
      "device": {
        "serviceInfo": {
          "fota_v2": [
            "APP",
            "MODEM",
            "BOOT"
          ]
        }
      }
    }
  }
}