Zerynth Advanced Device Manager

The Zerynth Advanced Device Manager (ADM) adds high level functionalities to connected devices:

  • simpler Over The Air (OTA) firmware updates (soon)
  • Remote procedure calls (RPC)
  • Per device custom graphical interfaces

Zerynth tools strive to be as agnostic as possible and the ADM is no different. It is compatible with most cloud providers (Azure, Amazon, Bluemix) but can also be installed on premises as a Docker container.

Each Zerynth user has access to an ADM sandbox instance hosted on the Zerynth servers. Once your product is ready for public deployment, an instance of the ADM can be run on your preferred cloud with no additional effort.

How to use the ADM

All ADM functionalities are configurable and accessible both from the Zerynth Toolchain and Zerynth Studio.

The typical usage consists of a few steps:

  • Device provisioning: a new device is created and added to the user’s device pool by assigning it an unique identifier (uid). During this step a security token is also generated in order to authenticate the device to the ADM. When the ADM is hosted on a cloud provider instance, the uid and security token are not necessary, since the authentication is perfomed by third party cloud components (e.g. Azure IoT Hub or AWS IoT Registry)
  • Device connection: a physical device is programmed using the Zerynth ADM Library library that takes care of connecting to the ADM and receiving commands
  • Template creation: a template is created and associated to the device. A template consists of HTML5, Javascript, CSS and image files that together form the device graphical interface. Such interface is accessible both from desktop browsers and the Zerynth App. Morevover, by adding the ADM javascript library to the template, a bidirectional communication can be established between the physical device and the template.
  • Remote Procedure Call: Python functions on a physical device can be called remotely by sending messages to the ADM that relays them to the device and back.

Interacting with the ADM

The ADM exposes a set of APIs to interact with connected devices. Such APIs are available at https://api.zerynth.com/v1 with the following endpoints:

  • /ws/uid, opens a websocket for the connected device identified by uid
  • /ws/:uid, opens a websocket for the group of devices identified by uid
  • /devices/uid/call/method, sends a RPC to the connected device to execute method.
  • /devices/uid, opens the connected device graphical interface showing the associated template. If no template is set, the default websocket console for the device is shown.

Templates & Mobile integration

A unique feature of the ADM is the integration of Web 2.0 technologies with connected device. By linking a device to a template (that can be as simple as a single static web page or as complex as a responsive website), the device can be monitored and controlled remotely both on a desktop computer or on a mobile app.

In order to enable bidirectional communication between the template and the device, the only necessary step is to include the ADM javascript library into the template and configure it with the appropriate callbacks.

Here is an example template:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>Zerynth ADM Template</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
    <script src="https://api.zerynth.com/zadm/latest/z.js"></script>     <!--  INCLUDE THE ZERYNTH ADM JS LIBRARY -->
  </head>
  <body>
    <div id="status" style="text-align:center"> </div>
    <script>
    <!-- CONFIGURE ADM LIBRARY ON READY -->
    $(document).ready(function() {
      Z.init({
        on_connected:     function(){$("#status").html("CONNECTED")},
        on_error:         function(){$("#status").html("ERROR")},
        on_disconnected:  function(){$("#status").html("DISCONNECTED"); return true},
        on_online:        function(evt){$("#status").html("ONLINE");},
        on_offline:       function(evt){$("#status").html("OFFLINE");},
        on_event:         function(evt){$("#status").html("EVENT!");},
        on_notify:        function(evt){$("#status").html("NOTIFICATION!");}
      })
    });
    </script>
  </body>
</html>

The template automatically connects to the ADM requesting access to the device uid specified in the url. It also reacts to events coming from the ADM by configuring a set of callbacks. In particular, the ADM Javascript library provides a global object Z that accepts the following callbacks in its init method:

  • on_connected, is called when the template successfully connects to the ADM
  • on_disconnected, is called when the template disconnects from the ADM. If the callback returns true, an attempt of reconnection is made
  • on_error, is called when the template connection to the ADM can’t be established
  • on_online, is called when the device connects to the ADM
  • on_offline, is called when the device disconnects from the ADM
  • on_event, is called when the device sends an event message to the ADM
  • on_notify, is called when the device sends a mobile notification request to the ADM

The Z object can also send messages to the device or group with the following methods:

  • call(method,args,callback), ask the connected device(s) to execute method method with arguments args (as an array of objects). If given, callback is executed when method completes.
  • send_raw(txt), accepts a string representing a valid JSON message and relays it to the connected device(s)

Valid JSON messages accepted by the ADM for RPC are:

{
    "cmd":"CALL",
    "method":"random",
    "args":[0,20],
    "cid": "4661c53b-ca74-4aef-8117-916b09400253"  //a unique identifier for the call
}

Messages coming from devices have the following format:

//Event message
{
    "cmd":"EVNT",
    "payload":{
        // custom fields
    }
}

//Notification message (to send push notifications from the device to the Zerynth App)
{
    "cmd":"NTFY",
    "payload":{
        "title":"Notification title",
        "text":"Notification body"
    }
}

//Return message (in response to a "CALL" message)
{
    "cmd":"RETN",
    "res": ... //result of method call
    "cid": "4661c53b-ca74-4aef-8117-916b09400253"  //the unique identifier for the call
}

Zerynth Studio integration

All the ADM features can be readily accessed from Zerynth Studio. On the Left Panel, by clicking the ADM icon, the list of connected devices is retrieved and displayed. New device can be created from the dropdown menu next to the panel title.

Create connected devices

As shown in the above image, a newly created connected device is assigned a uid and a security token. A new token can be requested by clicking on the old one. The connected device is associated to the default template and doesn’t belong to any group. Templates and groups can be added by clicking the respective “plus” icon.

The circle to the left of the device name is gray, indicating the offline status of the device; it turns to green when the device connects to the ADM. The eye icon to the right of the name, opens the associated template of the device on a system browser tab in order to allow template testing.

To test the connected device, a physical device must be programmed with a script based on lib.zerynth.adm using uid and token as credentials.

Online devices

Once the physical device connects to the ADM, its type is automatically added to the connected device instance (in the above image is Particle Photon). By clicking the eye icon, the default template for the connected device is opened and incoming messages can be monitor. RPC calls can be made as well, directly from the template by typing JSON messages in the dedicated field.

Default template

A new template can be created by clicking on the plus icon of the connected device or from the panel dropdown menu. On the dialog that appears, by clicking the upload icon, the folder containing the template files can be selected and uploaded to the ADM. Templates are therefore “independent” from devices and projects: a template can live in its own folder and can be associated to multiple connected devices.

Important

In each template there must be an index.html file that will be served by the ADM when the device UI is requested

Template creation

Connected devices can also be added to groups, and groups can be created and assigned easily from Zerynth Studio.