Bluetooth: Bluetooth LE master test app

The Bluetooth LE master test app is a Bluetooth® Low Energy (LE) central application designed to test basic Bluetooth functionality in peripheral samples. This application acts as a tester in the central role to validate Bluetooth LE peripheral applications in the nRF Connect SDK.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF54L15 DK	PCA10156	nrf54l15dk	nrf54l15dk/nrf54l15/cpuapp
nRF54H20 DK	PCA10175	nrf54h20dk	nrf54h20dk/nrf54h20/cpuapp
nRF5340 DK	PCA10095	nrf5340dk	nrf5340dk/nrf5340/cpuapp
nRF52 DK	PCA10040	nrf52dk	nrf52dk/nrf52832
nRF52840 DK	PCA10056	nrf52840dk	nrf52840dk/nrf52840
nRF52833 DK	PCA10100	nrf52833dk	nrf52833dk/nrf52833

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample requires a Bluetooth LE peripheral device for testing. You can use any of the following peripheral samples:

• Bluetooth: Peripheral UART

• Bluetooth: Peripheral HIDS keyboard

• Bluetooth: Peripheral HIDS mouse

• Bluetooth: Peripheral LBS

Overview

The Bluetooth LE master test app implements a Bluetooth LE central device that can discover and connect to peripheral devices. It performs automatic device discovery, service discovery, connection management, and supports security features.

The application follows a specific test sequence:

1. Initialization - Initializes the Bluetooth stack and sets up required modules.

2. Scanning - Actively scans for supported peripheral devices.

3. Connection - Automatically connects to discovered devices.

4. Service discovery - Discovers and logs GATT services.

5. Connection maintenance - Maintains the connection for five seconds.

6. Disconnection - Disconnects gracefully.

7. Reconnection - Waits three seconds, then reconnects.

8. Extended test - Maintains the connection for 10 seconds.

9. Final disconnection - Completes the test cycle.

10. Success indication - Prints SUCCESS when all steps are completed.

Supported device types

The application is configured to discover and test the following Bluetooth LE peripheral devices:

• Nordic UART Service

• Nordic Throughput

• NCS HIDS Keyboard

• NCS HIDS Mouse

• Nordic Lightweight Battery Service (LBS)

• Test Beacon

• HID devices (through UUID filtering)

Debugging

In this sample, the UART console is used to display test progress and results. Debug messages are not displayed in the UART console, instead, they are printed by the RTT logger.

To view debug messages, follow the procedure described in Testing and optimization.

FEM support

You can add support for the nRF21540 front-end module to this sample by using one of the following options, depending on your hardware:

• Build the sample for one board that contains the nRF21540 FEM, such as nRF21540 DK.

• Manually create a devicetree overlay file that describes how the nRF21540 FEM is connected to the SoC. See Configuring devicetree for different ways of adding the overlay file.

• Provide nRF21540 FEM capabilities by using a shield, for example the nRF21540 EK shield that is available in the nRF Connect SDK. In this case, build the project for a board connected to the shield you are using with an appropriate variable included in the build command, for example -DSHIELD=nrf21540ek. This variable instructs the build system to append the appropriate devicetree overlay file.

  nRF Connect for VS CodeCommand line

  To build the sample in nRF Connect for VS Code for an nRF52840 DK with the nRF21540 EK attached, add the shield variable in the build configuration’s Extra CMake arguments and rebuild the build configuration. For example: -DSHIELD=nrf21540ek.

  See How to work with build configurations in the nRF Connect for VS Code documentation for more information.

  See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example the nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Developing with Front-End Modules for more information about FEM in the nRF Connect SDK.

To add support for other front-end modules, add the respective devicetree file entries to the board devicetree file or the devicetree overlay file.

Configuration

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

Configuration options

Check and configure the following configuration options for the sample:

• CONFIG_BT_CENTRAL

• CONFIG_BT_SCAN

• CONFIG_BT_GATT_DM

• CONFIG_BT_SMP

Building and running

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

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

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.

When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build. The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device. If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.

Testing

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

nRF21, nRF52 and nRF53 DKsnRF54 DKs

1. Connect the device to the computer to access UART 0. If you use a development kit, UART 0 is forwarded as a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.

2. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

3. Reset the kit.

4. Observe that the text Starting Bluetooth LE test application is printed on the COM listener.

5. Power on a Bluetooth LE peripheral device that matches one of the supported device types.

6. Observe that the application discovers and connects to the peripheral device.

7. Monitor the console output for successful connection and service discovery.

8. Verify that the application completes the full test cycle and prints SUCCESS.

Sample output

The application provides detailed console output, including:

• Bluetooth initialization status

• Device discovery information

• Connection establishment details

• Service discovery results

• Security pairing information

• Test progress and results

The following is an example of the output:

Starting BLE test application
Bluetooth initialized
UART initialized
Scan module initialized
Scanning successfully started
Filters matched. Address: AA:BB:CC:DD:EE:FF connectable: 1
Connected
Service discovery completed
Disconnect successful
SUCCESS

Testing workflow

The application supports both manual and automated testing.

Manual testing

To test the sample manually, complete the following steps:

1. Build and flash the application to a development kit.

2. Power on a Bluetooth LE peripheral device (for example, Nordic UART Service sample).

3. Monitor the console output for successful connection and service discovery.

4. Verify that the application completes the full test cycle.

Automated testing

The application is designed for integration with automated test frameworks, providing:

• Seamless CI/CD pipeline support.

• Structured test results.

• Comprehensive documentation of test procedures.

• Full compatibility with Nordic Semiconductor’s test infrastructure.

Troubleshooting

If you have issues while using the sample, consider the following potential causes and recommended checks:

1. No devices discovered - Ensure the peripheral device is advertising with the correct name.

2. Connection failures - Check device compatibility and verify the Bluetooth stack configuration.

3. Service discovery errors - Verify that the peripheral device implements the expected services.

4. Build errors - Ensure all required dependencies are properly installed.

Dependencies

This sample uses the following nRF Connect SDK libraries:

• GATT Discovery Manager

• Bluetooth LE scanning

In addition, it uses the following Zephyr libraries:

• include/zephyr/types.h

• boards/arm/nrf*/board.h

• Kernel Services:

  • include/kernel.h

• Peripherals:

  • include/uart.h

• API:

  • include/bluetooth/bluetooth.h

  • include/bluetooth/gatt.h

  • include/bluetooth/hci.h

  • include/bluetooth/uuid.h

The sample also uses the following secure firmware component:

• Trusted Firmware-M