Radio test (short-range)

The Radio test sample demonstrates how to configure the 2.4 GHz short-range radio (Bluetooth® LE, IEEE 802.15.4 and proprietary) in a specific mode and then test its performance. The sample provides a set of predefined commands that allow you to configure the radio in three modes:

  • Constant RX or TX carrier

  • Modulated TX carrier

  • RX or TX sweep

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

Shields

nRF7120 DK

nrf7120dk

nrf7120dk/nrf7120/cpuapp

nRF7002 DK

PCA10143

nrf7002dk

nrf7002dk/nrf5340/cpunet

nRF54LV10 DK

PCA10188

nrf54lv10dk

nrf54lv10dk/nrf54lv10a/cpuapp

nRF54LS05 DK

PCA10214

nrf54ls05dk

nrf54ls05dk/nrf54ls05b/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nrf2220ek

nRF54L15 DK (emulating nRF54L10)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp

nRF54L15 DK (emulating nRF54L05)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l05/cpuapp

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpurad

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpunet

nrf2220ek nrf21540ek

nRF52 DK

PCA10040

nrf52dk

nrf52dk/nrf52832

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

You can use any one of the development kits listed above.

Note

On nRF5340 DK and nRF7002 DK, the sample is designed to run on the network core and requires the nRF5340: Remote IPC shell running on the application core. This sample uses the IPC service shell transport library to forward shell data through the physical UART interface of the application core.

The sample also requires one of the following testing devices:

Note

You can perform the radio test also using a spectrum analyzer. This method of testing is not covered by this documentation.

Front-end module

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

To add support for the FEM, build the sample for a board containing FEM like nRF21540 DK or create a devicetree overlay file describing how FEM is connected to the nRF52 Series SoC in your device.

Note

If you use the nRF21540 EK, append nrf21540ek shield to your build command instructing build system to append the appropriate devicetree overlay file. If you use the nRF21540 DK, build your application for the nRF21540 DK board target. The devicetree for the nRF21540 DK already contains the required FEM configuration, so you do not need to set an additional build option.

For example, to build the sample from the command line for an nRF5340 DK with an attached nRF21540 EK, invoke the following command within the sample directory:

west build -b nrf5340dk/nrf5340/cpunet -- -DSHIELD=nrf21540ek

For more details refer to the following documentation:

You can configure the front-end module (FEM) transmitted power control, antenna output, and activation delay using the main shell commands of the User interface.

Note

Each front-end module (FEM) has different capabilities and operating modes, so some commands may not be supported by a specific FEM and those supported may work differently on different FEMs.

Skyworks front-end module

The Skyworks SKY66114 and SKY66403 are front-end module (FEM) devices that support the 2-pin PA/LNA interface. You can also use other Skyworks FEM devices that provide the same hardware interface.

To use the generic FEM implementation with Skyworks front-end modules refer to Enabling support for front-end modules using Simple GPIO interface for details.

Use case of incomplete physical connections to the FEM module

The devicetree configuration allows you to use a minimal pin configuration. Connect all unused pins to the fixed logic level as instructed in the official documentation. For example, csd-gpios is an optional pin that sets the device into sleep mode. If this pin is not controlled by the driver, it must be connected to the fixed logic level.

You can configure the Skyworks front-end module (FEM) antenna output and activation delay using the main shell commands of the User interface.

Overview

To run the tests, connect to the development kit through the serial port and send shell commands. Zephyr’s Shell module is used to handle the commands. At any time during the tests, you can dynamically set the radio parameters, such as output power, bit rate, and channel. In sweep mode, you can set the time for which the radio scans each channel from one millisecond to 99 milliseconds, in steps of one millisecond. The sample also allows you to send a data pattern to another development kit.

The sample first enables the high frequency crystal oscillator and configures the shell. You can then start running commands to set up and control the radio. See User interface for a list of available commands.

Note

