Getting started¶
Downloading RIOT code ¶
You can obtain the latest RIOT code from our Github repository 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:
1 | git clone git://github.com/RIOT-OS/RIOT.git
|
Compiling RIOT ¶
Setting up a toolchainDepending on the hardware you want to use, you need to first install a corresponding toolchain. The Wiki on RIOT’s Github page contains a lot of information that can help you with your platform:
The build systemRIOT uses GNU make as build system. The simplest way to compile and link an application with RIOT, is to set up a Makefile providing at least the following variables:
APPLICATION
: should contain the (unique) name of your applicationBOARD
: specifies the platform the application should be built for by defaultRIOTBASE
: specifies the path to your copy of the RIOT repository (note, that you may want to usehere, to give a relative path)
Additionally it has to include the Makefile.include
, located in RIOT’s root directory:
1 2 3 4 5 6 | # a minimal application Makefile
APPLICATION = mini-makefile
BOARD ?= native
RIOTBASE ?= $(CURDIR)/../RIOT
include $(RIOTBASE)/Makefile.include
|
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:
1 | make BOARD=iotlab-m3
|
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.
For the native port, PORT
has a special meaning: it is used to identify the tap interface if the netdev_tap
module is used. The target debug
can be used to invoke a debugger on some platforms. For the native port the additional targets such as all-valgrind
and valgrind
exist. Refer to cpu/native/README.md
for additional information
Some RIOT directories 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.
Unless specified otherwise, make will create an elf-file as well as an Intel hex file in the bin
folder of your application directory.
Learn more about the build system in the Wiki
Building and executing an exampleRIOT provides a number of examples in the examples/
directory. Every example has a README that documents its usage and its purpose. You can build them by typing
1 | make BOARD=samr21-xpro
|
or
1 | make all BOARD=samr21-xpro
|
into your shell.
To flash the application to a board just type
1 | make flash BOARD=samr21-xpro
|
You can then access the board via the serial interface:
1 | make term BOARD=samr21-xpro
|
If you are using multiple boards you can use the PORT
macro to specify the serial interface:
1 | make term BOARD=samr21-xpro PORT=/dev/ttyACM1
|
Note that the PORT
macro has a slightly different semantic in native
. Here it is used to provide the name of the TAP interface you want to use for the virtualized networking capabilities of RIOT.
We use pyterm
as the default terminal application. It is shipped with RIOT in the dist/tools/pyterm/
directory. If you choose to use another terminal program you can set TERMPROG
(and if need be the TERMFLAGS
) macros:
1 2 3 4 | make -C examples/gnrc_networking/ term \
BOARD=samr21-xpro \
TERMPROG=gtkterm \
TERMFLAGS="-s 115200 -p /dev/ttyACM0 -e"
|