Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using shadows in devices

This section describes device communications with shadows using MQTT messages, the preferred method for devices to communicate with the Amazon IoT Device Shadow service.

Shadow communications emulate a request/response model using the publish/subscribe communication model of MQTT. Every shadow action consists of a request topic, a successful response topic (accepted), and an error response topic (rejected).

If you want apps and services to be able to determine whether a device is connected, see Detecting a device is connected.

The examples in this section use an abbreviated form of the topic where the ShadowTopicPrefix can refer to either a named or an unnamed shadow, as described in this table.

Shadows can be named or unnamed (classic). The topics used by each differ only in the topic prefix. This table shows the topic prefix used by each shadow type.

To create a complete topic, select the ShadowTopicPrefix for the type of shadow to which you want to refer, replace thingName, and shadowName if applicable, with their corresponding values, and then append that with the topic stub as shown in the following table. Remember that topics are case sensitive.

See Shadow topics for more information about the reserved topics for shadows.

Initializing the device on first connection to Amazon IoT

After a device registers with Amazon IoT, it should subscribe to these MQTT messages for the shadows that it supports.

After subscribing to the messages in the preceding table for each shadow, the device should test to see if the shadows that it supports have already been created by publishing a /get topic to each shadow. If a /get/accepted message is received, the message body contains the shadow document, which the device can use to initialize its state. If a /get/rejected message is received, the shadow should be created by publishing an /update message with the current device state.

For example, suppose you have a thing My_IoT_Thing which doesn't have any classic or named shadows. If you now publish a /get request on the reserved topic $aws/things/My_IoT_Thing/shadow/get, it returns an error on the $aws/things/My_IoT_Thing/shadow/get/rejected topic because the thing doesn't have any shadows. To resolve this error, first publish an /update message by using the $aws/things/My_IoT_Thing/shadow/update topic with the current device state such as the following payload.

{
	"state": {
		"reported": {
			"welcome": "aws-iot",
			"color": "yellow"
		}
	}
}

A classic shadow is now created for the thing and the message is published to the $aws/things/My_IoT_Thing/shadow/update/accepted topic. If you publish to the topic $aws/things/My_IoT_Thing/shadow/get, it returns a response to the $aws/things/My_IoT_Thing/shadow/get/accepted topic with the device state.

For named shadows, you must first create the named shadow or publish an update with the shadow name before using the get request. For example, to create a named shadow namedShadow1, first publish the device state information to the topic $aws/things/My_IoT_Thing/shadow/name/namedShadow1/update. To retrieve the state information, use the /get request for the named shadow, $aws/things/My_IoT_Thing/shadow/name/namedShadow1/get.

Processing messages while the device is connected to Amazon IoT

While a device is connected to Amazon IoT, it can receive /update/delta messages and should keep the device state matched to the changes in its shadows by:

While a device is connected, it should publish these messages when indicated.

Processing messages when the device reconnects to Amazon IoT

When a device with one or more shadows connects to Amazon IoT, it should synchronize its state with that of all the shadows that it supports by: