Getting Started

This section introduces you to the main features of Zerynth and provides you a step-by-step guide to get started with the system.

Create a Zerynth User Account

It is necessary to create a User Account to access Zerynth.

To register a new Zerynth Account or to Log in an existing one, you can proceed manually (email, username and password) or you can automatically register/login with social credentials (Facebook and Google+).

Zerynth Login

Note

For Manual Registration: check your email and verify your new account by clicking on the link provided in the confirmation email

Warning

The first time you create a user account or if you have sign-in issues, a restart of Zerynth Studio might be necessary

Clone an example and start with Zerynth Python Scripts

Zerynth Studio includes many examples to get started: from the most basic ones to the examples related to the installed libraries. Zerynth examples cannot be edited, they are “read only” folders and they can be used as reference for the design of new projects.

Zerynth examples can be cloned in just few clicks:

  1. open the Examples browser by clicking on the “light bulb” icon on the left panel of Zerynth Studio;
  2. select the example you prefer and clone it by clicking on the dedicated button;
  3. At this stage Zerynth converts the example into a new project giving you the possibility to edit the Title, the Description and the Folder of your new project project;
  4. click on “Create” and you are done!
Clone Example

Warning

Remember that Zerynth does not allow two projects to have the same Folder

Connect, Register and Virtualize your Device

To make a device usable with Zerynth, you need to “Virtualize” it. The “Virtualization” is the process of installing the Zerynth Virtual Machine by flashing it on a device. When launched, Zerynth Studio checks the connected peripherals and shows all the available devices on the Device Management Widget.

Zerynth Studio toolbar allows to “Virtualize” the selected device. The supported devices are grouped into Physical Devices (the ones physically connected to the local machine) and Target Devices (the devices usable with Zerynth).

Zerynth supports the devices, chips and architectures reported in the Supported Devices section.

Warning

Don’t forget to install the devices drivers following the procedures reported in Supported Devices.

The Zerynth “Target Devices” feature allows code verification on all the supported devices, without having them physically connected to the local machine.

Choose Target Device

Once one of the supported devices is connected, Zerynth Studio automatically recognizes it. The system then generates the unique Zerynth Virtual Machine for that registered device, which is now ready for the “Virtualization”.

To register a new device, you can follow these steps:

  1. connect your device to the machine. The “Devices Management Widget” notifies the devices list update with a yellow blink;
  2. select the device from the dropdown menu;
  3. click on the “Zerynth” button. Zerynth Studio will guide you in the entire process through info messages displayed in the log console section at the bottom of the screen. Some devices require to be set in Device Firmware Update (DFU) mode in order to allow their registration and the flashing of the Zerynth Virtual Machine. Detailed guides on how to put them in DFU mode is available in the Supported Devices section of the documentation.

The Device Info Window shows detailed information about the device, including the Flash/Ram size and the port for serial communication.

Device Info

Warning

Some boards cannot be automatically recognized by Zerynth Studio and need a disambiguation. In this case the system asks you to indicate the device type. You can always revert this choice by clicking on the “Forget” button.

Finally, the Device Pinmap window provides the pinout of the selected device, along with the hardware features and peripherals available on each pin. Thanks to the Device Pinmap window it is also possible to understand how the device embedded peripherals are grouped and/or multiplexed. This allows to better understand how to use each specific hardware feature in the Zerynth Python scripts without having hardware conflicts.

Device PinMap

Once the device is registered and connected to the machine (and if needed in DFU mode), you can follow these instructions to “Virtualize” your device:

  1. click on the “Zerynth” button;
  2. Select the Zerynth Virtual Machine from the available list and Zerynth will generate it;
  3. click again on the “Zerynth” button to “virtualize” the device. You are now ready to program your device.

Develop your First Zerynth Project

To create your First Zerynth Project you have to do just few steps:

  1. click on the button “Browse Project”;
  2. click on “New Project”;
  3. Decide a project title and the project folder, and write an optional description;
  4. click on the “Create” button.

Once you click on the “Create” button, the new Zerynth Project opens and you will be prompted with the editor of the “main.py” file. The main is where the principal Zerynth code is written in Python: here is where you develop the logic of your script.

Create Project

If you wish to add more files to the Zerynth project you can easily do it. In Zerynth you can create html, json, txt, bin files and save them together with the bytecode on the device flash memory. You can also create more .py files where you can develop other parts of your code like modules and functions to be used in the main.py file.

To add new files to a Zerynth project, follow these steps:

  • click on “Browse Project”;
  • click on “Add file” ;
  • after naming the file click on “Create”;
  • write the code within the empty field in the editor;

You can also add a new folder, delete a selected file, refresh the project folder, etc. by clicking the icon on the right of the “Project view” bar.

Project Actions

Note

