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
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.
3. Now Let’s create the first fleet inside the new workspace.
Use the following command
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.
- We’re ready to create our first device and then to connect it to the ZDM.
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.
Generate a password (as Jwt token) from the generated key
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:
In this case:
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:
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
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:
To see if the device received your remote procedure call, and to see the answer with the random number, type the command:
In this case:
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
Then link the firmware for the bytecode slot 0 and bytecode slot 1
Using your Virtual Machine UID using ztc command
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>.
then launch fota command:
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.