Skip to content

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:

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.
  • Cloud Device: ID of Virtual Device on zerynth cloud.
  • Provioning: Provisions 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.
  • Undo Provisioning: Disassociates a provisioned device from the related virtual device on the Zerynth cloud.
  • Launch 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.

let's have a look at how we can use the extension in doing the following operations

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

Once the example is cloned, VSCode shows a set of panels and terminals that are useful for working with the current project.

In the top half of the screen VSCode shows the source code of the project, represented by the file main.py. On the left, there are many panels, some are provided by VSCode, some by the Zerynth extension. In particular, the Zerynth Control Panel contains shortcuts to all the operations required to run a connected device.

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 disabled
  • warning: zinfo and zwarn keywords are effective, all the other keywords are disabled
  • error: zdebug is disabled, all the other keywords are effective
  • debug: all keywords are effective

Provisioning the device

Provisioning is a very important step that must be performed just once, before connecting any device to the Zerynth Device Manager. It consists of associating the device physical identity protected by the secure element with the device identity on the Zerynth Device Manager. 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 generates a signature by exploiting the capabilities of the secure element. The signature is then sent to the Zerynth Device Manager that, after verifying its authenticity, associates the physical identity with a Zerynth Device Manager device. The association is possible if the physical device is not already associated. In that case it must be deassociated first.

Once associated, the device can connect to the Zerynth Device Manager and begin to send data to the corresponding workspace.

All the steps above can be performed with a single click on the edit icon of the Provisioning in the Zerynth Control Panel. A popup window will be shown for selecting the Zerynth Device Manager device to associate with the physical one. If no devices are present in the workspace, one can be created from the VSCode popup.

Select a device to provision
Accept the confirmation dialog
Successful provisioning!
Updated control panel

Once a device is correctly provisioned, any project or example connecting to the Zerynth Device Manager will work out of the box. By clicking Cloud Device in the Zerynth Control Panel, the Zerynth Device Manager device page is opened in the browser, showing the device info.

Performing Over the Air Update (FOTA)

When the device is connected to the Zerynth Device Manager it is always possible to update the firmware remotely by sending a FOTA request. The device will download the new firmware and install 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.

More details on FOTA can be found here.

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 login
  • Zerynth > 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 content
  • Zerynth > Set Device Type, set the type of the physical device connected to the USB port
  • Zerynth > Device Pinmap, opens the device schematics in the browser
  • Zerynth > Device Documentation, opens the device documentation in the browser
  • Zerynth > Compile, produces an executable bytecode file compiling the current project for the physical device
  • Zerynth > Run, run the bytecode on the physical device
  • Zerynth > Console, open the serial port monitor for the physical device
  • Zerynth > Attach to ZDM, attach the physical device to a Zerynth Device Manager device identifier
  • Zerynth > Device Provisioning, attach the physical device credentials contained in the secure element to a Zerynth Device Manager device identifier
  • Zerynth > Detach from ZDM, detach the physical device credentials from the Zerynth Device Manager device identifier
  • Zerynth > FOTA, prepare the current project for over the air update and send the update to the device
  • Zerynth > Go To ZDM, open the Zerynth Device Manager web app
  • Zerynth > Device Page, open the device page on the Zerynth Device Manager web app
  • Zerynth > Add Workspace, create a new workspace in the Zerynth Device Manager
  • Zerynth > Add Fleet, create a new fleet of inside a Zerynth Device Manager workspace
  • Zerynth > Add Device, create a new device of inside a Zerynth Device Manager fleet
  • Zerynth > Logout, log out