When you add a .py file containing some code to be used in the main.py file (e.g. a file named helpers.py), you have to import it by adding the line import helpers in the main.py file. Thus, you can call functions located in the helpers.py file by using the following syntax:

helpers.fun_name(fun_attribute1, fun_attribute2, ...)

Note

If you want to save the template.html in the device flash as resource to be used by a specific module like the Zerynth App library, you have to use the new_resource() function defining the following code in the main.py file:

new_resource("template.html")

Search and Install Packages

Zerynth is a modular suite that can be easily extended to fit your purpose by adding new libraries, device packages and modules.

The Zerynth Package Manager (ZPM) is the engine that allows users to customize the setup of Zerynth by installing and organizing just the necessary modules and packages.

The ZPM handles packages installation, upgrades, removal and downgrades, along with the automatic resolution of package dependencies. The ZPM is accessible through the “puzzle” icon located in the left panel of Zerynth Studio.

To search and install new packages on your Zerynth Studio installation, you have to select the Zerynth Package Manager Section (“puzzle” icon) on the left toolbar. In this section you can search in your installed packages or in all the Zerynth repositories the packages you need.

In the screenshot below, the MQTT library has been searched among all available Zerynth packages by typing the keyword “MQTT”.

The results of the search are shown in the left column that displays a brief description of the found packages along with the related last available version; by clicking on the “install” button you start the package installation.You can also discover the package features through the “Docs” button.

Search and Install Package

Note

To update manually an already installed package you just have to install again the package; Zerynth Studio will overwrite the old version of the package

Import a Zerynth Package into a Project

Packages import syntax is very simple:

  • Official Packages are imported with: from c import m where c is the name of the package and m is the name of a module inside the package. (e.g. from cc3000 import cc3000 or from cc3000 import cc3000_tiny).
  • Community Packages are imported with: from community.b.c import m where b is the namespace of the package, c is the package name and m is the name of a module (e.g. from community.floyd.rtttl import rtttl)

The import autocomplete feature of Zerynth Studio makes the task of importing modules even easier: as soon as “from” or “import” is typed in the code editor, the autocomplete box lists all the matching modules.

The Zerynth Programming Guide and various programming examples are also provided.

For both the Official Library and the Community Library, a complete documentation is available and if the package contains usage examples, they can be found under the examples tab.

Finally, if you need help with Python, here you can find a good overview on Python 3 with simple and exhaustive examples.

You can always post your questions and doubts on the Zerynth Community Forum logging-in with your Zerynth Account.

Zerynth Studio update

When one or more packages installed on your pc are available, a notification “System Update!” will appear in the footer area of Zerynth Studio. By clicking the notification, the system will inform you, through a popup detailed list, about which of your installed packages have a new release; upon confirmation the system will update the available packages.

Zerynth Studio Update Message

Zerynth and Git

Zerynth Studio offers the possibility to store your projects on our backend, in a private git repository. Such feature is accessible from the Project View in the left panel by clicking the git “code-branch” icon.

Zerynth Studio Git

The first time a project is pushed to our backend, the “Create repository” option must be selected. From there on, the project view changes, showing a footer with information about the current remote/branch, the current tag if present, the number of modified files (identified by a bullet) and the status of the local repository with respect to the remote repository.

The project git repository is automatically configured with a remote called “zerynth” pointing to our backend. All git operations accessible from Zerynth Studio will operate on that remote. It is however possible to manually configure the project local repository to use different remotes (for example GitHub or GitLab). However, such configuration is up to the user.

Git operations not featured in Zerynth Studio (for example “merge”), can be performed manually using git from the command line.

Library Publishing

Zerynth Studio allows publishing your projects as library packages that can be used by everyone else in the Zerynth community. To publish a project, select the “Publish” option for the currently opened project to start the publish wizard.

The first wizard dialog asks for basic package information, namely the fullname and the repository to publish to.

Publishing Step 1

To form a valid fullname a namespace is needed. If you don’t already own a namespace, one can be created easily from the dropdown option “Create New...”. The package name is also important, it will determine how the library is imported once installed.

The second publishing step needs the specification of library title, description and keywords. Good titles and descriptions, together with keywords allow your library to be appear in the search results of other users more easily.

Publishing Step 2

The third and last step needs you to fill in the library information that varies with each library update, namely the version, the dependencies with other packages and a short description of what has changed with respect to the previous version. Dependencies are automatically calculated, while allowed versions are grouped in the version dropdown. All Zerynth version strings follow the Semantic Versioning scheme and it is up to the user to get them right.

Publishing Step 3

After the third step two things happen:

  • The project view changes showing library fullname and version
  • The newly published library is queued for review. Our team will come back to you only in the rare case something needs to be changed in your library, otherwise you will receive an email notification as soon as the library is made public.
Publishing Results

Important

In order for the users of your library to have a better programming experience, we strongly suggest to add examples and documentation. Please refer here for more details.