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¶
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 commandname
a name given by the user to the device in order to identify it
- The first step to connect your device to the ZDM, once you are logged, is the device creation.
- 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:
- Create
- List devices
- Get a single device
- Create a device’s key
- List a device’s keys
- Generate a password from a key
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 commandname
, 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 commandname
a name given by the user to the workspace in order to identify itdescription
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
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.