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

Build target

nRF52833 DK

PCA10100

nrf52833dk_nrf52833

nrf52833dk_nrf52833

nRF52833 DK (emulating nRF52820)

PCA10100

nrf52833dk_nrf52820

nrf52833dk_nrf52820

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp

nrf5340dk_nrf5340_cpuapp_ns

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 your application for information about how to permanently or temporarily change the configuration.

This sample configuration is split into the following two files:

  • generic configuration is available in the prj.conf file

  • board specific configuration is available in the boards/<BOARD>.conf file

Board specific configuration involves configuring the Bluetooth LE controller. For nRF5340 DK, the Bluetooth LE controller is part of a child image meant to run on the network core. Configuration for the child image is stored in the child_image/ subdirectory.

Angle of arrival mode

To build this sample with angle of arrival mode only, set OVERLAY_CONFIG to overlay-aoa.conf.

See Providing CMake options for instructions on how to add this option. For more information about using configuration overlay files, see Important Build System Variables in the Zephyr documentation.

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

Antenna matrix configuration for angle of departure mode

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

The overlay file provides the information about 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 order given by the dfegpio#-gpios properties. The order is important because it affects 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:

  • Provide the GPIO pins to dfegpio#-gpios properties in nrf52833dk_nrf52833.overlay file

  • Provide the default antenna that will be used to transmit a PDU dfe-pdu-antenna property in the nrf52833dk_nrf52833.overlay file

  • Update the antenna switching patterns in ant_patterns array in main.c.

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 maximum allowed value is 15.

If the number of switch-sample periods is greater than the number of stored switching patterns, then 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 option. If the required length of the antenna switching pattern is greater than the default value of CONFIG_BT_CTLR_DF_MAX_ANT_SW_PATTERN_LEN, set the CONFIG_BT_CTLR_DF_MAX_ANT_SW_PATTERN_LEN option to the required value in the board configuration file. For example, for the nRF52833 DK add CONFIG_BT_CTLR_DF_MAX_ANT_SW_PATTERN_LEN =N, where N is the required antenna switching pattern length, to 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.

See Building and programming an application for information about how to build and program the application.

Testing

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

  1. Connect to the kit that runs this sample with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  2. 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

  • Bluetooth:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/hci.h

    • include/bluetooth/direction.h

    • include/bluetooth/conn.h