For the IEEE 802.15.4 mode, the start channel and the end channel must be within the channel range of 11 to 26. Use the start_channel and end_channel commands to control this setting.

User interface

Main shell commands (in alphabetical order)

Command

Arguments

Description

cancel

Cancel the sweep or the carrier.

data_rate

<sub_cmd>

Set the data rate.

end_channel

<channel>

End channel for the sweep (in MHz, as difference from 2400 MHz).

fem

<sub_cmd>

Set front-end module (FEM) parameters.

output_power

<sub_cmd>

Output power set. If a front-end module is attached and the CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC Kconfig option is enabled, it has the same effect as the total_output_power command.

parameters_print

Print current delay, channel, and other parameters.

print_channel_sequence

Print the custom sequence set with the set_channel_sequence command

print_rx

Print the received RX payload.

set_channel_sequence

<sequence of up to 80 channels>

Set a custom channel sequence for the start_tx_with_sleep command

set_channel_sequence_hopping_mode

<hopping_mode>

Set the hopping mode for the channel sequence. Sequential (default order) | random <seed>

start_channel

<channel>

Start channel for the sweep or the channel for the constant carrier (in MHz, as difference from 2400 MHz).

start_duty_cycle_modulated_tx

<duty_cycle>

<packet_num> (optional)

Duty cycle as a percentage (two decimal digits, ranging from 01 to 90).

Number of packets to transmit (default is 0, which means continuous TX).

start_rx

<packet_num>

Start RX (continuous RX mode is used if no argument is provided).

start_rx_sweep

Start the RX sweep.

start_tx_carrier

Start the TX carrier.

start_tx_modulated_carrier

<packet_num>

Start the modulated TX carrier (continuous TX mode is used if no argument is provided).

start_tx_sweep

Start the TX sweep.

start_tx_sweep_with_sleep

<tx_time> (us) <sleep_time> (us)

Start TX sweep with a controlled sleep cycle

start_tx_sweep_with_sleep_modulated

<tx_time> (us) <sleep_time> (us)

Start modulated TX sweep with a controlled sleep cycle

time_on_channel

<time>

Time on each channel in ms (between 1 and 99).

toggle_dcdc_state

<state>

Toggle DC/DC converter state.

transmit_pattern

<sub_cmd>

Set transmission pattern.

total_output_power

<tx output power>

Set total output power in dBm. This value includes SoC output power and front-end module gain.

TX output power

This sample has a few commands that you can use to test the device output power. The behavior of the commands vary depending on the hardware configuration and Kconfig options as follows:

  • Radio Test without front-end module support:

    • The output_power command sets the SoC output command with a subcommand set. The output power is set directly in the radio peripheral.

  • Radio Test with front-end module support in default configuration (the CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC Kconfig option is enabled):

    • The output_power command sets the total output power, including front-end module gain.

    • The total_output_power command sets the total output power, including front-end module gain with a value in dBm unit provided by user.

    • For these commands, the radio peripheral and FEM transmit power control is calculated and set automatically to meet your requirements.

    • If an exact output power value cannot be set, a lower value is used.

  • Radio Test with front-end module support and manual TX output power control (the CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC Kconfig option is disabled):

    • The output_power command sets the SoC output command with a subcommands set.

    • The fem command with the tx_power_control subcommand sets the front-end module transmit power control to a value for given specific front-end module.

    • You can use this configuration to perform tests on your hardware design.

Configuration

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

The following sample-specific Kconfig options are used in this sample (located in samples/peripheral/radio_test/Kconfig) :

CONFIG_RADIO_TEST_USB

(bool) Radio Test shell over USB CDC ACM class

Selects USB instead of UART as the Radio Test shell transport. For nRF5340, the USB from application core is used as the communication interface.

CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC

(bool) Automatic power control

Sets the SoC output power and front-end module gain to achieve the requested TX output power. If the exact value cannot be achieved, power is set to closest value that does not exceed the limits If this option is disabled, set the SoC output power and FEM gain with separate commands.

