Difference between AWS IoT shadow file desired and reported fields

Question

I'm looking at the AWS IoT documentation for shadow states and trying to better understand the use of desired and reported in the shadow file.

The documentation states:

When the shadow's state changes, AWS IoT sends /delta messages to all MQTT subscribers with the difference between the desired and the reported states.

After looking through the rest of the documentation I don't feel like I have a clear grasp of the use case for desired vs reported. Can someone explain the use case? When do we use one vs. the other?

marco.santonocito marco.santonocito · Accepted Answer · 2021-01-25T09:13:11

Let's start from the beginning, a device shadow is a persistent virtual shadow of a Thing defined in AWS IoT Registry. Basically, it’s a JSON State Document that is used to store and retrieve current state information for a Thing. You can interact with a Device Shadow using MQTT Topics or REST API calls. The main advantage of Shadows is that you can interact with it, regardless of whether the thing is connected to the Internet or not.

A shadow’s document contains a state property that describes aspects of the device’s state:

{
  "state": {
    "desired": {
      "color": "RED"
    },
    "reported": {
      "color": "GREEN"
    },
    "delta": {
      "color": "RED"
    }
  }
}

Here's a description of each state:

Apps specify the desired states of device properties by updating the desired object.
Devices report their current state in the reported object.
AWS IoT reports differences between the desired and the reported state in the delta object.

Every shadow has a reserved MQTT Topic and HTTP URL that supports the get, update, and delete actions on the shadow. Let's take a look:

$aws/things/THING_NAME/shadow/update: publish to this Topic to update/create the Thing Shadow;
$aws/things/THING_NAME/shadow/update/accepted: AWS IoT publishes reported or desired portion of the State Document to this Topic, on accepting the update request;
$aws/things/THING_NAME/shadow/update/rejected: AWS IoT publishes an Error Message to this Topic when it rejects update request;
$aws/things/THING_NAME/shadow/update/documents: AWS IoT publishes a State Document with Previous and Current State information to this topic whenever an update to the shadow is successfully performed;
$aws/things/THING_NAME/shadow/update/delta: AWS IoT publishes a response Delta 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.

Here's an example. Let's say that we have an air purifier and we want to change the fan speed. The flow will be the following:

User changes the fan speed from the air purifier mobile application
The mobile application publishes the following JSON message to this MQTT topic: $aws/things/THING_NAME/shadow/update to update the device shadow with a new desired state: "fanSpeed": 50. It will look like this:

{
  "state": {
    "desired": {
      "fanSpeed": 50
    }
  }
}

On successful shadow update, if the previous reported state is different from "fanSpeed": 50, AWS IoT will publish desired state to delta topic $aws/things/THING_NAME/shadow/update/delta.
The shadow state document may look like this:

{
  "state": {
    "desired": {
      "fanSpeed": 50
    },
    "reported": {
      "fanSpeed": 100
    },
    "delta": {
      "fanSpeed": 50
    }
  }
}

The device (our air purifier) that is subscribed to delta topic will perform the requested operation (set fan speed to 50 in this case), and report back the new state to AWS IoT Device Shadow, using Update Topic $aws/things/THING_NAME/shadow/update with following JSON message:

{
  "state": {
    "reported": {
      "fanSpeed": 50
    }
  }
}

Now our air purifier has a fan speed of 50... and that's how it works ;)

Difference between AWS IoT shadow file desired and reported fields

1 Answers