Getting Started with (Apache) NuttX RTOS - Part 1

Alan C AssisJune 2, 20234 comments

Probably you have already heard about Apache NuttX RTOS, a small RTOS but very powerful in resources and features, but never stopped to look deeper into it. So let us start by raising a question: What separates NuttX from other RTOSes like FreeRTOS, Mbed, VxWorks, uC/OS-II, Contiki, Zephyr, RT-Thread, ThreadX, RIOT-OS, ChibiOS/RT and many others?

Quick Links

Well, first of all, NuttX is really small and very customizable, which makes it a good alternative to FreeRTOS and ChibiOS/RT for example. Also it has many useful and advanced features like USB, Ethernet, Audio and Graphics subsystems, a feature set that makes it a compelling substitute for Mbed, Zephyr, and RT-Thread. NuttX also has great network support for TCP, UDP, IP, 6LoWPAN, LoRa, WiFi, and Bluetooth, making it highly attractive to those seeking an alternative to Contiki and RIOT-OS. Finally, NuttX also has strict POSIX compliance which makes it an alternative to VxWorks and implements many Linux-like subsystems, presenting an alternative to Linux itself, especially for resource-constrained devices.

This article is available in PDF format for easy printing

Another important thing to note about NuttX is that it runs on microcontrollers and Systems on Chip (SoCs) that range from 8-bit to 64-bit. This flexibility allows you to experiment with the same or similar NuttX features on a broad range of chips from different architectures, families, and semiconductors vendors.

Now you know why companies like Sony (Japan), Xiaomi (China), Samsung (South Korea), Google/Fitbit (USA/Romania), Tata Elxsi (India), WEG (Brazil), GeoTab (Canada), WildernessLabs(USA) and many others are using it!

Can you imagine a fictional scenario where a virus spreads around the world and disrupts the semiconductor supply chain? How forgetful I am! Actually, this happened in 2020 with Coronavirus (COVID-19). So out of the blue, your chosen microcontroller is not available, or is not available in the quantity you need or for the price you can pay? If you are using NuttX you can move to another microcontroller without reinventing the wheel. Just like you can with Linux, but for a fraction of the price of the hardware to run it.

Unfortunately, things are not that simple in real life. To master NuttX you have a price to pay: you need to study and learn how it works. The good news is that it is not that difficult if you have a good guidance teacher. And that is exactly what I will do for you today. So, jump in the wagon and enjoy the landscape, because life is short and as you live, you are getting older!

The first question I know you want to ask me is: what board do I need to get started with NuttX? You can use any board supported by NuttX, such as STM32F4Discovery, STM32F103 BluePill (called stm32f103-minimum on NuttX), Raspberry Pi Pico, ESP32-Devkit, ESP32C3-Devkit, or any of those more than 300 boards supported by NuttX. If you don’t have a board, don’t worry. You don’t need one to get started with NuttX. It has a simulator that lets you test it without any board!

Let's start our journey to the NuttX RTOS using this simulator before using a real board.

First, you need to install the prerequisite packages on Linux, MacOS, or Windows/WSL. I'll duplicate here the steps for Linux, but for Windows or MacOS they's very similar. You can use this page for reference: https://nuttx.apache.org/docs/latest/quickstart/install.html

Installing the dependencies packages:

$ sudo apt install bison flex gettext texinfo libncurses5-dev libncursesw5-dev xxd \gperf automake libtool pkg-config build-essential gperf genromfs \
libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev \
libexpat-dev gcc-multilib g++-multilib minicom u-boot-tools util-linux

Install the ELF tools:

$ pip install pyelftools cxxfilt

Installing the Kconfig Frontends:

$ sudo apt install kconfig-frontends

Since we are going to use the simulator we don't need to install any cross-compiler or other toolchain, but in case you are planning to use NuttX with ARM, RISC, Xtensa, etc, you need to install the appropriate toolchain.

Creating a workspace, or let's say a nuttxspace:

$ mkdir ~/nuttxspace
$ cd ~/nuttxspace

Cloning the NuttX and NuttX-Apps repositories:

$ git clone https://github.com/apache/nuttx.git nuttx
$ git clone https://github.com/apache/nuttx-apps apps

Notice there is an " apps" after nuttx-apps, it is because the building system will look for ../apps instead of ../nuttx-apps.

Before continuing, please confirm that you can see the directories "nuttx" and "apps" inside ~/nuttxspace:

$ ls -l
drwxrwxr-x 1 alan alan 594 mai 29 18:00 apps
drwxrwxr-x 1 alan alan 488 mai 29 17:59 nuttx

Great, now enter inside nuttx to start the configuration and compilation.

Configuring NuttX:

Enter inside your nuttx directory that is inside nuttxspace and that inside your home directory (~)

$ cd ~/nuttxspace/nuttx

Please confirm all files were cloned correctly:

$ ls
arch  CONTRIBUTING.md  fs           libs   NOTICE     sched
audio crypto        graphics     LICENSE   openamp    syscall
AUTHORS  Documentation include      Makefile  pass1      tools
binfmt   drivers       INVIOLABLES.md  mm     README.md  video
boards   dummy         Kconfig      net    ReleaseNotes  wireless

