Introduction

#Introduction into RIOT

##Overview

RIOT is an operating system designed for the particular requirements of Internet of Things (IoT) scenarios. This requirements comprise a low memory footprint, high energy efficiency, real-time capabilities, a modular and configurable communication stack, and support for a wide range of low-power devices. RIOT provides a microkernel, utilities like cryptographic libraries, data structures (bloom filters, hash tables, priority queues), or a shell, different network stacks, and support for various microcontrollers, radio drivers, sensors, and configurations for entire platforms, e.g. TelosB or STM32 Discovery Boards.

The microkernel itself comprises thread management, a priority-based scheduler, a powerful API for inter-process communication (IPC), a system timer, and mutexes.

In order to build an application or library with RIOT, you need first to download the source code (Getting the source code). This contains - besides the before mentioned features - also some example applications (located in the examples subdirectory) and a sample Makefile you may use for your own project. This Makefile template shows you how to compile and link your project against RIOT (Compiling RIOT).

If you want to use RIOT directly with your embedded platform, you need to install the corresponding toolchain for the deployed microcontroller (ARM based platforms, TI MSP430 based platforms).

###Native RIOT - Run RIOT on your PC!

As a special platform, you will find a CPU and board called native in the repository. This target allows you to run RIOT as a process on Linux on most supported hardware platforms. Just set CPU and BOARD to native in your project's Makefile, call make, and execute the resulting elf-file. Further documentation about the native port can be found in cpu/native/README.

###Structure

The RIOT repository contains the following ten subdirectories:

• boards
• core
• cpu
• dist
• doc
• drivers
• examples
• pkg
• sys
• tests

The boards directory provides the configurations and initialization code for supported IoT platforms. In core you can find the kernel, while cpu comprises microcontroller specific implementations like startup and exception handling code. The folder dist contains a template for an application's Makefile and external utilities like the terminal program pyterm or a script to build your own toolchain for ARM microcontrollers. Not very surprisingly you will find the (doxygen) documentation in doc and peripheral driver code in drivers. The examples folder provides some exemplary applications, pkg includes Makefiles to integrate external libraries into RIOT, and sys system libraries as well as the implementation of the network stacks which are located in sys/net. Finally, the subdirectory tests contains test applications, including also a few expect scripts to automatically validate some of them.

###Special features

####The build system

RIOT uses GNU make as build system. The simplest way to compile and link a project (application or library) with RIOT, is to set up a Makefile providing at least the following variables:

• PROJECT
• BOARD
• RIOTBASE

and an instruction to include the Makefile.include, located in RIOT's root folder. PROJECT should contain the (unique) name of your project, BOARD specifies the platform the project should be built for by default, and RIOTBASE specifies the path to your copy of the RIOT repository (note, that you may want to use $(CURDIR) here, to give a relative path). You can use Make's ?= operator in order to allow overwriting variables from the command line. For example, you can easily specify the target platform, using the sample Makefile, by invoking make like this:

make BOARD=telosb 

Besides typical targets like clean, all, or doc, RIOT provides the special targets flash and term to invoke the configured flashing and terminal tools for the specified platform. These targets use the variable PORT for the serial communication to the device. Neither this variable nor the targets flash and term are mandatory for the native port.

Some RIOT folders contain special Makefiles like Makefile.base, Makefile.include or Makefile.dep. The first one can be included into other Makefiles to define some standard targets. The files called Makefile.include are used in boards and cpu to append target specific information to variables like INCLUDES, setting the include paths. Makefile.dep serves to define dependencies.

####Including modules

By default a RIOT project comprises only the projects' code itself, the kernel, and platform specific code. In order to use additional modules, such as a particular device driver or a system library, you have to append the modules' names to the USEMODULE variable. For example, to build a project using the SHT11 temperature sensor and 6LoWPAN network stack, your Makefile needs to contain these lines:

USEMODULE += sht11
USEMODULE += sixlowpan

To contribute a new module to RIOT, your module's Makefile needs to set the variable MODULE to a unique name. If the module depends on other modules, this information needs to be added to RIOT's Makefile.dep.

