Bluetooth: Direction finding peripheral

The direction finding peripheral sample demonstrates Bluetooth® LE direction finding transmission as a response to a request received from a connected central device.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF5340 DK	PCA10095	nrf5340dk	`nrf5340dk/nrf5340/cpuapp`
nRF52833 DK	PCA10100	nrf52833dk	`nrf52833dk/nrf52833`
nRF52833 DK (emulating nRF52820)	PCA10100	nrf52833dk	`nrf52833dk/nrf52820`

The sample also requires an antenna matrix when operating in angle of departure mode. It can be a Nordic Semiconductor design 12 patch antenna matrix, or any other antenna matrix.

Overview 

The direction finding peripheral sample uses Constant Tone Extension (CTE), that is transmitted with periodic advertising PDUs.

The sample supports two direction finding modes:

Angle of Arrival (AoA)
Angle of Departure (AoD)

By default, both modes are available in the sample.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

This sample configuration is split into the following two files:

Generic configuration available in the prj.conf file
Board-specific configuration available in the boards/<BOARD>.conf file

nRF5340 configuration files 

The following additional configuration files are available for the nRF5340 DK:

The Bluetooth LE controller is part of a child image meant to run on the network core. The configuration for the child image is stored in the child_image/ subdirectory.
The DTS overlay file boards/nrf5340dk_nrf5340_cpuapp.overlay is available for the application core. This file forwards the control over GPIOs to network core, which provides control over GPIOs to the radio peripheral in order to execute antenna switching.

Angle of arrival mode 

To build this sample with AoA mode only, set EXTRA_CONF_FILE to the overlay-aoa.conf file using the respective CMake option.

For more information about configuration files in the nRF Connect SDK, see Build and configuration system.

To build this sample for nRF5340 DK, with AoA mode only, add content of overlay-aoa.conf file to child_image/hci_ipc.conf file.

Antenna matrix configuration for angle of departure mode 

To use this sample when AoD mode is enabled, additional configuration of GPIOs is required to control the antenna array. An example of such configuration is provided in a devicetree overlay file nrf52833dk_nrf52833.overlay.

The overlay file provides the information of which GPIOs should be used by the Radio peripheral to switch between antenna patches during the CTE transmission in the AoD mode. At least two GPIOs must be provided to enable antenna switching.

The GPIOs are used by the Radio peripheral in the order provided by the dfegpio#-gpios properties. The order is important because it has an impact on the mapping of the antenna switching patterns to GPIOs (see Antenna patterns).

To successfully use the direction finding beacon when the AoD mode is enabled, provide the following data related to antenna matrix design:

The GPIO pins to dfegpio#-gpios properties in the nrf52833dk_nrf52833.overlay file.
The default antenna that will be used to receive a PDU dfe-pdu-antenna property in the nrf52833dk_nrf52833.overlay file.
Update the antenna switching patterns of the ant_patterns array in the main.c file.

Antenna patterns 

The antenna switching pattern is a binary number where each bit is applied to a particular antenna GPIO pin. For example, the pattern 0x3 means that antenna GPIOs at index 0,1 will be set, while the following are left unset.

This also means that, for example, when using four GPIOs, the pattern count cannot be greater than 16 and the maximum allowed value is 15.

If the number of switch-sample periods is greater than the number of stored switching patterns, the radio loops back to the first pattern.

The length of the antenna switching pattern is limited by the CONFIG_BT_CTLR_DF_MAX_ANT_SW_PATTERN_LEN Kconfig option. If the required length of the antenna switching pattern is greater than the default value of that option, set it to the required value in the board configuration file. For example, for the nRF52833 DK, set the option value to the required antenna switching pattern length in the nrf52833dk_nrf52833.conf file.

The following table presents the patterns that you can use to switch antennas on the Nordic-designed antenna matrix:

Antenna	PATTERN[3:0]
ANT_12	0 (0b0000)
ANT_10	1 (0b0001)
ANT_11	2 (0b0010)
RFU	3 (0b0011)
ANT_3	4 (0b0100)
ANT_1	5 (0b0101)
ANT_2	6 (0b0110)
RFU	7 (0b0111)
ANT_6	8 (0b1000)
ANT_4	9 (0b1001)
ANT_5	10 (0b1010)
RFU	11 (0b1011)
ANT_9	12 (0b1100)
ANT_7	13 (0b1101)
ANT_8	14 (0b1110)
RFU	15 (0b1111)

Building and Running 

This sample can be found under samples/bluetooth/direction_finding_peripheral in the nRF Connect SDK folder structure.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing 

After programming the sample to your development kit, complete the following steps to test it:

Connect to the kit that runs this sample with a terminal emulator (for example, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

In the terminal window, check for information similar to the following:

Bluetooth initialized
<inf> bt_hci_core: HW Platform: Nordic Semiconductor (XxXXXX)
<inf> bt_hci_core: HW Variant: nRF52x (XxXXXX)
<inf> bt_hci_core: Firmware: Standard Bluetooth controller (XxXX) Version 3.0 Build X
<inf> bt_hci_core: Identity: XX:XX:XX:XX:XX (random)
<inf> bt_hci_core: HCI: version 5.3 (XxXX) revision XxXXXX, manufacturer XxXXXX
<inf> bt_hci_core: LMP: version 5.3 (XxXX) subver XxXXXX

Dependencies 

This sample uses the following Zephyr libraries:

include/zephyr/types.h
lib/libc/minimal/include/errno.h
include/sys/printk.h
include/sys/byteorder.h
API:
- include/bluetooth/bluetooth.h
- include/bluetooth/hci.h
- include/bluetooth/direction.h
- include/bluetooth/conn.h