Device Shadow

A device shadow is a JSON document that stores the state of an nRF Cloud-connected device. It lets the device and the cloud exchange state even when they are not connected at the same time.

A shadow has three main sections:

• reported: The state last reported by the device.
• desired: The state requested for the device.
• delta: The desired values that differ from the reported values.

For example, you can set a desired reporting interval while a device is offline. When the device reconnects, it reads the change, applies it, and reports the new value. The value is removed from delta when the desired and reported values match.

Before you begin

Device Shadow is available for devices connected to nRF Cloud. The device must be onboarded into your nRF Cloud organization and project.

Your project role determines what you can do:

Permission	Default project roles	Access
device:read	Project Reader, Project Member, Project Manager, Organization Administrator	View and refresh the shadow
device:write	Project Member, Project Manager, Organization Administrator	Change and save desired values

Custom roles can grant or remove these permissions.

View a device shadow

1. Open Fleet → Devices.
2. Select a device.
3. Select the Device Shadow tab.

The Device Config table shows the configurable shadow settings:

• Reported is the latest value reported by the device.
• Desired is the value that nRF Cloud asks the device to apply.
• not set in the Desired column means that the setting has no desired value.
• Sync status shows pending when the desired and reported values differ.
• Last reported shows when the device last reported the setting.

Nested settings use dotted names. For example, control.logLvl represents logLvl inside the control object.

Click Refresh to retrieve the latest shadow. Refreshing does not discard changes that you have entered but not saved.

View the shadow JSON

The Device Shadow JSON card shows the complete desired, reported, and delta sections, including platform-managed settings that are not shown in the Device Config table. Click Copy JSON to copy these sections.

The JSON view does not include shadow metadata, constraints, or the shadow version. Use the REST API to retrieve those fields.

Change device configuration

To update one or more settings:

1. Change the values in the Desired column.
2. Resolve any validation errors. The expected value type is defined by the shadow constraints or inferred from the existing desired or reported value.
3. Click Save changes.

nRF Cloud merges only the changed settings into the existing desired state. Unchanged settings are not replaced.

Delete a desired value

To stop requesting a value for a setting:

1. Click the trash icon next to its desired value.
2. Click Save changes.

After the update succeeds, the Desired column displays not set. Deleting a desired value does not delete or change the value last reported by the device.

The Sync status displays pending until the device reports the requested value. How quickly this happens depends on when the device connects and processes shadow updates.

Click Cancel before saving to discard all changes made in the table. If a save fails, the changes remain in the table so that you can correct or retry them.

note

Platform-managed, read-only desired settings do not appear in the Device Config table. They remain visible in Device Shadow JSON. See Platform-controlled and typed state for the complete list.

Platform-controlled and typed state

nRF Cloud applies the following constraints to shadow updates:

Path	desired	reported	Value type
pairing	Read-only	Read-only	Any
nrfcloud_mqtt_topic_prefix	Read-only	Read-only	Any
connection	Read-only	Read-only	Any
device	Read-only	Writable	Any
control.alertsEn	Writable	Writable	Boolean
control.logLvl	Writable	Writable	Integer

A read-only constraint applies to the path and its nested values. Paths not listed in the table are not restricted by these platform constraints.

The web app omits read-only desired paths from the Device Config table. The REST API rejects updates to read-only paths unless the request explicitly uses force=true; value types are still enforced when forcing an update.

Work with Device Shadow through the REST API

The Device Shadow REST API uses an organization auth token (OAT) and organization- and project-scoped URLs. When creating the OAT, include the project that contains the device and select one of these Device Data access levels:

• Read to retrieve state. This grants device:read.
• Manage to retrieve and update state. This grants device:read and device:write.

Full Access also permits both operations but grants additional permissions that Device Shadow does not require.

Send Device Shadow requests to https://api.nrfcloud.com.

Retrieve a shadow

curl \
  "https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT/long-range/devices/$DEVICE_ID/state" \
  -H "Authorization: Bearer $NRFCLOUD_OAT"

The response contains reported, desired, delta, metadata, and version. For response details and JSONata transformations, see Retrieve the State of an nRF9x Device.

Update a shadow

Send a partial update containing the desired or reported values to change:

curl -X PATCH \
  "https://api.nrfcloud.com/v1/organizations/$NRFCLOUD_ORG/projects/$NRFCLOUD_PROJECT/long-range/devices/$DEVICE_ID/state" \
  -H "Authorization: Bearer $NRFCLOUD_OAT" \
  -H "Content-Type: application/json" \
  -d '{
    "desired": {
      "config": {
        "sampleInterval": 30
      }
    }
  }'

The API merges the patch into the existing state. Setting a key to null deletes it. The request is rejected if it violates a device state constraint. For writable paths, validation rules, and the force option, see Update the State of an nRF9x Device.

Work with Device Shadow from a device

Device-side shadow behavior does not change when you begin using the new web app. Devices continue to use their existing credentials and protocols:

• For MQTT shadow retrieval, updates, and delta notifications, see MQTT shadow topics.
• For CoAP state retrieval and updates, see CoAP state endpoints.
• For nRF Connect SDK integration, see the nRF Cloud CoAP library.

Troubleshooting

Symptom	Likely cause	Fix
The Device Shadow tab is not visible	The selected device is not connected to nRF Cloud	Confirm that you opened the nRF Cloud device in the organization where it was onboarded
Existing state is missing	You opened a different organization, project, or device	Compare the organization, project, and device ID with the expected device
Settings are visible but cannot be edited	Your role has device:read but not device:write	Ask an administrator to grant a role with device write access
A setting is absent from Device Config	The setting is platform-managed and read-only	Find it in Device Shadow JSON, or retrieve the complete shadow with the REST API
A setting remains pending	The device has not received, applied, or reported the desired value	Check device connectivity and its shadow-processing logic, then click Refresh
Save changes is disabled	One or more edited values are invalid	Correct the values identified by the validation messages
The REST API returns 401	The OAT is missing, invalid, or incorrectly formatted	Recopy the OAT and use Authorization: Bearer <OAT>
The REST API returns 403	The OAT lacks access to the project or the required Device Data access level	Include the project and select Read to retrieve state or Manage to update it
The REST API returns 404	A slug or device ID is wrong, or the URL uses the legacy shape	Verify all path values and use the organization- and project-scoped long-range endpoint
The REST API returns 422	A value has the wrong type or the request changes a constrained path	Review the response and the update API constraints, then correct the patch

If the same device shows different state in the legacy and new experiences, contact Nordic Semiconductor support on the DevZone community forum.