After a recent purchase of discontinued IKEA Trådfri shortcut buttons, I wanted to get a Zigbee coordinator on which Zigbee2MQTT could be installed. With that it should be possible to upgrade the firmware on a single Trådfri button. Since this would be done mostly out of curiosity, I wished to minimize the outlay of funds. Numerous sellers on Aliexpress are flogging "Wireless Zigbee CC2531 USB Interface Dongle Capture Packet Modules". These appear to be knockoffs of the CC2531EMK CC2531 USB Evaluation Module Kit at a bit more than a 10th of the price of the real thing. I purchased one of the cheap dongles, but it was not what was expected. So consider this post as a PSA if you are contemplating buying one of these USB dongles for any purpose other than sniffing Zigbee packets.

Table of Content

1. Why a CC2531 Based USB Dongle
2. Public Service Announcement about CC2531 Based USB Dongles
3. Getting the CC2531 Coordinator Firmware
4. Flashing the CC2531 with a Raspberry Pi, or Not
   1. Install WiringPi
   2. Connecting the Pi and the USB Stick
   3. Installing flash_cc2531 on the Pi
   4. Saving the CC2531 Factory Installed Firwmare
   5. Failure to Flash the Coordinator Firmware
5. What's Next?

Why a CC2531 Based USB Dongle

USB dongles with the Texas Instruments CC2531 chip are found in the Not recommended category on Zigbee2MQTT Supported Adapters. Here is the pertinent part of that document.

The outdated CC251 adapters are well supported since Zigbee2MQTT provides coordinator firmware, router firmware, and instructions for flashing the firmware. Note that its Buy link is a search for "cc2531" on Aliexpress.

What's more, Zigbee2MQTT offers a number of alternative firmware flashing methods which do not require a CC debugger. One of these requires a Raspberry Pi which I had. Following the instructions, I was able to read and write to the CC2531 flash memory. However I could not upload the coordinator firmware nor the router firmware. The next section explains why.

Public Service Announcement about CC2531 Based USB Dongles

The CC2531 system-on-chip comes in two flavours: CC2531F128 and CC2531F256. The first has 128KB of flash memory and the second, you have guessed it, comes with 256KB of flash memory. The recommended coordinator firmware is about 240KB, so it will not fit in the available flash on the CC2531F128.The problem is that most sellers of cheap CC2531 dongles do not specify the actual chip on the module. I purchased the dongle from a vendor with the following offer on AliExpress.

Like other sellers, there is no mention of the actual chip in the "detailed" description, but the product picture does show a CC2531F256. I have rarely done this, but I rated my purchase and reviewed the product. It's the third review as of the Jan. 29, 2024 and the only one with pictures.

The ethics of showing a picture that does not correspond to the product delivered is questionable even if many vendors do that. In all probability most vendors do not have the means to take decent photographs of every product in their store, but they could be more forthcoming in their descriptions. I still gave a 2-star rating because the product was delivered relatively quickly and it does enable one to sniff Zigbee packets with the help of something like WireShark. That could be of value, if you want to do that sort of thing, but I certainly don't.

The rest of this post will describe how I attempted to flash the coordinator firmware with a Raspberry Pi 1 and managed to restore the factory installed firmware after overwriting it trying to install the coordinator firmware. And therein is the second part of this PSA: do save the factory installed firmware on the CC2531's flash memory before attempting to write anything over it.

Finding the Dongle

Start to follow journal messages on the desktop and then plug in the CC2531 dongle to the desktop.

The dongle is enumerated as a USB device. Here is detailed information about it

On DEVICE HUNT 0451:16AE is identified as a Texas Instruments CC2531 Dongle, while 0451:16A8 is identified as a Texas Instruments CC2531 ZigBee. From elsewhere I did find that the two variants are out there.

In any case, the dongle is visible although it does not show up as a Linux serial device. Specific driver software is needed to talk to it.

Getting the CC2531 Firmware

No matter which method is used to program the CC2531, the desired firmware has to be obtained. There are three different types of firmware that can be uploaded to the dongle depending on what it needs to do.

• Coordinator: the dongle acts like a hub. Up to xx Zigbee devices can be paired with the dongle (xx depends on the installed firmware and version). The dongle acts as a radio transceiver between paired devices and the Zigbee2MQTT service running on the computer connected to the dongle with the USB port.
• Router: the dongle act like a repeater or bridge between xx Zigbee devices and a coordinator.
• Sniffer: the dongle exposes all Zigbee packets it receives to the device connected to its USB port. The CC2531 I purchased was sold as a sniffer and had the appropriate firmware loaded in its flash memory.

Koen Kanters, the founder of Zigbee2MQTT, makes available quite a few versions of the software for various chips. He also published the following guide when it comes to a choice of coordinator firmware for the CC2531.

In my case the choice is simple. I will download the Z-Stack_Home_1.2 default firmware for the CC2531 to the Raspberry Pi.

Only the Intel Hex file within the archive is needed.

Right there, looking at the size of the binary file, I should have realized I was in trouble, but I did not know that the flash memory of the CC2531 was limited to 131072 bytes. So let's continue to see what happened anyway.

The hex file has now been extracted.

Flashing with a Raspberry Pi

The first method proposed by Zigbee2MQTT in Alternative firmware flashing methods uses a Raspberry Pi. Having an old Raspberry Pi 1 on hand, I decided to try that method. Basically, the Zigbee2MQTT instructions amount to "use flash_cc2531" by Jean Michault.

Install WiringPi on the Raspberry Pi

Unfortunately, flash_cc2531 uses WiringPi to access the GPIO pins of the Raspberry Pi. It's unfortunate because that library is no longer included in the Raspberry Pi OS repository.

The author of WiringPi, Gordon, announced the end of public releases in August 2019. There is an unofficial fork on GitHub which was archived at the end of November 2023 because "this project is going nowhere. It has been archived to more clearly indicate this status". By the end of 2023, Gordon closed his site. At this point, I know of only one way to install the library, which is to build it from the last available source from the unofficial fork. Let's start by getting the source code and extracting it from the downloaded archive.

Compiling and installing the library is easily done.

We can test that the library is installed.

Remember, I am using a Raspbery Pi 1 with a GPIO header containing only 26 pins. The newer models have a 40-pin GPIO connector. Now that WiringPi is installed, it was time to clean up. By that I mean to keep the source archive in a downloads directory and to delete everything created just for building the library which was installed in /usr/local/lib and usr/local/include.

Connecting the Pi and the USB Stick

The following table displays the flash_cc2531 default connection between the Raspberry Pi's with 40 pin headers and the Pi and the CC2531 dongle debug header and the suggested connection between older Pi's with a 26-pin header and the debug header of the dongle.

(*) The dongle needs to be powered while it is being flashed. The easiest way to do this is to connect the dongle to a USB 5V power source. I used a free USB port on the desktop machine, but perhaps a USB port on the Pi would also work. I have read on the Web where some have used the connection shown above in the table to feed 3.3 volts to the dongle via the debug connector. Presumably, that means that a required "R2" resistor is mounted on the dongle. See page 11 of CC2531 USB Hardware User’s Guide.

The biggest problem with making these connections is the small size of the debug header. As far as I can tell, pins are 1.27 mm apart instead of the 2.54 mm breadboard standard. A special cable can be purchased (see the AliExpress vendors that sell the dongle), but I did not want to wait for that. Some solder Dupont wires directly to the header pins often bending these outward at different angles for better access. I happened to have a flat ribbon cable of the correct size with female IDC connectors at both ends purchased for use with an unusual sensor. I jury rigged the following with it.

Solid copper strands from CAT5 Ethernet cable fit perfectly into the IDC sockets. Four short lengths of that wire were inserted into the IDC connector. Very flexible silicone Dupont test clips completed the connections to the correct pins on the Raspberry Pi. It may not look very solid, but it nevertheless worked for numerous attempts at programming the dongle. Note how the pin layout of the free IDC connector is mirrored because the ribbon cable was bent back onto itself. Be careful when connecting the wires. You may want to measure continuity between the metal casing of the USB connectors of the Pi and the dongle with a VOM. Make sure nothing is powered when checking this.

