Skip to content

Device shadow

A device shadow or digital twin refers to a JSON document in nRF Cloud. It contains the state of the device. It enables you to set the desired state, see the device's reported state, and add metadata for the device. Device shadows apply only to IP devices.

Configuring a device

See more about device shadows in the AWS documentation.

Configuring a device

It is recommended to interact with devices through their shadows instead of sending them messages directly. MQTT devices can subscribe to the /shadow/update/delta topics and CoAP/HTTP devices can request the delta. A device can also be programmed to retrieve its shadow when it comes back online. This removes any concerns about a device being offline when you want to change its state.

You might, for example, want to change your device's configuration to send temperature sensor readings more frequently. Instead of publishing a message directly to the device, you can update the device's configuration in the shadow. The device sees the change, updates its message frequency, and reports back to nRF Cloud.

Configuring a device

Shadow schemas

nRF Cloud defines a shadow schema for nRF Cloud services and device interaction. A device's shadow must follow the definitions of the fields defined in the schema. All fields marked as "required" in the schema must always be present. The schema does not restrict additions to the "reported" and "desired" sections. You can add your own fields there, to define your own models for application communication. Device shadow schema definitions can be found in the JSON schema.

Nordic devices have a TLS buffer limit of 2 KB in the modem, so the effective maximum size of a device shadow is 2 KB.

Getting a device shadow

This section explains how to get data from the device shadow.

Through CoAP

The nRF Connect SDK provides integrated libraries for shadow interactions. See the nRF Cloud CoAP library on how to get and update a shadow for a CoAP-connected device.

Through the REST API

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

Alternatively, the nRF Connect SDK provides integrated libraries for shadow interactions. See the nRF Cloud REST library on how to get and update a shadow for a device using the REST API.

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 a 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:

curl -X PATCH https://api.nrfcloud.com/v1/devices/[device-id]/state \
-H "Authorization: Bearer [API-Key]" \
-H "Content-Type: application/json" \
-d '{ "desired": { "msg":"[message content]" }}'

Through the MQTT API

Devices can update 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"
          ]
        }
      }
    }
  }
}