Setup Development Environment

import Contact from '@components/contact.astro';

Choosing the Right Operating System

Linux (Recommended)

Most of the RIOT OS developers are using Linux on their development PCs, so you can expect the most streamlined experience here. Generally, most Linux distributions are supported.

If you are new to Linux, we recommend using Ubuntu, as it is the most widely used distribution and has the most extensive documentation and community support.

Some distributions, such as Fedora, do not provide the necessary packages for cross compilation. In this case, it is recommended to use the RIOT Docker Container.

Windows

Windows is supported through Windows Subsystem for Linux (WSL). The experience is not as streamlined as on Linux, but it is still possible to develop with RIOT.

:::note Please follow the installation guide for WSL to set up your development environment.

Afterwards, you can follow the Ubuntu installation guide. The installation of the required software packages is the same for both Ubuntu and WSL. :::

macOS

Native development on macOS machines is not officially supported.

What works well is using Linux in a virtual machine, but at much lower performance than running Linux natively.

We also offer Docker images that make it a bit easier to develop on macOS.

Installing the Required Software Packages

:::note It is also possible to run RIOT in a Docker container.

This is especially useful if you want to avoid installing the required software packages on your host system. For more information, see the Build in Docker guide. :::

Depending on the operation distribution you are using, the installation of the required software packages may vary.

Ubuntu

    sudo apt install make gcc-multilib python3-serial python3-psutil wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang

Arch Linux

    sudo pacman -S make gcc-multilib python-pyserial python-psutil wget unzip git openocd gdb esptool podman-docker clang

This will show something like this depending on your distribution:

• Confirm the installation by hitting the return-key
• The installation process will take some time
• Eventually the output will look like below (except for the exit)

Cloning the RIOT Repository and First Steps in the Terminal

:::note Even if you subsequently work only via VS Code, do NOT skip this step. You will still need a "clone" of the RIOT Repository to work with. :::

• Open the terminal.
• Type git clone https://github.com/RIOT-OS/RIOT and confirm with the return-key
• This may take some time. Eventually, it will print done. when it completed
• Type cd RIOT/examples/basic/hello-world and confirm with the return-key to enter the folder hello-world example app in the RIOT repo
• Type make and confirm with the return key to build the app for the board native

:::tip If you are having issues with missing libraries you can always also use the docker container to build the app. In this example you can type BUILD_IN_DOCKER=1 make to build the app in the docker container. :::

:::note The native board is a virtual board that will run an RIOT application as regular Linux process. This can be useful for testing or during development. The app should behave the same when run on real hardware. :::

• Now run the application by executing make term
• The output should look similar to the screenshot above
• You can close the terminal by:
  1. Press and hold the Ctrl-key
  2. With the Ctrl-key still held, press the C-key
  3. Release both keys

Generating compile_commands.json e.g. for Code Completion in IDEs

This target will honor the variables controlling the build process such as BOARD, TOOLCHAIN, DEVELHELP, etc. just like the usual build process. This works without actual compilation. By default, the compile_commands.json is placed in the RIOT base directory. This behavior can be overwritten using the COMPILE_COMMANDS_PATH variable by specifying the full absolute path (including file name) of the compile_commands.json instead.

:::note By default, the built-in include search directories of GCC will be explicitly added and flags incompatible with clangd will be dropped. This will allow using clangd as language server out of the box. If this is not desired, run export COMPILE_COMMANDS_FLAGS="" to turn modification of the compile commands off. For a list of available flags, run ./dist/tools/compile_commands/compile_commands.py --help in the RIOT base directory. :::

Using VS Code for Development

• If not already open, open the terminal
• Confirm that the terminal is pointed to the folder ~/RIOT/examples/basic/hello-world
  • The blue part left of the prompt (the $ sign in the terminal) shows the current working directory for the terminal
  • If the blue string is not ~/RIOT/examples/basic/hello-world, type cd ~/RIOT/examples/basic/hello-world to enter that path
• Inside ~/RIOT/examples/basic/hello-world run the command make compile-commands
• The output should look like below

• Navigate back to ~/RIOT using the command cd ~/RIOT
• run code . to launch VS Code
  • This will take a bit longer on the first launch
• Eventually, a VS Code Window should pop up that looks like this:

1. Click on "Yes, I trust the authors"

• Now, use the tree view in the left and open the examples folder
• Open the basic folder inside the examples folder
• Open the hello-world folder inside the basic folder
• Open the main.c file in the hello-world folder within examples
• The file should open and look like this:

1. Click on the "Install" button when prompted to install the C/C++ Extension.

:::note You can also install that extension via the extension marketplace if that pop up does not show up. :::

:::danger

