Getting Started with (Apache) NuttX RTOS - Part 1

• RTOS
• Linux
• Microcontroller

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!

Sign in