1. Home
  2. Docs
  3. Zerynth Device Manager
  4. Getting started
  5. Examples

Examples

Example 1: ZDM CLI basics

Let’s see a complete example of a ZDM use case.

1. At first register or login with the ZDM using one of the following commands

Copy to Clipboard

or

Copy to Clipboard

The login command will open your default browser into the Zerynth SSO, login with your credentials and insert the authentication token back to the zdm terminal.

2. If you want to test ZDM using default workspace and fleet skip to step 4. To create your first custom workspace use the command.

Copy to Clipboard

3. Now Let’s create the first fleet inside the new workspace.

Use the following command

Copy to Clipboard

Using your the id of your workspace generated at the step 1

4. You will see your fleet id as the result of this command.

  1. We’re ready to create our first device and then to connect it to the ZDM.
Copy to Clipboard

Use your fleet id to specify that it will contain the device, or leave it blank if you want the device inside your ‘default’ fleet and workspace.

You will receive device id fleet id and some other information as result.

5. To connect your device to the ZDM you must generate an authorization key for your device. Use the following commands:

Create a new key with a name.

Copy to Clipboard

Generate a password (as Jwt token)  from the generated key

Copy to Clipboard

The command produces a JWT token that can be used as the password of your device. You will have to use the “password” column value as your device’s password to connect ZDM, using the connect Zerynth Library function inside your firmware’s code.

6. Open Zerynth Studio IDE (version >= 2.4.3) and click on the bulb to access the examples section. Type ZDM in the search textbox and clone one of the available examples (for example the SIMPLE_ZDM). Edit the firmware code with your wifi and device’s credentials, then compile and uplink it.

7. Your device started sending data to the ZDM and you can just see them.

Just type the command:

Copy to Clipboard

In this case:

Copy to Clipboard
Tag Payload Device Timestamp
test {‘temp’: 11}  dev-id 2020-03-23T10:11:04
test {‘temp’: 26}  dev-id 2020-03-23T10:11:19
test {‘temp’: 25}  dev-id 2020-03-23T10:11:29
test {‘temp’: 22}  dev-id 2020-03-23T13:28:11
test {‘temp’: 26}  dev-id 2020-03-23T13:28:16
test {‘temp’: 29}  dev-id 2020-03-23T13:28:46
test {‘temp’: 28}  dev-id 2020-03-23T13:28:51
test {‘temp’: 13}  dev-id 2020-03-23T13:30:37
test {‘temp’: 20}  dev-id 2020-03-23T13:31:07
test {‘temp’: 25}  dev-id 2020-03-23T13:31:26
test {‘temp’: 15}  dev-id 2020-03-23T13:32:11
test {‘temp’: 14}  dev-id 2020-03-23T13:33:26
test {‘temp’: 29}  dev-id 2020-03-23T13:48:46
test {‘temp’: 15}  dev-id 2020-03-23T13:49:01
test {‘temp’: 27}  dev-id 2020-03-23T13:49:11
test {‘temp’: 14}  dev-id 2020-03-23T13:49:31
test {‘temp’: 11} dev-id 2020-03-23T13:50:01

Example 2: Send data to Ubidots dashboard

It’s possible to visualize device’s data also on UbiDots using generic ZDM Webhook (if you are using the ZDM CLI) or using the dedicated ZDM Ubidots Gate available on the ZDM web user interface.

If you don’t have one, create an Ubidots account on https://www.ubidots.com.

Add a new dashboard and then click on “Devices” to create a new device. Select your device’s type or just click on “Blank device” and give it a name.

If you click on the created device, you will see its device api_label, copy it and append to the Ubidots Webhook url like this:

Copy to Clipboard

Then you have to take your UbiDots token.

Click on your Ubidots profile icon on the right and click on “API Credentials”. You will see two tokens, show and copy your “Default Token”

Now return to the ZDM terminal and type the command

Copy to Clipboard

Example:

Copy to Clipboard

In which period means the interval (in seconds) of POST requests to your webhook (for example 10), workspace_id is the id of the workspace (created or default) containing your device and tag is the label used from the device to publish data (“test” in our example)

If you are using the ZDM web UI just copy the ubidots token and device label to the New Ubidots Gate creation form.

Now, go back to Ubidots and add a widget. For example a Gauge into your new dashboard and select the variable name selecting your device.

Click on the “+” button on the right

Select a widget type, for example a Gauge

Configure your widget with name, color, etc. (optional)

Select the device’s variable to associate it to the Gauge, for example temperature (they’re all random values)

8. The widget will show the real time value sent by the device!

You can repeat these steps with the other variables and use different widgets.

Example 3: Jobs via ZDM CLI

Now, let’s see an example to define a remote procedure in your firmware and how to call it using the ZDM CLI.

You can use the jobs.py file inside the examples directory that enable you to send ‘job1’ and ‘job2’ commands that send random data when they are called

Once uplinked the firmware, you will want to call jobs using the ZDM and see the result sent by the device.

Open the ZDM terminal and type the command:

Copy to Clipboard

for example:

Copy to Clipboard

To see if the device received your remote procedure call, and to see the answer with the random number, type the command:

Copy to Clipboard

In this case:

Copy to Clipboard

You will see random numbers sent by your device as response to the job.

Example 4: FOTA via CLI

The last main feature we will discuss in this guide is Fota (firmware over the air), used to update your device’s firmware remotely.

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

To enable fota using your device you have to uplink the ‘fota.py’ firmware on your device, upload a firmware to the ZDM and then send the fota command to your device.

Let’s upload a firmware to the ZDM using the ZDM fota commands, for example one of the firmwares in ‘examples’ directory.

At first upload the new firmware to the ZDM using

Copy to Clipboard

for example:

Copy to Clipboard

Then link the firmware for the bytecode slot 0 and bytecode slot 1

Copy to Clipboard
Copy to Clipboard

Using your Virtual Machine UID using ztc command

Copy to Clipboard

Now use the zdm prepare command to upload your firmware in ZDM.

Each firmware belongs to a workspace, and it’s identified by the couple <workspaceId, version>.

Copy to Clipboard

for example

Copy to Clipboard

then launch fota command:

Copy to Clipboard

that becomes

Copy to Clipboard

You can check the firmware update using the command fota check on ZDM, or check the device’s console in Zerynth studio to see if the device downloaded the new firmware correctly.

If this operation succeeds, you will see that the device will restart and run the downloaded firmware.