Do NOT configure RIOT as CMake project. VS Code will incorrectly detect RIOT as CMake project, because it contains external packages that indeed are using CMake.

1. Click on "Not now" to not configure RIOT as CMake project
2. Click on "Never" to never ask again whether RIOT should be configured as CMake project (not shown in screenshot) :::

• Confirm that when hovering over RIOT_BOARD in the source code, IntelliSense shows that it expands to "native".

:::note IntelliSense depends on information how to compile the source code to work correctly, which is provided in the file compile_commands.json. You can regenerate this file by running make compile-commands in the app you are working on. :::

:::caution Re-run make compile-commands when:

1. You create, delete or rename source files
2. You change the set of modules or packages used
3. You have updated the RIOT repository
4. You are switching the board to compile for :::

• Extend the message to be printed, e.g. by adding a puts("..."); statement in the source code
• Save the modified source code (e.g. Ctrl+S)
• Open the integrated terminal by clicking on the terminal tab at the bottom
• Navigate to ~/RIOT/examples/basic/hello-world using cd ~/RIOT/examples/basic/hello-world
• Run the make command to build the code
• Run make make term to launch the application
• The result should look like:

Congratulations! You just compiled your first RIOT application. To run RIOT on real hardware, proceed with the next to sections.

Architecture Specific Requirements

:::caution[Don't get lost] If this section overwhelms you, don’t worry, you can always come back to it later. This is only important if you want to develop for a specific architecture or board. For now everything should work fine with the packages installed above.

You can safely skip this section if you are just getting started with RIOT and want to try out the examples or develop for the native board. :::

For each architecture a default tool for flashing and on-chip debugging is listed below - in most cases OpenOCD. However, some boards use different tools, e.g. because a bootloader is installed that allows flashing via the serial interface. Check the board documentation for any details on this. If that documentation contains no info about a flashing tool, the default tool for its architecture is used.

:::tip Running BOARD=<INSERT_TARGET_BOARD_HERE> make info-programmers-supported in your application folder lists the programmers supported by RIOT for the given board. :::

Architecture: ARM7 and ARM Cortex M*

• GCC, binutils, and newlib for arm-none-eabi
  • Alternatively: Install docker and export BUILD_IN_DOCKER=1
• OpenOCD for debugging/flashing (most boards)
  • Some boards use UF2 based bootloaders, which require auto-mounting to work with make flash
  • Some boards default to using J-Link for flashing/debugging. Either install that or export PROGRAMMER=openocd to just use OpenOCD instead
  • installation instructions can be found here
• Optional: picolibc for arm-none-eabi to link against picolibc instead of newlib
• Optional: clang to build with TOOLCHAIN=llvm
• Optional: GDB multiarch for debugging
  • If no multiarch package is available, use GDB for arm-none-eabi instead

Architecture: Xtensa

ESP32

• Toolchain for ESP32
• esptool for flashing
• Optional: OpenOCD and GDB (multiarch version) for debugging via JTAG

ESP8266

• Toolchain for ESP8266
• esptool for flashing
• Optional: GDB (multiarch version) for debugging via the gdbstub interface for the ESP8266

Architecture: AVR

• GCC and binutils for AVR and avrlibc
  • Alternatively: Install docker and export BUILD_IN_DOCKER=1
• avrdude for flashing
• Optional: AVaRICE and GDB (multiarch version) for debugging

Architecture: RISC-V

• GCC, binutils, and newlib for RISC-V (target triple should start with riscv and end with -none-elf or -unknown-elf. Note that most packages are multilib, e.g. riscv64-unknown-elf will likely work fine for 32 bit RISC-V boards)
  • Alternatively: Install docker and export BUILD_IN_DOCKER=1
• OpenOCD for debugging/flashing (some new boards might require a patched version of OpenOCD or a recent build from the git sources)
• Optional: picolibc to link against picolibc instead of newlib (recommended)
• Optional: clang to build with TOOLCHAIN=llvm
• Optional: GDB multiarch for debugging

Architecture: MSP430

• GCC, binutils, and newlib for MSP430
  • Alternatively: Install docker and export BUILD_IN_DOCKER=1
• mspdebug for flashing/debugging
  • Optional: MSP Debug Stack for additional board support
• Optional: GDB multiarch for debugging

Architecture: native

• On 64 bit systems: multilib versions for your host compilers, standard C library, and development headers
  • Alternatively: Compile with BUILD_IN_DOCKER=1. Note that for running the executable you still need a multilib system (or 32 bit Linux) with glibc a standard C library.
• A C library supporting the deprecated POSIX.1-2001 ucontext library (e.g. glibc, FreeBSD's libc)
• Optional: GDB for debugging. (Prefer the multiarch version, this will also work for other boards)