Zerynth Device Manager CLI

ZDM Command Line Interface (CLI) allows managing the ZDM via command line. The ZDM CLI directly interface with the ZDM API allowing the creation of scripts that goes beyond the simplified ZDM web user interface.

Authentication

The ZDM allows the user to authenticate against the Zerytnh backend.

The following commands are available:

  • login to retrieve an authentication token.
  • logout to delete the current session.

Login

The login command enables the user to retrieve an authentication token. The token is used in most zdm commands to communicate with the Zerynth backend.

The login can be issued in interactive and non interactive mode. Interactive mode is started by typing:

zdm login

The zdm opens the default system browser to the login/registration page and waits for user input.

In the login/registration page, the user can login providing a valid email and the corresponding password. It is also possible (and faster) to login using Google plus or Facebook OAuth services. If the user do not have a Zerynth account it is possible to register providing a valid email, a nick name and a password. Social login is also available for registration via OAuth.

Once a correct login/registration is performed, the browser will display an authentication token. Such token can be copied and pasted to the zdm prompt.

Warning

multiple logins with different methods (manual or social) are allowed provided that the email linked to the social OAuth service is the same as the one used in the manual login.

Warning

For manual registrations, email address confirmation is needed. An email will be sent at the provided address with instructions.

Logout

Delete current session with the following command

zdm logout

Note

it will be necessary to login again.

Devices

In the ZDM a device is a peripheral that can execute Zerynth bytecode. In order to do so a device must be prepared and customized with certain attributes. The main attributes of a device are:

  • uid a unique id provided by the ZDM with the device creation command
  • name a name given by the user to the device in order to identify it
  1. The first step to connect your device to the ZDM, once you are logged, is the device creation.
  2. Then you have to create a key and generate a jwt.

There also are commands to list your devices, to get a single device info, update a device and to list all device’s key

List of device commands:

The list of supported devices is available here

Device creation

To connect your device to the ZDM you must first create a new device on ZDM, to obtain a new device uid. The creation command is:

zdm device create name

where name is the name that you want to give to your new device

If you create your device using this command, it will be associated to your default fleet inside your default workspace. If you want, you can choose to associate the device to another fleet with the optional argument:

--fleet-id uid

If you want to associate the device to another fleet, see the update command

List devices

If you want to list all your devices, you can use this command to see a table with a device for each rows and 4 columns containing the device uid, name and the uid of the fleet and workspace containing them to see all your devices use the command:

zdm device all

Get device

To get a single device information, you can use this command to see the device name and the uid of the fleet and the workspace that contain it.

zdm device get uid

where uid is the device uid.

Update a device

Once you’ve created a device, you can use this command to update the device name, or to change the fleet uid associated to. To update a device you just need its uid as argument, then you can use optional arguments to update its name or fleet uid. Use the command:

zdm device update uid

And the optional arguments are:

  • --fleet-id uid the uid of the fleet you want to associate the device to
  • --name name the name you want to give to the device

Create a key

To be able to connect your device to the ZDM you must create a key at first and then generate a password (as jwt token) from the created key. You can generate different keys with different names for your devices with the command:

zdm device key create uid name

Where uid is the device uid and name is the name you want to give to the key. This command returns the generated key information as the key id, the name, the creation date and if the key has been revoked or not.

To connect your device to the ZDM, there is one last step to follow: jwt generation

Generate a device’s password (jwt)

To be able to connect your device to the ZDM you must create a key at first and then generate a password (as jwt token) from the created key. You can generate different keys with different names for your devices with the command:

zdm device key generate uid kid

Where uid is the device uid and kid is the id of the key created. This command returns the generated key information as the key id, the name, the creation date and if the key has been revoked or not.

List device keys

To see all the keys you have created for a device, use the command:

zdm device key all uid

Where uid is the device uid.

This command returns for each key the id, the name, the creation date and if it’s or not revoked.

Fleets

In the ZDM a fleet is a set of devices. When you log in for the first time, a ‘default’ fleet will be created. The main attributes of a fleet are:

  • uid, a unique id provided by the ZDM after the fleet creation command
  • name, a name given by the user to the fleet in order to identify it

List of fleet commands:

Fleet creation

To create a new fleet of devices inside a workspace use the command:

zdm fleet create name workspace_uid

where name is the name you want to give to your new fleet and workspace_id is the uid of the workspace that will contain the fleet.

List fleets

If you want to list all your fleets, you can use this command to have information about the associated workspace, and the list of devices inside:

zdm fleet all

Get fleet

To get a single fleet information, you can use this command to see its name, the uid of the workspace that contains it and the list of devices inside:

zdm fleet get uid

where uid is the fleet uid

Fota

