RIOT-Lab - How to use RIOT in the IoT-Lab · Slidesareonlineavailableat. O. Hahm (INRIA) RIOT-Lab November 7, 2014 2 / 29. Start the RIOT ... nc RIOT netcat

RIOT-LabHow to use RIOT in the IoT-Lab

Oliver "Oleg" Hahm

INRIA

November 7, 2014

O. Hahm (INRIA) RIOT-Lab November 7, 2014 1 / 29

Agenda

1 Start the RIOT

2 Using RIOT

3 Writing an Application for RIOT

4 Reading a Sensor

5 Join the RIOT

Slides are online available at http://riot-os.org/files/riotlab-tutorial.pdf.


http://riot-os.org/files/riotlab-tutorial.pdf

Start the RIOT

Agenda

1 Start the RIOT

2 Using RIOT


4 Reading a Sensor

5 Join the RIOT


Start the RIOT Prepare your Toolchain

Recommended Build Environment

For the IoT-Lab nodes we recommend to use gcc-arm-embedded toolchain.It can be found on https://launchpad.net/gcc-arm-embedded.

A quick guide to install the proper toolchain can be found in the RIOT wiki:http://wiki.riot-os.org/Setup-a-Build-Environment

See also http://wiki.riot-os.org/Board%3A-IoT-LAB_M3 for particular informationon RIOT on the IoT-Lab nodes.

For the native port you have to install 32bit libraries.See http://wiki.riot-os.org/Family%3A-native#toolchains


https://launchpad.net/gcc-arm-embedded

http://wiki.riot-os.org/Setup-a-Build-Environment

http://wiki.riot-os.org/Board%3A-IoT-LAB_M3

http://wiki.riot-os.org/Family%3A-native#toolchains

Start the RIOT GitHub

Obtain the Code

git clone https://github.com/RIOT-OS/RIOT.gitor download the zipped version:

https://github.com/RIOT-OS/RIOT/archive/master.zip

For this tutorial please clone alsohttps://github.com/RIOT-OS/applications


https://github.com/RIOT-OS/RIOT/archive/master.zip

https://github.com/RIOT-OS/applications

Start the RIOT Understanding RIOT

The Architecture



The Folder Structure

RIOTboards

iot-lab_M3corecpu

cortex-m3_commonstm32f1

distdocdrivers

at86rf231isl29020

exampleshello-world

pkglibcoap

sysnet

network_layersixlowpan

tests



Best Practice for RIOT programming

DosUse static memorySelect the priorities carefullyMinimize stack usage with DEVELHELP and CREATE_STACKTESTUse threads

DontsDon’t use threads

Don’t use the POSIX wrapper if implementing something from scratch

Consult the Wiki: http://wiki.riot-os.org

...and the API documentation: http://doc.riot-os.org


http://wiki.riot-os.org

http://doc.riot-os.org


Best Practice for RIOT programming

DosUse static memorySelect the priorities carefullyMinimize stack usage with DEVELHELP and CREATE_STACKTESTUse threadsIncrease flexibility, modularity, and robustness by using IPC.

DontsDon’t use threadsTry not to use more than one thread per module.Don’t create threads for one-time tasks.Don’t use the POSIX wrapper if implementing something from scratch

Consult the Wiki: http://wiki.riot-os.org

...and the API documentation: http://doc.riot-os.org


http://wiki.riot-os.org

http://doc.riot-os.org

Using RIOT

Agenda

1 Start the RIOT

2 Using RIOT


4 Reading a Sensor

5 Join the RIOT


Using RIOT Working with an Example

Compile and run on native

Let’s prepare a simple, virtual network:

[RIOT]# cpu/native/tapsetup.sh create 2creating tapbr0 ...creating tap0 ...creating tap1 ...

Now we build and start the first virtual node.

[RIOT]# cd examples/default/[default]# make all termBuilding application default for native w/ MCU native."make" -C /home/oleg/git/RIOT/cpu/native...RIOT native board initialized.RIOT native hardware initialization complete.

kernel_init (): This is RIOT! (Version: 2014.05 -1314 - gace8a -zoidberg)kernel_init (): jumping into first task ......Welcome to RIOT!> helphelpCommand Description---------------------------------------reboot Reboot the nodeid Gets or sets the node ’s id.



Setup the second Node

Ok, how about a second node?Therefore, we specify the tap interface to use by (re-)using the PORT environment variable. Wecan use any created tap interface from the previous step. (Default is tap0.) Once the node hasstarted, we configure its radio address.

[default]# PORT=tap1 make termWelcome to RIOT!> addr 23[transceiver] trying to set address 23[transceiver] got address: 23

We do the same on the first node and configure it to address 42.



Connecting the two Nodes

