Device Management Dashboard

Mongoose OS provides an integrated service for device management. It is located at https://dash.mongoose-os.com/ , and provides the following functionality:

  • 24/7 access and monitoring for your devices in the field
  • Per-device cloud state object - a "device shadow". Ideal for implementing mobile and web apps that talk to your devices
  • RESTful API for accessing your devices programmatically, e.g. from mobile and web apps
  • Talk to your devices via the device shadow or directly via the RPC (remote procedure calls)
  • Online/Offline status, current firmware, disconnection logs
  • Firmware update (OTA) - upload firmwares and perform individual or bulk firmware updates with live status feedback
  • Store, view and export device logs
  • Configuration, file system, hardware peripherals management, and more

This is how it looks like:

How to add your device to the dashboard

Option 1 - using a pre-built demo-js app

  • Install a demo-js Mongoose OS app on your device by following the instructions on Mongoose OS download page. As a result, you should have your device flashed and WiFi configured.

  • Login to the https://dash.mongoose-os.com/, register a new device. That should give you a unique access token.

  • Update the dash configuration section. Do it either via the command line: mos config-set dash.enable=true dash.token=ACCESS_TOKEN or via the web UI:

Option 2 - build your own app

  • Edit the mos.yml file of your app, include dash library:

    libs:
      ...
      - origin: https://github.com/mongoose-os-libs/dash  # <-- Add this line!
  • Rebuild your app, flash it, and configure WiFi:

    mos build --arch ...
    mos flash
    mos wifi WIFI_NAME WIFI_PASSWORD
  • Repeat the last 2 steps from the previous section.

Device shadow

Dashboard implements device shadow mechanism, similar to to the Azure device twin, Amazon IoT device shadow, or Google IoT Core state/config objects.

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 three 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 the change is made to either desired or reported. This is the difference between desired and reported only for keys that are present in desired.

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
  • reported.online - boolean field, whether device is online or offline

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 its shadow object using C shadow API or JS shadow API. Also shadow could be updated via the RESTful API provided by the dashboard.

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.

Device logs

Devices can send logs. Logs are stored permanently and can be downloaded. Real-time logs are also displayed in the log window:

Device control commands

Click on "manage" button to go the the device page. When it shows, it connects to the device and asks for a list of RPC services implemented by the device - both built-in services, provided by Mongoose OS, and custom RPC services, implemented by the app developer.

That list is rendered in the dropdown menu. Select any RPC command, and the command arguments will be rendered in the arguments text input. Alter arguments as required, press Execute button - and see the command output in the logs window:

You can update firmware over-the-air, reboot the device, manage files, manipulate GPIO, and so on.

OTA firmware update

Select devices you want to update, choose the firmware, click "Start OTA Update". That will change the device shadow state to

{"desired": {"ota": {"url": "url_of_your_firmware" }}}

From that point on, a device shadow mechanims sends a message to all affected devices. The ota-shadow library catches the shadow event and triggers on OTA.

Note that this mechanism works the same way, with no changes, on AWS IoT as well.

Reporting data from the device

A device can send any arbitrary measurements to the device shadow, just like the dash library sends RAM statistics. Use shadow API and send your metrics like:

{"state": {"reported": {"myvalue": 1234}}}

Device side configuration overview

The dash library provides a couple of options for fine-tuning. To see full list of configuration options, do:

mos config-get dash
{
  "ca_file": "ca.pem",        # CA certs file for secure cloud TLS connectivity
  "enable": true,             # Enable management 
  "stats_interval": 1,        # RAM stats report interval in seconds
  "send_logs": true,          # Whether to send logs
  "send_stats": true,         # Whether to send stats
  "server": "wss://dash.mongoose-os.com/api/v1/rpc",  # Cloud server address
  "token": "xxxxxxxxx"       # Device access token
}
edit this doc