Creating your first RIOT project

Please note that this HOWTO assumes you're working on a Linux PC.

Preparation

First, make sure you've installed the dependencies for building RIOT on your native platform:

• RIOT only needs a c compiler that can handle gnu99, gcc and clang are proved to work!
• for x86-64 (64 bit) operation systems, you'll need at least glibc-dev and libgcc in the 32 bit edition

Then, you'll need to clone the RIOT repository

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

Now you can create your own project directory in RIOT/examples/. In this tutorial, we'll do this by copying the default project folder, which can easily be used as a template to base your own project on.

cd RIOT/examples
cp -R default my_project
cd my_project

From this directory, you will compile everything you need, including the RIOT OS itself– one small make and everything is ready.

Let's take a look at the contents of our new my_project directory:

##The Makefile We'll only go through the lines that could be relevant to you.

export PROJECT = default

Your project's name. In our case, you will have to change this line to export PROJECT = my_project

export BOARD = native

The board for which you want to compile my_project. native means that my_project will be compiled to run on your desktop PC.

# this has to be the absolute path of the RIOT-base dir
export RIOTBASE =$(CURDIR)/../../RIOT

Your project will be compiled to run as a normal program in your Linux operating system. To enable this, your compiler needs to know where the code for the OS lives. If you've set up the correct file structure, you won't need to adjust this path.

USEMODULE += posix
USEMODULE += uart0
USEMODULE += shell
USEMODULE += shell_commands
USEMODULE += ps
USEMODULE += vtimer
USEMODULE += auto_init
...
ifneq (,$(findstring native,$(BOARD)))
	USEMODULE += ltc4150
	USEMODULE += rtc
	USEMODULE += nativenet
	USEMODULE += transceiver
	USEMODULE += config
endif

RIOT contains modules that enable you to add certain functionalities to your RIOT kernel. To keep your RIOT binary nice and small, you can selectively include only those that you need to be compiled into your executable. This is done by adding the name of every module you need to the USEMODULE string, as shown above. For your first project you should throw out at least the transceiver and nativenet modules. For a shell project you need ``posix, uart0` and `shell`.

export INCLUDES += -I${RIOTBASE}/core/include/ -I${RIOTBASE}/sys/include/ -I${RIOTBASE}/drivers/include/

The INCLUDES tell the compiler where the header files of all included modules live.

main.c

shell_init(&shell, NULL, uart0_readc, uart0_putc);
shell_run(&shell);

This is the heart of your main.c file. If you run your compiled project later on, you'll notice that you will be greeted by an interactive shell. The two function calls above will start the shell. To extend the default commands with custom ones, you will have to pass a struct with name, description and pointers to your custom functions. my_project doesn't do this just yet, so let's add a little "Hello World".

Instead of NULL, we'll have to pass an array of shell_command_ts, each containing the command name, command description and the function that the command should call, as well as an all-null line to terminate the list like so:

void hello_world(char *str){
	printf("hello world!\n");
}

const shell_command_t shell_commands[] = {
	{"hello", "prints hello world", hello_world},
	{ NULL, NULL, NULL }
};

int main(void)
{
	…
	
	shell_init(&shell, shell_commands, uart0_readc, uart0_putc);
	shell_run(&shell);
}

running your first project

If you want to do any networking, you'll need to create the virtual interfaces that your RIOT instances will use to communicate:

../../cpu/native/tapsetup.sh create

This will set up a bridge for two tap devices to communicate over. If you want to use more than two devices, append the number of devices you need to the command above.

You can now run your project by executing

./bin/my_project.elf tap0

And then, in another terminal window,

./bin/my_project.elf tap1

etc. etc.
You should see the following output:

RIOT native interrupts/signals initialized.
RIOT native uart0 initialized.
LED_GREEN_OFF
LED_RED_ON
RIOT native board initialized.
RIOT native hardware initialization complete.

kernel_init(): This is RIOT!
Scheduler...[OK]
kernel_init(): jumping into first task...
UART0 thread started.
uart0_init() [OK]
native rtc initialized
Native LTC4150 initialized.
Welcome to RIOT!
>  

Type help for help. Play around a little. Press ctrl+c to exit. In case you need network functionality, try sending a message from one RIOT instance to the other with the txtsnd command (0 is a broadcast address). If this works, you're good to go.
Happy Hacking!