The Pyspinel sniffer tool connects to a Thread NCP or RCP device and converts it into a promiscuous packet sniffer, generating a pcap (packet capture) stream to be saved or piped directly into Wireshark.
Wireshark is an open-source tool that can decode network protocols in the Thread stack, such as IEEE 802.15.4, 6LoWPAN, IPv6, MLE (Mesh Link Establishment), UDP, and CoAP.
This guide covers how to configure Wireshark and run Pyspinel to sniff packets from a Thread network.
To use the Wireshark extcap plugin for packet sniffing, see Packet Sniffing using extcap.
Requirements
Hardware:
- A host machine to serve as an NCP and to run Pyspinel and Wireshark:
- macOS — 64 bit OS X 10.6 or later
- Ubuntu
- 1 OpenThread device flashed with an
ot-ncp-ftd
orot-rcp
build.
Software:
Installation
Set up the sniffer environment
Clone and install Pyspinel and dependencies:
- Install dependencies:
sudo apt install python3-pip
pip3 install --user pyserial ipaddress
- Clone the Pyspinel repository:
git clone https://github.com/openthread/pyspinel
- Install Pyspinel:
cd pyspinel
python3 setup.py install
Alternatively, set up the environment by installing the pyspinel
package. Note
that this package uses the Pyspinel v1.0.0a3
release and not
the latest Pyspinel master.
pip3 install --user pyspinel
Install Wireshark
Linux
Open a terminal and run the following commands to download and install Wireshark:
sudo add-apt-repository ppa:wireshark-dev/stable
sudo apt-get update
sudo apt-get install wireshark
We recommend running Wireshark as a non-root user. To do so, reconfigure the package:
sudo dpkg-reconfigure wireshark-common
When you get the dialog asking "Should non-superusers be able to capture packets?", select
Yes, then add the wireshark
user and update file permissions:
sudo adduser $USER wireshark
sudo chmod +x /usr/bin/dumpcap
macOS
Download and install Wireshark for macOS.
Build the sniffer
Build and flash an NCP device to serve as the sniffer, using the ot-rcp
binary output.
Nordic nRF52840
To set up the Nordic nRF52840 example for use as a sniffer:
- Clone OpenThread and set up the build environment:
git clone https://github.com/openthread/openthread
cd openthread
./bootstrap
- Build the OpenThread nRF52840 example, using a UART baud rate of 460800:
make -f examples/Makefile-nrf52840 CFLAGS="-DUART_BAUDRATE=NRF_UART_BAUDRATE_460800"
- Convert the
ot-rcp
binary output to hex:arm-none-eabi-objcopy -O ihex output/nrf52840/bin/ot-rcp ot-rcp.hex
- Flash the
ot-rcp.hex
file to the nRF52840 board as detailed in Flash the nRF52840. - Disable Mass Storage Device (MSD) on the nRF52840 to avoid issues with data
corruption or drops when using the debug port:
expect <<EOF
spawn JLinkExe
expect "J-Link>"
send "msddisable\n"
expect "Probe configured successfully."
exit
EOF
spawn JLinkExe SEGGER J-Link Commander V6.42b (Compiled Feb 5 2019 17:35:31) DLL version V6.42b, compiled Feb 5 2019 17:35:20
Thread network properties
Before continuing, get the following properties for the Thread network you wish to sniff. You'll need them for Wireshark configuration and running the Pyspinel sniffer.
Mesh Local Prefix
To get the Mesh Local Prefix from a device in the target Thread network:
- Using the OpenThread CLI:
dataset active
Mesh Local Prefix: fd33:3333:3344:0/64 - Using
wpanctl
with an NCP:wpanctl getprop IPv6:MeshLocalPrefix
IPv6:MeshLocalPrefix = "fd33:3333:3344:0::/64" - Using the OTBR Web GUI, select Status. The Mesh Local Prefix is listed
as IPv6:MeshLocalPrefix similar to
wpanctl
.
Channel
To get the Channel from a device in the target Thread network:
- Using the OpenThread CLI:
channel
15 - Using
wpanctl
with an NCP:wpanctl getprop NCP:Channel
NCP:Channel = 15 - Using the OTBR Web GUI, select Status. The Channel is listed as
NCP:Channel similar to
wpanctl
.
Master Key
The Thread network Master Key is used by Wireshark to decrypt packets after capture. To get the Master Key from a device in the target Thread network:
- Using the OpenThread CLI:
masterkey
33334444333344443333444433334444 - Using
wpanctl
with an NCP:wpanctl getprop Network:Key
Network:Key = [33334444333344443333444433334444]
The Thread network Master Key is not available in the OTBR Web GUI.
Wireshark configuration - Protocols
Wireshark must be configured to properly show Thread packets.
Select Preferences... in Wireshark and expand the Protocols section.
6LoWPAN
Select 6LoWPAN from the list of protocols and verify or change the following settings:
- Uncheck Derive ID according to RFC 4944.
- Update Context 0 with the Mesh Local Prefix for the target Thread network.

