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?
Quick Links
- Part 1: Getting Started with (Apache) NuttX RTOS - Part 1
- Part 2: Getting Started with (Apache) NuttX RTOS Part 2 - Looking Inside and Creating Your Customized Image
- Part 3: Getting Started with NuttX RTOS on Three Low Cost Boards
- Part 4: Using GPIO in (Apache) NuttX RTOS
- Part 5: Using (Apache) NuttX USERLED Subsystem
- Part 6: Using (Apache) NuttX Buttons Subsystem
- Part 7: How to use I2C devices in (Apache) NuttX: Scanning for Devices
- Part 8: How to use I2C devices in (Apache) NuttX: Adding support for an I2C device in your board
- Part 9: How to use SPI devices in NuttX RTOS
- Part 10: How to use analog input (ADC) on NuttX RTOS
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 gain experience!
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! :-)
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
install.
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.
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,
Alan
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: