Feedback
Feedback

If you are having issues with the exercises, please create a ticket on DevZone: devzone.nordicsemi.com
Click or drag files to this area to upload. You can upload up to 2 files.

Creating board files

In this topic, we will explore the different options to create custom board files and the guidelines for naming your custom board. You can watch the video below or go through the lesson’s text.

We will also cover the mandatory files required to define a custom board, optional files, and revision files used if you create revisions for your board. We will study these files one by one and understand the role of each.

In the exercises of Lesson 3, we will use the Create a new board GUI in nRF Connect for VS Code extension to help us populate most of the content of the mandatory files.

Naming your custom board

When naming your custom board, there are some conventions that you need to follow.

  • You need to give your board a unique name. Run west boards in the nRF Connect Terminal for a list of names that have already been taken; you can’t name your custom board with a name that is already in use.
  • It’s recommended that your board name include the name of the SoC at the end. For instance, suppose we want to make a new board called DevAcademy, which is based on the nRF52833 SoC. It’s highly recommended that you call your board “DevAcademy nRF52833”.

Note that the Create a new board GUI in nRF Connect for VS Code extension will ask you to provide a human-readable name for your board (Ex: DevAcademy nRF52833), and it will automatically generate your board ID (devacademy_nrf52833) that can be used by west build command or by the Add Build Configration GUI.

Where to define your custom board

There are three options for where to store custom board files with varying advantages and disadvantages:

  • Upstream in Zephyr. You usually select this path if you are developing a development kit, a module, a reference design, or a prototyping platform and want to make your board definition public and available to the public. Using this path may also apply if you design an open-source product. Remember that you must provide documentation for your board, and Zephyr maintainers will need to review and approve your board files Pull Request.
  • In a dedicated directory (out-of-tree board): Your board files will reside in a directory that is out-of-tree of nRF Connect SDK/ Zephyr. We will pass the custom board directory location to the build system. This method is recommended if you are developing a closed-source product and want to control access to the board files. This is the method that we will cover in this lesson.
  • In a boards folder in your application directory. Suitable for prototyping/debugging

Board files

As we mentioned before, we will use the nRF Connect for VS Code to create the template files for a new development kit called “DevAcademy nRF52833” which is based on the nRF52833 SoC. The board ID generated by the extension is devacademy_nrf52833. The extension will also automatically populate the architecture “ARCH” used by the SoC. As we will see in Exercise 1

When creating a custom board definition, remember that the hardware layers files from Architecture until SoC are provided by the SDK itself. We only need to populate the board layer. The board layer consists of these six mandatory files.

Below is a board layer consisting of all mandatory files, optional and special use cases files:

The devacademy_nrf52833 will be your board’s name, of course. We are using this name just as a placeholder.

Now, we will cover these files one by one.

The mandatory files are:

  1. Kconfig.board: The extension automatically generates this file, and we typically don’t need to change anything inside it. What it does is that it makes a Kconfig Symbol for your board BOARD_DEVACADEMY_NRF52833and it specifies a dependency to the SoC hardware support layer(through the depends on Keyword ).

2. Kconfig.defconfig: Board-specific default values for Kconfig options. The extension automatically generates this file, and we typically don’t need to change anything inside it.

The file is placed inside an if BOARD_DEVACADEMY_NRF52833 / endif pair of lines, as shown below. When the developer passes the selected target board through either west (CLI) or using nRF Connect for VS Code Build Configration window (GUI), the BOARD_DEVACADEMY_NRF52833 will be set and the Kconfig BOARD symbol will be set through the project. The other option we find in that file is BT_CTLR which is to enable support for SoC native Bluetooth LE controller implementation, and it is enabled only if the CONFIG_BT is selected by the application. This is added here due to the fact that the nRF52833 is widly used for Bluetooth LE applications.

  1. devacademy_nrf52833_defconfig: This file is the Kconfig fragment merged as-is into the final build of any application built for the specified board. The default Kconfig symbols that are generated by the extension are:
    • Series hardware support, in the case of the nRF52833 SoC is CONFIG_SOC_SERIES_NRF52X . which will enable the CPU and architecture support .
    • SoC hardware support, CONFIG_SOC_NRF52833_QIAA
    • Board hardware support
    • Also if the hardware suppot MPU, it will be added here

