-
Notifications
You must be signed in to change notification settings - Fork 2k
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 code 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
Direct links for Linux are
http://www.codesourcery.com/sgpp/lite/arm/portal/package3688/public/arm-none-eabi/arm-2008q3-66-arm-none-eabi.bin (with installer)
or
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 version is
####For Mac OS X
There is a tutorial to install the CodeSourcery toolchain on Mac OS X: https://gist.github.com/errordeveloper/1854389.
####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.