Custom Boards How-To

As explained in Configuring, supported boards (also known as “in-tree” boards) are configured using a standard syntax:

$ cd nuttx
$ ./tools/configure.sh -l board-name:config-name
  Copy files
  Select CONFIG_HOST_LINUX=y
  Refreshing...

Sometimes it is not appropriate, or not wanted, to add a new or custom board to the NuttX boards tree itself. If so, the board can be defined out-of-tree in a custom directory and still be built easily.

Add a Custom Board

The same set of files as provided for in-tree boards is required (i.e. configs, Kconfig, scripts, etc.) but these can be placed in a directory of your choice.

In this example, the files are assumed to exist in:

../nuttx/CustomBoards/MyCustomBoardName

$pwd
/home/nuttx/nuttx
$ ls -1 ../CustomBoards/MyCustomBoardName
configs
helpers
include
Kconfig
scripts
$ ls ../CustomBoards/MyCustomBoardName/configs
nsh
MyCustomConfig
$

At this stage, the contents of the files is not important. The notable exception to this is file named defconfig, which is stored in the directory MyCustomConfig (see the listing above.)

This file is autogenerated and should not be edited manually. However, it should also not be copied blindly from an existing board as the values within are incorrect for the custom board. This causes an issue because the configure script called below is supposed to create some symbolic links in the NuttX source tree and it is using the contents of the defconfig file for that. Since the file does not exist, configure script will fail which prevents the user from creating the defconfig file automatically.

As a workaround, a minimal defconfig file needs to be provided. See an example for AVR architecture:

CONFIG_ARCH="avr"
CONFIG_ARCH_AVR=y
CONFIG_ARCH_BOARD_CUSTOM=y
CONFIG_ARCH_BOARD_CUSTOM_DIR_RELPATH=y
CONFIG_ARCH_BOARD_CUSTOM_DIR="../CustomBoards/MyCustomBoardName/"
CONFIG_ARCH_BOARD_CUSTOM_NAME="MyCustomBoardName"
CONFIG_ARCH_CHIP="avrdx"

This minimal file should be sufficient for the configure script to succeed. Additional changes can be made using make menuconfig and proper defconfig file can then be generated using make savedefconfig.

To build the custom board, alter the contents of the example above to fit your architecture and chip, then use this syntax, which is slightly different from in-tree boards and configs:

$ ./tools/configure.sh -l ../CustomBoards/MyCustomBoardName/configs/MyCustomConfig
Copy files
Select CONFIG_HOST_LINUX=y
Refreshing...

Kconfig Settings

Once the board is configured, to ensure subsequent builds run correctly, there are two Kconfig settings that need to be set. These are:

Board Selection ‣ Custom Board Configuration ‣ Custom Board Name

Board Selection ‣ Custom Board Configuration ‣ Relative custom board directory

They should be set to suit your board name and directory location.

Note

If you subsequently run a make distclean operation, then these settings will be lost. They should be added back before building, and/or before running make menuconfig.

Kconfig flags

Some boards make using of Kconfig ARCH_HAVE_* flags in order to be able to select certain features. For example, ARCH_HAVE_LEDS is a necessary flag for enabling CONFIG_ARCH_LEDS=y because it tells the build system that the board has LEDs. Selecting ARCH_HAVE_* flags happens inside the NuttX build system, so it is not accessible to custom boards. If you need to enable these flags, then you should select them manually with the BOARD_CUSTOM_* options:

BOARD_CUSTOM_LEDS selects ARCH_HAVE_LEDS
BOARD_CUSTOM_BUTTONS selects ARCH_HAVE_BUTTONS
BOARD_CUSTOM_IRQBUTTONS selects ARCH_HAVE_IRQBUTTONS
BOARD_CUSTOM_INTERRUPT selects ARCH_PHY_INTERRUPT

If there are any other ARCH_HAVE_* selectors you cannot access but need for your custom board, please open an issue!

Kconfig file

You may have noticed that in-tree boards typically surround their board-level Kconfig logic with something like:

if ARCH_BOARD_BOARDNAME
endif # ARCH_BOARD_BOARDAME

You should not do this for custom boards; just write your Kconfig logic without the guard. However, it is still good practice to prefix your custom Kconfig options with the board name:

config BOARDNAME_MYOPTION
    bool "My custom option"
    default n
    ---help---
        This is my custom option for my custom board.