Kickstart MIMSY

WIP by @Jinyue Zhu, @ERIC WU, @Carol Yan

This tutorial is designed for beginners who haven’t developed an OpenWSN project using mimsy. After completing this tutorial, you can:

  1. Get familiar with the file structure of an OpenWSN project

  2. Compile an OpenWSN project in eclipse IDE or command-line interface

  3. Modify an OpenWSN program and see expected results from the laptop

  4. Construct a communication channel between an Openmote and a mimsy

Environment Setup

To distribute the environment without worrying too much about the version, we provide a mimsy virtual machine where you have the correct version of the development stack for this tutorial. You have to be a Berkeley student and ask for access from the BWRC faculty.

Understand OpenWSN File Structure

This section will walk you through the three important components in the OpenWSN and what does the stack consist of, including openwsn projects, openstack codes, and openapps, where your application code resides. The program execution workflow will be like this: an openwsn project starts the openstack initialization, and in openstack your application will be initialized.

File Structure

The root directory is openwsn-fw where the related firmware codes for the openwsn projects reside. Below you can see projects, openstack, and openapps directory are highlighted. These are the directory corresponding to the previous three components.

OpenWSN Projects

In this directory, you can find the main structure of your program.

Open the file openwsn-fw/projects/common/03oos_openwsn/03oos_openwsn.c.

The 03oos_openwsn is the project you will be using for your application. It’s like running your application under a certain kind of OpenWSN stacks which will handle the networking stack, the scheduler and so on.

In below, you can see the project will first initialize the board, the scheduler (code located in the openwsn-fw/kernel) and the openstack.


The openstack will build up the whole OpenWSN stack such as the ieee154e protocol or ipv6 protocol. The below code snippet can be found in openwsn-fw/openstack/openstack.c. It basically initializes all the stuff needed in the OpenWSN framework. For the application, openapps_init() is where your application is initialized.


You will be developing your application under the directory openwsn-fw/openapps/. For example, there’s an application called uinject under that directory. You can find the function such as uinject_init inside the uinject.c and uinject.h. That basically is what will be called in the openapps_init() to initialize your application.

Assume that you have compiled your program following the steps described below. You can find the openapps_init being defined with your <application_init>(). The below code snippet can be found in openwsn-fw/build/openapps/openapps_dyn.c. This file is generated when you build your project. You can build a project either through the terminal or eclipse. The command will be like

sudo scons board=openmote-cc2538 toolchain=armgcc bootload=/dev/ttyUSBx revision=A1 oos_openwsn apps=uinject

where in apps=uniject specify your application. The openapps_dyn.c will generate the correct application init according to that argument.


Congratulation! You now understand how an openwsn project is built and can work on developing your first openwsn project! The knowledge can help you more easily to understand the next tutorial easier and build your own project upon them.

Develop an OpenWSN Project

Hardware Requirements

  1. Segger Debugger + ARM-JTAG 20-10 pin converter

  2. two Openmotes

  3. a mimsy from Kris

  4. some wires

Please follow the below snapshot on how to connect the wires.

Connect using openbase

Connect using openmote

notes: the ground of the mimsy is on the edge of the board (red wire) and the power is the black wire in this particular case. Make sure your connection is correct (check this datasheet to see the power/gnd of mimsy)


Create Your Tutorial App

In this section, we demonstrate a basic routine to create an application in the openWSN framework. Consider the following steps:

  1. Open your Virtual Machine.

  2. Plug openmote/openbase into the computer and press connect to Linux.

3. Attach debugger to debug header on openmote or openbase.

4. Navigate to openwsn-mimsy/openwsn-fw/openapps.

5. Create a folder called tutorial.

6. Copy uinject/uinject.c and uinject/uinject.h into tutorial and rename them tutorial.c and tutorial.h.

7. In tutorial.c and tutorial.h rename all instances (upper case and lower case) of “uinject” to “tutorial” using find and replace.

8. Modify the application’s UDP port

a) Register udp: Navigate to openwsn-fw/inc/opendefs.h add WKP_UDP_TUTORIAL=2018

