Development Environment¶
Zerynth SDK offers a rich development environment. Firmware can be written, compiled and run with a set of flexibile tools. The editor of choice is Visual Studio Code (VSCode, version 1.51 or higher) that is installed automatically with the SDK together with its Zerynth Extension.
However, since all the operations required for compiling and running a firmware are performed via a command line interface, any editor can be used with any build system with some ad hoc configuration.
What is installed¶
Once the Zerynth SDK is installed, a Zerynth folder is created containing all the required components. Depending on the platform the zerynth folder can be found:
- under
~/.zerynth3
for Mac and Linux - under
C:\Users\<username>\zerynth3
on Windows 10
The SDK contains:
- A stripped down version of Python 3.8 for running the Zerynth toolchain
- GCC based compilers for all the Zerynth hardware
- Python and C libraries
- Board support packages (
bsp
) for Zerynth hardwares - An extensive set of examples
- The command line interface
- The latest version of VSCode if not already installed
At the end of installation, the PATH
environment variable is modified to point to relevant Zerynth executables that are therefore immediately available from any terminal:
ztc
will run the Zerynth Toolchain CLIzdm
will run the Zerynth Device Manager CLIzstudio
will run VSCode
Note
If a version of Zerynth before v3.0.0 is detected, there may be a clash between the old ztc
and zdm
commands. In that case, the ztc3
and zdm3
commands can be used in their place to maintain compatibility.
VSCode Extension¶
The VSCode Zerynth extension can be installed together with the SDK or can be installed from the Azure marketplace. The end result is the same and in both cases the full SDK is downloaded and installed.
Upon startup the Zerynth extension shows the greeting panel with some getting started instructions

By opening the explorer panel, the option to start a new Zerynth project is given, either from scratch or by cloning an existing example.
Zerynth Control Panel¶
Zerynth redesigned the control panel of the extension. The control panel enables the users to compile and run applications, View hardware information and handle cloud operations such as provisioning, FOTA...

Here is a description of each function:
- Physical Device: Recognize the connected device and aligns the project compilation and burning process.
- Erase Device: erases the device flash memory, bringing it to factory state.
- Device Information: Opens hardware page, containing information on hardware, pinmap...
- Device Pinmap: Opens Pinmaps of the device.
- Build: Compiles the current project.
- Clean and Build: Cleans temporary files, compiled files... and builds the project.
- Run: Compiles the project then burns the application to the device. Only the changed components are burned.
- Erase and Run: Erases the device flash memory, compiles the project then burns the application to the device.
- Console: Opens the serial terminal automatically configured for the connected device.
- Claim device: links the physical device by associating a virtual device on the Zerynth cloud. Burns a special firmware which creates the required credentials, certificates and register them to the Zerynth cloud.
- Unclaim device: unlinks a provisioned device from the related virtual device on the Zerynth cloud.
- Cloud Device: ID of Virtual Device on zerynth cloud.
- FOTA: compiles and prepares the compiled project for FOTA then launches the FOTA procedure.
- Upload firmware: compiles and uploads the current project on Zerynth Cloud for future FOTA deployments.
Zerynth Examples¶
From this panel the vast collection of examples can be browsed by category or searched by content. Cloning an example is the quickest way to create a working new project.

Cloning an example¶
The easiest way to setup a new project is to clone an example. It can be done either from the Clone Zerynth Example
button or from the Zerynth Examples
panel. Clicking the Clone Zerynth Example
button starts a popup for searching the installed examples. Typing something and hitting enter shows the matches:

After selecting an example, a folder where to clone it must be chosen
Running a project¶
In order to compile and run a project, a device must be first plugged in to a USB port. By pressing Physical device
in the Zerynth Control Panel
the device is automatically recognized and the project configured accordingly.

Note
Not all Zerynth hardwares can be automatically recognized. In that case, VSCode will present a popup where the correct device can be chosen
By clicking on Device documentation
and Device Pinmap
the documentation pages for the device datasheet and schematics are opened in the browser. Before opening the pages, VSCode will ask to trust the link; it is recommended to set zerynth.com
as a trusted domain in VSCode so that all pages will be opened without confirmation.
By clicking Build
the project is compiled. The output of compilation is shown in the terminal window named Task - Build
.

After a successful compilation two new directories appear in the project: build
and cache
. The former stores the result of a compilation, namely the file firmware.z
; the latter stores temporary files to speed up subsequent compilations.

By clicking Run
in the Zerynth Control Panel
, the project is compiled and flashed on the connected device. The result of the Run
operation is reported in the terminal window named Task - Run
.

