If you are completely new to OpenWSN, and you are using MAC OS X, read this page first. It will walk you through all the steps to install OpenWSN and explore a number of key features.
In particular you will:
|
At the time of writing, we are using the latest nd greatest of all software. Undoubtedly, this will become outdated very fast. If you see something out of the date, take action! Send an e-mail to Tengfei Chang or Thomas Watteyne to get this page update. Thanks! |
OpenWSN is a collection of repositories hosted on GitHub. We will download and use the following:
We will download these repositories side-by-side in an openwsn/
directory in your desktop using Git.
~$ cd Desktop/ ~/Desktop$ mkdir openwsn ~/Desktop$ cd openwsn/ ~/Desktop/openwsn$ git clone https://github.com/openwsn-berkeley/openwsn-fw.git [...] ~/Desktop/openwsn$ git clone https://github.com/openwsn-berkeley/openwsn-sw.git [...] ~/Desktop/openwsn$ git clone https://github.com/openwsn-berkeley/coap.git [...] |
At any time, you can make sure that you are using the latest code by using git pull
:
~$ cd Desktop/ ~/Desktop$ cd openwsn/ ~/Desktop/openwsn$ cd openwsn-sw/ ~/Desktop/openwsn/openwsn-sw$ git pull Already up-to-date. ~/Desktop/openwsn/openwsn-sw$ cd .. ~/Desktop/openwsn$ cd openwsn-fw/ ~/Desktop/openwsn/openwsn-fw$ git pull remote: Counting objects: 440, done. remote: Compressing objects: 100% (273/273), done. remote: Total 440 (delta 283), reused 212 (delta 128) Receiving objects: 100% (440/440), 127.67 KiB | 99 KiB/s, done. Resolving deltas: 100% (283/283), done. From https://github.com/openwsn-berkeley/openwsn-fw 87f68a6..94f18cd develop -> origin/develop 116e0f4..8e36607 develop_FW-186 -> origin/develop_FW-186 Updating 87f68a6..94f18cd Fast-forward firmware/openos/openwsn/03a-IPHC/iphc.c | 792 ++++++++++++++---------- firmware/openos/openwsn/03a-IPHC/iphc.h | 98 +-- firmware/openos/openwsn/03b-IPv6/forwarding.c | 451 ++++++++------ firmware/openos/openwsn/03b-IPv6/forwarding.h | 28 +- firmware/openos/openwsn/07-App/rleds/rleds.c | 10 +- firmware/openos/projects/python/SConscript.env | 12 +- 6 files changed, 814 insertions(+), 577 deletions(-) |
Frankly, it's a bit strange to start using OpenWSN with a simulation, since the firmware is really meant (and written) to run on real motes. But, not everyone has hardware, not always the same hardware, etc. So to make things nice and easy, we'll start by simulation. Oh, and the simulated code behaves exactly the same as the real code, so what you see now is what you'll get with real hardware.
Before we can start running a simulation, we need to compile the firmware as a Python extension. This is all explained in the OpenSim page if you want to know what's going on.
The MacPorts package provides the most recent open-source releases for the gcc C compiler, for the python interpreter and related packages. For this reason, we recommend to perform the following steps: Before you can go on, you need to install the Python header files:
|
~/Desktop/openwsn$ cd openwsn-fw/ ~/Desktop/openwsn/openwsn-fw$ scons board=python toolchain=gcc oos_openwsn [...] Archiving build/python_gcc/bsp/boards/python/libbsp.a Indexing build/python_gcc/bsp/boards/python/libbsp.a Linking (shared) firmware/openos/projects/common/oos_openwsn.so scons: done building targets. |
This step compile the complete OpenWSN firmware as a Python extension module (a form of shared library) which the simulation environment can import at run-time.
The extension module is at ~/Desktop/openwsn/openwsn-fw/build/python_gcc/projects/common/oos_openwsn.so
, no need to move it.
You can now start a simulation. Running a simulation just means taking the usual software which runs on your computer (and call "openvisualizer"), but running it in simulation mode. That is, instead of the openvisualizer connecting to read motes, it connects to emulated mote code actually running on you machine.
Before you can go on, you need to perform the following steps:
|
Start a simulation:
~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ sudo scons runweb --sim scons: Reading SConscript files ... ___ _ _ _ ___ _ _ | . | ___ ___ ._ _ | | | |/ __>| \ | | | || . \/ ._>| ' || | | |\__ \| | `___'| _/\___.|_|_||__/_/ <___/|_\_| |_| openwsn.org scons: done reading SConscript files. scons: Building targets ... Copy("bin/openVisualizerApp/sim_files", "../../../openwsn-fw/firmware/openos/bsp/boards/python/openwsnmodule_obj.h") Mkdir("bin/openVisualizerApp/sim_files/linux") Copy("bin/openVisualizerApp/sim_files/linux/oos_openwsn-x86.so", "../../../openwsn-fw/firmware/openos/projects/common/oos_openwsn.so") Copy("bin/openVisualizerApp/sim_files", "../../../openwsn-fw/firmware/openos/projects/common/oos_openwsn.so") Delete("build/runui/web_files") Mkdir("/home/thomas/Desktop/openwsn/openwsn-sw/software/openvisualizer/build/runui") Copy("build/runui/web_files", "bin/openVisualizerApp/web_files") Delete("build/runui/sim_files") Mkdir("/home/thomas/Desktop/openwsn/openwsn-sw/software/openvisualizer/build/runui") Copy("build/runui/sim_files", "bin/openVisualizerApp/sim_files") uiRunner(["bin/openVisualizerApp/openVisualizerWeb"], ["bin/openVisualizerApp/openVisualizerWeb.py"]) Child PID is 5144 scons: done building targets. thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ ioctl(TUNSETIFF): Device or resource busy created following virtual interface: 4: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 500 link/none inet6 bbbb::1/64 scope global valid_lft forever preferred_lft forever inet6 fe80::1/64 scope link valid_lft forever preferred_lft forever |
You need to run the openvisualizer with "sudo" since the Python program will create a |
That's it, an OpenWSN simulation is now running your computer!
Open http://127.0.0.1:8080/ to see the web interface of OpenWSN
Open the "Topology" tab:
Set up the topology to have a chain 1-2-3, and set each PDR to 1.
Back in the "Motes" tab, select mote 0001
and click on the "Toggle" button. You just declare mote 1 to be the root of your network (the DAGroot in RPL parlance, the sink in WSN parlance, the gateway, etc). You can select other motes and see that they quickly become "Synchronized!".
Congratulations, you have built your first OpenWSN simulated network!
By convention (i.e. this is hard-coded in the software), the IPv6 prefix of the simulated network is bbbb:/64
. This means that the IPv6 address of each mote will start with "bbbb::
". The remainder of a mote's IPv6 address is it's MAC address (or EUI-64). You can read this in the web interface (under "EUI-64").
Open a new terminal to ping mote 2:
~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ ping6 bbbb::1415:92cc:0:2 PING bbbb::1415:92cc:0:2(bbbb::1415:92cc:0:2) 56 data bytes 64 bytes from bbbb::1415:92cc:0:2: icmp_seq=1 ttl=64 time=51.1 ms 64 bytes from bbbb::1415:92cc:0:2: icmp_seq=2 ttl=64 time=134 ms 64 bytes from bbbb::1415:92cc:0:2: icmp_seq=3 ttl=64 time=137 ms 64 bytes from bbbb::1415:92cc:0:2: icmp_seq=4 ttl=64 time=101 ms ^C --- bbbb::1415:92cc:0:2 ping statistics --- 4 packets transmitted, 4 received, 0% packet loss, time 3004ms rtt min/avg/max/mdev = 51.172/106.146/137.486/34.713 ms |
You can also ping mote 3 which is 3 hops away:
~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ ping6 -s 10 bbbb::1415:92cc:0:3 PING bbbb::1415:92cc:0:3(bbbb::1415:92cc:0:3) 10 data bytes 18 bytes from bbbb::1415:92cc:0:3: icmp_seq=1 ttl=63 time=80.1 ms 18 bytes from bbbb::1415:92cc:0:3: icmp_seq=2 ttl=63 time=105 ms 18 bytes from bbbb::1415:92cc:0:3: icmp_seq=3 ttl=63 time=94.0 ms 18 bytes from bbbb::1415:92cc:0:3: icmp_seq=4 ttl=63 time=147 ms ^C --- bbbb::1415:92cc:0:3 ping statistics --- 4 packets transmitted, 4 received, 0% packet loss, time 3001ms rtt min/avg/max/mdev = 80.115/106.887/147.964/25.359 ms |
We had to reduce size of the ping request for that one ( |
CoAP is a protocol implement on each OpenWSN device, which makes it appear like a web server on the Internet.
By default, an OpenWSN mote implements a CoAP "info" resource which indicate what version of the code is running. You can test that by running the Python test script provided in the firmware:
~/Desktop/openwsn/openwsn-fw/openapps/cinfo$ python cinfo.py /home/thomas/Desktop/openwsn/openwsn-fw/openapps/cinfo OpenWSN 1.4.1 Python Python Python |
In simulation mode, the openvisualizer takes care of simulating the wireless medium. You can use Wireshark to take a peek at what goes over this simulated radio space.
Before you can go on, you need to install Wireshark:
|
Start Wireshark on the tun
interface at address bbbb::1
, and configure the filtering for zep
(the ZigBee encapsulation protocol).
You need to start Wireshark with "sudo":
|
For now, you don't see any packets, that's normal:
In the OpenVisualizer's "Event bus" tab, check the "Wireshark debug" box.
You now see all the packets exchanged over the simulated radio environment, exciting!
Here is an example pcap file of openwsn simulation network with three motes: example.
Now the embarrassing part. We haven't taken the time to implement a graceful way of stopping the openvisualizer, so you'll have to kill the process. Sorry.
~/Desktop$ ps -ef | grep openvisualizer root 5354 1 99 00:28 pts/0 00:36:58 python bin/openVisualizerApp/openVisualizerWeb.py -a /home/thomas/Desktop/openwsn/openwsn-sw/software/openvisualizer/build/runui -s -H 0.0.0.0 -p 8080 thomas 7321 5487 0 01:04 pts/2 00:00:00 grep --color=auto openvisualizer ~/Desktop$ sudo kill -9 5354 |
User experience with real hardware is identical than when using the simulator. Because it is a popular platform, we will use the TelosB mote, although any other supported hardware platform can be used instead.
When connecting a TelosB board, you Linux will assign it a device file. Reading/writing to/from that file results in bytes being sent to/from your TelosB over its UART interface. To know which device your TelosB is located at, plug it into your computer, wait a second, and type dmesg
:
[ 1181.904524] usb 1-3.3.2: new full-speed USB device number 5 using ehci_hcd [ 1182.002641] usb 1-3.3.2: New USB device found, idVendor=0403, idProduct=6001 [ 1182.002651] usb 1-3.3.2: New USB device strings: Mfr=1, Product=2, SerialNumber=3 [ 1182.002659] usb 1-3.3.2: Product: Crossbow Telos Rev.B [ 1182.002667] usb 1-3.3.2: Manufacturer: XBOW [ 1182.002674] usb 1-3.3.2: SerialNumber: XBRAHL2O [ 1182.035737] usbcore: registered new interface driver usbserial [ 1182.035784] usbcore: registered new interface driver usbserial_generic [ 1182.035819] USB Serial support registered for generic [ 1182.035835] usbserial: USB Serial Driver core [ 1182.041321] usbcore: registered new interface driver ftdi_sio [ 1182.041363] USB Serial support registered for FTDI USB Serial Device [ 1182.041627] ftdi_sio 1-3.3.2:1.0: FTDI USB Serial Device converter detected [ 1182.041785] usb 1-3.3.2: Detected FT232BM [ 1182.041793] usb 1-3.3.2: Number of endpoints 2 [ 1182.041801] usb 1-3.3.2: Endpoint 1 MaxPacketSize 64 [ 1182.041809] usb 1-3.3.2: Endpoint 2 MaxPacketSize 64 [ 1182.041815] usb 1-3.3.2: Setting MaxPacketSize 64 [ 1182.043704] usb 1-3.3.2: FTDI USB Serial Device converter now attached to ttyUSB0 [ 1182.043742] ftdi_sio: v1.6.0:USB FTDI Serial Converters Driver |
The penultimate line indicates that this TelosB is attached to /dev/ttyUSB0
. You can repeat the same procedure for the other boards. In my case, I have 3 motes connected:
thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-fw$ ls /dev/ttyU* /dev/ttyUSB0 /dev/ttyUSB1 /dev/ttyUSB2 |
Before going on, you need to make sure you have a recent version mspgcc:
In particular, earlier versions Ubuntu (e.g. 12.04 LTS) came with the older msp430-gcc 4.5.3. This will NOT work; see for details. |
The build environment allow you to build the firmware and load is on all your boards with a single command (how cool is that?):
thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-fw$ sudo scons board=telosb toolchain=mspgcc bootload=/dev/ttyUSB2 oos_openwsn scons: Reading SConscript files ... ___ _ _ _ ___ _ _ | . | ___ ___ ._ _ | | | |/ __>| \ | | | || . \/ ._>| ' || | | |\__ \| | `___'| _/\___.|_|_||__/_/ <___/|_\_| |_| openwsn.org scons: done reading SConscript files. scons: Building targets ... msp430-size firmware/openos/projects/common/03oos_openwsn_prog text data bss dec hex filename 41024 0 4138 45162 b06a firmware/openos/projects/common/03oos_openwsn_prog telosb_bootload(["firmware/openos/projects/common/03oos_openwsn_prog.phonyupload"], ["firmware/openos/projects/common/03oos_openwsn_prog.ihex"]) starting bootloading on /dev/ttyUSB2 MSP430 Bootstrap Loader Version: 1.39-telos-8 Mass Erase... Transmit default password ... Invoking BSL... Transmit default password ... Current bootstrap loader version: 1.61 (Device ID: f16c) Changing baudrate to 38400 ... Program ... 41024 bytes programmed. Reset device ... done bootloading on /dev/ttyUSB2 scons: done building targets. |
While the command allows you to program multiple motes in one go:
Linux seems to have synchronization errors when doing so. See . |
Once the motes are programmed, you have the exact same experience as when running a simulated network.
First, start the OpenVisualizer:
thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ sudo scons runweb scons: Reading SConscript files ... ___ _ _ _ ___ _ _ | . | ___ ___ ._ _ | | | |/ __>| \ | | | || . \/ ._>| ' || | | |\__ \| | `___'| _/\___.|_|_||__/_/ <___/|_\_| |_| openwsn.org scons: done reading SConscript files. scons: Building targets ... Delete("build/runui/web_files") Mkdir("/home/thomas/Desktop/openwsn/openwsn-sw/software/openvisualizer/build/runui") Copy("build/runui/web_files", "bin/openVisualizerApp/web_files") Delete("build/runui/sim_files") Mkdir("/home/thomas/Desktop/openwsn/openwsn-sw/software/openvisualizer/build/runui") Copy("build/runui/sim_files", "bin/openVisualizerApp/sim_files") uiRunner(["bin/openVisualizerApp/openVisualizerWeb"], ["bin/openVisualizerApp/openVisualizerWeb.py"]) Child PID is 2820 scons: done building targets. thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-sw/software/openvisualizer$ ioctl(TUNSETIFF): Device or resource busy created following virtual interface: 4: tun0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN qlen 500 link/none inet6 bbbb::1/64 scope global valid_lft forever preferred_lft forever inet6 fe80::1/64 scope link valid_lft forever preferred_lft forever |
Open http://127.0.0.1:8080/ to see the web interface:
Your TelosB motes turn on their blue LED once synchronized.
You might be tempted to look for a graphical representation of the topology. Unfortunately, this is only implemented in simulation mode. Really want it? Help fix . |
You can ping a mote exactly as you would in the simulator:
thomas@Thomas-X61s:~$ ping6 bbbb::1415:9200:12:e63b PING bbbb::1415:9200:12:e63b(bbbb::1415:9200:12:e63b) 56 data bytes 64 bytes from bbbb::1415:9200:12:e63b: icmp_seq=1 ttl=64 time=365 ms 64 bytes from bbbb::1415:9200:12:e63b: icmp_seq=2 ttl=64 time=354 ms 64 bytes from bbbb::1415:9200:12:e63b: icmp_seq=3 ttl=64 time=344 ms 64 bytes from bbbb::1415:9200:12:e63b: icmp_seq=4 ttl=64 time=340 ms 64 bytes from bbbb::1415:9200:12:e63b: icmp_seq=5 ttl=64 time=332 ms ^C --- bbbb::1415:9200:12:e63b ping statistics --- 5 packets transmitted, 5 received, 0% packet loss, time 4006ms rtt min/avg/max/mdev = 332.908/347.599/365.737/11.417 ms |
You can interact with a mote exactly as you would in the simulator. After modifying the cinfo.py
script to communicate with mote bbbb::1415:9200:12:e63b
:
thomas@Thomas-X61s:~/Desktop/openwsn/openwsn-fw/openapps/cinfo$ python cinfo.py /home/thomas/Desktop/openwsn/openwsn-fw/openapps/cinfo OpenWSN 1.4.1 TelosB MSP430f1611 CC2420 Done. Press enter to close. |
Congratulations! You've now gone through the trouble of installing all of the tools and pieces of OpenWSN. From now on, it's just fun.