Porting boards

At some point you might need to port a new BOARD to RIOT, either because that specific development board is not yet supported or because you have a custom BOARD for your project.

If you want to port a BOARD to RIOT you have two choices: doing it inside of RIOTBASE or outside. In either case the file structure is basically the same and moving from one to another is easy.

This guide details the generic structure you need to add a new BOARD to RIOT, the different files as well as their functionality.

Note
We assume here that your CPU and CPU_MODEL is already supported in RIOT so no peripheral or cpu implementation is needed.

General structure

Like applications or modules, boards consist on a directory containing source files and makefiles. Usually a BOARD directory has the following structure

board-foo/
|----dist/
|----scripts
|----board.c
|----doc.txt
|----include/
|----periph_conf.h
|----board.h
|----gpio_params.h
|----Makefile
|----Makefile.dep
|----Makefile.features
|----Makefile.include

Source files

Header files in board-foo/include define physical mappings or configurations. e.g:

  • periph_conf.h: defines configurations and mappings for peripherals as well as clock configurations.
  • board.h: holds board specific definitions or mappings, for example LEDs, buttons. It might as well override default drivers parameters (e.g.: assigning specific pin connections to a LCD screen, radio, etc.). Some boards might also define optimized XTIMER_% values (e.g. XTIMER_BACKOFF).
  • gpio_params.h: if the board supports SAUL then its saul_gpio_params_t is defined here.
  • other: other specific headers needed by one BOARD
Note
Header files do not need to be defined in include/, but if defined somewhere else then they must be added to the include path. In Makefile.include: INCLUDES += -I<some>/<directory>/<path>

Board initialization functions are defined in board.c. This file must at least define a board_init() function that is called at startup. This function initializes the CPU by callingcpu_init() among others.

void board_init(void)
{
/* initialize the CPU core */
/* initialize GPIO or others... */
...
}

Makefiles

Makefile

A board's Makefile just needs to include Makefile.base in the RIOT repository and define the MODULE as board (see modules for more details)

MODULE = board
include $(RIOTBASE)/Makefile.base

Makefile.dep

Dependencies on other MODULES or FEATURES can be defined here. This might specify MODULES or dependencies that need to be pulled under specific configurations. e.g.: if your board has a sx1276 lora chip:

ifneq (,$(filter netdev_default,$(USEMODULE)))
USEMODULE += sx1276
endif
Note
Makefile.dep is processed only once so you have to take care of adding the dependency block for your board before its dependencies pull in their own dependencies.

Makefile.features

This file defines all the features provided by the BOARD. These features might also need to be supported by the CPU. Here, define the CPU and CPU_MODEL (see build system basics for more details on these variables).

e.g.:

CPU = foo
CPU_MODEL = foobar
# Put defined MCU peripherals here (in alphabetical order)
FEATURES_PROVIDED += periph_i2c
FEATURES_PROVIDED += periph_spi
FEATURES_PROVIDED += periph_uart

Makefile.include

This file contains BSP or toolchain configurations for the BOARD. It should at least define the configuration needed for flashing (i.e. a programmer) as well as the serial configuration (if one is available).

e.g.:

# Define the default port depending on the host OS
PORT_LINUX ?= /dev/ttyUSB0
PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.usbserial*)))
# setup serial terminal
include $(RIOTMAKE)/tools/serial.inc.mk
# this board uses openocd
include $(RIOTMAKE)/tools/openocd.inc.mk

doc.txt

Although not explicitly needed, if upstreamed and as a general good practice, this file holds all BOARD documentation. This can include datasheet reference, documentation on how to flash, etc.

The documentation must be under the proper doxygen group, you can compile the documentation by calling make doc and then open the generated html file on any browser.

```md /**