Enhanced ShockBurst Sniffer

The Python scripts introduced in this document are used for the Enhanced ShockBurst: Monitor sample configured as Enhanced ShockBurst Sniffer.

Overview

There are two separate scripts you can use with the DK configured as an Enhanced ShockBurst sniffer:

  • main.py provides integration with the Wireshark extcap interface and the UART shell for real-time updates of sniffer parameters such as:

    • Bitrate

    • Channel

    • Radio addresses

    • Pipe prefixes

    • Enabled pipes

  • capture_to_pcap.py is a simple CLI utility to read packets from the DK and save them into pcap formatted file for further analysis.

Requirements

The script source files are located in the scripts/esb_sniffer directory. Complete the following steps to install scripts requirements:

  1. Install the Python requirements:

    pip3 install -r nrf/scripts/esb_sniffer/requirements.txt

  2. Install Wireshark.

Set up Wireshark

Complete the following steps to set up Wireshark:

  1. Enter nrf/scripts/esb_sniffer directory.

  2. Add a custom plugins to Wireshark:

    mkdir -p $HOME/.local/lib/wireshark/{extcap,plugins}
cp esb_dissector.lua $HOME/.local/lib/wireshark/plugins
cp extcap/esb_extcap.py $HOME/.local/lib/wireshark/extcap

  3. Enable the dissector for Enhanced ShockBurst:

    1. Open Wireshark.

    2. Go to Edit -> Preferences -> Protocols -> DLT_USER -> Edit.

    3. Click the Create new entry icon (bottom left).

    4. Select DLT=147 for DLT column and esb for Payload dissector column.

    5. Click Ok.

    6. Restart Wireshark.

After completing these steps, a new Enhanced ShockBurst sniffer interface appears in Wireshark.

main.py

This script works on Linux only.

Complete the following steps to use this script:

  1. Start the script:

    python3 main.py

  2. Start Wireshark and select the Enhanced ShockBurst sniffer interface.

  3. Observe the packets being received in Wireshark in real time.

  4. Type q or quit to stop the application.

capture_to_pcap.py

This script is not designed to work with a live Wireshark capture. You can capture packets into a file and open it in Wireshark later.

Complete the following steps to use this script:

  1. Start the script with the output filename as an argument:

    python3 capture_to_pcap.py output.pcap

  2. Type q or quit to stop the application.

Dependencies

The scripts use the pynrfjprog and pyserial libraries to communicate with the DK, and Wireshark as tool for visualizing Enhanced ShockBurst packets.