In this exercise, we will create a custom board definition for a board that is based on a Nordic SiP/SoC that has TF-M support. In other words, we will create a custom board with multiple board targets. We will use the nRF9151 SiP as an example, but the instructions will be very similar to other SiPs/SoCs in the nRF91, the nRF53 , or the nRF54L Series. We will develop a custom board called DevAcademyL3E2.

One key difference is that we will not create the new custom board template using the Create new board GUI in nRF Connect for VS Code. Instead, we will pick an existing board that is similar to the DevAcademyL3E2. (i.e., it uses the same SiP/SoC and has a similar schematic, which will be the nRF9151 DK). Then, we will copy the board files into a new folder and rename it to match the new board. Once done, this will serve as the template for our new board “DevAcademyL3E2,” which we can modify to match exactly the schematic/desired software configurations of our new board.

Exercise steps

Preparing the template

1. Create a new directory on your root directory and name it my_boards.

In this directory (for example C:\my_boards), we will store our custom board definitions.

2. Make a copy of the similar DK folder.

Since our custom board is based on the nRF9151 SiP, we will make a copy of the nRF9151 DK folder that we are basing our custom board file on, located in <install_path>\zephyr\boards\nordic\nrf9151dk into your custom board directory.

3. Point the build system to the custom board root directory.

By default, the build system in nRF Connect goes to specific folders to look for board definitions. Namely, <install_path>/zephyr/boards/nordic/ and <install_path>/nrf/boards/nordic/.

We need to tell the build system to look at the directory we created in Step 1. To do that, we have three different options:

Option 1: Inside the application CMake file, CMakeLists.txt.

This is done by defining the BOARD_ROOT before pulling in the Zephyr boilerplate with find_package(Zephyr ...). When specifying BOARD_ROOT in a CMakeLists.txt, then an absolute path must be provided, for example list(APPEND BOARD_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/<extra-board-root>). When using -DBOARD_ROOT=<board-root> both absolute and relative paths can be used. Relative paths are treated relatively to the application directory.

Option 2: At build time.

We can build an application targeting a custom board by specifying the location of the custom board information with the -DBOARD_ROOT parameter to the build system. This can be done both using CLI (west) or using the Add build configuration GUI. Ex: Using CLI

west build -b <board name> -- -DBOARD_ROOT=<path to boards>

When using -DBOARD_ROOT=<board-root> both absolute and relative paths can be used. Relative paths are treated relatively to the application directory.

Option 3: From within VS Code.

This is the method that we will demonstrate here. Navigate to the Settings of nRF Connect Extension. This can be done by navigating to File -> Preferences -> Settings -> Extensions -> nRF Connect -> Board Roots, then add the directory defined in Step 1.

4. Name your new custom board.

Naming should be done according to the rules discussed in the theory part of this lesson. We will name the custom board DevAcademyL3E2 (Human readable name), devacademyl3e2 (machine readable name). This means that the board will have two board targets devacademyl3e2/nrf9151 and devacademyl3e2/nrf9151/ns.

5. Rename existing board definitions.

5.1 Rename folder. Rename the newly copied folder to devacademyl3e2. This folder will contain both board targets.

5.2 Rename files. Open the devacademyl3e2 in VS Code. (File -> Open Folder). Make sure that your VS Code contains only one directory in the workspace which is the opened folder devacademyl3e2 .

Press (F2) or right-click on each file and select rename. Rename the files from the old name that is prefixed with nrf9151dk_****_**** to the new name devacademyl3e2_****_****. Also, make sure to rename Kconfig.nrf9151dk to Kconfig.devacademyl3e2 .

To:

5.3 Delete the doc folder as it contains documentation information for the old hardware (nRF9151 DK)

5.4 Rename content inside the files; this includes identifiers, and include files.

5.4.1 From the Edit menu open, click Replace in Files (Ctrl+Shift+H) and type the old DK name in small letters nrf9151dk in the Search field. Make sure to select Match Case. In the Replace field, put the new board name in small letters devacademyl3e2. This will change the board name in board.yml , update the include files to match the new board name, and also update the Twister metadata files for both board targets.

