Communicating with the Device Shadow

BioT uses named shadows to communicate security with the device.
This article will go over the basic communication sequence.

What is a Device Shadow

You can think of a device shadow as a persistent data store (text file) in the cloud that mirrors the state of a physical device. This file stores the current state and configuration of the device. BioT updates the shadow, and the device is automatically notified when changes are made.

Why use a Shadow

While BioT can directly send messages to devices, there are situations where this isn't ideal. For instance, the device might be offline. In these cases where BioT would like the device to get the message when the device gets back online, the device shadow comes in.

Working with Device Shadow

During normal operation while a device is connected, or when it reconnects to BioT after disconnection, it can receive /update/delta messages and should keep the device state matched with the changes in its states by:

• Reading all /update/delta messages received and synchronizing the device state to match.
• Publishing an /update message with a reported message body that has the device’s current state, whenever the device's state changes.

The following is an example showing how to update the configuration of a device:

The device state at the beginning is:

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

BioT “wants” to change the device color to yellow, so it will publish an update to the device’s state:

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

The new state will become:

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

📘

Note

The clientId in the following topics is configured in the device during the activation stage. See Direct IoT Device Integration

BioT publishes the new desired state to the delta topic:

$aws/things/<clientId>/shadow/name/configuration/delta

The device updates its own state and when finished, the new state is then reported to the BioT Device state using the Update topic.

$aws/things/<clientId>/shadow/name/configuration/update

With the following JSON message:

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