[Guide] Build a Zigbee CC2531 Sniffer & How to Use it

[jchurch]

The following process explains how to build your very own Zigbee CC2531 sniffer. Sniffing Zigbee traffic can be useful at times when you want to analyse the commands used by a device. Example you have Tuya device and you want to sniff the unique traffic when it talks back to the Tuya gateway as to help build drivers OR you have a ZigBee device or mesh issues and your trying to determine what is wrong.

Hardware Prerequisites

• Windows PC
• CC2531 with antenna
• CC debugger (note the kit above comes with the CC debugger as well)

1. Flashing the CC2531 stick

1. To flash the CC2531 stick it must be flashed with the sniffer firmware. Download the Zboss Sniffer firmware hex for the CC2531 USB dongle here. (note the software is free but you will need an account on their website to get access to the firmware etc also some people have found their activation email has taken some time to arrive but be patient). Save this file somewhere on your Windows PC.

2. Download and install the SmartRF Flash Programmer utility (DO NOT USE THE V2 VERSION) from here. This software is free but requires a Texas Instruments account in order to download. Once completed install the software to your Windows PC. You may also need the CC debugger driver for your Windows PC located here. Before continuing, verify that the CC Debugger driver has been installed correctly.

3. Connect your CC debugger to your CC2531 stick as per the below picture.
   

   

4. Plug the CC debugger and CC2531 stick into your Windows PC USB ports (yes both must be powered for this to work) and run the SmartRF Flash Programmer utility. If the light on the CC Debugger is RED press the reset button on the CC debugger. The light on the CC debugger should turn GREEN. In the flash image section locate your zboss_sniffer.hex firmware file and configure SmartRF Flash programmer utility like the below example picture. (note if you have issues flashing try changing the interface to slow from default fast)
   

   

5. Your CC2531 stick is now flashed with the zboss_sniffer.hex firmware. You can now unplug everything from your Windows PC and put your CC debugger away as you no longer require it.

2. Installing and configuring the Sniffing software and Sniff Zigbee Traffic

1. Download and install Wireshark from here.

2. Download and install the Zboss sniffer Windows PC software from here. (Note at this stage you should already have an account on their website to access the download file). Zboss sniffer is a portable Windows PC software so just copy it somewhere like C:\zboss so you’ll run the GUI from C:\zboss\gui\zboss_sniffer.exe. When you run the GUI it should look like the below. Also for Zboss GUI make sure the correct Zigbee channel is set to your zigbee mesh channel (mine is 20).
   

3. Now plug in your CC2531 stick into your Windows PC USB port. (note it should come up as a COM port on your PC if it was flashed correctly)

4. Click on start in the Zboss sniffer GUI it will auto open Wireshark. Wireshark will then start to log the Zigbee messages, however as these messages are encrypted you will be required to add 2 encryption keys into Wireshark to decipher them:

• The first is the Trust Center link key, which is the same for (almost) every Zigbee network. Add the Trust Center link key into Wireshark by Edit → Preferences → Protocols → ZigBee. Set Security Level to AES-128 Encryption, 32-bit Integrity Protection and click on Edit. Click on + and add 5a6967426565416c6c69616e63653039 with Byte Order Normal.
  

• The second is the network encryption key (Transport Key). There is two ways this can be achieved. The network encryption key is exposed when a device joins the network. Pair a new Zigbee device to your network (or re-pair an existing one) and grab the message where the Info is Device Announcement….. Open the message and expand ZigBee Network Layer Data → ZigBee Security Header.
  

  
  
  Copy the key value, as shown above and go to Edit → Preferences → Protocols → ZigBee → Edit and add the key with Byte Order Normal.
  Now Wireshark is able to decrypt the messages. When e.g. turning on a light you will see a message similar to:
  
  

• The third and fourth for things like Hue bridge as they use a different Trust Center link key you will need to copy into Wireshark by Edit → Preferences → Protocols → ZigBee. Set Security Level to AES-128 Encryption, 32-bit Integrity Protection and click on Edit. Click on + and add 814286865DC1C8B2C8CBC52E5D65D1B8 with Byte Order Normal and call that light link commissioning key and also add ‘9F5595F10257C8A469CBF42BC93FEE31’ and call that ZLL Master Key.

• Once all your keys are added into Wireshark it should look something like this.
  

5. You are all finished enjoy

[LosinIt]

@jchurch, this is the type of stuff my inquiring mind just loves to know. Too bad it’s Windows and not Linux.