It’s time to send our first packet (assuming that the first node is still running and configured toaddress 42.):

> txtsnd 42 riotlab[transceiver] Sending packet of length 8 to 42: riotlab[transceiver] Packet sent: 60

On the first node we should see something like:

Got radio packet:Length: 8Src: 23Dst: 42LQI: 0RSSI: 0

72 69 6F 74 6C 61 62 0



Using the same example on the real hardware

Running the same example on a real node is very similar.We use the environment variable BOARD to specify the target platform – and maybe PORT for theserial port.

[default]# BOARD=iot -lab_M3 make all flash termBuilding application default for iot -lab_M3 w/ MCU stm32f1."make" -C /home/oleg/git/RIOT/cpu/stm32f1...wrote 55296 bytes from file RIOT/examples/default/bin/iot -lab_M3/default.

hexin 2.454112s (22.004 KiB/s)...shutdown command invokedRIOT/dist/tools/pyterm/pyterm -p /dev/ttyUSB2 -b 500000INFO # Connect to serial port /dev/ttyUSB2Welcome to pyterm!Type ’/exit ’ to exit.helpINFO # > helpINFO #INFO # Command DescriptionINFO # ---------------------------------------INFO # reboot Reboot the nodeINFO # id Gets or sets the node ’s id.



...and on the Testbed

Call just BOARD=iot-lab_M3 make all to build the binary (elf and hex are built).

Flash the nodes like usual (using the IoT-Lab web interface).

If you want use it somewhat more comfortable than using netcat, you can use thesame tool which is used for a locally connected node: pyterm.You can find it in dist/tools/pyterm.

For example, run pyterm -ts m3-7:20000 on grenoble.iot-lab.info.


Using RIOT Using a Custom Application

The Shell in a Nutshell

For this step we will use sixlowapp application fromhttps://github.com/RIOT-OS/applications.

You can configure RIOT to provide you with some default system shell commands.

All available shell commands and some online help are shown by calling help:

> helphelpCommand Description---------------------------------------nc RIOT netcat - arbitrary UDP connections and listensping Send an ICMPv6 echo request to another nodereboot Reboot the nodeid Gets or sets the node ’s id.ps Prints information about running threads.addr Gets or sets the address for the transceivereui64 Gets or sets the EUI -64 for the transceiverchan Gets or sets the channel for the transceivertxtsnd Sends a text message to a given node via the transceiverpan Gets or sets the pan id for the transceivermonitor Enables or disables address checking for the transceiverifconfig Configures a network interface

The selection of commands depends on the configuration of your application (and may vary alittle bit for different platforms).


https://github.com/RIOT-OS/applications


Let’s communicate

The sixlowapp application provides you with two custom (application defined) shell commands:1 ping: The famous ICMP diagnosis tool.2 nc: A very basic variation of netcat for arbitrary UDP connections.

After we flashed two nodes, we’ll have to find out their IPv6 addresses using ifconfig:

> ifconfigINFO #INFO # Iface 0 HWaddr: 0xa86c Channel: 11 PAN ID: 0x0001INFO # EUI -64: 4d-5e-fd -8e-47-3c-5f-80INFO # Source address mode: shortINFO # Transceivers:INFO # * at86rf231INFO # inet6 addr: fe80::ff:fe00:a86c /128 scope: localINFO # inet6 addr: ff02 ::1: ff00:a86c /128 scope: local [

multicast]INFO # inet6 addr: ff02 ::1/128 scope: local [multicast]INFO #

Now we can try to ping the other node:

> ping fe80::ff:fe00:f01eINFO # ping fe80::ff:fe00:f01eINFO # Echo reply from fe80::ff:fe00:f01e received , rtt: 0.0340s



Virtualize your Network

If you run this example in native, you can also monitor the traffic with Wireshark.

The dissector can be found in dist/tools/wireshark_dissector.

There’s a python framework to setup arbitrary topologies using defined loss-rates:http://wiki.riot-os.org/Virtual-riot-network


http://wiki.riot-os.org/Virtual-riot-network

Writing an Application for RIOT

Agenda

1 Start the RIOT

2 Using RIOT


4 Reading a Sensor

5 Join the RIOT


Writing an Application for RIOT Setting up the Application

The Makefile

To create your own RIOT example, you need only two files:1 A C (or C++) file with a main function2 A Makefile

You can find a template for a Makefile in dist/Makefile.

# Giving your application a nameAPPLICATION = riotlab1# Choosing a default platformBOARD ?= native# Specifying the RIOT folderRIOTBASE ?= $(CURDIR)/../../ RIOT# Some helpful compiler flagsCFLAGS += -DSCHEDSTATISTICS -DDEVELHELP# Quieten the building processQUIET ?= 1# Modules to include:USEMODULE += posixUSEMODULE += vtimer# Let RIOT ’s build system take care of the restinclude $(RIOTBASE)/Makefile.include



