RIOT learning solutions - request for input

During the Summit breakout session about documentation (19 September 2023), it became clear that new RIOT-OS users experience difficulties in how to get started. It was suggested to design a ‘tutorial 0’ (format for writing tutorials) and templates for module descriptions. Laura Mellendijk and I have a background in Learning and Development and we’d like to help in resolving difficulties in this area. We would like to first get a clear view of the current situation and desired future situation, so we can help to bridge the gap between both.

What we’ve discovered so far:

  • The API ( contains reference documentation describing the available modules of RIOT.

  • There is a limited online tutorial ( that has not been reviewed didactically.

  • New users ask many questions in the chat and forum about how to get started using RIOT to build their specific project.

To be able to design and develop (learning) solutions, we need your help in getting additional information by answering the questions below:

  • What additions do you have regarding the current situation as described above?

  • What does already work well for new users starting with RIOT?

  • What problems do new users experience when starting using RIOT?

  • For whom, besides new users, is this a problem?

  • What does the situation look like when the problem is solved (desired future situation)?

  • In order to reach this desired future situation, what is needed to solve the problems?

If you have any questions or additional info you’d like to share, please let us know in the comments. Many thanks!

Laura and Karin


Let me answer your easy questions about “besides new users”. I’m a rather seasoned (30+ years) embedded systems expert. I have problems knowing how things in RIOT-OS have changed: specifically, I probably am ignorant of features and facilities in RIOT-OS which probably make my life easier, but they weren’t there two years ago, so I improvised. Tutorials need to exist at multiple (“fractal”) levels of complexity so that new people are not overwhelmed, but also so that seasoned people read them and comment on how things are better/worse, and how they can help new people.

1 Like

My experience observing and trying to help on the forum is that many new people, being inexperienced, often come with entirely unrealistic notions about how to do things, and the kind of background required. Let me make an analogy:

A new jumper arrives at the Olympic Ski Jumping slope. They plan to do a triple-axel 720 degree flip. They start discussing the required momentum changes that they will need in order to accomplish that with the first person they see, who happens to be a snow maintenance person. “Wow, that’s gonna be something to see. What colour skis are you gonna wear? It would be cool if they were flurorescent!”

New jumper: “Wait, this sport is done on skis”?

So a key part of any tutorial would be to identify what skills are required for each step, and then to point the new developer to the non-RIOT-OS specific training materials that provide the background.

1 Like


I recently came across this website, that might be helpful in structuring RIOT’s documentation :

As a new user, I can tell I’m having a hard time. But I hang on : I read examples and tests in the repo, often after reading posts in this forum, that point to the most relevant ones. But what strikes me most, is that the so-called “detailed description” in the documentation is too often no longer than a single line. That sure doesn’t help figure out realistic use cases…

I think the challenge is definitely worth the effort, since the learning curve is a major criteria in selecting a RTOS. And it implies effective documentation.


Hey Karin,

thanks for picking up our discussion from the Summit.

I try to provide some input from two perspectives: 1.) My own perspective as someone who used to know almost everything about RIOT but whose knowledge has outdated over the years quite a bit. 2.) The perspective of my students who are mostly completely new to RIOT (and often to embedded programming at all).

  • The API ( contains reference documentation describing the available modules of RIOT.

You’re right: initially this location by a has been meant for providing the API documentation. However, over the time we decided to make it the default location for most/all documentation. (By the way, in case you’re not aware): This part of the documentation is automatically generated from code and text files inside the RIOT source code repository by a tool called doxygen. Hence, I will refer to it as “doxygen documentation” in the following.)

When students ask me who do perform a particular feature in RIOT (or in working with RIOT) I often know that this feature exists but cannot recall exactly what needs to be done to use. In these cases, I often experience some difficulties in finding the documentation.

The main reason for these difficulties is a) not everything is (yet) documented in the doxygen documentation, b) the structure of the documentation is not coherent, the search function is of limited use (particular if you do not exactly what to search for).