b) Register component: Add COMPONENT_tutorial=0x2B

9. Register the application with the networking stack

a) Navigate to tutorial.c. Add WKP_UDP_TUTORIAL to tutorial_vars.desc.port. “desc.port” is which UDP port this application will be registered to. “desc.callbackReceive” is the function that is called when a UDP packet is received by the mote. “desc.callbackSendDone” is the function that is called when a UDP packet is done being sent by the mote. “openudp_register()” registers the UDP port and callbacks with the networking stack. “tutorial_vars.timerID = opentimers_create()” creates a timer instance. opentimers_schedulein() configures the timer period, type, and callback function.

b) Add WKP_UDP_TUTORIAL to l4_destination and l4_sourceport

c) In openwsn-fw/openstack/crosslayers/idmanager.c change idmanager_vars.myPanid[0:1] to something unique, such as your birthday month and day.

10. In tutorial.h, change the timer period so it fires every 1000 ms (tutorial_PERIOD_MS =1000)

11. Build Project and download the program to Mimsy

a) Open Eclipse and choose the default workspace(/home/vagrant/mimsy)

b) Right click on the OpenWSN folder in the Project Explorer window and open properties

c) In “Build command”, Change apps=urocket to apps=tutorial

d) Double click Build Targets/oos_openwsn to build project.

e) Click the arrow next to the debug bug icon and click debug configurations

f) Click “Debug”, the eclipse should change. Click the green play button at the top of the window to start the program.

Get Data from the Laptop

Now you have built an openwsn project with an application called tutorial. We are going to receive the data from the mimsy through the Openmote.

  1. Run the DAGroot Program

    1. Plug another Openmote into your computer, and click “connect to Linux”

    2. In terminal, run “ls /dev/ttyUSB*”. Take note of which ttyUSBx shows up, this is the com port your openmote is connected to

    3. In terminal, “cd /home/vagrant/openwsn-mimsy/openwsn-fw

    4. In terminal, “sudo scons board=openmote-cc2538 toolchain=armgcc bootload=/dev/ttyUSBx revision=A1 oos_openwsn

    5. Download this script to the VM

    6. Replace “COM7” in the last line of the script with “/dev/ttyUSBx” corresponding to your Openmote

    7. Navigate to the directory where is located. Enter the command line command: “sudo python

    8. You should see data streaming to your terminal eventually

Important Notes:

You might see some invalid messages from the terminal at first (shown in the below picture). Don’t panic, it is normal, just wait for the synchronization between the mimsy and the openmote complete, then you would see data streaming out. It is normal to wait for 3~5 minutes before the data comes out. Make sure that you don’t cut off the power of the mimsy and accidentally break the connection.

If you are curious about whether the mimsy is transmitting or not, you can try to blink the LED by doing so. Add the leds_radio_toggle() in the tutorial_task_cb function (located in the file openwsn-fw/openapps/tutorial/tutorial.c) so that when the mimsy is transmitting data, you can see the green led on the mimsy toggling. Also, you can add more debugging led such as leds_error_on() (this will turn on the red led) in the code segment before return. In the below code snippet, you can see the commented leds_error_on() before the three return statements to try to see if the mimsy is still syncing or not. If it is syncing then the red led will be turned on.

Temperature Project

This section will tell you how to get temperature data based on the tutorial application you just create using mimsy.

  1. include the file at the top

    #include "adc_sensor.h" #include "sensors.h"
  2. First add the sensors_init() in the tutorial_init().

  3. add the codes in the red box in the tutorial_task_cb(). It basically reads the temperature data from the mimsy and sends it out in the separate four bytes in the payload.

  4. On the PC side, modify as follows: uncomment line 219 and add the temp_data = … and print out the result.

  5. run sudo python again and WAIT.


Congratulation again! You know can measure your temperature using mimsy at your ease. COOL!


[1] Tutorial on receiving packets from Mimsy using openWSN framework

[2] OpenWSN + Mimsy2 Tutorial Presentation


Eric Wu:

Jinyue Zhu:

Carol Yan: