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 statusreported.stats
- object that keeps device RAM statisticsThe 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:
MGOS_SHADOW_CONNECTED
event that indicates that the
device is connected to its shadow, and report device current state to the
reported
key.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.
edit this doc