Good, now you can run the configuration script passing the SIMulator (sim) and the NuttSHell (nsh)

$ ./tools/configure.sh sim:nsh
  Copy files
# configuration written to .config

Compiling NuttX:

$ make -j
LD:  nuttx

In this case this created file "nuttx" is a Linux executable, see:

$ ls -l nuttx
-rwxrwxr-x 1 alan alan 2168728 mai 29 18:15 nuttx


$ file nuttx
nuttx: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=xxx, for GNU/Linux x.x.x, with debug_info, not stripped

Running NuttX simulator:

Just run this nuttx file:

$ ./nuttx
Login: admin
Password: Administrator
User Logged-in!

Congratulations, you are a NuttX user now!
While you try to become a NuttX developer, please enjoy the environment:

Who needs help when you can type "?" (spoiler alert: type help cmd_name if you want to see what a command does)

nsh> ?
help usage:  help [-v] [<cmd>].      cat    dmesg  help   mkfatfs   pwd    test   uptime     [      cd     echo   hexdump   mkrd   readlink  time   usleep    
?      cp     env    kill   mount  rm     true   xd  
alias  cmp    exec   losetup   mv     rmdir  truncate  
unalias   dirname   exit   ln     poweroff  set    uname
basename  dd     false  ls     printf sleep  umount    
break  df     free   mkdir  ps     source unset
Builtin Apps:
dumpstack  gpio    hello   nsh     sh

What is the first program candidate for future developer runs? You guest right!

nsh> hello
Hello, World!!

How much memory does our simulator have? I knew it was a Unix/Linux-like RTOS!

nsh> free
             total      used      free        largest   nused  nfree
Umem:        67108192   1791840   65316352    65316288  80     2

What is running on my CPU?

nsh> ps
0  0   0 FIFO  Kthread N-- Ready           0000000000000000 069584 Idle Task
1  1 255 FIFO  Kthread --- Waiting  Signal 0000000000000000 067504 loop_task
2  2 224 FIFO  Kthread --- Waiting  Semaphore 0000000000000000 067488 hpwork 0x5613aae96a20
3  3 100 FIFO  Task --- Running         0000000000000000 067504 nsh_main

Why is there a /proc/version and a uname command?

nsh> cat /proc/version
NuttX version 12.1.0 1a927a6cf3 May 29 2023 18:15:17

nsh> uname -a
NuttX 12.1.0 1a927a6cf3 May 29 2023 18:15:17 sim sim

Pay attention, they are not the same, uname will show the architecture (sim, arm, risc-v, etc) and the board name (sim, stm32f103-minimum, esp32c3-devkit, etc).

Ok, nice but how can I leave this simulator? Ctrl+C, Ctrl+Z, etc didn't work!!!

nsh> poweroff

Welcome back to your host computer!

Next, I will explain how to use the NuttX configuration menu to select new features or tools.

[ - ]
Comment by cederomJune 9, 2023

NuttX POWERZ! :-)

[ - ]
Comment by Paul ClaessenDecember 12, 2023

I upgraded my Ubuntu Linux system to version 23.10, and now I'm following along with the instructions in this tutorial.

When I get to:


Install the ELF tools:

$ pip install pyelftools cxxfilt


I get the following error:

paul@mail:~/nuttxspace/nuttx$ pip install pyelftools cxxfilt

error: externally-managed-environment

× This environment is externally managed

╰─> To install Python packages system-wide, try apt install

    python3-xyz, where xyz is the package you are trying to


    If you wish to install a non-Debian-packaged Python package,

    create a virtual environment using python3 -m venv path/to/venv.

    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make

    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,

    it may be easiest to use pipx install xyz, which will manage a

    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.

hint: See PEP 668 for the detailed specification.


When I then try the message's suggestion and try:


sudo apt install python3-pyelftools


it seems to work (at least it installs something), but when I then try 


sudo apt install python3-cxxfilt


I get the following error:


Reading package lists... Done

Building dependency tree... Done

Reading state information... Done

E: Unable to locate package python3-cxxfilt


So, how do I proceed?

Thanks in advance.

[ - ]
Comment by acassisDecember 12, 2023

Hi Paul,
Thank you very much for sharing your issues and partial found solution, it could help more people facing similar issues.

In fact python3-cxxfilt is not present on Ubuntu 23.10 (also not in 23.04). Anyway for normal usage you will not depend on cxxfilt.

This cxxfilt is only necessary to run parsetrace.py for specific tracing purpose. So you can follow the tutorials even without installing it.

BTW I opened an issue in the project asking more people to get ideas how to figure out this missing package: https://github.com/apache/nuttx/issues/11376

Best Regards,


[ - ]
Comment by garyhobsonDecember 12, 2023

I found the reason and solution on stackoverflow:


The recommended solution is:

python3 -m venv .venv
source .venv/bin/activate
pip install cxxfilt 

A simpler way is:

pip install --break-system-packages --user cxxfilt

To post reply to a comment, click on the 'reply' button attached to each comment. To post a new comment (not a reply to a comment) check out the 'Write a Comment' tab at the top of the comments.

Please login (on the right) if you already have an account on this platform.

Otherwise, please use this form to register (free) an join one of the largest online community for Electrical/Embedded/DSP/FPGA/ML engineers: