IEEE 802.15.4 PHY test tool

The IEEE 802.15.4 PHY test tool performs 802.15.4 RF Performance and PHY Certification tests, and can also provide information for a general evaluation of the performance of the integrated 802.15.4 radio.

Requirements 

The sample supports the following development kits:

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

Conducting tests using the sample also requires a testing device, like another development kit running the same sample, set into DUT mode. For more information, see Testing the sample.

Note

You can perform the testing using other equipment, like spectrum analyzers, oscilloscopes, or RF power meters, but these methods are not covered by this documentation.

Overview 

To perform the tests, connect to the development kit through the serial port and send supported commands.

See the Serial commands list for the list of the available commands.

Serial commands list 

This section lists the serial commands that are supported by the sample.

changemode - Change the device mode 

It changes the device mode if both modes are available.

custom changemode <mode>

The <mode> argument assumes one of the following values:

0 - DUT
1 - CMD

For example:

custom changemode 1

lindication - LED indication 

It makes the CMD device control the LED indicating packet reception.

custom lindication <value>

The <value> argument assumes one of the following values:

0 - none
1 - LED packet reception indication

For example:

custom lindication 1

rping - Ping the DUT 

It makes the CMD device send a PING to the DUT device and wait for the reply.

custom rping

lpingtimeout - Set the ping timeout 

It makes the CMD device set the timeout in milliseconds for receiving the pong responses from the DUT device.

custom lpingtimeout <timeout:1> <timeout:0>

The <timeout:1> value indicates the higher byte of the timeout.
The <timeout:0> value indicates the lower byte of the timeout.

For example:

custom lpingtimeout 0 255

setchannel - Set the common radio channel for the DUT and CMD 

It sets a common radio channel for the DUT and CMD devices, sends a PING, and waits for the response.

custom setchannel <channel:3> <channel:2> <channel:1> <channel:0>.

The four <channel:x> arguments are four octets defining the channel page and number.

For example:

custom setchannel 0 0 8 0

lsetchannel - Set the CMD radio channel 

It sets radio channel of the CMD device.

custom lsetchannel <channel:3> <channel:2> <channel:1> <channel:0>.

The four <channel:x> arguments are four bytes defining the channel page and number.

For example:

custom lsetchannel 0 0 16 0

rsetchannel - Set the DUT radio channel 

It sets the radio channel of the DUT device.

custom rsetchannel <channel>

The <channel> argument indicates the selected channel’s number.

For example:

custom rsetchannel 13

lgetchannel - Get the CMD radio channel 

It gets the current configured channel of the CMD device.

custom lgetchannel

lsetpower - Set the CMD radio power 

It sets the CMD device’s TX power.

custom lsetpower <mode:1> <mode:0> <power>

The <mode:1> and <mode:0> arguments are currently unsupported. Use 0 for both.
The <power> argument indicates the TX power as a signed integer in dBm.

For example:

custom rsetpower 0 0 -17

lgetpower - Get the CMD radio power 

It gets the current configured power of the CMD device.

custom lgetpower

rgetpower - Get the DUT radio power 

It gets the current configured power of the DUT device.

custom rgetpower

rstream - DUT modulated waveform transmission 

It commands the DUT device to start a modulated waveform transmission of a certain duration in milliseconds.

custom rstream <duration:1> <duration:0>

The <duration:1> argument indicates the higher byte of the duration value.
The <duration:0> argument indicates the lower byte of the duration value.

For example:

custom rstream 255 255

rstart - Start the RX Test 

It makes the DUT device start the RX test routine, clearing previous statistics.

custom rstart

rend - End the RX Test 

It makes the DUT device terminate the RX test routine. The DUT device also sends the test results to the CMD device

custom rend

find - Find the DUT 

It makes the CMD device cycle all the channels (11-26) trying to PING the DUT device. It stops upon receiving a reply.

custom find

lgetcca - Clear Channel Assessment 

It makes the CMD device perform a Clear Channel Assessment (CCA) with the requested mode and print the result.

custom lgetcca <mode>

