Package: openvisualizer
OpenVisualizerOpenVisualizer (OV) is part of UC Berkeley's OpenWSN project. It provides monitoring, visualization and simulation of OpenWSN-based wireless sensor network. See the projecthome pagefor more information. The project works in tandem with the OpenWSN firmware hosted atopenwsn-fw. OpenVisualizer interfaces with locally connected hardware, the OpenTestBed infrastructure,IoT-LABor an emulated OpenWSN network.Table of ContentsInstallationSetting up the virtualenvInstalling on OSX or LinuxInstalling on WindowsDevelopersArchitectureOpenVisualizer ServerOpenVisualizer ClientManualQuick StartHardwareSimulation modeIoT-LABOpenTestBedDocumentationTestingContributingContactInstallationOpenVisualizer is distributed throughPyPi. The only thing you need is a working Python 2.7 installation and pip. We recommend installing OpenVisualizer in a virtual environment. It makes it easier to manage multiple Python projects which require different Python versions and if something goes wrong you can simply delete the virtual environment without affecting your OS.Setting up the virtualenvInstall the virtualenv package, in case you do not already have it:$pipinstallvirtualenvCreate a virtual environment (the name can be anything, here we use the namevenv):$python-mvirtualenv<NAME_OF_YOUR_VIRTUAL_ENV>Once installed you need to activate the virtual environment. On Linux or OSX:$sourcevenv/bin/activateOn Windows (instructions have been tested for Windows CMD only):$.\venv\Scripts\activateInstalling on OSX or LinuxOnce you have your virtual environment set up you can simply install OpenVisualizer as follows:(venv)$pipinstallopenvisualizerPip will download and install all the dependencies.Installing on WindowsOn Windows the instructions are:(venv)$pipinstallopenvisualizerAfter installing OpenVisualizer you need to remove the packagepyreadline. The latter is a dependency of thecoloredlogspackage which is used to enabled colored logging output in OpenVisualizer. However, thepyreadlinepackage is outdated and buggy on Windows 10. To prevent issues, you should remove it, the log coloring will still work withoutpyreadlineinstalled.(venv)$pipuninstallpyreadlineDevelopersIf you wish to develop for OpenVisualizer or mess around with the code, you should follow these steps:Setup a virtual environment (as described above) and activate the environmentClone the repository(venv)$gitclonegit@github.com:openwsn-berkeley/openvisualizer.gitCheckout the appropriate branchMove to the root of the git repository and install the tools(venv)$pipinstall-e.The last command will locally install the Python package in an editable form. If you change your Python code the package will automatically use your new code.ArchitectureThe architecture of OpenVisualizer is split into two main components:OpenVisualizer ServerOpenVisualizer ClientOpenVisualizer ServerTheOpenVisualizer Servercontains all the code to interface with a mesh network consisting of motes running the OpenWSN firmware. The server can interact with locally connected hardware or with a networks deployed onIoT-LABor the OpenTestBed. Alternatively, the server can simulate a network and run the firmware code on emulated motes, locally on your computer. To achieve mote emulation, the OpenWSN firmware is compiled as a Python C extension. Mote emulation is particularly useful when you don't have hardware at hand or for debugging purposes. Inside theopenvisualizerPython package there are several subpackages. All of the subpackages, with exception of the package calledclient, implement different parts of theOpenVisualizer Server. Some important features are:motehandler:interfaces directly with the motes and the network. It allows other components of theOpenVisualizer Serverand theOpenVisualizer Clientsto communicate with the individual motes. In parallel, themotehandlerpackage maintains important status information about each mote in the network and provides parsing of the network and mote logging output.jrc:provides an implementation of the "Join Request Proxy". The JRC plays an important role when nodes want to join an existing network securely.rpl:implements RPL source routing for the mesh and provides the user with network topology information.opentun & openlbr:are packages that parse network traffic between the mesh and the Internet. Theopentunpackage specifically allows OpenVisualizer to route network traffic between the Internet and the mesh.TheOpenVisualizer Serveralso serves as a remote procedure call (RPC) server. It exposes a set of methods that are used byOpenVisualizer Clientsto inspect, monitor and manipulate the network or individual motes.OpenVisualizer ClientThere are two types of clients: theterminal clientand theweb interface client. Both clients are started with the same command and connect to theOpenVisualizer Server. They subsequently use RPC calls to interact with the network and the motes. They query the server for network and mote status information and display the results either directly in the terminal or through the web interface.The image below shows an instance ofOpenVisualizer Server(on the left), and five connectedOpenVisualizer Clients(on the right). Each client displays information about a specific mote, i.e., the neighbor table, the TSCH schedule, the packet queue pressure, general mote information, and MAC-layer statistics.ManualQuick StartPrerequisitesOpenVisualizer depends on the firmware code hosted in theopenwsn-fwrepository. Before you can run OpenVisualizer you should clone you theopenwsn-fwand define an environment variable calledOPENWSN_FW_BASEwhich points to the root of your localopenwsn-fwdirectory.$gitclonegit@github.com:openwsn-berkeley/openwsn-fw.git
$exportOPENWSN_FW_BASE=<PATH_TO_OPENWSN-FW>Alternatively you could use the--fw-pathoption when you launch theOpenVisualizer Server.UsageThere are two basic commands:openv-serveropenv-clientopenv-serverTheopenv-servercommand starts theOpenVisualizer Server. Depending on the provide options it will:Scan the local serial ports (/dev/tty*on Unix orCOM*on Windows) for connected hardware, seehardwareLaunch an emulated mesh network, seesimulationConnect toIoT-LAB, seeiotlabUse Inria's OpenTestBed, seeopentestbedAll the available options can be listed with the following command:(venv)$openv-server--helpopenv-clientTheopenv-clientcommand can change the parameters of the network and the server of display information. It takes several options and subcommands. More information can be displayed as follows:(venv)$openv-client--helpMostopenv-clientcommands will issue a single call to theOpenVisualizer Serverand exit immediately. For example the following command sets the mote with identifier AF8B, as the DAG root of the network.(venv)$openv-clientrootAF8BWe try to set mote 0001 as DAG root by running theopenv-client rootcommand. During the first attempt the OpenVisualizer Server is not active and the command fails. We then start a server instance in another terminal window and retry our command. This time the command is successful.Other useful commands are:boot: only available when the server is running a simulated network and when the emulated motes have not yet booted. By default the server will immediately boot the emulated motes, but you can change this behavior by adding the--no-bootoption.motes: lists the addresses of the connected motesThe addresses of the emulated motes before the network was formed and after network formation.shutdown: kills the serverThe final subcommand of theopenv-clientis calledview. It can display several types of mote or network status information. You can list the differentviewsas follows:(venv)$openv-clientview--helpEachviewcommand works in the same way. It starts a thread that periodically queries the server for a specific bit of information for a specified mote. It then displays this information nicely by using the Python packageblessed, a wrapper around the Pythoncursesmodule, or through the web browser (when you use theviewcalledweb).  The option--refresh-rate=<x>(not available for theweb view) can change how often theviewis updated, i.e., queries theOpenVisualizer Server(default is 1s).The top terminal panel shows the output of the OpenVisualizer Server. On the bottom there are two active views, schedule and neighbors, each in there own terminal panelIn the bottom-left terminal panel:(venv)$openv-clientviewschedule0001In the bottom-right terminal panel:(venv)$openv-clientviewneigbors0001The web view can be started as follows:(venv)$openv-clientviewwebWeb view (main tab)Web view (topology tab)HardwareSimulation modeIoT-LABPrerequisitesA valid IoT-LABaccountA set of flashed nodes. You can flashIoT-LABdirectly on the web interface or through their CLI tools. (refer to IoT-LABdocumentationfor this)UsageIts possible to connect theOpenVisualizer Serverwith theIoT-LABinfrastructure. A depiction of how the connection is set up can be found below.IoT-LAB connectionsWhen OpenVisualizer is not running on the SSH frontend (see figure above) a ssh-tunnel is opened to connect
to the IoT-LAB motes' TCP port.You can specify the motes to connect to by using the--iotlab-motesoption, it receives a list of IoT-LAB motes'network_addresses(e.g.,m3-4.grenoble.iot-lab.info).WhenOpenVisualizer Serverruns directly on the SSH frontend you can use the short address notation, e.g.,m3-4.SSH frontend:(venv)$openv-server--iotlab-motesm3-4m3-5.Locally:(venv)$openv-server--iotlab-motesm3-4.grenoble.iot-lab.infom3-5.grenoble.iot-lab.infoYou can authenticate toIoT-LABupfront by running:(venv)$iotlab-auth-u<login>Otherwise you need to pass your username and password as additional parameters:(venv)$openv-server--iotlab-motesm3-10m3-11--user<USERNAME>--password<PASSWORD>OpenTestBedRunning theOpenVisualizer Serveras a frontend for the OpenTestBed is as simple as:(venv)$openv-server--opentestbedThe server connects in the background to the MQTT server that gathers the data from the testbed and subscribes to the appropriate topics.DocumentationThe docs can be generated through Sphinx. Navigate to the root of the project and run the following the command:(venv)$sphinx-build-bhtmldocsbuilddocs is the source directorybuild will contain the outputMore information can be found on theSphinx webpageTestingTesting the serial communicationThe OpenWSN firmware uses the serial port extensively to communicate with OpenVisualizer and route packets (when in DAGroot mode). It is thus important that serial communication works well. To verify the serial communication between the hardware motes and your computer you can use theopenv-serialtool.openv-serial tool for testing the serial communicationTesting the TUN interfaceTo route packets between the Internet and the OpenWSN mesh network, OpenVisualizer uses a TUN interface. To create such an interface you need root privileges on your system. To test if everything works properly, you can runopenv-tun.openv-tun tool for testing the TUN interfaceContributingContributions are always welcome. We useflake8to enforce the Python PEP-8 style guide. The Travis builder verifies new pull requests and it fails if the Python code does not follow the style guide.You can check locally if your code changes comply with PEP-8. First, install the mainflake8package and twoflake8plugins:(venv)pipinstallflake8(venv)pipinstallpep8-naming(venv)pipinstallflake8-commasMove to the root of the OpenVisualizer project and run:(venv)flake8--config=tox.iniIf flake does not generate any output, your code passes the test; alternatively, you can check the return code:(venv)flake8--config=tox.ini(venv)echo$?0Contact