For each logical subsystem (e.g., motor, sensor, config), choose a distinct shadow name; use the named shadow MQTT topic prefix $aws/things/THING_NAME/shadow/name/SHADOW_NAME for all interactions.
Publish desired state updates by publishing JSON to the /update topic for that named shadow; the device receives the delta on the /update/delta topic containing only properties that differ from reported state.
The device applies the desired change, then publishes back to /update with a reported section reflecting the new actual state to clear the delta.
Use GetThingShadow via the REST API (GET /things/THING_NAME/shadow?name=SHADOW_NAME) or the MQTT /get topic to retrieve full shadow state from cloud services.
List all named shadows for a device with the ListNamedShadowsForThing API to enumerate subsystems without maintaining an external registry.
Classic (unnamed) shadows use the same topic structure without the /name/SHADOW_NAME segment; both types can coexist on the same thing.
Known gotchas
Each individual shadow document (desired + reported combined) is subject to a size limit; check current AWS IoT limits documentation for the exact per-shadow cap.
Delta messages are only published when desired and reported states differ; if the device's reported state already matches desired, no delta is sent after an update.
Shadow version numbers increment on every update; optimistic locking by specifying the current version in the clientToken prevents conflicting concurrent updates.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp