1. Home
  2. Docs
  3. Zerynth Device Manager
  4. Getting started
  5. The ZDM Command Line Interface

The ZDM Command Line Interface

This section is a guide for the most used ZDM CLI commands.

Note: that the zdm command line interface is available from Zerynth >= r2.4.3, download it here or update to the last version!

Adding ZDM to the OS path

In order to use the zdm command line interface, you need to add it to your OS path:

On Linux: open the terminal and launch the following command:

Copy to Clipboard

Close and reopen the terminal or reload the “source” builtin command.

On Windows: open the command prompt as administrator and launch the following command:

Copy to Clipboard

Close and reopen the command prompt.

On Mac: open the terminal and launch the following command:

Copy to Clipboard

Close and reopen the terminal or reload the “source” builtin command.

Now you can use the zdm command line interface by typing on your command prompt


Copy to Clipboard

To see the list of all the possible commands with details use the help command with option –help.

For example zdm –help or zdm device –help.

Login

The first step to use the ZDM (Zerynth device manager) using the Zerynth Toolchain is to log in using your Zerynth account.

Open a terminal and type this command to login with your Zerynth account:

Copy to Clipboard

You will be redirected to the Zerynth SSO and, once logged, you will see your authorization token.

Copy the generated token and paste it into the terminal. 

If you’re logging in for the first time, a default workspace and a default fleet will be created for  your account.

The first step to work with your devices and ZDM is to associate your devices to a fleet inside a workspace, so you can choose to use the default ones or to create your first custom workspace and fleet.

Account commands

Account’s information

Once you’re logged in, if you want to see your account information use the command:

Copy to Clipboard

Logout

To logout of the ZDM give the command:

Copy to Clipboard

and your current session will be closed.

Workspaces

Workspace creation

To create a new workspace use the following command:

Copy to Clipboard

WorkspaceName is the name you want to give to your workspace (don’t use  “default”).

You can also give your workspace a description using the option –description

If you create a workspace, you will see your workspace’s information:

ID Name Description
wks-id my-first description

Once you’ve created a workspace, you should create a fleet inside to be able to manage your devices’ data.

Copy your new workspace’s id or use the list workspaces command to see all your workspaces.

List workspaces and workspace information

If you want to see the list of workspaces you’ve created, their name, description and id

type the command:

Copy to Clipboard

You can also get information about one single workspace from your list giving the command:

Copy to Clipboard

Fleets

Fleet creation

To create a new fleet type the following command:

Copy to Clipboard

Also in this case, don’t use “default” as the fleet name, and use one of your workspaces’ id to create your new fleet.

A result message with the fleet name will be shown.

List fleets and fleet information

If you want to see the list of fleets you’ve created type:

Copy to Clipboard

You will have the fleet id, the name, and the workspace id of all of your fleets.

Devices

Device creation

Once you have created a new workspace and fleet, or you’ve decided to skip and to use the default ones, you can create a new device.

To create a device type the command:

Copy to Clipboard

DeviceName represents the device’s name, FleetId is the fleet id you want the device to belong to.

If you don’t specify a fleet id, the device will be associated to the default fleet in the default workspace.

To authenticate your new device, you have to generate a key for the device with the corresponding command. Let’s see a description of the other commands you can use to manage devices.

Device list and device information

If you want to list your devices or to get a device information you can use the list and get commands, to see the device name, id, and fleet id.

Give the command:

Copy to Clipboard

to list all your devices or

Copy to Clipboard

to have information about a single device.

Get the device’s workspace

To get the workspace’s name and id that contains your device, you can use the following command:

Copy to Clipboard

Device’s key generation

To be able to manage your device’s data you have to create a key at first and then generate a password (as jwt token) from the created key.

The generated key can be used as the password to connect your device to the ZDM in your firmware.

You can generate different keys with different names for your devices with the command:

Create a new key.

Copy to Clipboard

Generate a new Jwt password for a device starting from a generated key.

Copy to Clipboard

Jobs and actions

You can use ZDM  to remotely send a job command to your devices.

To send a new job to a device, you just have to start it using the command:

Copy to Clipboard

The ‘name’’ argument is a string representing the method name.

The ‘devices’’ argument is a list of the device ids you want to schedule the job (i.e. [“device1”, “device2”]).

If the device needs some arguments to execute the job, you can use the –arg option.

Events

You can use ZDM CLI to see the last 25 events sent by your devices.

Use the command

Copy to Clipboard

If you want to see the last 25 events filtering on device use the option

Copy to Clipboard

It’s also possible to filter results on date. You can indicate a start and end date (RFC3339 format) using the options:

Copy to Clipboard
Copy to Clipboard

Fota (Firmware over the air)

Important: In order to perform the FOTA of a device you need to have a Virtual machine with the “Fota Enable” feature.

Upload a firmware

The first step to start a FOTA update on your devices is to upload a firmware to the ZDM cloud.

To upload your firmware, use the command:

Copy to Clipboard

Where 

  • firmwareProjectPath is the firmware’s project location in your local file system,
  • deviceId is the id of the device you want to update, 
  • version is a string used to label your firmware (e.g., “1.0”)

Note that the firmware will be associated with the workspace that contains your device.

If you will associate new devices to the same workspace you can send them the same firmware.

Start FOTA

Once you’ve uploaded your firmware, you can send the FOTA command to the device typing:

Copy to Clipboard

For example: 

schedule the new firmware to the device with id dev-yyyyy

Copy to Clipboard

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, give the following commands to have a list of your fota and their status:

Copy to Clipboard

Gates

Using the ZDM you’re able to also receive your device’s data on your webhooks.

For example you can send data to a WebHook server or to Ubidots (see the example section).

Now let’s see a complete example, on how to connect a device to the ZDM and see data using an Ubidots dashboard and widgets.