Devices Managment Shadow

Device Shadow workflow

AWS IoT use a Thing's Shadow concept to report and react on state changes.

The Shadow Document is a representation of device state in the cloud, when a service like Eliot interact with your device will operate to the Shadow copy of the state, not directly on the device. This guarantee that device is always online and its state can be queried and changed even if the physical device is offline.

Shadow Document

This is an example of Shadow Document

{
  "state" : {
    "desired" : {
      "on": true
    },
    "reported" : {
      "on": false
    }
  },
  "metadata" : {
    "desired" : {
      "on": {
        "timestamp" : 12345
      }
    },
    "reported" : {
      "on": {
        "timestamp" : 12345
      }
    }
  },
  "version" : 10,
  "clientToken" : "xxxxxxxxxxxxxxxxxxxxxx",
  "timestamp": 123456789
}

state.reported is the actual state of the Thing, Eliot will query this property to know if the device is on, what's the current temperature, the current light brightness level and so on.

state.desired is the desired state of the Thing, this section of the document is update by Eliot when a state change is request from Google Home or Alexa.

metadata contain the timestamp of property changes.

timestamp indicates when the message was transmitted by AWS IoT

clientToken is unique token to associate request and response in an MQTT environment.

version is the Shadow Document version, every time the document change this number will be incremented.

Change workflow

Your device will be mapped with a remote Thing, in order to connect you need a private key, a client certificate and the root CA certificate, follow the AWS guide. Use the Thing's attached certificate and the IoT Registry host to connect your device.

Report state

Once connected can report its state to the Registry in this way:

{
  "state" : {
    "reported" : {
      "on": false
    }
  }
}

Desired changes

When a state property change is asked by Google Home or Alexa, Eliot will update the desired part of state. For example if you ask "Hey Google, switch on the Led" the Shadow Document will be update in this way:

{
  "state" : {
    "desired" : {
      "on": true
    },
    "reported" : {
      "on": false
    }
  }
}

This change will raise an event into Topic $aws/things/Led/shadow/update/accepted, since there is a differed from desired and reported and other event will be sent into $aws/things/Led/shadow/update/delta.

React to state delta

Your device should listen for event from $aws/things/Led/shadow/update/delta

{
  "delta": {
    "on": true
  }
}

Then made the request changes (in this example give power to a led and switch it on) and change the reported state:

{
  "state" : {
    "reported" : {
      "on": true
    }
  }
}