Press on Replace All. Make sure there is no space after the words.

5.4.2 From the Edit menu open, click Replace in Files (Ctrl+Shift+H) and type the normalized old board name NRF9151DK in the Search field. Make sure to select Match Case. In the Replace field, put the normalized new board name DEVACADEMYL3E2. This will change the content in Kconfig.defconfig, Kconfig.devacademyl3e2 , and the debug/flash board.cmake files to match the new normalized board name. Make sure to press on Replace All.

5.4.3 From the Edit menu open, click Replace in Files (Ctrl+Shift+H) and type the string nRF9151 DK, which represents the human-readable name of the old DK, in the Search field. In the Replace field, put the string DevAcademyL3E2. This changes the comments and Kconfig string descriptors to reflect the new board name.

Adjusting the template to match your schematic /Software Configration

6. Now, we have the template ready in the custom board folder. If the new board (ex: DevAcademyL3E2) has hardware differences from the board template we copied (nRF9151 DK), this must be reflected in the Devicetree files. The same applies to the software configurations. Basically, you use the same concepts and practices we covered in earlier topics.

Testing

7. Build and flash the application to your board.

In this part, we will build and flash different samples on the custom board DevAcademyL3E2 for testing purposes. You can see the custom board from the Add Build Configuration Window.

Note that you should see two board targets for the (DevAcademyL3E2) available in the Custom board. devacademyl3e2/nrf9151_ns (with TF-M) and devacademyl3e2_nrf9151 (without TF-M).

Simple samples like (Hello World and Blinky) will be runnable on both build targets. Samples with Cellular IoT connections will only run on the devacademyl3e2_nrf9151_ns (built with TF-M) as they are designed that way.

7.1 Test Serial Console/UART.

Create a new application based on the Hello World sample. Build the application for the new custom board the same way we did in Exercise 1.

You should see the following output on the terminal once the build is complete. Notice how the TF-M is included as a child image

Flash the application to the board. Flashing to the board will write the merged hex that contains both images for the application and TF-M. You should see the following output on the serial terminal:

*** Booting nRF Connect SDK ***
Hello World! devacademyl3e2/nrf9151/ns

The Hello World sample should run on both targets. However, as mentioned before applications with cellular IoT connectivity needs to run on the devacademyl3e2/nrf9151/ns build target.

7.2 Test LEDs and buttons.

Build the “Button” Sample for the target devacademyl3e2/nrf9151/ns and flash it to your board . You should see that every time you press Button 1 on the DK , LED 1 is turned on. Also you should see the following output on the terminal.

*** Booting nRF Connect SDK ***
Set up button at gpio@50000000 pin 11
Set up LED at gpio@50000000 pin 13
Press the button
Button pressed at 219119
Button pressed at 242602
Button pressed at 269271
Button pressed at 273719

7.3 Test PWM.

Build the “PWM LED ” Sample for the target devacademyl3e2/nrf9151/ns and flash it to your board. You should see that LED 1 is turned on and off and then gradually start fading. Also, you should see the following output on the terminal.

*** Booting nRF Connect SDK ***
[00:00:00.365,966] <inf> main: Testing LED 0 - no label
[00:00:00.371,826] <inf> main:   Turned on
[00:00:01.376,647] <inf> main:   Turned off
[00:00:02.381,530] <inf> main:   Increasing brightness gradually
[00:00:04.408,447] <inf> main:   Blinking on: 0.1 sec, off: 0.1 sec

Note: Not all Cycle periods are supported on all hardware.

7.4 Test the Cellular Modem (application must run on the /ns variant).

Build the AT Client or the AT Monitor sample for the target devacademyl3e2/nrf9151/ns and flash it to your board. Test the selected sample as specified in the document.

7.5 Test I2C and SPI.

To test I2C or SPI you would need external components. You could follow the instructions in these lessons for I2C and SPI.

The solution for this exercise can be found in the GitHub repository, l3/l3_e2_sol of whichever version you are using.