The ZERYNTH IDE¶

ZERYNTH is integrated with a dedicated development environment. The ZERYNTH IDE is a browser based development environment that runs on Windows, Linux and Mac.

Through the ZERYNTH IDE all the supported boards can be managed and the corresponding programs can be developed in Python 3. Projects developed with the ZERYNTH IDE can be saved locally or synced with the ZERYNTH cloud.

The ZERYNTH IDE includes:

A code editor with syntax highlighting, multi-tab support, code auto-completion and error highlighting feature;
An integrated compiler;
A smart uplinker with modular structure;
A board discovery and management toolbar;
An integrated debugging console and serial port monitor with search and auto connect features;
A project database with tagging and search features;
A local git storage with cloud syncing feature;
An HTML 5 editor for ZERYNTH App templates design (soon);
Themes support;
Auto-update engine;
Direct project publishing/forking on GitHub (soon);
Integrated Off-Line documentation, and board feature and pin mapping info window,
Integrated use tutorial;
Tens of code examples-

Code Editor¶

The ZERYNTH IDE integrates a code editor based on Code Mirror, one of the most used open source browser-based text editor.

The ZERYNTH IDE supports multi-tab giving the possibility to have various files opened in parallel. Opened files can belong to different projects allowing a high code reusability and integration.

The code editor includes a text editing toolbar and provides the following short-cuts:

ctrl+c/ctrl+v/ctrl+x: copy/paste/cut
ctrl+z/ctrl+y: undo/redo
ctrl+f: find
ctrl+g: find next
ctrl+shift+g: find previous
ctrl+shift+f: replace
ctrl+q: comment/uncomment selected lines
alt+Up: indent more
alt+Down: indent less

Projects Browser¶

The project browser panel is where all the user’s available projects are listed. It can be opened from the left toolbar dedicated button.

The project list view can be switched from by name to by tag (respectively left and right snapshots of the following image) using the dedicated button located on the top right side of the Projects Browser.

Through the plus button new projects can be created.

From this panel it is possible to sync all the user’s projects with the ZERYNTH Cloud remote repository in a click. The Sync All procedure will check the status of each project and will do the following:

If a local project is not on the cloud, it is created and loaded,
If a local project is newer than its remote version the project is uploaded,
If a remote project is newer than its local version the projects is downloaded,
If a local project is not aligned with its remote version (e.i the project has been modified locally from two different machines) the IDE notifies the user that a manual intervention is required showing a dedicated window on which the conflict can be solved.

In the getting started section a dedicated tutorial on how to use create and mange ZERYNTH projects is available.

Example Browser¶

The ZERYNTH IDE integrates an example browser from which ZERYNTH official examples can be cloned. ZERYNTH examples can’t be edited in order to avoid involuntary modifications.

In the getting started section a dedicated tutorial on how to use clone ZERYNTH examples is available.

Opened Projects Panel¶

The Opened Projects Panel shows all the currently opened projects labeled with different colours.

Opened files are shown on the editor as tabs marked with the colour of the project they belong to.

The Current Project (Hello ZERYNTH i is the project the user is working on and it is always marked with Green ZERYNTH colour).

The Current Project is the one that will be compiled and uploaded on the selected board by using the related buttons. Moreover, from the compile button window is also possible to clean the project forcing a complete recompile and also open the ZERYNTH debugger (See the dedicated section below for more details).

Files from non-current opened projects allow code selection and copy only, editing is locked.

It is always possible to switch the Current Project among the opened projects in order to enable editing, code verifying or uploading.

By clicking the plus button a new file is added to the current project.

Current Project is automatically saved into local git repository. If the user is logged into the ZERYNTH Cloud, the Current Project can be also manually synced with the ZERYNTH cloud repository using the “send” and “get” cloud buttons.

In the getting started section a dedicated tutorial on how to verify, upload and debug a ZERYNTH project is available.

System Messages and Serial Console¶

The ZERYNTH IDE also includes a System Messages Panel on which all the compiler, debugger and server messages are reported.

Moreover a Serial Terminal Console is also integrated in the right bar. The ZERYNTH IDE supports multiple Serial Terminal Console opened in parallel. Various projects output can be monitored from the same panel switching between the opened tab.