Default devacademy_nrf52833_defconfig generated by the tool.

What we need to add in this file in addition to the default Kconfig symbols are any Kconfig symbols that we want to be enabled for any application build for our board.

In the case of the DevAcademy nRF52833 we want to add UART, RTT and GPIO support. Therefore, we will append the following :

Note

<BoardID>_defconfig is a Kconfig fragment merged as-is into the final build of any application built for the specified board, and must enable the bare minimum. It’s the application configuration’s (prj.conf) responsibility to configure what is needed.
  1. devacademy_nrf52833.dts: The hardware description in devicetree format that represents the schematics of your board. We call this file board-level devicetree file. It Includes connectors and any other hardware components such as LEDs, buttons, sensors, or communication peripherals (USB, BLE controller, etc). Flash partitioning is also done in this file. We will rely heavily on the automation provided by nRF Connect for VSCode extension, including the DeviceTree visual editor, to help us populate this file.
  2. devacademy_nrf52833-pinctrl.dtsi : This file defines the pin-mapping of your board’s peripherals. Note that the extension does not create this file; we must create it ourselves. We will learn how to populate this file in Exercise 1

The optional files are:

  • board.cmake: used for Flash and debug support, if the board has Flash or Debug support.
  • CMakeLists.txt: If you need to add source files to be executed Pre or Post kernel. This is in case your hardware uses some muxes or needs to be configured in a particular way. Customization can be added here, as done for the case of the nRF52840 Dongle where the board_nrf52840dongle_nrf52840_init() is executed at PRE_KERNEL_1 before the kernel. Note that the extension does not create the CMakeLists.txt file; we can manually create it ourselves if needed.
  • doc/index.rst, doc/devacademy_nrf52833.png: documentation for and a picture of your board. You only need this if you’re Contributing your board to Zephyr.
  • Kconfig : Give us the flexibility of creating a board menu
  • devacademy_nrf52833.yaml: a YAML file with miscellaneous metadata used by the Test Runner (Twister).

Board revisions

In case you will be creating new hardware revisions for your board. In other words, when you decide to modify your schematics and make a new PCB, you don’t have to create a new board definition, all you need to do is to add the modifications inside the board folder by adding the following files: devacademy_nrf52833_<revision>.conf , devacademy_nrf52833_<revision>.overlay and revision.cmake

  • The optional Kconfig settings specified in the file devacademy_nrf52833_<revision>.conf will be merged into the board’s default Kconfig configuration.
  • The optional devicetree overlay devacademy_nrf52833_<revision>.overlay will be added to the common devacademy_nrf52833.dts devicetree file
  • The revision.cmake file controls how the Zephyr build system matches the <board>@<revision> string specified by the user when building an application for the board for either the west build CLI or the nRF Connect for VS Code extension. An example development kit that uses the board revisions is the nRF9160 DK.

Note

When creating a new custom board, it is always a good idea to start looking into the SDK-defined boards with the same SoC/SIP as your custom board for inspiration. There is a long list of Development Kits, Prototyping Platforms, and Reference designs already shipped in the SDK that can serve as a good starting point.

They are available in two locations <install_path>/zephyr/boards/arm/ and <install_path>/nrf/boards/arm/

See the Zephyr Board Porting Guide.
Register an account
Already have an account? Log in
(All fields are required unless specified optional)

  • 8 or more characters
  • Upper and lower case letters
  • At least one number or special character

Forgot your password?
Enter the email associated with your account, and we will send you a link to reset your password.