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 firmware update (FOTA)
- 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:
- Create a connected device
- Retrieve info on a connected device
- Set properties of a connected device
- Retrieve the list of connected devices
- Create groups of devices
- Add a connected device to a group
- List groups of devices
- Create a graphical template
- Update a graphical template
- List all graphical templates
- Prepare for a FOTA update
- Check for FOTA status
- Start a FOTA update
- Stop a FOTA update
Details about 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 devicetoken
: 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 of:
token
, the security token for the devicename
, the device namedescription
, the device descriptionlocation
, the description of the device locationgeo
, the latitude and longitude of the device positiongroups
, the list of groups the device belongs tolast_seen
, the time of the last detected presence of the connected deviceonline
, the status of the device connectionplatform
, the type of the physical device using this connected device credentialsnotifications
, 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:
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 firstn
connected devices. Defaultn
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.
Prepare a FOTA update¶
The command:
ztc ota prepare device firmware
uploads to the ADM instance the correctly compiled and linked firmware update contained in the firmware
file for device with uid device
.
To correctly prepare a FOTA update refer to the link <ztc-cmd-link> command.
Start a FOTA update¶
The command:
ztc ota start device
signals the ADM to start the previously prepared FOTA update for device device
.
Stop a FOTA update¶
The command:
ztc ota stop device
signals the ADM to stop the previously prepared or started FOTA update for device device
.
Check a FOTA update¶
The command:
ztc ota check device
display the status of the FOTA process for device
.
The displayed information is:
ota_support
,True
if the connected device runs a FOTA enabled VMbcslot
, the index of the slot the current bytecode is running onvmslot
, the index of the slot the current VM is running onvmuid
, the unique identifier of the running VMota_request
, a unique identifier specifying the ongoing FOTA update, empty if FOTA is not ongoingota_next_request
, a unique identifier specifying the FOTA update that will be started by the start command, empty if no FOTA has been preparedota_fail
, a message specifying the last failed FOTA update error message, empty if oklast_ota
, the timestamp of last successful FOTA update