In this exercise, we will create a custom board definition from scratch for a board that is based on a single-core Nordic SoC that does not have TF-M support. We will use the nRF52833 SoC as an example, but the instructions will be very similar to other SoCs.

The hardware that we will be developing the custom board for is based on the nRF52833 DK. We will assume that the new board will have almost the exact schematics except that it doesn’t have an Arduino shield. So it’s more like a small-factor version of the Development Kit. Therefore, we will use the Hardware Schematics of the DK as our starting point.

If you are using a different development kit for this course. Use the hardware schematic of your board as a starting point. They can be found here: nRF52840 DK, nRF52 DK.

The schematic below was obtained from the nRF52833 DK schematics.

Exercise steps

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. Open VS Code, and from the Welcome page, click on Create a new board.

You will be prompted with five steps:

1. Provide a human-readable name for your board. You need to follow the instructions provided in Creating board files when naming your board. We will name our board DevAcademy nRF52833
2. The board ID will be automatically generated from the human readable name. We can change it if we want to . However, we will leave it as is devacademy_nrf52833
3. Select the SoC used by your custom board. This is a very critical step, and we need to select the exact SoC number (nRF52840, nRF52832, etc.) and variant used (QIAA , CIAA, etc.) on the custom board. We will be using the nRF52833 QIAA.
4. Set the root directory where your board will be defined. We will pass the directory we defined in step 1: C:\my_boards
5. Provide your company name. In our case, we will pass “Nordic Semiconductor” for the exercise.

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, <SDK Installation Path>/zephyr/boards/arm/ and <SDK Installation Path>/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 3 is used for this exercise ):

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 use in this exercise. 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. Open the custom board definition folder in VS Code.

In VS Code, head to File->Open Folder, then navigate to the custom board definition folder we created in the previous steps then select the folder of the newly created board. This will open the board’s files in the Explorer of VS Code.

5. Open devacademy_nrf52833_defconfig.

This file is a Kconfig fragment that is merged as-is into the final build of any application built for the specified board. In addition to the default Kconfig symbols in this file, we need to add any Kconfig symbols we want to be enabled for any application built for our board. In the case of the DevAcademy nRF52833, since the schematic contains an interface MCU with RTT support and USB/Serial converter, we want to add UART, RTT. We will also enable GPIO support.

Therefore, append the following to the end of the file

# Enable RTT
CONFIG_USE_SEGGER_RTT=y

# enable GPIO
CONFIG_GPIO=y

# enable uart driver
CONFIG_SERIAL=y

# enable console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y

# additional board options
CONFIG_GPIO_AS_PINRESET=y

CONFIG_PINCTRL=y

6. Create a new file called Kconfig.

This file will allow us to create a board menu and set default configuration, enabling the user to change it directly from within the menu.

Add the following inside Kconfig

# DevAcademy nRF52833 board configuration

# Copyright (c) 2019 Nordic Semiconductor ASA
# SPDX-License-Identifier: Apache-2.0

config BOARD_ENABLE_DCDC
	bool "DCDC mode"
	select SOC_DCDC_NRF52X
	default y
	depends on BOARD_DEVACADEMY_NRF52833

We will enable the System on Chip Voltage DC/DC regulator since the schematic of the custom board contains the needed components to support this mode.

7. Create a new application based on the Hello World sample.

Create an application based on the Hello World sample, save it somewhere on your disk (do not save it in the boards directory). Then build the application for the new custom board, as shown in the screenshot below. The sample will not be runnable at the beginning. The purpose here is to build the sample so that the DeviceTree Visual Editor will be able to parse the project.

8. Go to the DeviceTree Visual Editor.

Once the build is complete, press on the DeviceTree in the ACTIONS Panel.

The DeviceTree Visual Editor provides an overview of the devicetree context and a visual representation of the devicetree structure of your project. We will use it along with the devicetree text editor to seamlessly populate the devicetree files.

Notice that it used the default devacademy_nrf52833.dts as a starting point. It also pulls in the SoC devicetree, since it’s included in the devacademy_nrf52833.dts. The SoC devicetree has some nodes enabled, but the majority are disabled (For example, the GPIOs are disabled). We will use the features provided both in the DeviceTree Visual Editor and the Devicetree text editor to help us populate the content of the devacademy_nrf52833.dts file.

