How I setup Wireshark to capture Zigbee messages

I would like to thank @MikeMaxell for his generous help as well as a number of other websites providing numerous pieces of this puzzle.

How I setup Wireshark to capture Zigbee messages:

Wireshark

Software:
TI Packet Sniffer v2.18.0 contains the cebal driver and will read the dongle with no setup. Use this to verify your dongle is functional
TI Wireshark Packet Converter v1.11.7 Reads the cebal connected dongle and creates a "piped" stream that Wireshark can input (in real time, no save to file etc)
Wireshark v4.4.3

Hardware:
CC25xx (actually CC2531) USB Dongle Rev 1.0
I purchased mine from HiLetgo. It was received with the TI dongle hex already programmed in. Had it not I would have had to flash it with the TI dongle hex (can be found on the TI website). Note here: to gain access to the TI files you will have to create a TI account. There is no cost and only took me a few minutes.

-- TI Packet Sniffer configuration:

  1. install the TI Packet sniffer.
  2. plug the dongle into a USB port. It should create a "Cebal controlled devices" in MS Device Manager. With an entry "CC2531 USB dongle".
  3. Run the packet sniffer. Set the message bar option to "Zigbee 2007/PRO"
  4. Click the "run" icon (5th from the left). You should see some "Dest. PAN" id's the match one of you Zigbee devices.

If this works then you know your dongle is connected and able to read Zigbee packets.
We don't continue with this Packet sniffer because it cannot decode the packets, so you will not be able to make sense from the "sniffed" data. Hence the use of Wireshark.

-- Wireshark Configuration.
First, I will say I have Wireshark configured enough I can read and decode Zigbee messages from the TI Dongle. However, I am sure my configuration is not ideal in any sense. If users find my configure is lacking settings or not setting some parameter at optimum please suggest an alternate.

BOTH TiWsPc and Wireshark are run in the administrator mode.

Now we will configure the TiWcPc. Using the menu bar icons:
-- File/ no options to set
-- Data/ no configuration settings, Use the Data/ to find and start the pipe running
-- Options/Device Config Set you Zigbee channel here
-- Options/Pipe Configuration/Link Layer Name = LINKTYPE_IEEE802_15_4
-- Options/Pipe Configuration/ set "Leave Pipe Open"

The TiWcPc packet converter function is to "read" the dongle messages and send them through a data "pipe". Wireshark is capable of attaching to this pipe and reading the data.
Running the TiWcPc is a bit of a PIA as you need to:

  • Open TiWcPc and "Start All" BEFORE Wireshark is opened.
  • Whenever you stop Wireshark you will have to restart TiWcPc then Wireshark.

Configure Wireshark: This is where there are likely more refined configurations however these work for me.

-- Edit/Preferences/Capture Set "Capture Packets in promiscuous mode" & "Update list of packets in real time", set pipe input (see screenshot)
-- Edit/Capture/Options/Input/Manage Interfaces (in bottom right)/Pipes/ add local file path = "\.\pipe\tiwcpc_data"
-- Edit/Capture/Options/Input/Manage Interfaces (in bottom right)/Pipes/ should now show "\.\pipe\tiwcpc_data" should now show

-- Analyze/Enable Protocols = set all the protocols with "Zigbee" in the description.
-- Statistics/Conversations = set IEEE802.15.4 and Zigbee
-- Statistics/Endpoints = set IEEE802.15.4, IPv4 is set by default, TCP, UDP, Zigbee. Likely not all of these are needed but it will get you started.

-- whew!

Now there is one last thing we have to do to get data to be decrypted.
There are two "keys" required for description:

  1. the "Trusted Network Key" that is common to most all Zigbee networks. For Hubitat that key is; 5A6967426565416C6C69616E63653039
  2. the "Transport Key" This is unique to each installation (hub). To obtain that takes a few step.

Install the above Trusted Network Key:
-- Edit/preferences/protocol/Zigbee enter the above Trusted network key. Press OK to complete the action.

You can capture Zigbee messages to and from your hub, however they will not be decoded/decrypted. Fortunately the initial communication of the Transport Key to a joining device is no encrypted (couldn't be else you couldn't capture it).

To get the "Transport Key" you must start capturing messages by:
-- Start (as admin) TiWxPC and "start" the pipe stream by pressing "Start all"
-- Start Wireshark (as admin). Wireshark will start capturing messages. Become familiar with the messages, you will see the network ID of different devices both when they are receiving or sending. Trigger a working device and see the resulting messages.
Once you feel at least a little comfortable with the captured messages we can capture the "Transport Key"

-- While Wireshark is running, you will have to join a Zigbee device. During the join, the hub will send the "Transport Key" without encryption. It can be read in the details of a message "Transport Key". Copy that key and add it as a 2nd line in:
-- Edit/preferences/protocol/Zigbee enter the above "Transport Key". Press OK to complete the action.

You should now be able to capture messages and have their contents decrypted for you to read.

Good luck
JohnRob

PS When going through the process of getting the above working I made many side trips, adding other software. I haven't been able to test this procedure on a "clean" machine so there may be some holes it this procedure I am unaware of.

Pref Protocol IEEE802.15.4 settings

Trusted network Key entry

7 Likes

Thanks for the detailed writeup!

And if you tire of the naked look, this case works great.

3 Likes