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

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

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

  • 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 DataZigBee 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.
    image

  1. You are all finished enjoy :slight_smile:
7 Likes

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

1 Like

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 :slight_smile:

3 Likes

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.

2 Likes

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.

3 Likes

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

1 Like

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

2 Likes

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

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

2 Likes

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

2 Likes

Thanks, looks like I’ll be buying both :slight_smile:
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

1 Like