####The main function

After the board is initialized, RIOT starts two threads: the idle thread and the main thread. The idle thread has the lowest priority and will run, whenever no other thread is ready to run. It will automatically use the lowest possible power mode for the device. The main thread - configured with a default priority that is right in the middle between the lowest and the highest available priority - is the first thread that runs and calls the main function. This function needs to be defined by the project.

####The IPC

Like any microkernel system, RIOT has an IPC API that enables data exchange between modules or a single module and the kernel. This API is documented in the doxygen documentation. The IPC can be used in several ways, such as synchronous or asynchronous, blocking or non-blocking, with or without a message queue. In the default case, a thread does not have a message queue. Hence, messages sent in a non-blocking manner are lost, when the target thread is not in receive mode. A thread may set up a message queue using the corresponding function, but has to provide the memory for this queue itself.

####Auto-init

Most modules require initialization before they can be used. In some cases the initialization function does not require a parameter. For these modules you might use the auto-init feature by adding a line like

USEMODULE += auto_init

to your Makefile. Auto-init calls all module initialization functions with a void parameter just before the main thread gets executed.

####The transceiver module

The transceiver module is an abstraction layer and multiplexer between the network stack and the radio driver. It runs in a single thread with the PID transceiver_pid. It provides an IPC interface that enables to configure and use available radio drivers, e.g. setting the radio channel or sending a packet. A thread may also register at the transceiver module, in order to get notified whenever a packet for a particular radio transceiver is received. The notification message contains a pointer to the packet struct. After processing the packet, the registered thread needs to decrease this struct's member processing which acts as a semaphore for the packet's memory buffer.

##Getting the source code

You can obtain the latest RIOT code from our Github account either by downloading the latest tarball or by cloning the git repository.

In order to clone the RIOT repository, you need the Git revision control system and run the following command:

git clone git://github.com/RIOT-OS/RIOT.git

The repository contains the kernel, support for different CPUs and platforms, device drivers, system libraries, and network stack implementations. In addition it comprises various example applications to demonstrate the usage of some important features.

It also provides you with useful tools like a terminal program and scripts to setup a toolchain.

##Compiling RIOT

Depending on the hardware you want to use, you need to first install a corresponding toolchain.

###Platforms based on ARM

For platforms based on ARM microcontrollers (such as the MSB-A2, the STM32 Discovery Board series or the HiKoB Fox we recommend an older version (2008q3) of CodeBench (formerly CodeSourcery) from Mentor Graphics. It can be obtained here.

####For Linux

You can get the Linux version from CodeSourcery with installer or source code only.

Please note that you will have to add the directory with executables (arm-none-eabi-gcc, arm-none-eabi-as etc.) to your PATH variable in both cases. On a typical shell like bash or zsh this can be done using export, e.g.

export PATH=${PATH}:/path/to/arm-none-eabi-gcc

####For Windows

The direct link for the Windows Installer.

####For Mac OS X

There is a tutorial to install the CodeSourcery toolchain on Mac OS X.

Alternatively there is a tap repository for Homebrew package manager that can be used to install the CodeSourcery toolchain. For further instructions see the README.

####Build the toolchain from sources

There is also the possibility to build the toolchain from the sources, allowing for newer versions of GCC, binutils, and Newlib. A script to build a toolchain for the MSB-A2 is available in the RIOT git repository at

dist/tools/toolchains/build_gnuarm.sh

###Platforms based on TI MSP430

Download and install GCC toolchain for MSP430 according to the information provided on the website.

###For the native port

In order to build RIOT for the native port, you just need the GNU Compiler Collection.

There is a README that explains how to use natives network controller. Once you have set up the toolchain, you can create your own project. Apart from the C file(s) containing your source code you need a Makefile. A template Makefile is available in the dist folder of the RIOT repository.

Within your project's Makefile, you can define the target hardware as well as the modules you want to use.

Unless specified otherwise, make will create an elf-file as well as an Intel hex file in the bin folder of your project directory.