Wireshark uses context configurations to parse the compressed IPv6 address and display the IPv6 source and destination addresses correctly.
To show the addresses for other on-mesh prefixes configured on the gateway, update other Context IDs with those prefixes.
To get the Context ID for a specific on-mesh prefix, view the Thread Network Data TLV in any MLE Data response message. For example:
Context 1: fd00:7d03:7d03:7d03::/64
CoAP
Select CoAP from the list of protocols and set CoAP UDP Port to 61631. This ensures TMF messages (like address solicit) are displayed.
IEEE 802.15.4
Select IEEE 802.15.4 from the list of protocols and verify or change the following settings:
- Set 802.15.4 Ethertype (in hex) to "0x809a".
- Set the Security Suite to "AES-128 Encryption, 32-bit Integrity Protection".
- Click the Edit... button next to Decryption Keys, which is where you
add the Thread network Master Key for packet decryption.
- Click + to add a Decryption key.
- Enter the Thread network Master Key into the Decryption key column.
- Enter "1" as the Decryption key index.
- Select Thread hash from the Key hash column listbox.
- Click OK to save the decryption key.
Thread
Select Thread from the list of protocols and verify or change the following settings:
- Enter "00000000" for the Thread sequence counter.
- Uncheck Use PAN ID as first two octets of master key.
- Check Automatically acquire Thread sequence counter.
Click the OK button to save any protocol changes.
Some Thread traffic might be analyzed as the ZigBee protocol. To correctly display these two protocols, edit the enabled protocols in Wireshark:
- In Wireshark, go to Analyze > Enabled Protocols.
- Uncheck the following protocols:
- LwMesh
- ZigBee
- ZigBee Green Power
Wireshark configuration - RSSI
To display RSSI in Wireshark:
- Go to Preferences > Protocols > IEEE 802.15.4.
- Set the FCS Format:
- If IEEE 802.15.4 TAP disabled: TI CC24xx metadata.
- If IEEE 802.15.4 TAP enabled: ITU-T CRC-16.
See the
--tap
flag for more information.
- Click OK to save and return to the Preferences menu.
- From Preferences, select Appearance > Columns.
- Add a new entry:
- Title: RSSI
- Type: Custom
- Fields: wpan.rssi

Sniffer options
Options | |||||
---|---|---|---|---|---|
-u or --uart |
|
||||
-c or --channel |
|
||||
--no-reset |
|
||||
--crc |
|
||||
-b or --baudrate |
|
||||
--rssi |
|
||||
--tap |
|
Run the sniffer
Make sure to use the specific device path for your NCP and the channel for the Thread network you are attempting to sniff.
If following this guide, the nRF52840 DK should be attached the host machine by
the debug port, as described in Flash the
nRF52840. To run the Pyspinel sniffer,
use the -b
flag to specify the baud rate (if it was changed from the default)
and omit the --no-reset
flag.
For example, to sniff on Channel 15 using a device mounted at /dev/ttyACM0
with RSSI included in the Wireshark output:
cd <path-to-pyspinel>
python sniffer.py -c 15 -u /dev/ttyACM0 --crc --rssi -b 460800 | wireshark -k -i -
You should now be able to see the packets and related protocols for this configuration in Wireshark:
See the Spinel sniffer reference for more information on running the Pyspinel sniffer.
Native USB connection
Using the nRF52840 DK USB port requires the OpenThread ot-rcp
binary to
be built with the USB=1
flag:
make -f examples/Makefile-nrf52840 USB=1
Flash the nRF52840 DK, connect it to the host machine by the USB
port, then use the --no-reset
flag
but omit the -b
flag when running the sniffer:
python sniffer.py -c 15 -u /dev/ttyACM0 --crc --no-reset --rssi | wireshark -k -i -
Resources
For more information on how to use Pyspinel and Wireshark, see the following: