shadow.md - adityasivaraj/mongoose-os-docs GitHub Wiki

Device shadow

Dashboard implements device shadow mechanism, semantically identical to to the Azure device twin and Amazon IoT device shadow. Google IoT Core state/config objects provide similar functionality, but implemented quite differently.

Device shadow is a JSON object that is associated with a device. It lives on a cloud, keeps device state, and always available regardless whether the associated device is online or offline. Shadow object has four top-level keys:

  • desired - this is the state you want your device to have.
  • reported - this is the state your device actually has.
  • delta - automatically generated by the cloud every time desired or reported changes. delta is the difference between desired and reported only for keys that are present in desired.
  • tags - arbitrary settings invisible to the device but visible to the cloud user.

The structure of the desired and reported subobjects is arbitrary - create whatever structure you wish. However, the dash library that connects your device to the dashboard, reserves some keys:

  • reported.ota - object that keeps firmware information and last OTA status
  • reported.stats - object that keeps device RAM statistics

The device shadow is displayed in the device list, and it is available for edit in the device panel (when clicked on the device name):

Devices can update their shadow using C API or JavaScript API, see shadow library for reference.

In order to create new keys, send a shadow update with that new key and its value. In order to delete a key, send a shadow update where that key is set to null.

The best practive for using shadow on the device side is this:

  • Catch the MGOS_SHADOW_CONNECTED event that indicates that the device is connected to its shadow, and report device current state to the reported key.
  • Catch MGOS_SHADOW_UPDATE_DELTA event, and apply all keys in the delta to the device. If the state is changed, report and update to the reported key.

Example: see example-shadow-js app for the JavaScript example, and https://github.com/cesanta/mongoose-os-smart-light for C example. Both implement the canonical best practice mentioned above.