The <mode> argument indicates the IEEE 802.15.4 CCA mode (1-3).

For example:

custom lgetcca 1

lsetcca - Clear Channel Assessment 

If enabled, it makes the CMD device perform a Clear Channel Assessment (CCA) before each transmission.

custom lsetcca <toggle>

The <toggle> argument enables or disables the execution of a CCA before each transmission. You can set it to the following values:

1 - enable CCA
0 - disable CCA

For example:

custom lsetcca 1

lgeted - Perform Energy Detection 

It starts the energy detection and reports the result as 2 hexadecimal bytes.

custom lgeted

lgetlqi - Get Link Quality Indicator 

It puts the CMD device in receive mode and makes it wait for a packet. It then outputs the result as 2 hexadecimal bytes.

custom lgetlqi

lgetrssi - Measure RSSI 

It gets the RSSI in dBm.

custom lgetrssi

lsetshort - Set short address 

It sets the CMD device’s short address. It is used for frame filtering and acknowledgment transmission.

custom lsetshort 0x<short_address>

The <short_address> argument indicates the IEEE 802.15.4 short, two-byte address.

For example:

custom lsetshort 0x00FF

lsetextended - Set extended address 

It sets the CMD device’s extended address. It is used for frame filtering and acknowledgment transmission.

custom lsetextended 0x<extended_address>

The <extended_address> argument indicates the IEEE 802.15.4 long, 8-byte address.

For example:

custom lsetextended 0x000000000000FFFF

lsetpanid - Set PAN ID 

It sets the PAN ID. It is used for frame filtering and acknowledgment transmission.

custom lsetpanid 0x<panid>

The <panid> argument indicates the two-bytes of the IEEE 802.15.4 PAN ID.

For example:

custom lsetpanid 0x000A

lsetpayload - Set payload for burst transmission 

It sets an arbitrary payload of a raw IEEE 802.15.4 packet.

custom lsetpayload <length> <payload>

The <length> argument indicates the length of the payload in bytes.
The <payload> argument indicates the bytes of the packet payload.

For example:

custom lsetpayload 5 FFFFFFFFFF

ltx - Burst transmission of packets 

It starts the transmission of packets with a random (or previously defined) payload.

custom ltx <number> <delay>

The <number> argument indicates the number of packets to be sent. Set to 0 for an infinite transmission.
The <delay> argument indicates the delay in milliseconds between the transmissions.

For example:

custom ltx 10 1000

ltxend - Stop the burst transmission of packets 

It makes the CMD device stop current burst transmission.

custom ltxend

lstart - Start the continuous receive mode 

It makes the sample enter the continuous receive mode and print the received packet information over a serial connection. The sample does not accept any other command until it receives custom lend.

custom lstart

lend - End the continuous receive mode 

It makes the sample leave the continuous receive mode and print statistics

custom lend

The statistics are shown in the following format:

[total]0x%x%x%x%x [protocol]0x%x%x%x%x [totalLqi]0x%x%x%x%x [totalRssiMgnitude]0x%x%x%x%x

lsetantenna - Set CMD antenna ID 

It sets the antenna used by the CMD device for both TX and RX operations.

custom lsetantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom lsetantenna 1

lsetrxantenna - Set CMD antenna ID for RX 

It sets the antenna used by the CMD device for RX operations.

custom lsetrxantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom lsetrxantenna 1

lsettxantenna - Set CMD antenna ID for TX 

It sets the antenna used by the CMD device for TX operations.

custom lsettxantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom lsettxantenna 1

lgetrxantenna - Get CMD RX antenna ID 

It gets the antenna used by the CMD device for RX operations.

custom lgetrxantenna

lgettxantenna - Get CMD TX antenna ID 

It gets the antenna used by the CMD device for TX operations.

custom lgettxantenna

lgetbestrxantenna - Get last best CMD RX antenna ID selected by antenna diversity algorithm 

It gets the last best antenna selected for RX operations by the antenna diversity algorithm.

custom lgetbestrxantenna

rsetantenna - Set DUT antenna ID 

It sets the antenna used by the DUT device for both TX and RX operations.

custom rsetantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom rsetantenna 1

rsettxantenna - Set DUT TX antenna ID 

It sets the antenna used by the DUT device for TX operations.

custom rsettxantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom rsettxantenna 1

rsetrxantenna - Set DUT RX antenna ID 

It sets the antenna used by the DUT device for RX operations.

custom rsetrxantenna <antenna>

The <antenna> argument indicates the antenna ID. It can either be 0 or 1.

For example:

custom rsetrxantenna 1

rgetrxantenna - Get DUT TX antenna ID 

It gets the antenna used by the DUT device for TX operations.

custom rgettxantenna

rgettxantenna - Get DUT RX antenna ID 

It gets the antenna used by the DUT device for RX operations.

custom rgetrxantenna

rgetbestrxantenna - Get last best DUT RX antenna ID selected by antenna diversity algorithm 

It gets the last best antenna selected for RX operations by the antenna diversity algorithm.

custom rgetbestrxantenna

lcarrier - Unmodulated waveform (carrier) transmission 

It starts the transmission of the unmodulated carrier.

custom lcarrier <pulse_duration> <interval> <transmission_duration>

The <pulse_duration> argument indicates the duration of the continuous signal transmission. It ranges between 1 and 32767 milliseconds.
The <interval> argument indicates the duration of the interval between the pulses. It ranges between 0 and 32767 milliseconds.
The <transmission_duration> argument indicates the upper limit for the command’s execution. It ranges between 0 and 32767 milliseconds. Set to 0 for infinite transmission.

For example:

custom lcarrier 10 200 2000

lstream - Modulated waveform transmission 

It starts a modulated waveform transmission.

custom lstream <pulse_duration> <interval> <transmission_duration>

The <pulse_duration> argument indicates the duration of the continuous packet transmission. It ranges between 1 and 32767 milliseconds.
The <interval> argument indicates the duration of the interval between the pulses. It ranges between 0 and 32767 milliseconds.
The <transmission_duration> argument indicates the upper limit for the command’s execution. It ranges between 0 and 32767 milliseconds. Set to 0 for infinite transmission.

For example:

custom lstream 100 200 20000

rhardwareversion - Get the DUT hardware version 

It gets the hardware version of the DUT device.

custom rhardwareversion

rsoftwareversion - Get the DUT software version 

It gets the software version of the DUT device.

custom rsoftwareversion

lclk - High-frequency clock output on a selected pin 

It makes the CMD device disable or enable the high-frequency clock output on a selected pin. The actual clock frequency depends on the SoC used. It is the highest possible considering the GPIO and CLOCK modules possibilities.

custom lclk <pin> <value>

The <pin> argument indicates the GPIO pin number. It ranges between 0 and the number of GPIO pins supported by the SoC.
The <value> argument can assume one of the following values:
- 0 - disabled
- 1 - enabled

For example:

custom lclk 10 1

lsetgpio - Set GPIO pin value 

It makes the CMD device set the value of the selected GPIO out pin.

custom lsetgpio <pin> <value>

The <pin> argument indicates the GPIO pin number. It ranges between 0 and the number of GPIO pins supported by the SoC.
The <value> argument can assume one of the following values:
- 0 - low
- 1 - high

For example:

custom lsetgpio 29 0

lgetgpio - Get GPIO pin value 

It makes CMD reconfigure the selected GPIO pin to INPUT mode and read its value.

custom lgetgpio <pin>

The <pin> argument indicates the GPIO pin number. It ranges between 0 and the number of GPIO pins supported by the SoC.

For example:

custom lgetgpio 29

lsetdcdc - Set DC/DC mode 

It makes the CMD device disable or enable the DC/DC mode. It has no effects on unsupported boards.

custom lsetdcdc <value>

The <value> argument can assume one of the following values:
- 0 - disabled
- 1 - enabled

For example:

custom lsetdcdc 1

lgetdcdc - Get DC/DC mode 

It gets the DC/DC mode of the CMD device. It is always 0 for unsupported boards.