Installing flash_cc2531 on the Pi

Jean Michault has written a collection of programs that can be used to read and write the flash memory of the CC231 connected with a simple USB cable to a Linux computer such as the Raspberry Pi. We only need to download the repository.

Let's extract the content of the archive which will create a directory named flash_cc253-master by default.

The files cc_chipid, cc_erase, cc_read, and cc_write are all exectable, so there is no need to build anything. Again, its not a bad idea to rename the directory created by unzip and then cleanup a bit.

To quote Jean Michault, now one can read the CC2531 ID, save, erase and write its flash memory with the following commands.

Of course if the default wiring was used, then the wPi pin parameters should not be used and the commands would simply be as follows.

In preparation for the programming step, I copied the Zigbee coordinator hex file into the flash_cc2531 directory.

Saving the CC2531 Factory Installed Firmware

I followed the instructions give above to identify the chip and to download the installed firmware.

And then; being paranoid, I did this a second time. After I peeked at the content of the saved hex files and checked that they were identical.

Of course I was still in the dark about the real size of the flash memory. In retrospect, how could cc_read report reading 256 KB from the flash memory? The saved hex file is considerably smaller than the coordinator hex file. So it was a bit surprising to find that factory_sniffer.hex contained 4 32-bit segment addresses just like CC2531ZNP-Prod.hex.

It turns out that none of these were needed.

Because the last 16-byte record was written at address 0x2190, the next record would be at 0x21A0 = 8,608. Since the trailing 0xFF bytes look like padding, the actual size of the binary file might be only 8,599 bytes in size. So a 128KB flash memory is big enough for the packet sniffing firmware. But again this is all in retrospect.

Failure to Flash the Coordinator Firmware

The device ID was unusual, b522 instead of the b524 shown in most guides. I am not too sure why that would be, but it is something I have observed with other "cloned" USB devices. In any case, it was time to upload the coordinator firmware.

That erase result was what I expected from reading others' posts. However, the session froze while writing page 1. I used CtrlC to exit. After powering the dongle off and then back on, I tried again but with a timing change.

This is an improvement. I tried different values for the time base parameter m, but could never get beyond page 65, even if the error message changed.

I started to get suspicious that precisely half of the pages had been written. Consequently, I tried writing smaller older firmware and the router firmware but I would get no further.

That's when the penny dropped. Sure enough on searching I discovered that there were two versions of the CC2531 chip one of which only has 128 KB of memory. On checking the chip on my dongle, I confirmed that this what it had. Click on the thumbnail at the right and the F 128 will be visible on the bigger image.

Just to make sure that the problem had nothing to do with the flashing software, I read back what was flashed onto the CC2531 and compared it with the original firmware saved initially.

So new firmware had been written to the flash memory. The good news is that flash_cc2531 had no problem restoring the original firmware.

What's Next?

What to do next? I see many possibilities right now.

• Follow Mat (notenoughtech)'s advice and Get CC2531 on the ITEAD store instead. I may need to flash newer firmware on it, but that's easy enough to do. Unfortunately, that dongle does not have an external antenna which might be useful for reaching Zigbee devices that are far away.
• Go back to AliExpress and try to find a vendor willing to vouch that the dongle comes with a CC2531F256 on a revision 2.4 board.
• Purchase a CC2531F256 and solder it in place of the chip on my board. Chances of success: 1%, cost of a chip about 14 $ before shipping and taxes.
• Purchase a CC2530 serial board on Aliexpress. But this one is even worse, being available with 32, 26, 128 or 256 KB of flash memory (see its datasheet and Flash CC2530).
• Purchase an ESP32-H2 or ESP32-C6 because these Risc-V microcontrollers support Zigbee natively. At this time, I have no idea which Zigbee stack would run on these boards and if they could be used to perform OTA which was the whole idea at the start of this project.
• Wait until the Tasmotized ZBBridge in place can no longer handle additional Zigbee devices slowly being added to the system. At that point getting a decent ZigBee coordinator and one or two routers might be warranted.

Time will tell.