For example: For our native “board”, the required packages are documented directly on the entry page: Native Board For other boards, you need to look at the getting started page: Getting started

I typically give a pointer to this tutorial for RIOT newcomers. But since this tutorial has originally been designed as a guided tutorial some things are often difficult to figure out when the students are on their own. (E.g., which packages need to be installed when working on their own Linux installation.)

  • New users ask many questions in the chat and forum about how to get started using RIOT to build their specific project.

Many people seem to hesitate from asking beginners’ questions in the forum or on Matrix - even though people are usually quite helpful and friendly. Maybe we need a particular newbie section in the forum and/or a newbie channel in Matrix.

  • For whom, besides new users, is this a problem?

I can only second what Michael wrote. It is often difficult to keep track of changes for experienced users who are not following the development that closely. Maybe we could think about periodic newsletter or blog which offers some sort of documented changelog.

Cheers Oleg

– /*

  • For moronic filesystems that do not allow holes in file.
  • We may have to extend the file. */ linux-2.4.0-test2/fs/buffer.c
1 Like

Problem with that is that it is quite outdated, at the moment at least (case and point Provide Github Action workflow to compile test the tasks by miri64 · Pull Request #79 · RIOT-OS/Tutorials · GitHub).

There are also

While there were thoughts about merging this, I think at this point I am against these: Every tutorial was designed with a different goal, a different target audience in mind, and that is a good thing. Especially with learning material, I came to the conclusion that there is no one-fits-all solution (some like to dig through the API doc from the start, others like to go through a step-by-step tutorial, yet others again like to look at examples and even in these groups people approach things differently).

However, maybe it would be a good idea to put some of the newer stuff from riot-exercises and riot-course that worked well also into Tutorials?

1 Like

Thank you very much for your reactions! They are very helpful in giving us a better overview of the current situation. Also thanks for suggesting so many possible solutions, this is very valuable.

A short summary so far:

Beginners seem to have a hard time getting into RIOT (but they hang on! Very nice, @emeutier :slight_smile: ) . They lack some basic knowledge, documentation is incomplete and/or it is unclear where to find what. Also there is no easy ‘entrance’ to start using modules based on the API. The online tutorial seems to be outdated and is difficult to use on your own. Forum posts, however, help beginners in finding the most relevant examples and tests in the repository.

In general, documentation is seen as a concern. It is hard to get it logical, retrievable and complete.

Other area for improvement is keeping up with added features to the code for experienced users, which could be solved by a periodic newsletter/blog or a timeline with features added. Would this be possible to add to every release (@maintainers)?

Since there are diverse areas for improvement, we decided to first focus on facilitating getting started with RIOT for beginners. Therefore, we would like to know as well:

  • What does already work well for new users?

  • Can you describe what the most ideal start for beginners with RIOT would look like?

We would like to also talk individually with some new RIOT users to get more in-depth information about their experiences. If you are a beginner with RIOT and open to this, please let us know! (in reaction to this post or via Matrix

Have a nice day!

Hello all, here a short update on the learning solutions for RIOT newcomers.

We have had our first conversations with individual community members, which have given us many interesting insights. More interviews will follow in the next weeks, after which I will provide a more substantive update here.

If you would like to share your experience or other information relevant to improving the learning process of beginners, please send me a message via forum or chat!

Have a nice day :slight_smile:

1 Like

Also see this related (but slightly more technically oriented) issue: [tracking] improving the onboarding experience · Issue #20388 · RIOT-OS/RIOT · GitHub

1 Like

General information on RIOT learning solutions

After speaking with 5 people from the community about learning solutions for RIOT newcomers, I have found out the following about learning solutions for RIOT newcomers.

There are three different tutorials/courses available:

  1. ‘Regular’ tutorial
  • This is the first made tutorial, intended as first drop-in for newcomers.

  • It works from the shell in the terminal, no hardware needed

  • It needs updating, because it is outdated and can be confusing. For example, there are already 2 ways of ‘setup’ described on the front page.

  1. RIOT course
  • Intended as the leading tutorial during summit (before corona).

  • This uses Jupiter Notebook, via browser, no hardware needed.

  • License CC-BY-ND, so it cannot be adapted and redistributed.

  • Nice start for who wants to use RIOT for research work

  1. Tutorial and exercises for students of HAW and TU Dresden
  • This has first been made for the RIOT summit +/- 2017.

  • This material is used for teaching at HAW for some years now, TU Dresden will start using it this semester. Both links lead to the same content; a different link is used to prevent confusion for students of both universities.

  • Hardware is used in these tutorials, so students learn to use RIOT on hardware.

My findings on preferred ways of learning RIOT:

  • Beginners differ in preferred way of learning. Experienced (and mostly 30+) users prefer written explanations and documentation. Younger users (students) often prefer a combination of written and video explanation.

  • Most people prefer to first get an overall introduction from someone, before doing a tutorial by yourself. Also because tutorials 1 ‘regular’ tutorial and 3 HAW/TU Dresden tutorial are not intended and suitable to be completed entirely on your own (not sure how this is with the 2 RIOT course).

  • Everyone likes it when there is a real person available to explain and ask questions to. This may be online or offline. For online asking for help, it is preferable that the beginner knows the person (s)he asks questions. Otherwise the threshold for asking help is high, because of fear of asking dumb questions.

Recommended improvements, mentioned by the interviewees and myself


  • The tutorial is not findable from the main RIOT page with information about how to get started. Can there be placed a link to ‘regular’ tutorial 1 at that page?

  • Indicate at the start of the tutorial what skills are required to successfully finish the tutorial. For example: makefile, build system, git, Jupiter. This allows the person who wants to do the tutorial to easily see if they meet the requirements.

  • Make an overview with links to the non-RIOT specific training materials needed to start with the RIOT tutorial (for example: makefile, build system, git). Place this link at the start of the tutorial, with the ‘skills required to successfully finish the tutorial’. This allows the person who wants to do the tutorial to brush up their lacking knowledge themselves so that they will be able to successfully complete the RIOT tutorial.

  • Improve the ‘regular’ tutorial 1 with good parts of the RIOT course 2 and Tutorial and exercises for students of HAW/TU Dresden 3. This is a big(ger) task, checking out the material of all three tutorials and decide on what content could be added where.

Create more elaborate examples

  • Write an extensive example, work everything out in detail. For example for use model. So that you instruct people with such example where to find the information, so that they can find such information themselves.
  • Mark solutions on questions in the forum the same way as stack overflow, just as has been done with this post. This makes it easier for beginners to find solutions to questions that have already been asked on the forum.

Encourage beginners to ask questions

  • Encourage beginners to ask questions in more places. Have mentioned in all beginners documentation that you may absolutely ask questions and where they can do so (forum, chat). Put this in the tutorial, in the ‘getting started guide’ etc. So that it is everywhere and a beginner hopefully feels a lower threshold in asking questions. “Have doubts? Ask us!”
  • Create a matrix chat for RIOT newcomers. This may lower the threshold to ask questions, because it is intended especially for beginners. Explicitly show that we care about newcomers.

Related topics

A lot of other important topics with suggestions for improvement came up during the conversations. Documentation has been discussed extensively, on-boarding in general, communication tools, good practices of other projects and the RIOT community. I would like to share the more about these topics as well. In which topics does the greatest need lie/would you like to receive more information? And where is the best place to share this information?

Final remarks

I think we can make a lot of great improvements for the on-boarding of beginners and would be happy to help further on this in the coming time. So please let me know if you’re also working on bits of on-boarding and other community-related stuff, because I like to connect and think & help along! Together we can implement a lot of small areas for improvement piece by piece, making the start and on-boarding for newcomers easier and the community as a whole even greater! :slight_smile: