Using the device shadow

This page explains operations with the device shadow.

Using the device shadow in the nRF Cloud portal

This section explains device shadow management operations available through the nRF Cloud portal. You can view the full shadow in the portal, but the only section you can edit through the portal is config.

Viewing the full shadow

To view the device shadow in the nRF Cloud portal:

1. Log in to the nRF Cloud portal.

2. Select Device Management from the left sidebar.

   A panel opens to the right.

3. Select Devices.

4. Click the ID of the desired device.

   The device view opens.

5. Click the Shadow tab under the Device Information card. This is the full device shadow, with "reported" and "desired" sections.

Viewing and editing the device config

To edit the config section of the device shadow in the nRF Cloud portal:

To view the device config section:

1. Click View Config button in the page header.

   A pop-up opens.

2. See the Reported section for the current device config.

To edit the existing config:

1. Click View Config in the page header.

   A pop-up opens.

2. Click Edit Configuration. The field is empty by default.

3. Click Copy Reported to import and edit the existing configuration.

4. Specify the desired configuration. See Shadow schemas for more information on accepted formatting.

5. Click Commit.

The Desired section shows your changes. The Reported section updates once the device is online and updates its configuration.

Getting the device shadow

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

Through the REST API

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

Through the MQTT API

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

Updating the device shadow

This section explains how to update the device shadow.

Through the REST API

You can update a device shadow through the UpdateDeviceState endpoint.

Through the MQTT API

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. 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"
          ]
        }
      }
    }

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"]
        }
      }
    }
  }
}