8.1 Enable GPIOs and GPIOTE.

The first thing we need to enable in the devicetree is the GPIOs and GPIOTE. In the NODES View, Expand soc and scroll down to gpio0, gpio1, and gpiote. Then, tick the boxes next to it. Depending on the soc used, there could be more or less GPIO/GPIOTE ports.

Ticking the box next to their entries in the GUI (DeviceTree Visual Editor) will write the following into the devacademy_nrf52833.dts file.

&gpio0 {
    status = "okay";
};

&gpio1 {
    status = "okay";
};

&gpiote {
    status = "okay";
};

You should also notice that the GPIOs and Pins are now visible on the SoC. This can be done by switching to the Pins view in the bottom right corner.

Switch to the text editing mode by pressing on the below symbol in the top right corner. Pressing on the Open Text Editor button on the upper right corner will display the devicetree file in text format.

You could also have the windows next to each other, by dragging the title of the opened file to the right of the screen, as shown below. Doing this will help understand what is happening on the deivcetree files when using the Devicetree Visual Editor.

Switch back to the Peripherals view by clicking on the icon below in the bottom right corner

8.2 Define LEDs and Buttons

The Buttons and LEDs on the schematics are connected to the DevAcademy nRF52833 custom board as shown below:

Let’s convert this into Devicetree syntax using the GUI (DeviceTree Visual Editor).

8.2.1 Adding LEDs

The GPIOs connected to the four LEDs are P0.13, P0.14 , P0.15, and P0.16, and the LEDs are connected to VDD on the other end. Therefore, we need to configure the GPIOs as active low. We will use both the visual editor and text editor to do that, as shown below:

8.2.1.1 Add an LED

Click on the + sign. This will promote you with the add node windows.

Select I/O pins , LED, and name the new node as led_0. Select the pin to which the LED is connected to. The first LED is connected to P0.13 in the schematics. This is demonstrated in the video below:

This will create a parent node called leds of compatible gpio-leds and create a child node called led_0. In the next step, we will configure the led_0 node.

8.2.1.2 Configure the led_0 node

Make sure you are in the Peripherals View, and the led_0 node is selected. Add a label to the led_0 node . Name the node label led0 . Note that this is a node label and not a label property( As covered in the nRF Connect SDK Fundamentals course ). Then configure the node properties to match the hardware schematics ( In the case of the DevAcademy nRF52833, change it to active low ), and finally, change the label property to “Green LED 0”.

8.2.1.3 Add the remaining LED nodes

Add the remaining LED nodes and set the configurations of the nodes to match the schematics as shown in the video below. Since we have already set the configration for one LED and the rest are to some extent similar ( except they have different pin assignments and should have different human-readable labels), we will use the text editor to add them. Notice how the GUI has updated accordingly when changes are done directly to the devicetree files. This is demonstrated in the video below:

8.2.2 Adding buttons

The GPIOs connected to the four buttons are P0.11, P0.12, P0.24, and P0.25, and the buttons are connected to the ground on the other end. Therefore, we must pull up these GPIOs and make them active low. This is done as illustrated below:

8.2.2.1 Add a button and configure it.

Same as we did with the LED. Click on the + sign on nodes. This will promote you with the add node window. Select Select I/O pins , Button, name the button node button_0 . Select the pin to which the Button is connected to. The first Button is connected to P0.11 in the schematics. This will create a parent node called buttons of compatible gpio-keys and create a child node called button_0 .

After that, Add a label to the button_0 node . Name the label button0 . Then, configure the node properties to match the hardware schematic, and finally, change the label property to “Push button switch 0”.

8.2.2.2 Add the remaining Button nodes

Add the remaining nodes and set the configurations of the nodes to match the schematics as shown in the video below:

8.3 Adding the Pinctrl file

The pin mappings of the various nodes (except for LEDs and buttons) must be done in a separate file called the pinctrl file(<board_name>-pinctrl.dtsi). This file must be created manually and included in the board devicetree file (<board_name>.dts)

8.3.1 Create a pinctrl file

Name the pinctrl file: devacademy_nrf52833-pinctrl.dtsi .This file, of course, must reside in the custom board directory. Inside the pinctrl file, you always need to reference the pinctrl node as shown below:

