Controlling Home Appliances with AWS IoT Device Shadow: A Hands-on

Synchronizing desired, reported and delta, and design lessons from a real infinite-loop accident

Published

October 18, 2026

Introduction

English version — machine-assisted translation (by generative AI, Anthropic Claude) of the original Japanese hands-on. 日本語版はこちら.

You say “Alexa, turn on the light”, and via the cloud an infrared remote control at home (an ESP32) sends a signal to the light —— at the heart of this mechanism is AWS IoT Core’s Device Shadow.

The Shadow combines the cloud’s “please make it like this” (desired) and the device’s “this is how it is now” (reported) into a single JSON document, and delivers the discrepancy between them (delta) to the device. It is convenient, but if you do not correctly understand “when, and with what contents” a delta is delivered, accidents like these happen:

  • the second command never arrives at all
  • a single operation makes the light keep turning on and off (an infinite loop)

This hands-on is based on accidents the author actually caused when making a home-made infrared remote control work with Alexa.

ImportantAll behaviour described here has been measured

The Shadow behaviour described in this material (the conditions under which a delta is delivered, how the infinite loop arises, etc.) was confirmed by experiments on AWS IoT Core (Tokyo region). The simulator that runs in the browser was also built to match those experimental results, and is checked against them by tests.

Goals of this hands-on

  1. Explain the relationship between desired, reported, delta and version in a Device Shadow
  2. Interact with AWS IoT Core without real hardware, using Python on your PC as a virtual device
  3. Explain why “the same value does not arrive”, “infinite loops”, “partial updates”, “missed messages” and “double execution” happen, and design to prevent them
  4. Learn a safe verification procedure before trying changes on the production device, and how to perform an emergency stop

What we will build

flowchart LR
  A["send.py<br>(stands in for Alexa's Lambda)"] -- "update desired" --> S[("Device Shadow<br>AWS IoT Core")]
  S -- "deliver delta (MQTT)" --> D["virtual_device.py<br>(pretends to be the IR remote)"]
  D -- "update reported" --> S

You do not need a real ESP32 or appliances. A Python program running on your PC pretends to be the “infrared remote control” and operates a light (slot 5, a toggle type that switches between on and off each time it is pressed) and an air conditioner. The key points of the ESP32 implementation and the mechanism for operating it from Alexa are explained in Chapters 7 and 8.

Intended audience

  • People interested in how IoT devices connect to the cloud (easier to follow if you have built something with an ESP32, Raspberry Pi, etc.)
  • People who can run commands in a terminal and read Python code
  • People who have (or can create) an AWS account

What you need

  • An AWS account and AWS CLI v2 (in a state where aws sts get-caller-identity succeeds)
  • Python 3.10 or later
  • The ability to open three terminals (device, monitor, operator)
NoteAbout cost

Only AWS IoT Core messaging and Device Shadow are used, and within the scope of this hands-on (hundreds to thousands of messages) the cost is negligible. At the end, delete everything you created using the procedure in Chapter 2.

Sample code

Download and extract code.zip. It contains the following.

code/
├── requirements.txt          paho-mqtt (MQTT) and boto3 (AWS SDK)
├── setup/create_thing.sh     creates the Thing, certificate and policy
├── setup/cleanup.sh          deletes everything that was created
├── device/virtual_device.py  virtual device (--bug reproduces the accidents)
└── device/send.py            operates the Shadow from the cloud side

Chapter structure

Chapter Contents
1 What is a Device Shadow? — desired, reported, delta, version
2 AWS setup — Thing, certificate and a least-privilege policy
3 Running the virtual device
4 Pitfall 1: the same value does not arrive
5 Pitfall 2: infinite loops — a safe verification procedure and emergency stop
6 Pitfall 3: partial updates, missed messages and double execution
7 On to a real ESP32 (explanation)
8 Operating from the cloud: Lambda and Alexa (explanation)
9 Design checklist and review questions

Chapters 1, 4, 5 and 6 include a Shadow simulator that runs in the browser. Even without an AWS account, you can experience the pitfalls with the simulator alone.