When a Serial Terminal Console is opened it is automatically configured to open the serial port assigned to the selected board (USB OS assigned serial port). The IDE console baud-rate is set by default at different values depending on the selected board. The baud rate for a board is displayed during bytecode upload. This console has to be considered as an integrated debugging output to be used with the ZERYNTH default print function.

To read a board serial port configured with a different baudrate an external serial port terminal like Putty should be used. Any other external port terminals can conflict with the ZERYNTH Serial Terminal Console. Users should close the Serial Terminal Console before launching any other external terminals.

The ZERYNTH IDE serial console also has scroll lock holding, delete all and find-in features (ctrl+f on the console).

ZERYNTH Integrated Debugger¶

To analyse programs behavior without crashing the execution, ZERYNTH has builtins support for exceptions: a typical feature of Python. The example “Exception-Debugger Basics” shows how a “division by zero” is identified in the code without causing any crash.

Exceptions can be detected in a program and printed to the console. The console is able to recognize printed exceptions marking them with an error icon. By clicking such icon, the exception explorer activates, showing the exception traceback (up to the fourth level of calls).

If a different serial port is used to print exceptions, the “exception coordinates”, i.e. the exception message following “@”, can be copied to the exception explorer to obtain the traceback.

Moreover, from the debug window it is also possible to inspect the ZERYNTH bytecode giving users access to low level details of the ZERYNTH VM.

ZERYNTH Package Manager¶

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 possible dependencies between packages. Moreover, you can read the changelog of the package version clicking on the “info” icon. In addition, the “lib” packages can be enabled or disabled.

The ZPM is accessible through the puzzle icon located in the left bar of the ZERYNTH IDE. The ZPM toolbar is composed of a set of icons that help you sorting and filtering the packages according to how the packages are rated, downloaded and released. Various view for navigating the available ZERYNTH packages are selectable. The right side icon displays the installed packages with available updates.

Within each of these views it is possible to search the packages to install. In addition it is possible to filter the search results by clicking on the “setting” icon on the left of the search bar.

In the getting started section a dedicated tutorial on how to use the ZPM is available.

To search and install a package:

click on the “Package Installer” icon of the left toolbar.
click on the “Search” icon of the ZPM toolbar.
type your query in the form. In this case we want to use the TOI Shield library.
click on the “Install” icon in the package view.
click on “Install”.

ZERYNTH News¶

The ZERYNTH IDE is also a tool to stay connected with the ZERYNTH community. On the left bar, the ZERYNTH News tab can be accessed. It displays the latest news available in the forum about packages, updates, releases and bug fixes.

Creating and publishing libraries¶

It is possible to create user libraries and publish them to the ZERYNTH Package Manager database.

To create a library, select the “Library” tab in the create project dialog. For a library to be successfully created the following info is required:

namespace: a namespace is a unique name identifying a particular developer (or group of developers). The namespace is used by the ZERYNTH Package Manager to correctly assign a library to its owner. A special namespace “local” is used for libraries that are not going to be published online and will live only in the current instance of ZERYNTH.

path: the library path is a name indentifying the Python library and together with the namespace is used to correctly import modules from the library.

keywords: keywords, together with description and title will be included in the package textual information (used by the package search engine) once the library is published

A library is created with the following files:

main.py: it is equivalent to the main.py file for projects. However, when the library is published, the main.py file is not included in the package. Its purpose is just to contain the code used to test the library.

a file named as the library path, which contains the library code.

docs/docs.json: it contains info on how to build the library documentation.

docs/index.rst: the index of the library documentation.

readme.md: a readme containing the library description.

Library Documentation¶

Each library can have its own documentation. Documentation can be spread across multiple files. reStructureText files (.rst), Python files (.py), C files (.c and .h), JSON files (.json) can all contain documentation info. The final documentation is built following these rules:

docs/docs.json is read and the files specified in the “files” section are scanned for info

if the file has a .py extension, Python docstrings are extracted to generate the corresponding .rst file

if the file has a .rst extension, it is included without modification

