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+).
For Manual Registration: check your email and verify your new account by clicking on the link provided in the confirmation email
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:
- open the Examples browser by clicking on the “light bulb” icon on the left panel of Zerynth Studio;
- select the example you prefer and clone it by clicking on the dedicated button;
- 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;
- click on “Create” and you are done!
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.
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.
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:
- connect your device to the machine. The “Devices Management Widget” notifies the devices list update with a yellow blink;
- select the device from the dropdown menu;
- 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.
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.
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:
- click on the “Zerynth” button;
- Select the Zerynth Virtual Machine from the available list and Zerynth will generate it;
- 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:
- click on the button “Browse Project”;
- click on “New Project”;
- Decide a project title and the project folder, and write an optional description;
- 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.
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.
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, ...)
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
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.
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 mwhere c is the name of the package and m is the name of a module inside the package. (e.g.
from cc3000 import cc3000or
from cc3000 import cc3000_tiny).
- Community Packages are imported with:
from community.b.c import mwhere 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 updates¶
Zerynth Studio has two different update mechanisms:
- major system release
- rolling updates
When a new major version of Zerynth is released a notification “System Update!” will appear in the footer area of Zerynth Studio. By clicking the notification, the new version will be downloaded and installed. After a restart, the new version will be selected and launched. However, the previous version is still there and can be selected during the launch phase. If a previous version is not needed anymore, it can be deleted from the “Preferences” menu.
On the contrary, rolling updates do not change the system version but just a group of packages. Rolling updates are notified by the “Rolling update” label in the footer area of Zerynth Studio. By clicking the notification, the list of updated packages and a detailed changelog are displayed. If accepted, a rolling update will download the selected packages only and will unpack them. After a restart, the launcher will take care of finishing the update and start Zerynth Studio.
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.
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.
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.
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.
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.
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.
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.