Markdown test¶

USING THE NATIVE PORT WITH NETWORKING¶

If you compile RIOT for the native cpu and include the nativenet module, you can specify a network interface like this: PORT=tap0 make term

./dist/tools/tapsetup/tapsetup [-c [<count>]]

Install a Toolchain¶

The toolchain used to build is arm-gcc, to check if it is currently installed run:

$ arm-none-eabi-gcc -v
Using built-in specs.
Target: arm-none-eabi
Configured with: /scratch/julian/lite-respin/eabi/src/gcc-4.3/configure
...
(skip)
...
Thread model: single
gcc version 4.3.2 (Sourcery G++ Lite 2008q3-66)

Else install from https://launchpad.net/gcc-arm-embedded

Drivers¶

The Re-Mote features a FTDI serial-to-USB module, the driver is commonly found in most OS, but if required it can be downloaded from http://www.ftdichip.com/Drivers/VCP.htm

Watchdog disable¶

wdog-disable.bin is a location-independent watchdog disable function with a breakpoint instruction at the end. Useful for disabling the watchdog directly from OpenOCD.

Usage:

openocd -c 'reset halt' \
  -c 'load_image wdog-disable.bin 0x20000000 bin' \
  -c 'resume 0x20000000' # watchdog is disabled and core halted

Control IoT-LAB via Make¶

include $(RIOTBASE)/dist/testbed-support/Makefile.iotlab

Instrucions¶

The Eclipse project must be located at “/RIOT” inside your Eclipse workspace, otherwise change cmdline2xml.sh accordingly (ECLIPSE_PROJECT_NAME=RIOT).

In the shell:

cd to application directory (e.g. examples/hello-world)
make eclipsesym

In Eclipse:

1. Open the project properties, menu Project->Properties
2. Select C/C++ General->Paths and Symbols
3. (optional) Click Restore Defaults to delete any existing macros and include paths
4. Click Import Settings...
5. Select eclipsesym.xml in your application directory and press Finish
6. Rebuild C/C++ index, menu Project->C/C++ Index->Rebuild

All conditional compilation and all include paths should now resolve properly for your application.

The file eclipsesym.xml is specific to the application being built and may differ depending on what modules are enabled and which platform is being built. Make sure that everything is set up properly in your shell and that regular make all works before running make eclipsesym

About¶

This sniffer script can be used to sniff network traffic using RIOT based nodes. It is primarily designed for sniffing wireless data traffic, but can also well be used for wired network traffic, as long as the used network devices support promiscuous mode and output of raw data.

The sniffer is based on a RIOT node running the sniffer application application located in RIOTs application repository. This node outputs received network traffic via a serial port or a network socket in the Wireshark pcap format. This output is then parsed by the sniffer.py script included in this folder run on a host computer.

