Setup Development Environment

We don't bite, reach out for help!

Do not be afraid to ask for help e.g. in our forum or Matrix chat.

We are happy to help you get started with RIOT, and we appreciate your feedback.

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

Ubuntu command to install required packages

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

Arch Linux

Arch Linux command to install required packages

    sudo pacman -S make gcc-multilib python-pyserial 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/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

Using VS Code for Development

• If not already open, open the terminal
• Confirm that the terminal is pointed to the folder ~/RIOT/examples/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/hello-world, type cd ~/RIOT/examples/hello-world to enter that path
• Inside ~/RIOT/examples/hello-world run the command make compile-commands
• The output should look like above

• 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 hello-world folder inside the examples 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/hello-world using cd ~/RIOT/examples/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.