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.
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.
To use Wireshark with Pyspinel, refer to the installation recommendations in the next step. You'll also need to configure Wireshark to properly show Thread packets and receive RSSI measurements.
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 and Windows
Download and install Wireshark. To optimize security for your operating system, refer to Wireshark — platform-specific information about capture privileges.
Configure Wireshark Protocols
To configure protocols, select Preferences... in Wireshark and expand the Protocols section.
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
Select CoAP from the list of protocols and set CoAP UDP Port to 61631. This ensures TMF messages (like address solicit) are displayed.
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.
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, then click Enabled Protocols.
Uncheck the following protocols:
- ZigBee Green Power
Configure Wireshark RSSI
To display RSSI in Wireshark:
- Select Preferences... and expand the Protocols section, then click IEEE 802.15.4.
Set the FCS Format:
Click OK to save and return to the Preferences menu.
From Preferences, select Appearance, then Columns.
Add a new entry:
- Title: RSSI
- Type: Custom
- Fields: wpan.rssi