/*
 * Copyright (c) 2022 Nordic Semiconductor
 * SPDX-License-Identifier: Apache-2.0
 */

&pinctrl {

};

8.3.2 Include the pinctrl file in the board devicetree file

Add the following line at the beginning of the devacademy_nrf52833.dts file

#include "devacademy_nrf52833-pinctrl.dtsi"

8.4 Adding Serial Console / UART

Pins P0.05, P0.06, P0.07, and P0.08 on the nRF52833 SoC are connected on the schematic to an Interface MCU that does USB<->UART conversion.

8.4.1 Add the following pinctrl definitions inside the &pinctrl in devacademy_nrf52833-pinctrl.dtsi

	uart0_default: uart0_default {
		group1 {
			psels = <NRF_PSEL(UART_TX, 0, 6)>,
				<NRF_PSEL(UART_RTS, 0, 5)>;
		};
		group2 {
			psels = <NRF_PSEL(UART_RX, 0, 8)>,
				<NRF_PSEL(UART_CTS, 0, 7)>;
			bias-pull-up;
		};
	};

	uart0_sleep: uart0_sleep {
		group1 {
			psels = <NRF_PSEL(UART_TX, 0, 6)>,
				<NRF_PSEL(UART_RX, 0, 8)>,
				<NRF_PSEL(UART_RTS, 0, 5)>,
				<NRF_PSEL(UART_CTS, 0, 7)>;
			low-power-enable;
		};
	};

8.4.2 Enable the UART node, set the default baud rate, and the pinctrl states. Add the following code at the end of the devacademy_nrf52833.dts file

&uart0 {
	status = "okay";
	current-speed = <115200>;
	pinctrl-0 = <&uart0_default>;
	pinctrl-1 = <&uart0_sleep>;
	pinctrl-names = "default", "sleep";
};

8.4.3 Add the following two lines inside the chosen node

		zephyr,console =  &uart0 ;
		zephyr,shell-uart =  &uart0 ;
		zephyr,uart-mcumgr = &uart0;

The chosen node’s properties are used to configure system- or subsystem-wide values. So, these values are referenced by the different software modules you configured, usually through the DT_CHOSEN() macro. See the example of the UART Console and the UART MCUmanager and the shell UART backedend.

Note that there are other “chosen” preoperties related to Bluetooth LE boards. Namely: zephyr,bt-mon-uart and zephyr,bt-c2h-uart if you plan to use the Host monitor or HCI over UART (Expose the Bluetooth LE controller to external MCU), respectively.

8.5 Adding I2C, SPI, and PWM Peripherals

8.5.1 I2C

The P0.26 and P0.27 GPIOs are used for I2C peripheral. On the nRF52833, there are two I2C peripherals , we will enable i2c0 and connect it to these two pins.

8.5.1.1 Add the following in devacademy_nrf52833-pinctrl.dtsi

	i2c0_default: i2c0_default {
		group1 {
			psels = <NRF_PSEL(TWIM_SDA, 0, 26)>,
				<NRF_PSEL(TWIM_SCL, 0, 27)>;
		};
	};

	i2c0_sleep: i2c0_sleep {
		group1 {
			psels = <NRF_PSEL(TWIM_SDA, 0, 26)>,
				<NRF_PSEL(TWIM_SCL, 0, 27)>;
			low-power-enable;
		};
	};

8.5.1.1 Enable the I2C0 node by setting its status to “okay” and set its pinctrl . Add the following code in devacademy_nrf52833.dts

&i2c0 {
	status = "okay";
	pinctrl-0 = <&i2c0_default>;
	pinctrl-1 = <&i2c0_sleep>;
	pinctrl-names = "default", "sleep";
}; 

8.5.2 SPI

We will use the dedicated SPI peripheral (spi1) on the nRF52833 SoC. Note that spi0 is shared with i2c0 as a serial unit so we can use only one at a time.

8.5.2.1 Add the following in devacademy_nrf52833-pinctrl.dtsi