Debugging a project¶
Once the firmware is running on the device, it is possible to monitor its execution by opening the device Console
. It establishes a serial communication over USB and shows the output of the firmware.

Sometime a firmware may throw an exception which is shown in the console and recognized. By clicking on the Problems
tab the list of problems is shown together with their location in the code.

Advanced Debugging¶
The firmware can print to the console or not depending on the chosen debug level. By default the debug level is disabled and the only way to output something to the console is by using print
in the program. However, Zerynth allows the usage of additional keywords whose output is printed to the console conditionally. The keywords are zinfo
, zwarn
, zerror
and zdebug
. To enable the corresponding debug level, the project contains a configuration file called config.yml
. Inside config.yml
the configuration parameter ZERYNTH_DEBUG
can be enabled and set to one of four levels:
info
:zinfo
keyword is effective, all the other keywords are disabledwarning
:zinfo
andzwarn
keywords are effective, all the other keywords are disablederror
:zdebug
is disabled, all the other keywords are effectivedebug
: all keywords are effective
Claiming the device¶
Claiming the device is a very important step that must be performed just once, before connecting any device to the Zerynth cloud. It consists of associating the device physical identity protected by the secure element with the device identity on the Zerynth cloud. This step guarantees that the physical device is owned only by the Zerynth account that performs the associations.
Under the hood the physical device is loaded with a provisioning firmware that uses the secure element to generate a signature. This signature is sent to the Zerynth cloud, after verifying its authenticity, Zerynth cloud associates the physical identity with a virtual device. The association is possible only if the physical device is not already associated. In that case it must be deassociated first.
Once associated, the device is ready to communicate with the cloud.
during the claim device process You will be asked to
- choose which fleet you want to register your device to.
- Create a new cloud device for this board.

- Accept the provisioning firmware (the existing firmware will be overwritten).

- After provisioning, the terminal should print "Claim finished successfully". if you click on cloud device section, you will be directed to the device page in zerynth cloud.
Performing Over the Air Update (FOTA)¶
the cloud enables users to remotely update and manage the firmware of the device seamlessly and in a fail-safe way.
The device downloads the new firmware and installs it. Upon reset, the new firmware will validate itself and if everything works correctly, it becomes permanent. FOTA can be easily tested directly from VSCode by clicking Launch FOTA
in the Zerynth Control Panel
; the current project is compiled and the firmware.z
is uploaded to the Zerynth Device Manager as a new firmware version. The FOTA
request is sent to the device automatically and by opening the console, its progress can be monitored.
We wrote a quick FOTA demo, click here to check it.
Shortcuts¶
All the commands of the extension can be run from VSCode command palette. Just press Ctrl+Shift+P
and type one of the following (or just part of it until it appears in the dropdown):
Zerynth > Login
, start loginZerynth > New Zerynth project
, creates a new Zerynth project with some default folders and files:- .vscode, a folder containing the project workspace settings;
- .zerynth, required by Zerynth;
- main.py, the firmware main python file;
- readme.md, a description file initially filled with creation date;
- .gitignore, ignore SDK temporary files;
- config.yml, a configuration file for firmware macros and settings.
Zerynth > Clone Example
, clone a Zerynth example into a new project.Zerynth > Search Examples
, search examples based on their contentZerynth > Set Device Type
, set the type of the physical device connected to the USB portZerynth > Device Pinmap
, opens the device schematics in the browserZerynth > Device Documentation
, opens the device documentation in the browserZerynth > Compile
, produces an executable bytecode file compiling the current project for the physical deviceZerynth > Run
, run the bytecode on the physical deviceZerynth > Console
, open the serial port monitor for the physical deviceZerynth > Attach to ZDM
, attach the physical device to a Zerynth Device Manager device identifierZerynth > Device Provisioning
, attach the physical device credentials contained in the secure element to a Zerynth Device Manager device identifierZerynth > Detach from ZDM
, detach the physical device credentials from the Zerynth Device Manager device identifierZerynth > FOTA
, prepare the current project for over the air update and send the update to the deviceZerynth > Go To ZDM
, open the Zerynth Device Manager web appZerynth > Device Page
, open the device page on the Zerynth Device Manager web appZerynth > Add Workspace
, create a new workspace in the Zerynth Device ManagerZerynth > Add Fleet
, create a new fleet of inside a Zerynth Device Manager workspaceZerynth > Add Device
, create a new device of inside a Zerynth Device Manager fleetZerynth > Logout
, log out