Bluetooth: Direct Test Mode¶

Overview
Debugging
Requirements
Building and running
- Testing
Dependencies

This sample enables the Direct Test Mode functions described in Bluetooth Core Specification: Version 5.2, Vol. 6, Part F.

Overview ¶

The sample uses Direct Test Mode (DTM) to test the operation of the following features of the radio:

Transmission power and receiver sensitivity
Frequency offset and drift
Modulation characteristics
Packet error rate
Intermodulation performance

Test procedures are defined in the document Bluetooth Low Energy RF PHY Test Specification: Document number RF-PHY.TS.p15

You can carry out conformance tests using dedicated test equipment, such as the Anritsu MT8852 or similar, with an nRF5 running the DTM sample set as device under test (DUT).

DTM sample ¶

The DTM sample includes two parts:

The DTM, Direct Test Mode library, which manages the nRF radio and controls the standard DTM procedures.
A sample that provides an external interface to the library.

You can find the source code of both parts here: samples/bluetooth/direct_test_mode/src.

The DTM sample contains a driver for a 2-wire UART interface. The driver maps two-octet commands and events to the DTM library, as specified by the Bluetooth Low Energy DTM specification.

The implementation is self-contained and requires no Bluetooth Low Energy protocol stack for its operation. The MPU is initialized in the standard way. The DTM library function dtm_init configures all interrupts, timers, and the radio.

main.c may be replaced with other interface implementations, such as an HCI interface, USB, or another interface required by the Upper Tester.

The interface to the Lower Tester uses the antenna connector of the chosen development kit. While in principle an aerial connection might be used, conformance tests cover the reading of the transmission power delivered by the DUT. For this reason, a coaxial connection between the DUT and the Lower Tester is employed for all conformance testing.

DTM module interface ¶

The DTM function dtm_cmd_put implements the four commands defined by the Bluetooth Low Energy standard:

TEST SETUP (called RESET in Bluetooth 4.0)
RECEIVER_TEST
TRANSMITTER_TEST
TEST_END

In the dtm_cmd_put interface, DTM commands are accepted in the 2-byte format. Parameters such as: CMD code, Frequency, Length, or Packet Type are encoded within this command.

The following DTM events are polled using the dtm_event_get function:

PACKET_REPORTING_EVENT
TEST_STATUS_EVENT [ SUCCESS | FAIL ]

Supported PHYs ¶

The DTM sample supports all four PHYs specified in DTM, but not all devices support all the PHYs.

Supported PHYs¶
PHY	nRF5340
LE 1M	Yes
LE 2M	Yes
LE Coded S=8	Yes
LE Coded S=2	Yes

Bluetooth Direction Finding support ¶

The DTM sample supports all Bluetooth Direction Finding modes specified in DTM.

Supported Bluetooth Direction Finding modes¶
Direction Finding mode	nRF5340
AoD 1 us slot	Yes
AoD 2 us slot	Yes
AoA	Yes

The following antenna switching patterns are possible:

1, 2, 3, …, N
1, 2, 3, …, N, N - 1, N - 2, …, 1

The application supports a maximum of 19 antennas in the direction finding mode. The RADIO can control up to 8 GPIO pins for the purpose of controlling the external antenna switches used in direction finding.

The antenna is chosen by writing consecutive numbers to the SWITCHPATTERN register. This means that the antenna GPIO pins act like 8-bit registers. In other words, for the first antenna, antenna pin 1 is active, for the second antenna, pin 2 is active, for the third antenna, pins 1 and 2 are active, and so on.

nRF21540 front-end module ¶

Note

Software FEM support is not present on nRF53 Series devices yet. For now, it also cannot be combined with multiprotocol operation.

You can add support for the nRF21540 front-end module to the sample. See Radio front-end module (FEM) support for more information.

To add support for the nRF21540 FEM, add the provided dts-nrf21540-fem.overlay devicetree overlay file when building. The file is located in the samples/bluetooth/direct_test_mode folder. Make sure that the GPIOs in the file correspond to those in which your front-end module is connected.

Note