CONFIG_RADIO_TEST_RX_TIMEOUT

(int) RX packet reception timeout

Specifies the time in seconds that the application waits for the first packet to be received in RX mode when a specified number of packets are set to be received. If the timeout is reached before the first packet is received, the radio will be disabled.

Building and running

This sample can be found under samples/peripheral/radio_test 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.

Note

On the nRF5340 or nRF7002 development kit, the Radio Test sample requires the nRF5340: Remote IPC shell sample on the application core. The Remote IPC shell sample is built and programmed automatically by default.

Pin debugging of RADIO events

The sample can be built with an extra overlay file to enable pin debugging of RADIO events for nR54L series devices with the following command:

west build -bnrf54l15dk/nrf54l15/cpuapp -p -- -DEXTRA_DTC_OVERLAY_FILE=pin_debug_54l.overlay

With pin debugging enabled two GPIOs will be configured to toggle on RADIO events: - One pin is set high on the RADIO->EVENTS_READY and low on the RADIO->EVENTS_DISABLED. - One pin is set high on the RADIO->EVENTS_ADDRESS and low on the RADIO->EVENTS_END.

The pins used for debugging are configured in samples/peripheral/radio_test/pin_debug_54l.overlay.

Remote USB CDC ACM Shell variant

This sample can run the remote IPC Service Shell through the USB on the nRF5340 DK application core. For example, when building on the command line, use the following command:

west build samples/peripheral/radio_test -b nrf5340dk/nrf5340/cpunet -- -DFILE_SUFFIX=usb

You can also build this sample with the remote IPC Service Shell and support for the front-end module. You can use the following command:

west build samples/peripheral/radio_test -b nrf5340dk/nrf5340/cpunet -- -DSHIELD=nrf21540ek -DFILE_SUFFIX=usb

Note

You can also build the sample with the remote IPC Service Shell for the nRF7002 DK board (PCA10143) using the nrf7002dk/nrf5340/cpunet board target in the commands.

Testing

After programming the sample to your development kit, complete the following steps to test it in one of the following two ways:

Note

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

Testing with another development kit

Complete the following steps:

  1. Connect both development kits to the computer using a USB cable. The kits are assigned serial ports. 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 both kits with a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

  3. Run the following commands on one of the kits:

    1. Set the data rate with the data_rate command to ble_2Mbit.

    2. Set the transmission pattern with the transmit_pattern command to pattern_11110000.

    3. Set the radio channel with the start_channel command to 40.

  4. Repeat all steps for the second kit.

  5. On both kits, run the parameters_print command to confirm that the radio configuration is the same on both kits.

  6. Set one kit in the Modulated TX Carrier mode using the start_tx_modulated_carrier command.

  7. Set the other kit in the RX Carrier mode using the start_rx command.

  8. Print the received data with the print_rx command and confirm that they match the transmission pattern (0xF0).

Testing with the RSSI Viewer app

Complete the following steps:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Open a serial port connection to the kit using a terminal emulator that supports VT100/ANSI escape characters (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

  3. Set the start channel with the start_channel command to 20.

  4. Set the end channel with the end_channel command to 60.

  5. Set the time on channel with the time_on_channel command to 50 ms.

  6. Set the kit in the TX sweep mode using the start_tx_sweep command.

  7. Start the RSSI Viewer app and select the kit to communicate with.

  8. On the application chart, observe the TX sweep in the form of a wave that starts at 2420 MHz frequency and ends with 2480 MHz.

Dependencies

This sample uses the following nRF Connect SDK libraries:

This sample has the following nrfx dependencies:

  • nrfx/drivers/include/nrfx_timer.h

  • nrfx/hal/nrf_power.h

  • nrfx/hal/nrf_radio.h

The sample also has the following nrfxlib dependency:

In addition, it uses the following Zephyr libraries: