Retaining device state while the device is offline with Device Shadows

These tutorials show you how to use the AWS IoT Device Shadow service to store and update the state information of a device. The Shadow document, which is a JSON document, shows the change in the device's state based on the messages published by a device, local app, or service. In this tutorial, the Shadow document shows the change in the color of a light bulb. These tutorials also show how the shadow stores this information even when the device is disconnected from the internet, and passes the latest state information back to the device when it comes back online and requests this information.

We recommend that you try these tutorials in the order they're shown here, starting with the AWS IoT resources you need to create and the necessary hardware setup, which also helps you learn the concepts incrementally. These tutorials show how to configure and connect a Raspberry Pi device for use with AWS IoT. If you don't have the required hardware, you can follow these tutorials by adapting them to a device of your choice or by creating a virtual device with Amazon EC2.

Tutorial scenario overview

The scenario for these tutorials is a local app or service that changes the color of a light bulb and that publishes its data to reserved shadow topics. These tutorials are similar to the Device Shadow functionality described in the interactive getting started tutorial and are implemented on a Raspberry Pi device. The tutorials in this section focus on a single, classic shadow while showing how you might accommodate named shadows or multiple devices.

The following tutorials will help you learn how to use the AWS IoT Device Shadow service.

AWS IoT Device Shadow overview

A Device Shadow is a persistent, virtual representation of a device that is managed by a thing resource you create in the AWS IoT registry. The Shadow document is a JSON or a JavaScript notation doc that is used to store and retrieve the current state information for a device. You can use the shadow to get and set the state of a device over MQTT topics or HTTP REST APIs, regardless of whether the device is connected to the internet.

A Shadow document contains a state property that describes these aspects of the device's state.

Here is an example of a Shadow state document.

{
  "state": {
    "desired": {
      "color": "green"
      },
    "reported": {
      "color": "blue"
      },
    "delta": {
      "color": "green"
      }
   }
}

To update a device's Shadow document, you can use the reserved MQTT topics, the Device Shadow REST APIs that support the GET, UPDATE, and DELETE operations with HTTP, and the AWS IoT CLI.

In the previous example, say you want to change the desired color to yellow. To do this, send a request to the UpdateThingShadow API or publish a message to the Update topic, $aws/things/THING_NAME/shadow/update.

{
  "state": {
    "desired": {
      "color": yellow
    }
  }
} 

Updates affect only the fields specified in the request. After successfully updating the Device Shadow, AWS IoT publishes the new desired state to the delta topic, $aws/things/THING_NAME/shadow/delta. The Shadow document in this case looks like this:

{
  "state": {
    "desired": {
      "color": yellow
    },
    "reported": {
      "color": green
    },
    "delta": {
      "color": yellow
      }
  }
} 

The new state is then reported to the AWS IoT Device Shadow using the Update topic $aws/things/THING_NAME/shadow/update with the following JSON message:

{
  "state": {
    "reported": {
      "color": yellow
    }
  }
} 

If you want to get the current state information, send a request to the GetThingShadow API or publish an MQTT message to the Get topic, $aws/things/THING_NAME/shadow/get.

For more information about using the Device Shadow service, see AWS IoT Device Shadow service.

For more information about using Device Shadows in devices, apps, and services, see Using shadows in devices and Using shadows in apps and services.

For information about interacting with AWS IoT shadows, see Interacting with shadows.

For information about the MQTT reserved topics and HTTP REST APIs, see Device Shadow MQTT topics and Device Shadow REST API.