Install and Configure Wireshark

View source on GitHub

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.

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 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.

6LoWPAN

Select 6LoWPAN from the list of protocols and verify or change the following settings:

  1. Uncheck Derive ID according to RFC 4944.
  2. Update Context 0 with the Mesh Local Prefix for the target Thread network.

OT Sniffer Wireshark 6LoWPAN

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:

  1. Set 802.15.4 Ethertype (in hex) to "0x809a".
  2. Set the Security Suite to "AES-128 Encryption, 32-bit Integrity Protection".

  3. Click the Edit... button next to Decryption Keys, which is where you add the Thread network Master Key for packet decryption.

    1. Click + to add a Decryption key.
    2. Enter the Thread network Master Key into the Decryption key column.
    3. Enter "1" as the Decryption key index.

    4. Select Thread hash from the Key hash column listbox.

      OT Sniffer Wireshark IEEE 802.15.4

    5. 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:

  1. In Wireshark, go to Analyze, then click Enabled Protocols.

  2. Uncheck the following protocols:

    1. LwMesh
    2. ZigBee
    3. ZigBee Green Power

Configure Wireshark RSSI

To display RSSI in Wireshark:

  1. Select Preferences... and expand the Protocols section, then click IEEE 802.15.4.

  2. 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. If you're following the Packet Sniffing guide for the Nordic Semiconductor nRF52840 DK, refer to the --tap flag for more information.

  3. Click OK to save and return to the Preferences menu.

  4. From Preferences, select Appearance, then Columns.

  5. Add a new entry:

    • Title: RSSI
    • Type: Custom
    • Fields: wpan.rssi

OT Sniffer Wireshark RSSI