.. _ViperIDE: **************** 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. .. figure:: /custom/img/ide.png :align: center :figwidth: 700 :alt: ZERYNTH IDE 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: .. figure:: /custom/img/ide_shortcuts.png :align: right :alt: ZERYNTH ide_shortcuts * 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. .. figure:: /custom/img/ZERYNTH_IDE-Switch-Project-View.gif :align: center :figwidth: 700 :alt: ZERYNTH IDE Projects 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. .. figure:: /custom/img/ide_examples.png :align: center :figwidth: 700 :alt: ZERYNTH IDE Examples 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. .. figure:: /custom/img/ide_projects.png :align: center :figwidth: 700 :alt: ZERYNTH IDE Projects 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. .. figure:: /custom/img/ZERYNTH_IDE-verify_clean_debug.png :align: center :figwidth: 700 :alt: ZERYNTH IDE upload In the `getting started `_ section a dedicated tutorial on how to verify, upload and debug a ZERYNTH project is available. Board Management Toolbar ======================== Through the ZERYNTH IDE **Boards Management Bar** all the connected devices can be managed. The **Boards Management Bar** can be used for Virtualizing the connected boards by uploading on them the ZERYNTH Virtual Machine. Moreover, all the ZERYNTH supported boards are listed also if not connected as *Virtual Boards* allowing code verification for specific platforms without requiring physical connection. When launched, the ZERYNTH IDE starts a Python local server that controls the connected peripherals showing all the available boards on the **Boards Management Bar**. .. figure:: /custom/img/ChooseBoard-ZERYNTH-IDE.png :align: center :figwidth: 400 :alt: ZERYNTH IDE upload From the **Boards Management Bar** it is possible to select the board where the **Current Project** will be uploaded. Moreover, it is also possible to open a serial consoles that will be automatically configured with the port number and parameters required by the selected board. The **Boards Management Bar** also includes a **Board Info Window** where the selected board pinout, features and details are provided. More info about board pin mapping, features and pin naming can be found in the ZERYNTH supported board section. The **Board Info Window** also allow to assign all the connected board with different names and IDs. .. The **Board Info Window** also allows to define specific pin labels that allow to write real cross-platform ZERYNTH scripts. For example, let’s take the case of a ZERYNTH script that uses one PWM and one ADC and has to be run on an Arduino DUE and on a Particle Core. These two boards have different footprints but both have all the required features. If the user needs to connect the PWM on Arduino D3 and on Spark D1 can do this through the **Board Info Window** instead of writing an IF check that verifies on which board the script is loaded and assigns specific pin numbers to the required pin labels. .. User can open the **Board Info Window** and add the label *My_PWM* on Arduino DUE pin D3.PWM and on Spark Core pin D1.PWM. Now the *My_PWM* label is the generic PWM pin name to be used in the ZERYNTH script. Please refer to the programming guide section for more details on how pin names and functionalities are organized in ZERYNTH. .. To accomplish such behaviour, the ZERYNTH IDE generates a *board_cfg.py* file that will be included in the project and used by the compiler to translate the pin names in the board specific pins IDs. In the `getting started `_ section a dedicated tutorial on how to manage ZERYNTH supported boards 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. .. figure:: /custom/img/ide_console.png :align: center :figwidth: 700 :alt: ZERYNTH IDE Console 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. .. figure:: /custom/img/ZERYNTH-degugger-project.gif :align: center :figwidth: 700 :alt: ZERYNTH Integrated Debugger 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). .. figure:: /custom/img/ZERYNTH-exception-info.png :align: center :figwidth: 700 :alt: ZERYNTH Integrated Debugger 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. .. figure:: /custom/img/zpm-toolbar-icon.gif :align: center :figwidth: 700 :alt: ZPM-toolbar-icon.gif 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”. .. figure:: /custom/img/zpm-install-toishield.gif :align: center :figwidth: 700 :alt: ZPM-install-toishield.gif 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. .. figure:: /custom/img/ZERYNTH-news.png :align: center :alt: ZERYNTH-news 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 .. figure:: /custom/img/lib-create-dialog.png :align: center :figwidth: 700 :alt: Create a library 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. .. figure:: /custom/img/lib-publish-1.png :align: center :figwidth: 400 :alt: Start publishing Then a set of examples from the existing projects is selected. .. figure:: /custom/img/lib-publish-2.png :align: center :figwidth: 400 :alt: Select examples The next dialog shows the automatically calculated library dependencies. A library can not be published if it depends on other unpublished or local libraries. .. figure:: /custom/img/lib-publish-3.png :align: center :figwidth: 400 :alt: Dependencies 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. .. figure:: /custom/img/lib-publish-4.png :align: center :figwidth: 400 :alt: Versions 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. .. figure:: /custom/img/lib-publish-5.png :align: center :figwidth: 400 :alt: Github