if the file has a .c or .h extension, all Doxygen style comment blocks are extracted and the corresponding .rst is generated

if the file has a .json extension, it is processed in the same way of docs/docs.json.

each file specified in docs/docs.json is used to generate a __toc.rst file that can be included in any .rst file to render the main documentation table of contents

each .json file will generate a corresponding .rst file containing the table of contents build from the “files” field. Before the table of contents, an optional text can be defined by adding a “text” field in the json file

The following file is the docs.json used to build the ZERYNTH standard library documentation:

{
   "version":"0.3.2",
   "title":"ZERYNTH Programming Guide",
   "copyright":"ZERYNTH Team",
   "files":[
      ["Python Basics","quickpython.rst"],
      ["Pin Mapping","pin_mapping.rst"],
      ["Standard Library","stdlib.json"],
      ["C Language Interface","clang.rst"]
   ]
}

The “title” field will be used to generate the documentation main title. The “files” field is a list of pairs where the first element is the title given to the documentation contained in the second element. Such configuration will create a documentation with four sections. The “Standard Library” section is generated by parsing the stdlib.json file:

{
   "title":"ZERYNTH Standard Library",
   "text":"The ZERYNTH standard library is composed of many modules ranging from hardware interfaces to high level functionalities.",
   "files":[
    ["Builtins","__builtins__.py"],
    ["ADC","adc.py"],
    ["PWM","pwm.py"],
    ["ICU","icu.py"],
    ["Hardware Timers","hwtimers.py"],
    ["I2C","i2c.py"],
    ["SPI","spi.py"],
    ["Garbage Collector","gc.py"],
    ["Streams","streams.py"],
    ["Multithreading","threading.py"],
    ["Timers","timers.py"],
    ["Wireless","wireless/wifi.py"],
    ["JSON","json.py"],
    ["MsgPack","msgpack.py"],
    ["Sockets","socket.py"],
    ["HTTP","requests.py"],
    ["urlparse","urlparse.py"],
    ["Fifo","fifo.py"]
   ]
}

The stdlib.rst file is created from stdlib.json and will containing all the docstrings extracted from the Python files.

Documentation can be built from the dropdown of the Verify button (Compile Docs) and once created, can be viewed with the View Docs button.

Library Usage¶

User libraries can be used from projects by simply importing them. The import syntax has some rules:

from local.path import module_name: import from a local user library with path path a module called module_name

from community.namespace.path import module_name: import from library with namespace namespace and path path a module called module_name. The library has been assigned to a non local namespace that can’t be changed.

Library Publishing¶

Publishing a user library means creating a package, validating it through the ZERYNTH Package Manager and sharing it with all the ZERYNTH community. The requisites for library publishing are:

having an approved namespace. A namespace can be generated during library creation, however it must be approved by the ZERYNTH admins before it can be used to publish a library

having a Github account where to host the library code

successfully completing the publishing procedure from the IDE

having the library reviewed and added to the package database by a ZERYNTH admin

Before publishing a library it is important to compile the documentation and check it thoroughly. It is also important to prepare a couple of examples to be included in the package. Examples are normal projects that make use of the library.

The IDE has a simple wizard for library publishing; it is accessed from the dropdown of the Verify Project button.

Then a set of examples from the existing projects is selected.

The next dialog shows the automatically calculated library dependencies. A library can not be published if it depends on other unpublished or local libraries.

A version must be assigned to the library. The first time, two possible versions are available:

0.1.0: to convey that the library is still in “beta”

1.0.0: to convey that the library is mature and stable

If the library is published a second time, three possible versions are available:

a bugfix version with only the third digit increased (x.y.z+1)

a backward compatible version with the second digit increased (x.y+1.0)

a non backward compatible version with the first digit increased (x+1.0.0)

It is the most important responsibility of the library owner to ensure that the version is correct, so that no dependency is broken.

Afterwards, Github credentials are asked. A repository with the given name is created (if not existing) and the library code pushed to it. The Github repository is configured in such a way that everytime a new version is pushed, the ZERYNTH Package Manager gets notified. Every version must be reviewed before becoming publicly available. A series of automated email will detail the review process.