Getting Started with (Apache) NuttX RTOS - Part 1
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?
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.
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.
$ 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 Select CONFIG_HOST_LINUX=y Refreshing... … # # 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
and:
$ 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:
Login: admin Password: Administrator User Logged-in! nsh>
Congratulations, you are a NuttX user now!
While you try to become a NuttX developer, please enjoy the environment:
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 nsh>
What is the first program candidate for future developer runs? You guest right!
nsh> hello Hello, World!! nsh>
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 nsh>
What is running on my CPU?
nsh> ps PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACK COMMAND 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 nsh>
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.- Comments
- Write a Comment Select to add a comment

NuttX POWERZ! :-)
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: