Enhanced ShockBurst: Monitor

The Monitor sample shows how to use the Enhanced ShockBurst (ESB) protocol in Monitor mode. It demonstrates how to configure the Enhanced ShockBurst protocol to receive all the traffic generated on the configured channel and pipes.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF54LS05 DK

PCA10214

nrf54ls05dk

nrf54ls05dk/nrf54ls05b/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nRF54L15 DK (emulating nRF54L10)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp

nRF54L15 DK (emulating nRF54L05)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l05/cpuapp

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpunet

nRF52 DK

PCA10040

nrf52dk

nrf52dk/nrf52832

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

Overview

The sample consist of one receiver configured as a monitor that uses the Enhanced ShockBurst library. After building and programming each sample on a DK, you can monitor the traffic generated by the kits programmed with the Transmitter and Receiver samples, respectively. You can see the received traffic in real time using the Serial Terminal app. Successful monitoring is also indicated by the LEDs that should be in sync on all kits.

User interface

All LEDs:

Indicate that packets are received.

When used together with the Transmitter sample:

The first four packets turn on the LEDs sequentially.

The next four packets turn them off again in the same order.

To disable LEDs, unset the CONFIG_LED_ENABLE Kconfig option.

The following sniffer shell subcommands are available when the CONFIG_ESB_SNIFFER Kconfig option is set:

Sniffer shell commands

Subcommand

Arguments

Description

show

Print actual sniffer configuration

start

Start listening

stop

Stop listening

set addr0

<xx.xx.xx.xx>

Set base address 0

set addr1

<xx.xx.xx.xx>

Set base address 1

set bitrate

<bitrate>

Set bitrate

set channel

<channel number>

Set ESB channel

set prefix

<xx.xx.xx.xx> <xx.xx.xx.xx>

Set prefix0 and prefix1

pipe enable

<pipe number> <pipe number> … or all

Enable selected pipes, or all pipes when argument is all

pipe disable

<pipe number> <pipe number> … or all

Disable selected pipes, or all pipes when argument is all

pipe prefix

<pipe number> <prefix>

Set <prefix> on <pipe number>

Configuration

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

Configuration options

Check and configure the following options:

CONFIG_LED_ENABLE

Enable led changes while receiving packets. It is intended to use together with the Transmitter sample. This option is enabled by default.

CONFIG_ESB_SNIFFER

Disable logging received packets through UART, set RTT as transport layer for the packets, and enable the shell. It is intended for use together with scripts/esb_sniffer/main.py or scripts/esb_sniffer/capture_to_pcap.py scripts. This option is disabled by default.

Building and running

The Monitor sample is located in the samples/esb/esb_monitor folder in the nRF Connect SDK folder structure.

See Building an application and Programming an application for information on how to build and program the application, respectively.

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.

    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.

Testing

After programming the DKs with the Monitor, Transmitter, and Receiver samples, you can test their functionality.

Complete the following steps to test the samples:

  1. Power on all kits.

  2. Observe that the LEDs change synchronously on all kits.

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

  4. Observe the logged traffic of the DK programmed with the Monitor sample.

Complete the following steps to test the sample with the CONFIG_ESB_SNIFFER Kconfig option enabled:

  1. Power on the DK.

  2. Read and follow the instructions in the Enhanced ShockBurst Sniffer file to configure your environment.

  3. Run the scripts/esb_sniffer/capture_to_pcap.py script with the name of the output file as argument. For example:

    python3 capture_to_pcap.py output.pcap

  4. Analyze the captured traffic in Wireshark.

Dependencies

This sample uses the following nRF Connect SDK library:

In addition, it uses the following Zephyr libraries: