Device shadow
When a device goes offline, applications lose visibility into its state. Device shadow stores the last-known device state in the cloud so applications can read or update it at any time — and syncs the desired state back to the device automatically when it reconnects. If you use the Premium Edition, consider the Thing Specification Language (TSL) model instead for richer modeling capabilities.
How device shadow works
A device shadow is a JSON document that stores the state reported by a device and the desired state set by an application.
Each device has exactly one shadow. It acts as a persistent broker between the device and your application:
The device reads and writes the shadow over MQTT to report its current state or receive a desired state.
Applications use the IoT Platform software development kit (SDK) to read the shadow or push a desired state without needing a direct connection to the device.
SDK usage
Version requirements
Aliyun IoT Python SDK version 1.1.0 or later
Update the shadow
Call thing_update_shadow to report the device's current state to the cloud.
reported = {"color": "red"}
# reported - The shadow data to report.
# version - The version number of the shadow data. In this example, the version is 1.
res = linkkit.thing_update_shadow(reported, 1)
if res == 0:
print('success')This call is asynchronous — it returns an rc value immediately and delivers the final result through the on_thing_shadow_get callback. An rc value of 0 means the request was sent successfully.
Register the callback before calling any shadow method:
linkkit.on_thing_shadow_get = on_thing_shadow_get
...
def on_thing_shadow_get(self, payload, userdata):
print("on_thing_shadow_get:", payload)When the update succeeds, the callback delivers:
{
"method": "reply",
"payload": {
"status": "success",
"version": 1
},
"timestamp": 1544686266
}Query shadow data
Call thing_get_shadow to fetch the latest shadow from the cloud.
res = linkkit.thing_get_shadow()
if res == 0:
print('success')This call is asynchronous. An rc value of 0 confirms the request was submitted; the shadow data arrives in the on_thing_shadow_get callback.
Register the callback to receive the query result:
linkkit.on_thing_shadow_get = on_thing_shadow_get
...
def on_thing_shadow_get(self, payload, userdata):
print("on_thing_shadow_get:", payload)When the query succeeds, the on_thing_shadow_get callback delivers:
{
"method": "reply",
"payload": {
"status": "success",
"state": {
"reported": {
"color": "red"
}
},
"metadata": {
"reported": {
"color": {
"timestamp": 1544701176
}
}
}
},
"timestamp": 1544784614,
"version": 1
}The SDK also caches a local copy of the shadow from the /shadow/get/{pk}/{dn} topic. Call local_get_latest_shadow to read it without a network round-trip.
Listen for shadow changes
When an application sets a desired state in the cloud, IoT Platform pushes the change to the device through the shadow.
Register the
on_thing_shadow_getcallback to receive desired-state changes.The result is delivered asynchronously. Set the
on_thing_shadow_getcallback function — it handles update, query, and desired-state push.
linkkit.on_thing_shadow_get = on_thing_shadow_get
...
def on_thing_shadow_get(self, payload, userdata):
print("on_thing_shadow_get:", payload)When a desired-state change arrives, the on_thing_shadow_get callback payload includes both the reported and desired states so you can compute the delta:
{
"method": "control",
"payload": {
"status": "success",
"state": {
"reported": {
"color": "red"
},
"desired": {
"color": "green"
}
},
"metadata": {
"reported": {
"color": {
"timestamp": 1544701176
}
},
"desired": {
"color": {
"timestamp": 1544702121
}
}
}
},
"timestamp": 1544702121,
"version": 3
}