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