[jchurch]

@LosinIt

this is the type of stuff my inquiring mind just loves to know. Too bad it’s Windows and not Linux.

You can do this on Linux but I have documented it for Windows. However we would welcome a similar guide if you would like to put one together

[Cjkeenan]

Very interesting read, how does this method compare to using a XBee? Same recipe different ingredients or do they each have their use case?

[jchurch]

@Cjkeenan

Very interesting read, how does this method compare to using a XBee? Same recipe different ingredients or do they each have their use case?

I believe the Xbee can be used as a router or endpoint including network mapping when in router mode however as I understand it cannot be used to sniff zigbee traffic to decipher unique messages etc to be used in fault resolution or the building of drivers.

[markus]

@jchurch

I believe the Xbee can be used as a router or endpoint including network mapping when in router mode

This is correct, Xbees don’t have a firmware which allows promiscuous mode. Xbees are more for diagnosing routing and mesh issues and also functions very well as repeaters. They can also be used for developing your own Zigbee devices.
The CC2531 can be programmed with many different types of firmwares, such as the one mentioned here. Depending on the firmware they can be used for different things. By itself the CC2531 makes for a poor repeater since the transmit power is limited, for sniffing traffic this is of no importance. As @jchurch mentions, the traffic captured can then be analyzed in order to understand how a device functions. It can also be used to see exactly what is going on in a mesh and for example help in troubleshooting why a device drops of a mesh.

[roberto]

Great. I still have the 2531 stick. ordered the other stuff. It will take a while but at end I’ll recall how to!
Thank you!!!

[april.brandt]

Just got my boards today. I’m up and running. Excited put it to work.

[alexandruy2k]

Can the CC2531 be used to build a network map or is it just used to sniff packets?

I’ve moved from smartthings to hubitat and I’m missing the route that devices use to communicate to the hub. Smartthings shows in the online IDE the path that a devices uses to communicate with the hub. It’s not a full map, but the bare minimum in my opinion to see if a sleepy device communicates to the hub using a bad repeater such as a light bulb for example.

So I’m wondering if I can use the CC2531 or do I need to buy an Xbee

Thank you

[LosinIt]

I’m pretty sure you’ll need an Xbee. Sure enough that mine will be here Tuesday.

[jchurch]

Correct you will need an Xbee for building network maps the sniffer is purely for sniffing zigbee traffic only,

[alexandruy2k]

Thanks, looks like I’ll be buying both
I had bought the cheaper CC2531 based on information on a different forum that suggested that the CC2531 might be able to show the route information just not as easy to digest as the XCTU network diagram

[LosinIt]

@jchurch

Download the Zboss Sniffer firmware hex for the CC2531 USB dongle

@jchurch

Download and install the SmartRF Flash Programmer utility

Shame on me for not completing this setup back when I bought the hardware because now we can’t download these packages without a “professional” email address.

And to make matters more annoying neither of these sites tell you about needing a “professional” email address until you’ve already given up your name and whatever email address you tried to use.

[Subn0iz3]

What qualifies as a “professional” email address? Just can’t be a typical free provider like Gmail etc? I’m sure there’s a handful of folks here that own domains and use them for email

[LosinIt]

@Subn0iz3

“professional” email address

They don’t say exactly but I assume it has to be on a list of businesses/universities/orgs/gov that they approve of.

I have just found this page and I have cc-tool installed and my CC2531 flashed.

Sniff Zigbee traffic | Zigbee2MQTT

Now I’m trying to find ZBOSS Sniffer for Linux…

EDIT: ZBOSS Sniffer is needed on Winx. The (apparently) equivalent Linux package is whsniff according to the link above

EDIT2: The whsniff tool is broken and hangs before capturing any packets. This issue was noted Sept. '21 and has not been addressed. I added my $0.02, hoping it might prompt the author to have a look.

[Rxich]

Just ordered one of these based on EFR32MG21, the Aliex link for firmware is dead-404 error, but found it through searching(UNtested by me)

GitHub

GITHUB - XSP1989/ZIGBEEFIRMWARE

Contribute to xsp1989/zigbeeFirmware development by creating an account on GitHub.

aliexpress.com

10.28US $ 40% OFF|ZIGBEE 3.0 ZB-GW04 USB DONGLE WIRELESS ZIGBEE GATEWAY…

Smarter Shopping, Better Living! Aliexpress.com