custom lgetdcdc

lseticache - Set ICACHE configuration 

It makes the CMD device disable or enable the ICACHE

custom lseticache <value>

The <value> argument can assume one of the following values:
- 0 - disabled
- 1 - enabled

For example:

custom lseticache 1

lgettemp - Read SoC temperature 

It makes the CMD device print the SoC temperature in the format <.%02>.

custom lgettemp

lsleep - Transition radio to sleep mode 

It makes the CMD device put the radio in sleep mode.

custom lsleep

lreceive - Transition radio to receive mode 

It makes the CMD device put the radio in receive mode.

custom lreceive

lreboot - Reboots the device 

It reboots the device

custom lreboot

Configuration 

See Configuring your application for information about how to permanently or temporarily change the configuration.

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 nrf21540dk_nrf52840.
Manually create a devicetree overlay file that describes how FEM is connected to the nRF5 SoC in your device. See Set devicetree overlays 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 SHIELD=nrf21540ek. This variable instructs the build system to append the appropriate devicetree overlay file.
To build the sample in the nRF Connect for VS Code IDE 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 nRF Connect for VS Code extension pack documentation for more information.
To build the sample from the command line for an nRF52840 DK with the nRF21540 EK attached, use the following command within the sample directory:
west build -b nrf52840dk_nrf52840 -- -DSHIELD=nrf21540ek
See Programming nRF21540 EK for information about how to program when you are using a board with a network core, for example nRF5340 DK.

Each of these options adds the description of the nRF21540 FEM to the devicetree. See Working with RF 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.

Note

The sample provides support for the antenna diversity feature on the nRF52840. To enable the feature, set the CONFIG_PTT_ANTENNA_DIVERSITY option as enabled.

Building and running 

This sample can be found under samples/peripheral/802154_phy_test in the nRF Connect SDK folder structure.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Note

On the nRF5340 DK board (PCA10095), the IEEE 802.15.4 PHY Test Tool 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 Remote IPC shell sample is built and programmed automatically by default.

Testing the sample 

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

Connect the development kit to the computer using a USB cable. Use the development kit’s programmer USB port (J2). The kits are assigned a COM port (in Windows) or a ttyACM device (in Linux), visible in the Device Manager or in the /dev directory.
Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.
If the sample is configured to support both modes (the default setting), switch the development kit into CMD mode by sending the following command:
```
custom changemode 1
```
On the bottom side of your development kit, locate the table describing the GPIO pin assignment to the LEDs.
Read the numbers of the GPIO pins assigned to LED 1, 2, 3 or 4.

For example, on the nRF52840DK, the LEDs are controlled by the pins ranging between P0.13 and P0.16. The LEDs on nRF5340DK and nRF52840DK are in the sink configuration.
To turn the LEDs on, set the respective pin’s state to low to let the current flow through the LED, using the custom lsetgpio <pin> 0 command, where <pin> is the number of the pin assigned for selected LED.

See the following example for how to light up LED 1 on the nRF5340DK:
```
custom lsetgpio 28 0
```

If the selected LED lights up, the sample works as expected and is ready for use.

Performing radio tests without the serial interface 

Make sure that at least one of the development kits can be set into CMD mode and the other one to the DUT mode.

The DUT device does not initialize the serial interface. The easiest way to achieve this is to flash both devices with the sample configured to support both modes (default setting).
Connect both development kits to the computer using a USB cable.

The kits are assigned a COM port (in Windows) or a ttyACM device (in Linux), visible in the Device Manager or the /dev directory.
Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.
If the samples are configured to support both modes (the default setting), switch one of the development kits into CMD mode by sending the following command:
```
custom changemode 1
```
Run the following command on the development kit running in CMD mode:
```
custom find
```
The development kit running in CMD mode should respond with one of the following two responses:
- channel <ch> find <ack> - if the CMD device successfully communicates with the DUT device.
- DUT NOT FOUND - if it could not exchange packets with the DUT device.

Refer to the Serial commands list for the complete list of the available commands.