spi1_default: spi1_default {
		group1 {
			psels = <NRF_PSEL(SPIM_SCK, 0, 31)>,
				<NRF_PSEL(SPIM_MOSI, 0, 30)>,
				<NRF_PSEL(SPIM_MISO, 1, 8)>;
		};
	};

	spi1_sleep: spi1_sleep {
		group1 {
			psels = <NRF_PSEL(SPIM_SCK, 0, 31)>,
				<NRF_PSEL(SPIM_MOSI, 0, 30)>,
				<NRF_PSEL(SPIM_MISO, 1, 8)>;
			low-power-enable;
		};
	};

8.5.2.2 Enable the SPI1 node by setting its status to “okay” and set its pinctrl . Add the following code in devacademy_nrf52833.dts

&spi1 {
	status = "okay";
	pinctrl-0 = <&spi1_default>;
	pinctrl-1 = <&spi1_sleep>;
	pinctrl-names = "default", "sleep";
};

8.5.3 PWM

Let’s enable a PWM peripheral. There are 4 dedicated PWM peripherals on the nRF52833 SoC. We will use PWM0 and connect it’s output to LED0.

8.5.3.1 Add the following in devacademy_nrf52833-pinctrl.dtsi for the pin assignment.

pwm0_default: pwm0_default {
	group1 {
		psels = <NRF_PSEL(PWM_OUT0, 0, 13)>;
		nordic,invert;
	};
};

pwm0_sleep: pwm0_sleep {
	group1 {
		psels = <NRF_PSEL(PWM_OUT0, 0, 13)>;
		low-power-enable;
	};
};

8.5.3.2 Enable the PWM0 node by setting its status to “okay” and set its pinctrl. Add the following code in devacademy_nrf52833.dts

&pwm0 {
	status = "okay";
	pinctrl-0 = <&pwm0_default>;
	pinctrl-1 = <&pwm0_sleep>;
	pinctrl-names = "default", "sleep";
};

8.5.3.3 In the root node, add the node pwmleds of type pwm-leds and set the channel and the default period

	pwmleds {
	compatible = "pwm-leds";
	pwm_led0: pwm_led_0 {
		pwms = <&pwm0 0 PWM_MSEC(20) PWM_POLARITY_INVERTED>;
	};
};

8.6 The samples in nRF Connect SDK and Zephyr OS uses fixed aliases for devicetree nodes. Therefore, to ensure that samples find these aliases, it’s crucial to add aliases in the board devicetree file . Add the following inside the / root node.

/* These aliases are provided for compatibility with samples */
aliases {
	led0 = &led0;
	led1 = &led1;
	led2 = &led2;
	led3 = &led3;
	pwm-led0 = &pwm_led0;
	sw0 = &button0;
	sw1 = &button1;
	sw2 = &button2;
	sw3 = &button3;
	bootloader-led0 = &led0;
	mcuboot-button0 = &button0;
	mcuboot-led0 = &led0;
	watchdog0 = &wdt0;
};

8.7 If you plan to use other peripherals on your device on all applications built for this board, for example, the USB device perioheral. You will also need to enable its node in the board devicetree.

Testing

9. Build and flash the application to your board.

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

9.1 Test Serial Console/UART.

Build the “Hello World” sample for the target devacademy_nrf52833 and flash it to your board. You should see the following output.

Booting nRF Connect SDK v2.x.x

Hello World! devacademy_nrf52833 

With this, we have validated that the serial Console / UART is working properly.

9.2 Test LEDs and buttons.

Build the “Button” Sample for the target devacademy_nrf52833 and flash it to your board . You should see that everytime 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 v2.x.x

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

9.3 Test PWM.

Build the “PWM LED ” Sample for the target devacademy_nrf52833 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 v2.x.x

[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

9.4 Test the Bluetooth LE Radio.

The radio node for the Bluetooth LE is already enabled “status = "okay" in the SoC devicetree file. Therefore you don’t need to do any changes in the board devicetree file. However, if you plan to use the IEEE 802.15.4 radio (for Zigbee or Thread), you will need to enable the ieee802154 and set the chosen property zephyr,ieee802154 = &ieee802154 in the board devicetree file.

Build the “Peripheral UART ” or the “Peripheral LBS” sample for the target devacademy_nrf52833 and flash it to your board and test the sample as specified in the document for the selected sample.

9.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_exer1_solution.