TimothyClaeys / openwsn-fw

OpenWSN firmware: stuff that runs on a mote

Table of Contents

• Overview
• Prerequisites
  • Linux
  • Windows
  • Mac OSX
• Building
  • Python board
  • Cross-compiling
  • Optional modules
  • Graphical configuration
• Contributing
• Contact

Overview

The OpenWSN project aims at building a reference implementation of the 6TiSCH networking stack. The project is split in two parts: OpenWSN-FW and OpenVisualizer.

• The OpenWSN-FW repository provides the C code that runs on constrained hardware.
• The OpenVisualizer repository holds OpenVisualizer Python packages that allows visualizing, debugging and interacting with an OpenWSN network.

The OpenWSN-FW code supports several hardware platforms:

• openmote-cc2538: a Cortex-M3 based SoC (cc2538) with an IEEE 802.15.4 compliant radio
• openmote-b: an updated version of the openmote-cc25538.
• iot-lab_M3: a Cortex-M3 based CPU with the AR86RF231 radio.
• python: a Python C extension of the firmware code. Its goal is to emulate motes on a computer and simulate a 6TiSCH network through OpenVisualizer. The Python board allows easy development and debugging of the firmware code without the need of real hardware and (JTAG) debuggers.

Overview of the different modules of the OpenWSN stack

Prerequisites

Depending on the hardware you are using and your operating system you will need different toolchains.

Linux (tested on Ubuntu 20.04 LTS)

OpenMote-CC2538, OpenMote-B, IoT-Lab_M3

To build for the firmware for the openmote-cc2538, openmote-b and iot-lab_M3 boards you will need to install the Arm GNU toolchain.

$ sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
$ sudo apt update
$ sudo apt install gcc-arm-none-eabi

Python board

To run the python board and build OpenWSN-FW as a Python C extension you will require GCC and Python3.6 or higher. Ubuntu 20.04 LTS comes with GCC and Python3.8 preinstalled, but you also need the python-dev containing the header files (e.g., Python.h) and libraries to build Python C extension.

$ sudo apt update
$ sudo apt install python-dev

Windows 10

OpenMote-CC2538, OpenMote-B, IoT-Lab_M3

To build for the firmware for the openmote-cc2538, openmote-b and iot-lab_M3 boards you will need to install the Arm GNU toolchain.

You can download the toolchain here. Follow the installation wizard to complete the installation. Afterwards you verify the correct installation by opening cmd.exe and typing:

$ arm-none-eabi-gcc --version

Python board

To build the Python C extension on Windows you will need the Microsoft compiler toolchain (>= 2015), MinGW (to get mingw32-make) and Python (>=3.6).

Microsoft Compiler Toolchain

The easiest way to get everything you need is to download MSVC.

MinGW

You can find the installer here. After installation, open the MinGW Installation Manager and select m̀ingw32-base.

Installing MinGW-base

Python

Python is not included in the default Windows installation so you need to install it manually. You can download a recent Python version here.

ℹ️NOTEℹ️: During the installation you should make sure to select:

• Add Python to environment variables

So you can simply type python in your command prompt, and

• Download debugging symbols
• Download debug binaries

otherwise you won't be able to build the Python extension in debug mode.

Python installation wizard on Windows

Mac OSX

Building

To build the project we use cmake. The cmake workflow uses in two steps:

1. Configuring and generating
2. Build

ℹ️NOTEℹ️: By default cmake will select (during the configure step) your standard system compiler (CC/CXX environment variables in Linux) to compile the project code. If you wish to cross-compile for constrained hardware you need to tell cmake explicitly to use a different toolchain by providing it with a toolchain file.

Cross-compiling

When you build the firmware for a specific target you should specifiy the board name and the toolchain file. For example, to compile for the openmote-cc2538, move to the root of the repository and type the following:

$ mkdir build && cd build
$ cmake .. -DBOARD=openmote-cc2538 -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/cc2538.cmake

As output of the command you should see something like this:

