The Viper IDE¶
Viper is integrated with a dedicated development environment. The Viper IDE is a browser based development environment that runs on Windows, Linux and Mac.
Through the Viper IDE all the supported boards can be managed and the corresponding programs can be developed in Python 3. Projects developed with the Viper IDE can be saved locally or synced with the Viper cloud.

The Viper 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 Viper 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 Viper IDE integrates a code editor based on Code Mirror, one of the most used open source browser-based text editor.
The Viper 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 Viper 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 Viper projects is available.
Example Browser¶
The Viper IDE integrates an example browser from which Viper official examples can be cloned. Viper examples can’t be edited in order to avoid involuntary modifications.

In the getting started section a dedicated tutorial on how to use clone Viper 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 Viper i is the project the user is working on and it is always marked with Green Viper 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 Viper 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 Viper Cloud, the Current Project can be also manually synced with the Viper 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 Viper project is available.
Board Management Toolbar¶
Through the Viper IDE Boards Management Bar all the connected devices can be managed. The Boards Management Bar can be used for Viperizing the connected boards by uploading on them the Viper Virtual Machine. Moreover, all the Viper supported boards are listed also if not connected as Virtual Boards allowing code verification for specific platforms without requiring physical connection.
When launched, the Viper IDE starts a Python local server that controls the connected peripherals showing all the available boards on the Boards Management Bar.

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 Viper supported board section.
The Board Info Window also allow to assign all the connected board with different names and IDs.
Please refer to the programming guide section for more details on how pin names and functionalities are organized in Viper.
In the getting started section a dedicated tutorial on how to manage Viper supported boards is available.
System Messages and Serial Console¶
The Viper 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 Viper 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 Viper 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 Viper Serial Terminal Console. Users should close the Serial Terminal Console before launching any other external terminals.

The Viper serial console also has scroll lock holding, delete all and find-in features (ctrl+f on the console).
Viper Integrated Debugger¶
To analyse programs behavior without crashing the execution, Viper 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 Viper bytecode giving users access to low level details of the Viper VM.
Viper Package Manager¶
The Viper Package Manager (VPM) is the engine that allows users to customize the setup of Viper by installing and organizing just the necessary modules and packages.
The VPM 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 VPM is accesible through the puzzle icon located in the left bar of the Viper IDE. The VPM 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 Viper 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 VPM 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 vpm 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”.

Viper News¶
The Viper IDE is also a tool to stay connected with the Viper community. On the left bar, the Viper 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 Viper 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 Viper 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 Viper.
- 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 Viper standard library documentation:
{
"version":"0.3.2",
"title":"Viper Programming Guide",
"copyright":"Viper 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":"Viper Standard Library",
"text":"The Viper 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 Viper Package Manager and sharing it with all the Viper 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 Viper 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 Viper 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 Viper Package Manager gets notified. Every version must be reviewed before becoming publicly available. A series of automated email will detail the review process.
