Zigbee Sniffer

Overview

The Trident Zigbee sniffer is composed of 2 pieces, a sniffer application that runs on embedded hardware and a PC application that communicates to the embedded hardware. The hardware component is used to capture the Zigbee packets and send them over a USB interface to the PC application. The PC application supported today is Wireshark, though there is an AI powered wireless protocol sniffer coming soon from Trident IoT!

Sniffer Hardware Setup

To set up hardware that can be used to sniff Zigbee packets, all that is needed is to use elcap to create a new project for the zigbee sniffer application, build it, and flash it to the desired PCBA target. The sniffer application has been provided as a project template so that the end user can build the sniffer application for Trident development boards AND can build the application to run on custom hardware. Once the sniffer application is running on the desired hardware target, the next step is to use the files found at the [your_sniffer_app]/wireshark directory to add the sniffer capabilities into Wireshark. The Extcap extension script, trident_wireshark.py, will look for the USB PID and VID for the Trident development board to allow it to show up in Wireshark so development board must be used to detect by default. If you wish to modify this script to detect other USB targets, you are free to do so as well.

Wireshark Setup Instructions

Dependencies

1. Wireshark extension files must be gathered from the Trident sniffer project
2. Wireshark must be installed
3. Must have python 3 installed and on your PATH - verified using python 3.12
4. Pyserial needs to be installed:

   pip install pyserial 

5. psutil needs to be installed:

   pip install psutil 

EXTCAP Installation

Once the dependencies have been installed, the next step is to extend wireshark to support the Trident Zigbee sniffer. To do this, locate the "wireshark" directory found in the sniffer project created using elcap. This was covered in Sniffer Hardware Setup.

Next, copy the trident_wireshark.py file into the Wireshark Extcap path directory. This can be found by opening Wireshark and going to help->About Wireshark->Folders. As long as python is on your PATH, then this is sufficient to run the extension on MacOS and Linux. For Windows you will also need to copy the trident_wireshark.bat into the same directory. If you run into issues on MacOS then you can also copy the trident_wireshark.sh into the same directory.

Once the file(s) have been copied over, restart wireshark. Once wireshark is open, make sure the "External Capture" interface is enabled. If you have a compatible sniffer hardware device plugged in to your computer then it should appear at this point.

Summary:

1. Create zigbee sniffer application using elcap.
2. Build and flash zigbee sniffer application to desired hardware target (ex. DKNCM11C10).
3. Locate "wireshark" directory within the generated sniffer application.
4. Open wireshark and go to help->About Wireshark->Folders to discover your wireshark Global Extcap path directory.
5. Copy trident_wireshark.py into your wireshark Global Extcap path directory.
6. Copy trident_wireshark.bat for Windows into the same directory.
7. Optionally copy trident_wireshark.sh for MacOS into the same directory.
8. Make sure the script(s) are executable on your system. (ex. sudo chmod +x /path/to/trident_wireshark.py for Linux)
9. Restart Wireshark.
10. Make sure "External Capture" interfaces are visible.
11. Observe Trident Zigbee Sniffer appear in the interface list.

Usage

Starting a Capture

1. Connect your Zigbee sniffer device via USB
2. Open Wireshark
3. Select the Trident Zigbee Sniffer interface from the interface list
4. Click the gear icon next to the interface
5. Configure the channel:
   • Select the desired Zigbee channel (11-26)
6. Configure the out-of-band metadata:
   • "IEEE 802.15.4 TAP" - Standardized format with 28-byte TLV header
   • "IEEE 802.15.4 NO FCS" - Raw packets without Frame Check Sequence
   • "Custom Lua dissector" - Compact 6-byte custom header format
7. Start capture by clicking start or by highlighting all desired interfaces and clicking the blue shark fin

Wireshark Color Configuration - Optional

Wireshark allows you to create custom color profiles to highlight specific types of Zigbee network traffic. This can be particularly useful when analyzing Zigbee captures to quickly identify different types of packets and network behavior. The color filter configuration file has been provided as part of the sniffer application directory that is created using elcap.

Creating a Custom Color Profile

A Trident provided colorfilters file is in the [your_sniffer_app]/wireshark directory along with the other trident_wireshark.* files. Follow the below steps to add this colorfilters file in to your wireshark setup to add color formatting to your Zigbee capture!

Step 1: Create a New Profile in Wireshark

1. Open Wireshark
2. Go to Edit → Configuration Profiles
3. Click the "+" button to create a new profile
4. Enter a name for your profile (e.g., "trident_wireshark")
5. Click "OK"

Step 2: Locate the Profile Directory

The profile directory location varies by operating system:

• Windows:

  %APPDATA%\Wireshark\profiles\[your_profile_name]\

• Linux:

  ~/.config/wireshark/profiles/[your_profile_name]/ 

• macOS:

  ~/.config/wireshark/profiles/[your_profile_name]/ 

Step 3: Navigate to Profile Directory

Windows:

1. Press Win + R to open Run dialog
2. Type

   %APPDATA%\Wireshark\profiles 

   and press Enter
3. Open your profile folder

Linux/macOS:

1. Open Terminal
2. Navigate to:

   cd ~/.config/wireshark/profiles/[your_profile_name] 

3. Or use file manager and show hidden files

Step 4: Import Color Filters

1. Close Wireshark (important - must be closed to prevent overwriting)
2. Copy the provided colorfilters file to the profile directory
3. Replace the existing colorfilters file if one exists

Step 5: Activate Your Profile

1. Open Wireshark
2. Go to Edit → Configuration Profiles
3. Select your profile name from the list
4. Click "OK"

Step 6: Verify Color Filters

1. Open a Zigbee capture file or start a new capture
2. Go to View → Coloring Rules to verify your color filters loaded correctly
3. The imported color rules should now be visible and active

Note

If colors don't appear after importing, try restarting Wireshark completely and ensure the correct profile is selected.

Troubleshooting

ZUTH Python Version Issue

Using the sniffer alongside ZUTH can be challenging because ZUTH requires the system level python version to be set to v3.7. The Extcap extension requires a newer version of python to run so this creates a conflict. This can be resolved by using either the trident_wireshark.bat or trident_wireshark.sh scripts for Windows and MacOS respectively to set the python version to use when running the trident_wireshark.py script from within Wireshark. This is done by specifying the specific version of python to use.

For example,

exec python3.12 $(dirname "$0")/trident_wireshark.py "$@" 

Note

The trident_wireshark.sh script is already setup to do this as an example.

User Interface on the DKNCM11C10

USB-C Interface

Plugging a USB-C cable from a computer into the DKNCM11C10 will enable a COM port to appear on the computer. This can be connected used to open a connection to the sniffer app that is running on the device.

COM Port Settings
Baud	115200
Data Bits	8
Stop Bits	1
Parity	None
Flow Control	None

Buttons

Button	Action	Description
BTN0	Press	Hardware reset
BTN1	Press	None
BTN2	Press	None

LEDs

The LEDs are used to display the status of the running sniffer application. Anytime a new LED state activates, the other LEDs are turned off.

LED	Behavior	Description
Green	On solid until new LED behavior overrides	Turns on solid when sniffer starts
Red	On solid until new LED behavior overrides	Turns on solid when sniffer is in stopped state
Blue	On for 50ms	Turns on for 50ms when packet is received