The main() Function

The only mandatory thing in your application is a main function with this prototype:int main(void)

Standard C libraries can be used and parts of POSIX are ble through a wrapper within RIOT.

#include <stdio.h>#include <unistd.h>

#define WAIT_USEC (1000 * 1000)

int main(void){

puts("Hello!");usleep(WAIT_USEC);puts("Good night!");

return 0;}



Doing it the RIOT way

Instead of POSIX functions is usually advisable (and more efficient) to just use the native RIOTfunctions:

#include <stdio.h>#include "vtimer.h"

int main(void){

puts("Let’s throw a brick!");vtimer_usleep(SEC_IN_USEC);puts("System terminated");

return 0;}


Writing an Application for RIOT Some helpful Features

Starting the Shell

#include "posix_io.h"#include "shell.h"#include "shell_commands.h"#include "board_uart0.h"

...const shell_command_t shell_commands [] = {

{"ping", "Send an ICMPv6 echo request to another node",sixlowapp_send_ping},

{NULL , NULL , NULL}};...

/* Open the UART0 for the shell */posix_open(uart0_handler_pid , 0);

/* initialize the shell */shell_t shell;shell_init (&shell , shell_commands , UART0_BUFSIZE , uart0_readc , uart0_putc

);

/* start the shell loop */shell_run (& shell);


Writing an Application for RIOT Some helpful Features

...and 6LoWPAN

kernel_pid_t monitor_pid =thread_create(monitor_stack_buffer , sizeof(monitor_stack_buffer),

PRIORITY_MAIN - 2, CREATE_STACKTEST , sixlowapp_monitor ,NULL , "monitor");

ipv6_register_packet_handler(monitor_pid);...while (1) {

msg_receive (&m);if (m.type == IPV6_PACKET_RECEIVED) {

ipv6_buf = (ipv6_hdr_t *) m.content.ptr;if (ipv6_buf ->nextheader == IPV6_PROTO_NUM_ICMPV6) {

icmpv6_hdr_t *icmpv6_buf =(icmpv6_hdr_t *) &(( uint8_t *) ipv6_buf)[( IPV6_HDR_LEN)];

if (icmpv6_buf ->type == ICMPV6_TYPE_ECHO_REPLY) {if (_waiting_for_pong) {

msg_t m;m.type = ICMP_ECHO_REPLY_RCVD;_waiting_for_pong = 0;msg_send (&m, _waiter_pid , false);

}}

}}

}


Writing an Application for RIOT Up to the Transport Layer

Starting a UDP Server

sock = socket_base_socket(PF_INET6 , SOCK_DGRAM , IPPROTO_UDP);

memset (&sa , 0, sizeof(sa));sa.sin6_family = AF_INET;sa.sin6_port = HTONS(sixlowapp_netcat_listen_port);

if (-1 == socket_base_bind(sock , &sa , sizeof(sa))) {printf("Error bind failed !\n");socket_base_close(sock);sixlowapp_netcat_listen_port = 0;continue;

}

printf("Listening for incoming UDP connection at port %" PRIu16 "\n",sixlowapp_netcat_listen_port);

int32_t recsize = socket_base_recvfrom(sock , (void *) buffer_main ,UDP_BUFFER_SIZE , 0, &sa, &fromlen);

if (recsize < 0) {printf("ERROR: recsize < 0!\n");

}

printf("UDP packet received , payload: %s\n", buffer_main);

socket_base_close(sock);


Reading a Sensor

Agenda

1 Start the RIOT

2 Using RIOT


4 Reading a Sensor

5 Join the RIOT


Reading a Sensor Get your Hands dirty

Now it’s up to you

Your task is now to extend the sixlowapp example.

Check the documentation for the sensor API, e.g. for the light sensor:http://doc.riot-os.org/group__driver__isl29020.html

Initialize all four sensors in the beginning of the application.

Extend the netcat command to send optionally measured sensor data.

Print the measurements on the receiving side.


http://doc.riot-os.org/group__driver__isl29020.html

Join the RIOT

Agenda

1 Start the RIOT

2 Using RIOT


4 Reading a Sensor

5 Join the RIOT


Join the RIOT Getting Support

Where to get help

Mailing [email protected]@riot-os.org

IRC on irc.freenode.org, #riot-os

Regular video conferencing meetings


The Last Slide™ Q&A

Thank you!Any questions?


Documents

RIOT-Lab - How to use RIOT in the IoT-Lab · Slidesareonlineavailableat. O. Hahm (INRIA) RIOT-Lab November 7, 2014 2 / 29. Start the RIOT ... nc RIOT netcat