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. We will use the nRF9161 SiP as an example, but the instructions will be very similar to other SiPs/SoCs in the nRF91 Series or the nRF53 Series. We will develop a custom board called DevAcademy nRF9161.

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 DevAcademy nRF9161. (i.e., it uses the same SiP/SoC and has a similar schematic, which will be the nRF9161 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 “DevAcademy nRF9161,” 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 nRF9161 DK folder.

Make a copy of the nRF9161 DK folder that we are basing our custom board file on, located in <install_path>\zephyr\boards\arm\nrf9161dk_nrf9161 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, /zephyr/boards/arm/ and /nrf/boards/arm/.

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 DevAcademy nRF9161 (Human Readable name). This means that the board will have two build targets devacademy_nrf9161 and devacademy_nrf9161_ns and two Kconfig Symbols BOARD_DEVACADEMY_NRF9161 and BOARD_DEVACADEMY_NRF9161_NS .

5. Rename existing board definitions.

5.1 Rename folder. Rename the newly copied folder to devacademy_nrf9161. This folder will contain both build targets.

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

Press (F2) or right-click on each file and select rename. Rename the files from the old name that is prefixed with nrf9161dk_nrf9161_**** to the new name devacademy_nrf9161_****.

To:

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

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

5.4.1 From the Edit menu open, click Replace in Files (Ctrl+Shift+H) and type the old build target nrf9161dk_nrf9161 in the Search field. Make sure to select Match Case. In the Replace field, put the new build target devacademy_nrf9161. Note that we will change both build targets (the non-secure and secure) in one go. Also the included files will be renamed to match the changes we have made in step 3.2.

Press on Replace All.

5.4.2 From the Edit menu open, click Replace in Files (Ctrl+Shift+H) and type the old Kconfig symbol NRF9161DK_NRF9161 in the Search field. Make sure to select Match Case. In the Replace field, put the Kconfig symbol devacademy_nrf9161. Note that we will change both the non-secure and secure in one go. 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 nRF9161 DK in the Search field. Make sure to select Match Case. In the Replace field, put the string DevAcademy. 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: DevAcademy nRF9161) has hardware differences from the board template we copied (nRF9161 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 DevAcademy nRF9161 for testing purposes. You can see the custom board from the Add Build Configuration Window.

Note that you should see two build targets for the (DevAcademy nRF9161) available in the Custom board. devacademy_nrf9161_ns (with TF-M) and devacademy_nrf9161 (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 devacademy_nrf9161_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 2.6.1-3758bcbfa5cd ***
Hello World! devacademy_nrf9161_ns

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

7.2 Test LEDs and buttons.

Build the “Button” Sample for the target devacademy_nrf9161_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 2.6.1-3758bcbfa5cd ***
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 devacademy_nrf9161_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 2.6.1-3758bcbfa5cd ***
[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

7.4 Test the Cellular Modem (application must run on the _ns build target).

Build the “AT Client” or the AT Monitor sample for the target devacademy_nrf9161_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, lesson3/inter_less3_exer2_solution.