You must add the provided overlay file if you use the nRF21540 EK. If you use the nRF21540 DK, build your application for the nrf21540dk_nrf52840 board. The devicetree for the nRF21540 DK already contains the required FEM configuration, so you do not need to add the overlay file.

See Set devicetree overlays for different ways of adding the overlay file.

The easiest way to add the file when building is to set it in the DTC_OVERLAY_FILE variable. However, doing so will override the default settings. For some boards, this sample requires additional overlay files, which are automatically included when building with the default settings. When you set the DTC_OVERLAY_FILE variable, you must specify all overlay files that are needed for building. Check the boards folder to see the additional overlay files.

Follow the instructions in Providing CMake options to specify the DTC_OVERLAY_FILE variable. For example, to build the sample from the command line for an nRF52833 DK with an attached nRF21540 EK, invoke the following command within the sample directory:

west build -b nrf52833dk_nrf52833 -- -DDTC_OVERLAY_FILE="boards/nrf52833dk_nrf52833.overlay;../common/dts-nrf21540-fem.overlay"

Alternatively, you can copy the contents of dts-nrf21540-fem.overlay to the board’s overlay file.

To add support for other front-end modules, add the respective overlay files in the same way.

You can configure the transmitted power gain and activation delay in nRF21540 using vendor-specific commands, see Vendor-specific packet payload.

Vendor-specific packet payload ¶

The Bluetooth Low Energy 2-wire UART DTM interface standard reserves the Packet Type, also called payload parameter, with binary value 11 for a Vendor Specific packet payload.

The DTM command is interpreted as a Vendor-Specific one when both the following conditions are met:

Its CMD field is set to Transmitter Test, binary 10.
Its PKT field is set to Vendor-Specific, binary 11.

Vendor specific commands can be divided into different categories as follows:

If the Length field is set to 0 (symbol CARRIER_TEST), an unmodulated carrier is turned on at the channel indicated by the Frequency field. It remains turned on until a TEST_END or RESET command is issued.
If the Length field is set to 1 (symbol CARRIER_TEST_STUDIO), this field value is used by the nRFgo Studio to indicate that an unmodulated carrier is turned on at the channel. It remains turned on until a TEST_END or RESET command is issued.
If the Length field is set 2 (symbol SET_TX_POWER), the Frequency field sets the TX power in dBm. The valid TX power values are specified in the product specification ranging from -40 to +4. 0 dBm is the reset value. Only the 6 least significant bits will fit in the Length field. The two most significant bits are calculated by the DTM module. This is possible because the 6 least significant bits of all valid TX power values are unique. The TX power can be modified only when no Transmitter Test or Receiver Test is running.
If the Length field is set to 3``(symbol ``NRF21540_ANTENNA_SELECT), the Frequency field sets the nRF21540 FEM antenna. The valid values are:
- 0 - ANT1 enabled, ANT2 disabled
- 1 - ANT1 disabled, ANT2 enabled
If the Length field is set to 4 (symbol NRF21540_GAIN_SET), the Frequency field sets the nRF21540 FEM TX gain value in arbitrary units. The valid gain values are specified in the nRF21540 product-specific range from 0 to 31.
If the Length field is set to 5 (symbol NRF21540_ACTIVE_DELAY_SET), the Frequency field sets the nRF21540 FEM activation delay in microseconds relative to a radio start. By default, this value is set to (radio ramp-up time - nRF21540 TX/RX settling time).
All other values of Frequency and Length field are reserved.

The DTM-to-Serial adaptation layer ¶

main.c is an implementation of the UART interface specified in the Bluetooth Core Specification: Vol. 6, Part F, Chap. 3.

The default selection of UART pins is defined in zephyr/boards/arm/board_name/board_name.dts. You can change the defaults using the symbols tx-pin and rx-pin in the DTS overlay file at the project level.

Debugging ¶

In this sample, the UART console is used to exchange commands and events defined in the DTM specification. Debug messages are not displayed in this UART console. Instead, they are printed by the RTT logger.

If you want to view the debug messages, follow the procedure in Connecting via RTT.

Requirements ¶

The sample supports the following development kit:

