In this topic, we will explore the different options to create custom board files and the guidelines for naming your custom board.
We will also cover the mandatory files required to define a custom board in HWMv2, optional files, and revision files used if you create revisions for your board. We will study these files one by one and understand their role.
In Exercise 1 of Lesson 3, we will use the Create a new board GUI in the nRF Connect for VS Code extension to populate most of the mandatory files’ content.
Note
The Create new board GUI in the latest version of nRF Connect for the VS Code extension uses a west extension command called ncs-genboard. If you are confident with CLI, you could use it directly.
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.
In HWMv2, it’s no longer needed to include the name of the SoC at the end of the board name. Instead, the SoC(s) name(s) are specified explicitly in the board.yml file
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. The Human-readable name (also known as full_name) could include white spaces or capital letters. (Ex: My nRF54L DK , DevAcademyL3E1), and it will automatically generate your board ID (Ex: my_nrf54l_dk, devacademyl3e1) that can be used bywest buildcommand or by the Add Build Configuration GUI.
HWMv2 – Board terminology
In Hardware Model version 2, each board will have a board name. The board name (Board ID) used in the build system is usually the human-readable name, formatted in all lowercase letters and using underscores (_) to replace all whitespaces. Each board must have one SoC at a minimum.
In addition to the board name and SoC. A board could have an optional board revision and board qualifiers. Now let’s take a look at the board terminology used in HWMv2. We will take a look at the BL5340 DVK from Ezurio which is based on the nRF5340 SoC.
Board Target: The full string that can be provided to any of the Zephyr build tools(E.g. west) to compile and link an image for a particular hardware system. A key point to understand is that boards with single-core SoCs typically have one board target, while more advanced boards with multiple SoCs or multi-core SoCs may have several board targets.
Board qualifiers: The set of additional tokens, separated by a forward slash / that follows the board name (and optionally board revision).
Variant: In the context of board qualifiers, a variant designates a particular type or configuration of a build for a combination of SoC and CPU clusters. Common uses of the variant concept include introducing both secure and non-secure builds for platforms with TrustedFirmware-M support, or selecting the type of RAM used in a build. Another use of variants is for different builds of hardware(not a revision). For example, if you have a board that includes sensors and another exact one that does not include sensors.
Board revision: This is used to capture new changes in new versions of the hardware(New schematics, new PCB).
For example, a board with a human-readable name “DevAcademyL3E1” will have a board name (board ID) of devacademyl3e1 . Let’s assume the kit is based on the nRF52833 SoC . The board will have the board target devacademyl3e1/nrf52833 . The board could have an optional revision that can be specified as [email protected]/nrf52833 and it could have an optional variant [email protected]/nrf52833/sense . The CPU cluster(s) is defined by the SoC layer as we will see later. The nRF52833 SoC does not include any clusters.
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 community. 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 “DevAcademyL3E1” which is based on the nRF52833 SoC. The board name generated by the extension is devacademyl3e1. The extension will also populate the “vendor” of 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 four mandatory files.
Below is a board layer consisting of all mandatory files, optional and special use cases files:
Copy
boards/<vendor>/devacademyl3e1├── board.yml├── Kconfig.devacademyl3e1├── devacademyl3e1_<qualifiers>.dts ├── devacademyl3e1_<qualifiers>-pinctrl.dtsi├── devacademyl3e1_<qualifiers>_defconfig├── Kconfig.defconfig├── board.cmake # Used for flash and debug├── CMakeLists.txt # Needed in special cases ├── c_files.c # Needed in special cases├── doc # Optional │ ├── devacademyl3e1.png│ └── index.rst├── Kconfig # Optional to create a board Kconfig options menu├── devacademyl3e1_<qualifiers>.yml # Optional for Test Runner (Twister)├── devacademyl3e1_<qualifiers>_<revision>.conf # Needed to support hardware revisions├── devacademyl3e1_<qualifiers>_<revision>.overlay #Needed to support hardware revisions└── dts # Optional └── bindings
The term devacademyl3e1 serves as a placeholder for the board name, and <vendor> is a placeholder for the vendor name. If the board has qualifiers, such as multiple SoCs, CPU clusters, or variants (i.e., multi board target), these qualifiers must be appended to the board name to clearly indicate where you want these files to apply.
Now, we will cover these files one by one.
The mandatory files are:
1. board.yaml: This is a new file introduced in HWMv2 . It’s mandatory, so each board folder needs to have one board.yaml file.
It defines the board(s) name.
Must select at least one SoC.
Revisions are optional.
Variants are special use cases.
The CPU clusters are inherited from the SoC selected and should not be described here.
You could define multiple boards in one folder and with one board.yaml, but it’s not a common use case.
The extension automatically generates this file when you provide the tool with your board name, SoC, SoC variant, and vendor, and you typically don’t need to change anything inside it.
Note
You could also include full_name: in board.yml to specify the human-readable name of your board.
Here are some examples of board.yml for some Nordic development kits:
So for a single board target like the nrf52840 dongle, which is based on the nrf52840 SoC, a single-core device with no CPU clusters.
For the nRF54L15, there are two cpuclusters defined by the SoC layer, cpuapp and cpuflpr, and you can see that the board.yml defines a new variant called xip which is associated with the cpuflpr cpucluster. It also defined another variant called ns (TF-M Enabled) with the cpuapp cpucluster. So in total, you have 4 board targets.
For the nRF9161 DK, there are no cpuclusters defined for the nRF9161 SiP , there is a variant called ns that is associated with the nrf9161 SoC. It also defines two revisions 0.9.0 (default) and 0.7.0.
2. Kconfig.devacademyl3e1: This file has a fixed-defined task: selecting the specific SoC(s) used by a board. Hence, it pulls in lower layers of SW support (SoC, Family, Series, CPU, Arch). It also defines a Kconfig symbol for the board that is a normalized name of the board name ( with capital letters, and whitespace converted to underscore _ ) prefixed with BOARD_ .
It contains select statement(s)
Only selectis needed for a single board target
select … if statements for multi-cores SoC or multi-SoC board
Here are some examples:
Below is an example of our devacademyl3e1 (single board target) that we will develop in Exercise 1, which is based on the nRF52833 QIAA.
Copy
configBOARD_DEVACADEMYL3E1selectSOC_NRF52833_QIAA
Here is another example for the nRF54L15 DK (quad board target). The file selects the appropriate SoC support layer based on the normalized board target triggered from the build system.
3.devacademyl3e1.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). Memory 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. Keep in mind that if your board has multiple board qualifiers, you need to create a board-level device tree file for each board target. Also, it’s worth mentioning that you can structure the board-level device tree file into multiple files to improve readability and maintainability.
4.devacademyl3e1-pinctrl.dtsi : This file defines the pin-mapping of your board’s peripherals. Keep in mind that if your board has multiple board qualifiers, you need to create a pin-mapping file for each. We will learn how to populate this file in Exercise 1.
The optional files are:
devacademyl3e1_defconfig : This file is a Kconfig fragment merged as-is into the final build of any application built for the specified board.
Default devacademyl3e1_defconfig generated by the tool (Differs from one SoC to another).
<boardname>_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.
Keep in mind that if your board has multiple board qualifiers, you need to specify the qualifiers in the name of the file devacademyl3e1_<qualifiers>_defconfig to take effect when a certain qualifier is passed to the build system.
Kconfig.defconfig : Board-specific default values for Kconfig options. The content of this file is placed inside if /endif pair. This file is generated by the tool. Let’s see the example of our devacademyl3e1 , which has a single board target devacademyl3e1/nrf52833.
We can see we have the 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.
You could have multiple if/endif pairs for the different normalized board targets (if the board has multiple board targets). Let’s take the example of Kconfig.defconfig of the nRF54L15 DK.
Now, let’s look at the remanding of optional files.
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/devacademyl3e1.png: You only need documentation and a picture of your board if you’re Contributing your board to Zephyr.
Kconfig: Give you the flexibility of creating a board menu.
devacademyl3e1.yml: a YML file with miscellaneous metadata used by the Test Runner (Twister). If your board has multiple qualifiers, you need to have a .yml for each.
Board revisions
In case you are 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: devacademyl3e1_<revision>.conf , devacademyl3e1_<revision>.overlay and update board.yml . Keep in mind that if your board has multiple board qualifiers, you need to specify the .conf and .overlay files to the affected qualifiers: devacademyl3e1_<qualifiers>_<revision>.conf , devacademyl3e1_<qualifiers>_<revision>.overlay.
The optional Kconfig settings specified in the file devacademyl3e1_<revision>.conf will be merged into the board’s default Kconfig configuration.
The optional devicetree overlay devacademyl3e1_<revision>.overlay will be overlayed to the board-level devacademyl3e1.dts devicetree file.
The board.yml file through the revision: key controls how the Zephyr build system matches the <board_name>@<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/nordic/ and <install_path>/nrf/boards/nordic/
In this topic, we will explore the different options to create custom board files and the guidelines for naming your custom board.
We will also cover the mandatory files required to define a custom board in HWMv2, optional files, and revision files used if you create revisions for your board. We will study these files one by one and understand their role.
In Exercise 1 of Lesson 3, we will use the Create a new board GUI in the nRF Connect for VS Code extension to populate most of the mandatory files’ content.
Note
The Create new board GUI in the latest version of nRF Connect for the VS Code extension uses a west extension command called ncs-genboard. If you are confident with CLI, you could use it directly.
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.
In HWMv2, it’s no longer needed to include the name of the SoC at the end of the board name. Instead, the SoC(s) name(s) are specified explicitly in the board.yml file
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. The Human-readable name (also known as full_name) could include white spaces or capital letters. (Ex: My nRF54L DK , DevAcademyL3E1), and it will automatically generate your board ID (Ex: my_nrf54l_dk, devacademyl3e1) that can be used bywest buildcommand or by the Add Build Configuration GUI.
HWMv2 – Board terminology
In Hardware Model version 2, each board will have a board name. The board name (Board ID) used in the build system is usually the human-readable name, formatted in all lowercase letters and using underscores (_) to replace all whitespaces. Each board must have one SoC at a minimum.
In addition to the board name and SoC. A board could have an optional board revision and board qualifiers. Now let’s take a look at the board terminology used in HWMv2. We will take a look at the BL5340 DVK from Ezurio which is based on the nRF5340 SoC.
Board Target: The full string that can be provided to any of the Zephyr build tools(E.g. west) to compile and link an image for a particular hardware system. A key point to understand is that boards with single-core SoCs typically have one board target, while more advanced boards with multiple SoCs or multi-core SoCs may have several board targets.
Board qualifiers: The set of additional tokens, separated by a forward slash / that follows the board name (and optionally board revision).
Variant: In the context of board qualifiers, a variant designates a particular type or configuration of a build for a combination of SoC and CPU clusters. Common uses of the variant concept include introducing both secure and non-secure builds for platforms with TrustedFirmware-M support, or selecting the type of RAM used in a build. Another use of variants is for different builds of hardware(not a revision). For example, if you have a board that includes sensors and another exact one that does not include sensors.
Board revision: This is used to capture new changes in new versions of the hardware(New schematics, new PCB).
For example, a board with a human-readable name “DevAcademyL3E1” will have a board name (board ID) of devacademyl3e1 . Let’s assume the kit is based on the nRF52833 SoC . The board will have the board target devacademyl3e1/nrf52833 . The board could have an optional revision that can be specified as [email protected]/nrf52833 and it could have an optional variant [email protected]/nrf52833/sense . The CPU cluster(s) is defined by the SoC layer as we will see later. The nRF52833 SoC does not include any clusters.
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 community. 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 “DevAcademyL3E1” which is based on the nRF52833 SoC. The board name generated by the extension is devacademyl3e1. The extension will also populate the “vendor” of 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 four mandatory files.
Below is a board layer consisting of all mandatory files, optional and special use cases files:
Copy
boards/<vendor>/devacademyl3e1├── board.yml├── Kconfig.devacademyl3e1├── devacademyl3e1_<qualifiers>.dts ├── devacademyl3e1_<qualifiers>-pinctrl.dtsi├── devacademyl3e1_<qualifiers>_defconfig├── Kconfig.defconfig├── board.cmake # Used for flash and debug├── CMakeLists.txt # Needed in special cases ├── c_files.c # Needed in special cases├── doc # Optional │ ├── devacademyl3e1.png│ └── index.rst├── Kconfig # Optional to create a board Kconfig options menu├── devacademyl3e1_<qualifiers>.yml # Optional for Test Runner (Twister)├── devacademyl3e1_<qualifiers>_<revision>.conf # Needed to support hardware revisions├── devacademyl3e1_<qualifiers>_<revision>.overlay #Needed to support hardware revisions└── dts # Optional └── bindings
The term devacademyl3e1 serves as a placeholder for the board name, and <vendor> is a placeholder for the vendor name. If the board has qualifiers, such as multiple SoCs, CPU clusters, or variants (i.e., multi board target), these qualifiers must be appended to the board name to clearly indicate where you want these files to apply.
Now, we will cover these files one by one.
The mandatory files are:
1. board.yaml: This is a new file introduced in HWMv2 . It’s mandatory, so each board folder needs to have one board.yaml file.
It defines the board(s) name.
Must select at least one SoC.
Revisions are optional.
Variants are special use cases.
The CPU clusters are inherited from the SoC selected and should not be described here.
You could define multiple boards in one folder and with one board.yaml, but it’s not a common use case.
The extension automatically generates this file when you provide the tool with your board name, SoC, SoC variant, and vendor, and you typically don’t need to change anything inside it.
Note
You could also include full_name: in board.yml to specify the human-readable name of your board.
Here are some examples of board.yml for some Nordic development kits:
So for a single board target like the nrf52840 dongle, which is based on the nrf52840 SoC, a single-core device with no CPU clusters.
For the nRF54L15, there are two cpuclusters defined by the SoC layer, cpuapp and cpuflpr, and you can see that the board.yml defines a new variant called xip which is associated with the cpuflpr cpucluster. It also defined another variant called ns (TF-M Enabled) with the cpuapp cpucluster. So in total, you have 4 board targets.
For the nRF9161 DK, there are no cpuclusters defined for the nRF9161 SiP , there is a variant called ns that is associated with the nrf9161 SoC. It also defines two revisions 0.9.0 (default) and 0.7.0.
2. Kconfig.devacademyl3e1: This file has a fixed-defined task: selecting the specific SoC(s) used by a board. Hence, it pulls in lower layers of SW support (SoC, Family, Series, CPU, Arch). It also defines a Kconfig symbol for the board that is a normalized name of the board name ( with capital letters, and whitespace converted to underscore _ ) prefixed with BOARD_ .
It contains select statement(s)
Only selectis needed for a single board target
select … if statements for multi-cores SoC or multi-SoC board
Here are some examples:
Below is an example of our devacademyl3e1 (single board target) that we will develop in Exercise 1, which is based on the nRF52833 QIAA.
Copy
configBOARD_DEVACADEMYL3E1selectSOC_NRF52833_QIAA
Here is another example for the nRF54L15 DK (quad board target). The file selects the appropriate SoC support layer based on the normalized board target triggered from the build system.
3.devacademyl3e1.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). Memory 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. Keep in mind that if your board has multiple board qualifiers, you need to create a board-level device tree file for each board target. Also, it’s worth mentioning that you can structure the board-level device tree file into multiple files to improve readability and maintainability.
4.devacademyl3e1-pinctrl.dtsi : This file defines the pin-mapping of your board’s peripherals. Keep in mind that if your board has multiple board qualifiers, you need to create a pin-mapping file for each. We will learn how to populate this file in Exercise 1.
The optional files are:
devacademyl3e1_defconfig : This file is a Kconfig fragment merged as-is into the final build of any application built for the specified board.
Default devacademyl3e1_defconfig generated by the tool (Differs from one SoC to another).
<boardname>_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.
Keep in mind that if your board has multiple board qualifiers, you need to specify the qualifiers in the name of the file devacademyl3e1_<qualifiers>_defconfig to take effect when a certain qualifier is passed to the build system.
Kconfig.defconfig : Board-specific default values for Kconfig options. The content of this file is placed inside if /endif pair. This file is generated by the tool. Let’s see the example of our devacademyl3e1 , which has a single board target devacademyl3e1/nrf52833.
We can see we have the 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.
You could have multiple if/endif pairs for the different normalized board targets (if the board has multiple board targets). Let’s take the example of Kconfig.defconfig of the nRF54L15 DK.
Now, let’s look at the remanding of optional files.
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/devacademyl3e1.png: You only need documentation and a picture of your board if you’re Contributing your board to Zephyr.
Kconfig: Give you the flexibility of creating a board menu.
devacademyl3e1.yml: a YML file with miscellaneous metadata used by the Test Runner (Twister). If your board has multiple qualifiers, you need to have a .yml for each.
Board revisions
In case you are 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: devacademyl3e1_<revision>.conf , devacademyl3e1_<revision>.overlay and update board.yml . Keep in mind that if your board has multiple board qualifiers, you need to specify the .conf and .overlay files to the affected qualifiers: devacademyl3e1_<qualifiers>_<revision>.conf , devacademyl3e1_<qualifiers>_<revision>.overlay.
The optional Kconfig settings specified in the file devacademyl3e1_<revision>.conf will be merged into the board’s default Kconfig configuration.
The optional devicetree overlay devacademyl3e1_<revision>.overlay will be overlayed to the board-level devacademyl3e1.dts devicetree file.
The board.yml file through the revision: key controls how the Zephyr build system matches the <board_name>@<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/nordic/ and <install_path>/nrf/boards/nordic/
This exercise tab is for nRF Connect SDK v2.6.2 – v2.5.2, where Hardware model v1 (HWMv1) is used. HWMv1 is deprecated and will be removed in nRF Connect SDK v3.0.0. Use HWMv2 for all new designs (newest tab)
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 bywest buildcommand 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 five mandatory files.
Below is a board layer consisting of all mandatory files, optional and special use cases files:
Copy
boards/<ARCH>/devacademy_nrf52833├── Kconfig.board ├── Kconfig.defconfig ├── devacademy_nrf52833_defconfig├── devacademy_nrf52833.dts ├── devacademy_nrf52833-pinctrl.dtsi├── board.cmake # Used for flash and debug├── CMakeLists.txt # Needed in special cases ├── c_files.c # Needed in special cases├── doc # Optional │ ├── devacademy_nrf52833.png│ └── index.rst├── Kconfig # Optional to create a board Kconfig options menu├── devacademy_nrf52833.yaml # Optional for Test Runner (Twister)├── devacademy_nrf52833_<revision>.conf # Needed to support multiple hardware revisions├── devacademy_nrf52833_<revision>.overlay # Needed to support multiple hardware revisions└── revision.cmake # Needed to support multiple hardware revisions└── dts # Optional └── bindings
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:
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_NRF52833 and 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 widely used for Bluetooth LE applications.
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 support 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 :
<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.
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.
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
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/
In this Privacy Policy you will find information on Nordic Semiconductor ASA (“Nordic Semiconductor”) processes your personal data when you use the Nordic Developer Academy.
References to “we” and “us” in this document refers to Nordic Semiconductor.
2. Our processing of personal data when you use the Nordic Developer Academy
2.1 Nordic Developer Academy
Nordic Semiconductor processes personal data in order to provide you with the features and functionality of the Nordic Developer Academy. Creating a user account is optional, but required if you want to track you progress and view your completed courses and obtained certificates. If you choose to create a user account, we will process the following categories of personal data:
Email
Name
Password (encrypted)
Course progression (e.g. which course you have completely or partly completed)
Certificate information, which consists of name of completed course and the validity of the certificate
Course results
During your use of the Nordic Developer Academy, you may also be asked if you want to provide feedback. If you choose to respond to any such surveys, we will also process the personal data in your responses in that survey.
The legal basis for this processing is GDPR article 6 (1) b. The processing is necessary for Nordic Semiconductor to provide the Nordic Developer Academy under the Terms of Service.
2.2 Analytics
If you consent to analytics, Nordic Semiconductor will use Google Analytics to obtain statistics about how the Nordic Developer Academy is used. This includes collecting information on for example what pages are viewed, the duration of the visit, the way in which the pages are maneuvered, what links are clicked, technical information about your equipment. The information is used to learn how Nordic Developer Academy is used and how the user experience can be further developed.
2.2 Newsletter
You can consent to receive newsletters from Nordic from within the Nordic Developer Academy. How your personal data is processed when you sign up for our newsletters is described in the Nordic Semiconductor Privacy Policy.
3. Retention period
We will store your personal data for as long you use the Nordic Developer Academy. If our systems register that you have not used your account for 36 months, your account will be deleted.
4. Additional information
Additional information on how we process personal data can be found in the Nordic Semiconductor Privacy Policy and Cookie Policy.
Nordic Developer Academy Terms of Service
1. Introduction
These terms and conditions (“Terms of Use”) apply to the use of the Nordic Developer Academy, provided by Nordic Semiconductor ASA, org. nr. 966 011 726, a public limited liability company registered in Norway (“Nordic Semiconductor”).
Nordic Developer Academy allows the user to take technical courses related to Nordic Semiconductor products, software and services, and obtain a certificate certifying completion of these courses. By completing the registration process for the Nordic Developer Academy, you are agreeing to be bound by these Terms of Use.
These Terms of Use are applicable as long as you have a user account giving you access to Nordic Developer Academy.
2. Access to and use of Nordic Developer Academy
Upon acceptance of these Terms of Use you are granted a non-exclusive right of access to, and use of Nordic Developer Academy, as it is provided to you at any time. Nordic Semiconductor provides Nordic Developer Academy to you free of charge, subject to the provisions of these Terms of Use and the Nordic Developer Academy Privacy Policy.
To access select features of Nordic Developer Academy, you need to create a user account. You are solely responsible for the security associated with your user account, including always keeping your login details safe.
You will able to receive an electronic certificate from Nordic Developer Academy upon completion of courses. By issuing you such a certificate, Nordic Semiconductor certifies that you have completed the applicable course, but does not provide any further warrants or endorsements for any particular skills or professional qualifications.
Nordic Semiconductor will continuously develop Nordic Developer Academy with new features and functionality, but reserves the right to remove or alter any existing functions without notice.
3. Acceptable use
You undertake that you will use Nordic Developer Academy in accordance with applicable law and regulations, and in accordance with these Terms of Use. You must not modify, adapt, or hack Nordic Developer Academy or modify another website so as to falsely imply that it is associated with Nordic Developer Academy, Nordic Semiconductor, or any other Nordic Semiconductor product, software or service.
You agree not to reproduce, duplicate, copy, sell, resell or in any other way exploit any portion of Nordic Developer Academy, use of Nordic Developer Academy, or access to Nordic Developer Academy without the express written permission by Nordic Semiconductor. You must not upload, post, host, or transmit unsolicited email, SMS, or \”spam\” messages.
You are responsible for ensuring that the information you post and the content you share does not;
contain false, misleading or otherwise erroneous information
infringe someone else’s copyrights or other intellectual property rights
contain sensitive personal data or
contain information that might be received as offensive or insulting.
Such information may be removed without prior notice.
Nordic Semiconductor reserves the right to at any time determine whether a use of Nordic Developer Academy is in violation of its requirements for acceptable use.
Violation of the at any time applicable requirements for acceptable use may result in termination of your account. We will take reasonable steps to notify you and state the reason for termination in such cases.
4. Routines for planned maintenance
Certain types of maintenance may imply a stop or reduction in availability of Nordic Developer Academy. Nordic Semiconductor does not warrant any level of service availability but will provide its best effort to limit the impact of any planned maintenance on the availability of Nordic Developer Academy.
5. Intellectual property rights
Nordic Semiconductor retains all rights to all elements of Nordic Developer Academy. This includes, but is not limited to, the concept, design, trademarks, know-how, trade secrets, copyrights and all other intellectual property rights.
Nordic Semiconductor receives all rights to all content uploaded or created in Nordic Developer Academy. You do not receive any license or usage rights to Nordic Developer Academy beyond what is explicitly stated in this Agreement.
6. Liability and damages
Nothing within these Terms of Use is intended to limit your statutory data privacy rights as a data subject, as described in the Nordic Developer Academy Privacy Policy. You acknowledge that errors might occur from time to time and waive any right to claim for compensation as a result of errors in Nordic Developer Academy. When an error occurs, you shall notify Nordic Semiconductor of the error and provide a description of the error situation.
You agree to indemnify Nordic Semiconductor for any loss, including indirect loss, arising out of or in connection with your use of Nordic Developer Academy or violations of these Terms of Use. Nordic Semiconductor shall not be held liable for, and does not warrant that (i) Nordic Developer Academy will meet your specific requirements, (ii) Nordic Developer Academy will be uninterrupted, timely, secure, or error-free, (iii) the results that may be obtained from the use of Nordic Developer Academy will be accurate or reliable, (iv) the quality of any products, services, information, or other material purchased or obtained by you through Nordic Developer Academy will meet your expectations, or that (v) any errors in Nordic Developer Academy will be corrected.
You accept that this is a service provided to you without any payment and hence you accept that Nordic Semiconductor will not be held responsible, or liable, for any breaches of these Terms of Use or any loss connected to your use of Nordic Developer Academy. Unless otherwise follows from mandatory law, Nordic Semiconductor will not accept any such responsibility or liability.
7. Change of terms
Nordic Semiconductor may update and change the Terms of Use from time to time. Nordic Semiconductor will seek to notify you about significant changes before such changes come into force and give you a possibility to evaluate the effects of proposed changes. Continued use of Nordic Developer Academy after any such changes shall constitute your acceptance of such changes. You can review the current version of the Terms of Use at any time at https://academy.nordicsemi.com/terms-of-service/
8. Transfer of rights
Nordic Semiconductor is entitled to transfer its rights and obligation pursuant to these Terms of Use to a third party as part of a merger or acquisition process, or as a result of other organizational changes.
9. Third Party Services
To the extent Nordic Developer Academy facilitates access to services provided by a third party, you agree to comply with the terms governing such third party services. Nordic Semiconductor shall not be held liable for any errors, omissions, inaccuracies, etc. related to such third party services.
10. Dispute resolution
The Terms of Use and any other legally binding agreement between yourself and Nordic Semiconductor shall be subject to Norwegian law and Norwegian courts’ exclusive jurisdiction.