The sniffer.py script is a modified version of malvira’s script for the Redbee Ecotag (https://github.com/malvira/libmc1322x/wiki/wireshark).

Dependencies¶

The sniffer.py script needs pyserial.

Installing the dependencies:

apt-get install python-serial

pip install pyserial

Usage¶

General usage:

1. Flash an applicable RIOT node with the sniffer application from (https://github.com/RIOT-OS/applications/tree/master/sniffer)
2. Run the sniffer.py script For serial port:

$ ./sniffer.py serial <tty> <baudrate> <channel> [outfile]

For network socket:

$ ./sniffer.py socket <host> <port> <channel> [outfile]

The script has the following parameters:

• connType: The type of connection to use. Either serial for serial ports or socket for network sockets.
• host: The host if the socket connection type is in use.
• port: The port of the host if the socket connection type is in use.
• tty: The serial port the RIOT board is connected to. Under Linux, this is typically something like /dev/ttyUSB0 or /dev/ttyACM0. Under Windows, this is typically something like COM0 or COM1. This option is used for the serial connection type.
• baudrate: The baudrate the serial port is configured to. The default in RIOT is 115200, though this is defined per board and some boards have some other value defined per default. NOTE: when sniffing networks where the on-air bitrate is > baudrate, it makes sense to increase the baudrate so no data is skipped when sniffing. This option is used for the serial connection type.
• channel: The radio channel to use when sniffing. Possible values vary and depend on the link-layer that is sniffed. This parameter is ignored when sniffing wired networks.
• [outfile]: When this parameter is specified, the sniffer output is saved into this file. See the examples below for alternatives to specifying this parameter. (optional)

$ ./sniffer.py serial /dev/ttyUSB1 500000 17 > foo.pcap

$ ./sniffer.py serial /dev/ttyUSB1 500000 17 | wireshark -k -i -

$ ./sniffer.py serial COM1 500000 17 foo.pcap

$ ./sniffer.py socket localhost 20000 26 > foo.pcap
$ ./sniffer.py socket localhost 20000 26 | wireshark -k -i -

Usage¶

./list-ttys.sh

List all currently connected USB to serial adapters by searching through /sys/bus/usb/devices/.

./find-tty.sh [serial_regex1] [serial_regex2] ... [serial_regexZ]

Write to stdout the first tty connected to the chosen programmer. serial_regexN are extended regular expressions (as understood by egrep) containing a pattern matched against the USB device serial number. Each of the given expressions are tested, against each serial number until a match has been found.

In order to search for an exact match against the device serial, use ‘^serialnumber$’ as the pattern. If no pattern is given, find-tty.sh returns the first found USB tty (in an arbitrary order, this is not guaranteed to be the /dev/ttyUSBX with the lowest number).

Serial strings from all connected USB ttys can be found from the list generated by list-ttys.sh.

Exit codes¶

find-tty.sh returns 0 if a match is found, 1 otherwise.

Makefile example usage¶

The script find-tty.sh is designed for use from within a board Makefile.include. An example section is shown below (for an OpenOCD based solution):

# Add serial matching command
ifneq ($(PROGRAMMER_SERIAL),)
  OOCD_BOARD_FLAGS += -c 'ftdi_serial $(PROGRAMMER_SERIAL)'

  ifeq ($(PORT),)
    # try to find tty name by serial number, only works on Linux currently.
    ifeq ($(OS),Linux)
      PORT := $(shell $(RIOTBASE)/dist/tools/usb-serial/find-tty.sh "^$(PROGRAMMER_SERIAL)$$")
    endif
  endif
endif

# Fallback PORT if no serial was specified or if the specified serial was not found
ifeq ($(PORT),)
    ifeq ($(OS),Linux)
      PORT := $(shell $(RIOTBASE)/dist/tools/usb-serial/find-tty.sh)
    else ifeq ($(OS),Darwin)
      PORT := $(shell ls -1 /dev/tty.SLAB_USBtoUART* | head -n 1)
    endif
endif

# TODO: add support for windows as host platform
ifeq ($(PORT),)
  $(info CAUTION: No terminal port for your host system found!)
endif
export PORT

Limitations¶

Only tested on Linux, and probably only works on Linux.

Setting up a toolchain {#setting-up-a-toolchain}¶

Depending 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:

• ARM-based platforms
• TI MSP430
• Atmel ATmega
• native

The build system {#the-build-system}¶

RIOT 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 application
• BOARD: specifies the platform the application should be build for by default
• 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)

Additionally it has to include the Makefile.include, located in RIOT’s root directory:

# 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:

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 netdev2_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 examples {#building-and-executing-and-example}¶

RIOT 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

make BOARD=samr21-xpro

or

make all BOARD=samr21-xpro

into your shell.

To flash the application to a board just type

make flash BOARD=samr21-xpro

You can then access the board via the serial interface:

make term BOARD=samr21-xpro

If you are using multiple boards you can use the PORT macro to specify the serial interface:

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:

make -C examples/gnrc_networking/ term \
    BOARD=samr21-xpro \
    TERMPROG=gtkterm \
    TERMFLAGS="-s 115200 -p /dev/ttyACM0 -e"

core¶

This directory contains the actual kernel. The kernel consists of the scheduler, inter-process-communication (messaging), threading, thread synchronization, and supporting data-structures and type definitions.

See @ref core for further information and API documentations.

boards¶

The platform dependent code is split into two logic elements: CPUs and boards, while maintaining a strict 1-to-n relationship, a board has exactly one CPU, while a CPU can be part of n boards. The CPU part contains all generic, CPU specific code (see below).

The board part contains the specific configuration for the CPU it contains. This configuration mainly includes the peripheral configuration and pin-mapping, the configuration of on-board devices, and the CPU’s clock configuration.

On top of the source and header files needed for each board, this directory additionally may include some script and configuration files needed for interfacing with the board. These are typically custom flash/debug scripts or e.g. OpenOCD configuration files. For most boards, these files are located in a dist sub-directory of the board.

See here @ref boards for further information.

cpu¶

For each supported CPU this directory contains a sub-directory with the name of the CPU. These directories then contain all CPU specific configurations, such as implementations of power management (LPM), interrupt handling and vectors, startup code, clock initialization code and thread handling (e.g. context switching) code. For most CPUs you will also find the linker scripts in the ldscripts sub-directory.

In the periph sub-directory of each CPU you can find the implementations of the CPU’s peripheral drivers like SPI, UART, GPIO, etc. See @ref drivers_periph for their API documentation.

Many CPUs share a certain amount of their code (e.g. all ARM Cortex-M based CPUs share the same code for task switching and interrupt handling). This shared code is put in its own directories, following a xxxxx_common naming scheme. Examples for this is code shared across architectures (e.g. cortexm_common, msp430_comon) or code shared among vendors (e.g. kinetis_common).

See @ref cpu for more detailed informtation.

drivers¶

This directory contains the drivers for external devices such as network interfaces, sensors and actuators. Each device driver is put into its own sub-directory with the name of that device.

All of RIOT’s device drivers are based on the peripheral driver API (e.g. SPI, GPIO, etc.) and other RIOT modules like the xtimer. This way the drivers are completely platform agnostic and they don’t have any dependencies into the CPU and board code.

See @ref drivers for more details.

sys¶

RIOT follows the micro-kernel design paradigm where everything is supposed to be a module. All of these modules that are not part of the hardware abstraction nor device drivers can be found in this directory. The libraries include data structures (e.g. bloom, color), crypto libraries (e.g. hashes, AES) , high-level APIs (e.g. Posix implementations), memory management (e.g. malloc), the RIOT shell and many more.

See @ref sys for a complete list of available libraries

sys/net¶

The sys/net sub-directory needs to be explicitly mentioned, as this is where all the networking code in RIOT resides. Here you can find the network stack implementations (e.g. the GNRC stack) as well as network stack agnostic code as header definitions or network types.

See @ref net for more details on networking code.

pkg¶

RIOT comes with support for a number of external libraries (e.g. OpenWSN, microcoap). The way they are included is that RIOT ships with a custom Makefile for each supported library that downloads the library and optionally applies a number of patches to make it work with RIOT. These Makefiles and patches can be found in the pkg directory.

See @ref pkg for a detailed description on how this works.

examples¶

Here you find a number of example applications that demonstrate certain features of RIOT. The default example found in this directory is a good starting point for anyone who is new to RIOT.

For more information best browse that directory and have a look at the README.md files that ship with each example.

tests¶

Many features/modules in RIOT come with their own test application, which are located in this directory. In contrary to the examples these tests are mostly focusing on a single aspect than on a set of features. Despite for testing, you might consider these tests also for insights on understanding RIOT.

dist & doc¶

All the tooling around RIOT can be found in these two folders.

doc contains the doxygen configuration and also contains the compiled doxygen output after running make doc.

Lastly, the dist directory contains tools to help you with RIOT. These include the serial terminal application pyterm, generic scripts for flashing, debugging, reseting (e.g. support for OpenOCD, Jlink), as well as code enabling easy integration to open testbeds such as the IoT-LAB. Furthermore you can find here scripts to do all kind of code and style checks.