-- The C compiler identification is GNU 9.3.1
-- The ASM compiler identification is GNU
-- Found assembler: /opt/arm_toolchains/gcc-arm-none-eabi-9-2020-q2-update/bin/arm-none-eabi-gcc
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /opt/arm_toolchains/gcc-arm-none-eabi-9-2020-q2-update/bin/arm-none-eabi-gcc - skipped
-- Detecting C compile features
-- Detecting C compile features - done

-- OPENWSN-FW:..................VERSION-2.0
-- COMPILER TOOLCHAIN:..........GNU
-- COMPILER VERSION:............9.3.1
-- CMAKE_GENERATOR:.............Unix Makefiles
-- BOARD:.......................openmote-cc2538
-- PROJECT:.....................oos_openwsn
-- BUILD_SHARED_LIBS............OFF
-- CMAKE_BUILD_TYPE:............Debug
-- SANITIZERS:..................OFF

-- PRINTF:......................OFF
-- LOG LEVEL:...................6
-- CRYPTO HARDWARE:.............OFF

-- CHANNEL HOPPING:.............0
-- ADAPTIVE-MSF:................OFF
-- FORCE TOPOLOGY:..............OFF
-- L2 SECURITY:.................OFF
-- 6LOWPAN-FRAG:................OFF
-- PING:........................OFF
-- UDP:.........................OFF
-- PACKETQUEUE_LENGTH:..........20
-- PANID:.......................0xcafe
-- DAGROOT:.....................OFF

-- COAP:........................OFF
-- DEFAULT COAP PORT:...........5683

-- CJOIN:.......................OFF
-- CSTORM:......................OFF
-- CEXAMPLE:....................OFF
-- CLED:........................OFF
-- CINFRARED:...................OFF
-- CINFO:.......................OFF
-- C6T:.........................OFF
-- UECHO:.......................OFF
-- RRT:.........................OFF
-- WELLKNOWN....................OFF

-- Configuring done
-- Generating done
-- Build files have been written to: /home/timothy/Projects/OpenWSN/openwsn-fw/build

Make sure to verify that the board name is set to openmote-cc2538 and the compiler toolchain is GNU. From the same build directory you can now start the compilation process.

cmake --build .

When the compilation process ends it prints out a small summary of the size of the compiled binary.

[100%] Linking C executable oos_openwsn
   text	   data	    bss	    dec	    hex	filename
  75620	    652	  14972	  91244	  1646c	/home/timothy/Projects/OpenWSN/openwsn-fw/build/projects/common/03oos_openwsn/oos_openwsn
[100%] Built target oos_openwsn

For a new build (after you change something in the code), you don't need to do the configuration step again. You can simply retype the build command cmake --build .. If you wish to build from scratch you should remove the build folder entirely.

Compiling the Python C extension

When building for the Python board we don't call cmake directly but through the setup.py script. The script is responsible for building the Python C extension and installs it in the local user site-packages directory.

Move to the root of the repository and type:

$ python setup.py install --user

The setup.py file automatically configures CMake for you and compiles the entire project.

To test if the build and installation was successful you can type:

$ python -c "import openwsn"

⚠️WARNING⚠️: Do not delete the Python build artifacts or you won't be able to import the openwsn Python module.

Optional OpenWSN-FW options

In the above steps you have compiled the project in its basic minimalistic configuration, however, OpenWSN can use a bunch of optional modules. To use these optional modules you need to specify them during the CMake configuration.

Cross-compilation:

$ cmake .. -DBOARD=openmote-cc2538 -DOPT-PING=ON -DOPT-UDP -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/cc2538.cmake

To output of the configuration step should now have changed to:

-- PING:........................ON
-- UDP:.........................ON

Python C extension

To add options to the setup.py file you must specify them after the --user argument.

python setup.py install --user -DOPT-PRINTF=ON -DOPT-UDP=ON

Graphical configuration

CMake also provides to option to configure the project through a TUI and/or GUI.

For cross-compilation simply type ccmake .. (not on Windows) or cmake-gui from the build folder to open up the graphical configuration screen.

ccmake configuration GUI

Contributing

Contact

Mailing list: [e-mail]