9 Design Checklist and Review Questions
9.1 Design checklist for Shadow synchronization
Things to check when using a Shadow (or a similar mechanism that delivers the difference between desired and reported).
| # | What to check | Chapter |
|---|---|---|
| 1 | Is the policy restricted to only that Thing’s Shadow topics? Have you avoided committing the private key? | 2 |
| 2 | Have you split commands into the command type (execute every time) and the state type (put it in that state)? | 4 |
| 3 | For the command type, did you put an element that changes every time into the value itself ("5-<time>")? |
4 |
| 4 | For the state type, did you add a cmdId that changes every time so that the same state can be resent? | 4 |
| 5 | Do you write the processed value back to reported with the same value and the same type? Are you avoiding clearing it with null? |
5 |
| 6 | Did you combine write-backs of multiple fields into a single publish? | 5 |
| 7 | Can desired values the device cannot achieve (out-of-range temperatures, etc.) be left lingering? | 5 |
| 8 | Are you avoiding filling fields that were not in the delta with default values (overwrite the current state instead)? | 6 |
| 9 | Do you get right after connecting to pick up deltas from while disconnected? | 6 |
| 10 | Even if the same delta arrives twice, do you execute it only once (idempotent)? | 6 |
| 11 | Before the production device, did you send once and monitor version? Have you prepared an emergency stop procedure (desired to null)? | 5 |
9.2 Review questions
With desired {"power": true} and reported {"power": true}, the cloud writes {"power": true} to desired once more. What happens to version and delta?
version increases by 1, but no delta is produced (nothing reaches the device). This is because fields with the same value are not included in the delta (Chapter 4). To resend, send a cmdId that changes every time along with it.
While {"sendSlot": "5-100"} remains in desired, the device writes a temperature sensor value to reported every minute. What happens?
Every time the temperature sensor value is written, the delta {"sendSlot": "5-100"} is redelivered. Even for updates to unrelated fields, the entire delta is delivered while a discrepancy remains (Chapter 5, measured). If the device has no duplicate check, the light toggles every minute. The countermeasures are to write sendSlot back correctly to clear the discrepancy, and to add a duplicate check.
The device wrote {"cmdId": 1791382616543} back to reported. The cmdId in desired is "1791382616543". What happens?
A number and a string are different values, so the discrepancy remains and the delta is redelivered after every write-back, causing an infinite loop (measured: 8 times in 0.4 seconds). Write back with the same type as desired (a string) (Chapter 5).
While the air conditioner is “ON, cooling, 24℃”, the delta {"temp": 26} arrives. What should the device send?
“ON, cooling, 26℃”. A delta contains only the fields that changed, so overwrite only temp onto the current state. Filling power with a default value (false) would turn the power off (Chapter 6).
After flashing modified firmware, the light keeps turning on and off. What is the first thing to do?
Set desired to null ({"state": {"desired": null}}; in this hands-on, send.py stop). The delta disappears, and it can be stopped from the cloud side regardless of the device code. Even if you unplug and reboot the device, if desired remains, it will receive the same delta via the get right after connecting (Chapter 5).
The device has recovered from a Wi-Fi disconnection. If someone said “Alexa, turn on the air conditioner” while it was disconnected, what should it do to execute that command?
Send get right after connecting and process state.delta in the response. With a clean-session MQTT connection, deltas delivered while disconnected do not arrive. A persistent session (QoS 1) retains them for a certain time, but get is reliable regardless of settings (Chapter 6).
9.3 Cleaning up
Delete the AWS resources created in the hands-on (Chapter 2).
python device/send.py stop # clear desired, just in case
bash setup/cleanup.sh # delete the Shadow, certificate, policy and Thing9.4 Closing
The Device Shadow mechanism itself is simple, but from a single rule —— “while a discrepancy remains, the delta is delivered after any update” —— accidents arise: commands that do not arrive, loops that do not stop, actions that happen twice.
- Split commands into the command type and the state type, and mix in values that change every time
- Write back with the same value, the same type, in a single publish, leaving no discrepancy
- Prepare for both non-arrival (missed messages) and double arrival (duplicates)
- Before the production device, send once and watch version. To stop, set desired to null
Check your own device against this checklist too, and then try asking your family to say “Alexa, turn on the light”.