Hardware platforms	PCA	Board name	Build target
nRF5340 DK	PCA10095	nrf5340dk_nrf5340	`nrf5340dk_nrf5340_cpunet`
nRF21540 DK	PCA10112	nrf21540dk_nrf52840	`nrf21540dk_nrf52840`

Additionally, the sample requires one of the following testing devices:

Dedicated test equipment, like an Anritsu MT8852 tester. See Testing with a certified tester.

Another development kit with the same sample. See Testing with another development kit.

Another development kit connected to a PC with the Direct Test Mode sample available in the nRF Connect for Desktop. See Testing with nRF Connect for Desktop.

Building and running ¶

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

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

Note

On the nRF5340 development kit, the Direct Test Mode sample is a standalone network sample. It does not require any counterpart application sample. However, you must still program the application core to boot up the network core. You can use any sample for this, for example, the nRF5340: Empty firmware for application core.

The Bluetooth Low Energy DTM UART interface standard specifies:

8 data bits
No parity
1 stop bit
No hardware flow control
A selection of bit rates from 9600 to 1000000, one of which must be supported by the DUT. It might be possible to run other bit rates by experimenting with parameters.

The default bit rate of the DTM UART driver is 19200 bps, which is supported by most certified testers.

Testing ¶

After programming the sample to your development kit, you can test it in the three following ways.

Note

For the nRF5340 DK board (PCA10095), see Getting logging output for information about the COM terminals on which the logging output is available.

Testing with a certified tester¶

Conformance testing is done using a certified tester. The setup depends on the tester used, and details about the test operation must be found in the tester documentation.

Application note nAN34 describes two alternatives for setting up a production test with DTM using one of our old devices.

Testing with another development kit¶

Connect both development kits to the computer using a USB cable. The computer assigns to the development kit a COM port on Windows or a ttyACM device on Linux, which is visible in the Device Manager.
Connect to both kits with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.
Start TRANSMITTER_TEST by sending the 0x80 0x96 DTM command to one of the connected development kits. This command will trigger TX activity on the 2402 MHz frequency (1st channel) with 10101010 packet pattern and 37-byte packet length.
Observe that you received the TEST_STATUS_EVENT packet in response with the SUCCESS status field: 0x00 0x00.
Start RECEIVER_TEST by sending the 0x40 0x96 DTM command to the second development kit. Command parameters are identical to the ones used for the TRANSMITTER_TEST command.
Observe that you received the TEST_STATUS_EVENT packet in response with the SUCCESS status field: 0x00 0x00.
Finish RX testing using the TEST_END DTM command by sending the 0xC0 0x00 packet.
Observe that you received the PACKET_REPORTING_EVENT packet in response. For example, the 0xD6 0xAC message indicates that 22188 Radio packets have been received.
Experiment with other combinations of commands and their parameters.

Testing with nRF Connect for Desktop¶

Connect the development kit to the computer using a USB cable. The computer assigns to the development kit a COM port on Windows or a ttyACM device on Linux, which is visible in the Device Manager.
Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.
Start the TRANSMITTER_TEST by sending the 0x80 0x96 DTM command to the connected development kit. This command triggers TX activity on 2402 MHz frequency (1st channel) with 10101010 packet pattern and 37-byte packet length.
Observe that you received the TEST_STATUS_EVENT packet in response with the SUCCESS status field: 0x00 0x00.
Start the Direct Test Mode application in nRF Connect for Desktop and select the development kits to communicate with.
Set the Receiver mode and 37th channel in the test configuration menu.
Start the test.
On the application chart, observe that the number of RX packets is increasing for the 2402 MHz channel.
Stop the test.
Swap roles. Set the application to the RX mode and the connected development kit to the TX mode.

Dependencies ¶

This sample uses the following nrfx dependencies:

nrfx/drivers/include/nrfx_timer.h

nrfx/hal/nrf_nvmc.h

nrfx/hal/nrf_radio.h

nrfx/helpers/nrfx_gppi.h

In addition, it uses the following Zephyr libraries:

Device Driver Model:
- drivers/clock_control.h
- drivers/uart.h