Connected Devices

The Zerynth Advanced Device Manager (ADM) allows connections between the devices programmed with Zerynth and the ADM sandbox instance hosted on the Zerynth backend server. The ADM adds to each connected device the following functionalities:

  • executing functions triggered by a remote request (remote procedure call)
  • performing over the air (OTA) firmware update
  • displaying and interacting with a graphical user interface both on a mobile app or desktop browser

Such functionalities can be configured and controlled through the following ZTC commands:

Details about the ADM can be found here. Info on how to write a Zerynth script for the ADM can be found here.

Create a connected device

In order to connect a physical device to the ADM, a bit of device provisioning must be made. In particular, a new connected device instance must be created on the ADM and the assigned credentials used in the script running on the physical device.

The command:

ztc thing add name

creates a new connected device instance with name name in the ADM server. Such instance can have many different properties, but only a subset of them is mandatory and generated by the ADM:

  • uid: the unique identifier of the connected device
  • token: the security token used to authenticate the physical device to the ADM

Additional properties can be specified at the moment of creation by specifying the corresponding options:

  • --location loc adds the description of the location the physical device is placed
  • --lat lat --lon lon attaches coordinates to the device
  • --description desc specifies the device description
  • --tag tag attaches a set of tags to the device (the option can be given multiple times)

Each Zerynth user can create an unlimited number of connected devices instances, however only a subset of them is allowed to be connected to the ADM at the same moment.

Retrieves device info

The command:

ztc thing info uid

retrieves information about the connected device with unique identifier uid.

The information retrieved consists in:

  • token, the security token for the device
  • name, the device name
  • description, the device description
  • location, the description of the device location
  • geo, the latitude and longitude of the device position
  • groups, the list of groups the device belongs to
  • last_seen, the time of the last detected presence of the connected device
  • online, the status of the device connection
  • platform, the type of the physical device using this connected device credentials
  • notifications, a boolean determing if mobile notifications are enabled for this device

Configure a device

The command:

ztc thing config uid

sets the properties of the connected device with unique identifier uid.

The properties are specified with the following options:

  • --name name, changes the device name
  • :option:`–description desc `, changes the device description
  • --location loc, changes the device location
  • --lat x / --lon y, change the device coordinates
  • --token, asks for a new security token
  • --template template_uid, sets the device template

Connected devices list

The command:

ztc thing config list

retrieves the list of connected devices. Options can be specified to filter the results:

  • --from n, skips the first n connected devices. Default n is zero.
  • --status online/offline, filters connected devices based on online status. If not given, all devices are retrieved

Create a group of devices

The command:

ztc thing group add name

creates a group named name, initially empty. Devices can be added to the group with the config command.

Group configuration

The command:

ztc thing group config uid --add dev0_uid --remove dev1_uid

can be used to add or remove devices (identified by their uids dev0_uid and dev1_uid) to the group identifiedby uid.

The options --add and --remove can be repeated multiple times in the same command.

Group configuration

The command:

ztc thing group list

retrieves the list of all groups. The option --from n can be used to skip the first n groups.

Create a device template

The Zerynth ADM allows to remotely store a graphical interface for each connected device called device template. A template is just a collection of HTML5, javascript, css and image files hosted on the ADM backend. The template is able to receive and send messages to the connected device in response to user interactions with its graphical components.

The command:

ztc thing template add name

creates a new empty template named name. A template is identified by a generated uid.

Upload a template

A newly created template is empty. Files and subfolders can be added to the template with the following command:

ztc thing template upload uid path

where path is the folder containing the template files and uid is the uid indentifying the template to update.

The files at path are compressed and transferred to the ADM backend. There are limitations on the size of a template and on the type of files that can be uploaded. If the upload is successfull, the files previously associated with the template are erased permanently (no history is kept).

Retrieve template list

The command:

ztc thing template list

retrieves all the created templates. The option --from n skips the first n templates.