The ZDM allows you to enable FOTA (over the air firmware updates) on your devices.

List of FOTA commands:

Prepare the FOTA

The command compiles and uploads the firmware for a device into ZDM. The version is a string identifying the version of the firmware (e.g., “1.0”).

zdm fota prepare [Firmware project path] [DeviceId] [Version]

Start a FOTA

Once you’ve uploaded your firmware, you can send the FOTA command to a device that will download it from the ZDM and uplink it. If the FOTA operation is finished, you can see if the device has accepted or refused it using the check fota status command.

To start a fota, type the command:

zdm fota schedule fw_version device_id

where fw_version is the firmware version associated to the device’s workspace uid and device_id is the device you want to send the command to.

Check FOTA status

To check the status of a FOTA you started, to know if the device finished the task or if an error occurred, type the following command:

zdm fota check device_uid

where device_uid is the uid of the device you want to check.

Webhooks

Using the ZDM you’re able to receive your device’s data on your webhooks. You can activate a webhook to receive all the data sent on a specific tag in a workspace. ZDM allows you also to visualize data on Ubidots through a Webhook.

List of commands:

Webhook creation

To create a new webhook use the command:

zdm webhook start name url token period workspace_id

where name is the name that you want to give to your new webhook url is the your webhook token is the authentication token for your webhook (if needed)

workspace_id is the uid of the workspace you want to receive data from

You also have the possibility to add filters on data using the following options:

--tag To specify a tag to filter data (you can specify more than one) --fleet To specify a fleet to filter data (you can specify more than one) --token Token used as value of the Authorization Bearer fot the webhook endpoint. --origin Webhook source (data or events) by default is data.

List webhooks

To see a list of your webhooks use the command:

zdm webhook all workspace_id

where workspace_id is the uid of the workspace you want to receive data from.

You also have the possibility to add filters on data using the following options:

  • --status active|disabled to filter on webhook status
  • --origin data to filter on data origin (data)

Get a webhook

To see information about a single webhook use the command:

zdm webhook get webhook_id

where webhook_id is the uid of the webhook.

Disable a webhook

To disable a webhook use the command:

zdm webhook disable webhook_id

where webhook_id is the uid of the webhook.

Enable a webhook

To enable a webhook use the command:

zdm webhook enable webhook_id

where webhook_id is the uid of the webhook.

Delete a webhook

To delete a webhook use the command:

zdm webhook delete webhook_id

where webhook_id is the uid of the webhook.

Jobs

In the ZDM a job is a function defined in your firmware that you can call remotely through the ZDM. There are to operations available in the ZDM for jobs:

List of device commands:

Schedule a job

In the ZDM will be soon available to schedule jobs in time, At the moment, it’s only possible to send it immediately to a device. To call remotely a function defined in your firmware, use the command:

zdm job schedule job uid

where job is the function name and uid is the device uid.

If your function expects parameters to work, you can use the command option --arg

Check a job status

If you want to check the status of a job you scheduled, type the command:

zdm job check job uid

where job is the job name and uid is the device uid you want to check, you will see if your device sent a response to the job.

Events

In the ZDM events are used in devices to notify the occurrence of certain conditions.

List of device commands:

  • Get events

Get events

To get all the events of a workspace use the command:

zdm events uid

where uid is the uid of the workspace.

You can also filter result adding the options: * --device-id * --start * --end

Workspaces

In the ZDM a workspace is the root node in Zerynth device management. A workspace represents a project containing fleets of devices. The main attributes of a workspace are:

  • uid a unique id provided by the ZDM with the workspace creation command
  • name a name given by the user to the workspace in order to identify it
  • description a string given by the user to describe the project

At your first log in, a ‘default’ workspace containing a ‘default’ fleet will be created.

List of workspace commands:

The list of supported devices is available here

List workspaces

To see the list of all your workspaces, use the command:

zdm workspace all

Get workspace

To get a single workspace information, you can use this command:

zdm workspace get uid

where uid is the workspace uid.

Workspace creation

To create a new workspace on the ZDM use the command:

zdm workspace create name

where name is the name that you want to give to your new workspace

You can also insert a description of your workspace adding the option --description desc

List tags

When a device publish data to the ZDM it label them with a string called tag. With the following command you can see all the tags that devices associated to your workspace used as data label.

zdm workspace tags uid

where uid is the uid of the workspace

Get data

To get all the data of a workspace associated to a tag use the command:

zdm workspace data uid tag

where uid is the uid of the workspace.

You can also filter result adding the options: * --device-id * --start * --end

List firmwares

To have a list of the firmwares you uploaded to the ZDM associated to a workspace use the command:

zdm workspace tags uid

where uid is the uid of the workspace.