Menu
AWS IoT
Developer Guide

Thing Shadow MQTT Topics

The Thing Shadows service uses reserved MQTT topics to enable applications and things to get, update, or delete the state information for a thing (thing shadow). The names of these topics start with $aws/things/thingName/shadow. Publishing and subscribing on thing shadow topics requires topic-based authorization. AWS IoT reserves the right to add new topics to the existing topic structure. For this reason, we recommend that you avoid wild card subscriptions to shadow topics. For example, avoid subscribing to topic filters like $aws/things/thingName/shadow/# because the number of topics that match this topic filter might increase as AWS IoT introduces new shadow topics. For examples of the messages published on these topics see Thing Shadows Data Flow.

The following are the MQTT topics used for interacting with thing shadows.

/update

Publish a request state document to this topic to update the thing shadow:

Copy
$aws/things/thingName/shadow/update

A client attempting to update the state of a thing would send a JSON request state document like this:

Copy
{ "state" : { "desired" : { "color" : "red", "power" : "on" } } }

A thing updating its thing shadow would send a JSON request state document like this:

Copy
{ "state" : { "reported" : { "color" : "red", "power" : "on" } } }

AWS IoT responds by publishing to either /update/accepted or /update/rejected.

For more information, see Request State Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["iot:Publish"], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/update"] }] }

/update/accepted

AWS IoT publishes a response state document to this topic when it accepts a change for the thing shadow:

Copy
$aws/things/thingName/shadow/update/accepted

For more information, see Response State Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/accepted"] }] }

/update/documents

AWS IoT publishes a state document to this topic whenever an update to the shadow is successfully performed:

Copy
$aws/things/thingName/shadow/update/documents

The JSON document will contain two primary nodes: previous and current. The previous node will contain the contents of the full shadow document before the update was performed while current will contain the full shadow document after the update is successfully applied. When the thing shadow is updated (created) for the first time, the previous node will contain null.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/documents"] }] }

/update/rejected

AWS IoT publishes an error response document to this topic when it rejects a change for the thing shadow:

Copy
$aws/things/thingName/shadow/update/rejected

For more information, see Error Response Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/rejected"] }] }

/update/delta

AWS IoT publishes a response state document to this topic when it accepts a change for the thing shadow and the request state document contains different values for desired and reported states:

Copy
$aws/things/thingName/shadow/update/delta

For more information, see Response State Documents.

Publishing Details

  • A message published on update/delta includes only the desired attributes that differ between the desired and reported sections. It contains all of these attributes, regardless of whether these attributes were contained in the current update message or were already stored in AWS IoT. Attributes that do not differ between the desired and reported sections are not included.

  • If an attribute is in the reported section but has no equivalent in the desired section, it is not included.

  • If an attribute is in the desired section but has no equivalent in the reported section, it is included.

  • If an attribute is deleted from the reported section but still exists in the desired section, it is included.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/update/delta"] }] }

/get

Publish an empty message to this topic to get the thing shadow:

Copy
$aws/things/thingName/shadow/get

AWS IoT responds by publishing to either /get/accepted or /get/rejected.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": ["arn:aws:iot:region:account:topic/$aws/things/thingName/shadow/get"] }] }

/get/accepted

AWS IoT publishes a response state document to this topic when returning the thing shadow:

Copy
$aws/things/thingName/shadow/get/accepted

For more information, see Response State Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/accepted"] }] }

/get/rejected

AWS IoT publishes an error response document to this topic when it can't return the thing shadow:

Copy
$aws/things/thingName/shadow/get/rejected

For more information, see Error Response Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/get/rejected"] }] }

/delete

To delete a thing shadow, publish an empty message to the delete topic:

Copy
$aws/things/thingName/shadow/delete

The content of the message is ignored.

AWS IoT responds by publishing to either /delete/accepted or /delete/rejected.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topic filter/$aws/things/thingName/shadow/delete"] }] }

/delete/accepted

AWS IoT publishes a message to this topic when a thing shadow is deleted:

Copy
$aws/things/thingName/shadow/delete/accepted

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/accepted"] }] }

/delete/rejected

AWS IoT publishes an error response document to this topic when it can't delete the thing shadow:

Copy
$aws/things/thingName/shadow/delete/rejected

For more information, see Error Response Documents.

Example Policy

The following is an example of the required policy:

Copy
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iot:Subscribe", "iot:Receive" ], "Resource": ["arn:aws:iot:region:account:topicfilter/$aws/things/thingName/shadow/delete/rejected"] }] }