Orbifx's compendium

Getting started for NuttX development on Linux

Nuttx is a cool POSIX OS; learn how to start developing with it.

| | | topics: computing | keywords: nuttx
id: 9ac57de8-43ae-4843-bb81-6f9ba9da99b9


This guide is based on information from the main ReadMe and the SAM4-EK ReadMe as an example because it is the platform of interest to the author. Other platforms will require similar processes, so this guide should be useful in other cases too.

Why NuttX

Nuttx is small, aims for POSIX compatibility and can run on devices with or without a memory management unit (MMU). It is open source, with a very permissive licence.

Having an operating system means a lot of functionality is already there, as well as a layer for third-party applications to work with your application. Since your application is likely to depend on the operating system, it can run anywhere the operating system can run.

The alternatives would be to use closed source, vendor specific tools, either targeting the bare metal or running on top of the their propriety system. In both cases your investment is "locked" to work only for those devices, with those tools.

Be warned that NuttX doesn't include GNU extensions, which a lot of Linux applications depend on. This is for keeping POSIX compatibility and potentially avoiding extensions which aren't friendly for the targeted architectures.

The NuttX package

Download from servers

NuttX can be downloaded from the downloads page as a package or as a git repository. The git repository is recommended.

git clone https://bitbucket.org/patacongo/nuttx.git

Since this article was first written, the git cloning process has changed. The project is sub-divided in modules know; read how to clone submodules.

Package files

There are two directories of interest for the scope of this guide nuttx & apps. The directory nuttx contains all the code for the operating system and apps contains essential and optional applications.

Other dependencies

Tool chain

To get NuttX on running on a device you need a tool chain (which includes the compiler). The recommended compiler is arm-none-eabi-gcc, which targets the "bare metal".

In Arch Linux you can install the tool chain with:

pacman -Syu arm-none-eabi-gcc

In Ubuntu Linux:

apt-get install gcc-arm-none-eabi

If you are not using the above distributions, check your own distribution if it has a similar package. Otherwise you can build your own but this is beyond the scope of this writing.


Starting off with an existing one

NuttX comes with plentiful configurations for devices or boards. Take a look in nuttx-code/nuttx/configs/. Every directory in there contains configurations.

To install a configuration before the build, change to the tools directory and use the configuration tool:

cd nuttx-code/tools
./configure.sh sam4e-ek/nsh

In the example above we call on use the nsh (NuttX Shell) configuration to build NuttX. If the tool runs successfully, return to the nuttx-code/nuttx directory. Where make takes place.

Configuring before the build

Whether because you are starting without an existing configuration or because you want to modify an existing one you can run one of the kconfig front-ends to modify the nuttx-code/nuttx/.config file. This file contains definitions which control the whole building process. Depending on what you want to do, it may be enough to configure this file and build the binary that will run on your device.


If you are not looking to reconfigure the build .config you can skip this section.

Kconfig is the Linux kernel configuration tool and originates from http://kernel.org/. You can also download it from https://github.com/guillon/kconfig, by cloning the directory and building it according its ReadMe file.

When you have Kconfig installed, execute:

make menuconfig

Or instead of menuconfig use your front-end of preference (qconfig, gonfig, ..). This will start a screen which controlls the build process of NuttX.


To build the package switch to the nuttx directory and run make.

cd nuttx-code/nuttx

The conventional make rules apply (make clean etc). Make should run for a little while depending on your machines resources. If successful it will result in nuttx-code/nuttx/nuttx.bin, which is the operating system, along with all the applications. A complete binary to download on the device for execution.

Installing on device


There are different "programmers", so this section used the Atmel's case as an guide for other devices. The idea is that the nuttx.bin binary file generated, need to be appropriately installed on the device and any parameters for the device need to be configured.


In the case of the Atmel devices the programming software is called Atmel SAM-BA In-system Programmer, which should work on Linux in general.

For Arch, the easiest way to get it is by installing the AUR at https://aur.archlinux.org/packages/sam-ba/. Ubuntu could have something in the PPA repository, like freesba.

The software is installed in the /opt/sam-ba directory, as /opt is used for all stand-alone applications. It is important that your user is part of the uucp group. Erase the device's memory, otherwise it won't appear in the following program, even if connected to the computer. When the device is erased and connected execute:


on a 64 bit machine, or:


on a 32 bit machine. This starts the program's graphical user interface. The initial dialogue has three fields:

Select the connect: <port used to connect to device, automatically detected>
Select your board:  <board type, automatically detected>
JLink TimeoutMultiplier: <Defaut is 0>

As an example in my case the values I have are:

Select the connect: /dev/ttyACM0
Select your board:  at91sam4e16-ek
JLink TimeoutMultiplier:    0

By clicking connect and if all goes well, the dialogue should be replaced by a window for configuring the device. There is a lot of functionality available here, but only the basic downloading will be covered here, in a series of steps:

  1. From Scripts
    • select "Enable flash access"
    • click Execute.
  2. In the Download / Upload File
    • Click the folder icon for the Send File Name field
    • Find and select the nuttx.bin file
    • Click Send File
  3. From Scripts select:
    • "Boot from Flash (GPNVM1)"
    • Click Execute.

Make sure the jumper is not in flash reset position. Reset the board.

Running the application

Connecting to the console

With the device programmed, connect the serial port selected for the console (DBGU for SAM4-EK) to a serial port of your computer. This is the port which will send & receive the NuttX Shell console to your computer.

To connect to this console, you can use a program like [screen][https://en.wikipedia.org/wiki/GNU_Screen], with the following command:

screen /dev/ttyS0 115200 8N

In this command /dev/ttyS0 is the device pathname, which can vary from machine to machine. The number 115200 is the baud rate and 8N1 describes the character format. This information is applicable to any application used to connect to the device's serial port.

Depending on what has to start when the device boots, like DHCP, this may take a while. The LEDs on the board are a clue if things are running normally. Eventually you should see this message, the prompt:

NuttShell (NSH)

If you somehow connect to the console after the prompt was send, just hit enter and see if you get another prompt.

If you decide to use screen you will be glad to know how to quit it: hit Ctrl+a and then \.

Doing things with the console

NSH (NuttX Shell) is a conventional console shell. It doesn't have some of the handy features other shells have, but consider it a lesson on understanding how far computing has come. I'll excite your motivation with some basic commands to get you started:

Help is all you need to know to get started, specially if you are familiar with Unix-y consoles. Notice that in the bottom part of the message returned by help, there is a list of the built-in applications you may have chosen to build with NuttX during the configuration stage. There is another way of running applications (from the file system) but that is outside the scope of this article.

So an application you make, if you compile it as a build-in, should appear in this list. To run it just type the name of the application as it appears in the list.

What next

This guide had a goal of getting someone started with developing on NuttX. From there on you need to learn how to develop applications for it. I may be writing a guide on that, but until I do you can checkout of the following article:

Writing NuttX Applications