ZigBee CC2531 smart home USB adapter

Use a CC2531 USB Stick as a ZigBee Concentrator to replace your Philips HUE, Osram Lightify, Xiaomi/Aqara Hub, IKEA tradfri, etc. gateway.

Public Chat
Similar projects worth following
In this project I'll show you how to flash a cheap (around 7 US$ on ali or ebay) CC2531 USB-Adpter to become a concentrator/gateway for your smart home solution.

Once you have installed the correct firmware, you can use this along with most of your favourite smart-home solutions such as iobroker, home assistant, openhab, etc. This replaces the need for a separate proprietary gateway from Philips, Osram, Ikea, Xiaomi etc. and instead gives you an all-in-one solution for a multitude of components, lights and sensors from different manufacturers.

Since I had some issues myself getting this to work I want to share my experience and a working method of flashing the CC2531 adapter without the need for a proprietary programming device.
All you need is a CC2531 USB adapter (or a CC2530 module with additional serial interface such as FTDI, CH340 or Prolific) and an arduino compatible board of your choice.

This is how I did it with an ESP8266 wemos d1 mini

The CC2531 is a complete ZigBee / IEEE 802.15.4 transceiver bundled with an 8051 CPU and an USB interface on one chip. You can get these for a few dollars from aliexpress or ebay. Since it has a programming port, you can upload/install a custom firmware which acts as a zigbee concentrator.

Once you have the correct firmware installed, you can use it to replace most if not all of your proprietary ZigBee gateways and use it to control a variety of different devices, such as lamps, temperature sensors, switches, etc.

Depending on your home automation system, you can either use the stick directly with an appropriate adapter or have it plugged into a raspberry pi (or orange pi, etc. ) and use it as remote ZigBee to MQTT gateway which can be placed in a suitable location in order to get a better range.

Once you have your stick up and running, see also my other project on how to add an antenna socket for increased range: CC2531 USB Adapter Antenna mod

[2019-01-29] update: new Z-Stack-Firmware with group support and increased stability from Kkoenk available:


Modified Arduino Sketch for the Wemos D1 mini with modified pins and increased delay() time (See instructions for more details)

x-arduino - 7.60 kB - 01/20/2019 at 19:05



Modified Firmware for use with the CCLib_proxy. You do not have to remove the second line from the bottom! This is the same file I flashed on my other adapter

hex - 680.74 kB - 01/19/2019 at 21:08



The firmware I used to flash one of my adapters

hex - 665.61 kB - 01/19/2019 at 21:08


  • 1
    get required software

    I assume you are familiar with the Arduino IDE and have it installed on your PC.

    Download CCLib from

    This is the firmware for your custom, ESP8266 based programmer

    Download CC2531 Firmware

    You can use either


    On Linux, you can simply download it by typing


    I installed and verified both versions to be working. Hence I have attached them to this project.

    If you download the CC2531ZNP-Prod.hex from here ( you do not have to modify the file!

    Important note: 

    When using the arduino based CCLib_proxy debugger/programmer as described here, the custom firmware ( from Koen Kanters, has to be modified. Otherwise you will not be able to flash it!

    The modification is really simple: 

    Unzip the archive and open the .hex file in a text editor of your choice.

    Scroll to the very bottom of the file and remove the second line from the bottom. In the .hex file above, the according line is


     Just save the file and you are good to go.

    You will also need Python 2.7 or later installed to your system.

    Once you've downloaded/unzipped CCLib, open a terminal and change directory into the Python folder

    cd CCLib/Python/

    Now, install the required python modules by typing:

     pip install -r requirements.txt 
  • 2
    Prepare your wemos d1 mini board

    Install the Arduino/CCLib library to your arduino IDE

    Open the CCLib_proxy.ino from CCLib/Arduino/CCLib/Examples/CCLib_proxy

    I have uploaded my modified version  of the arduino sketch to
    If you have downloaded the CCLib_proxy.ino  linked above you can skip the following code modification.

    Modify the code:

    Specify the correct Pins for the ESP8266 / Wemos D1 mini

    This is important, since it makes a big difference which Pins you use! I was not able to make the programmer work when I initially used other pins. After more than an hour experimenting I found this configuration to be working flawlessly out of the box.

    See approx. line 37

    // Pinout configuration (Configured for wemos D1 mini)
    int CC_RST   = D5;
    int CC_DC    = D7;
    int CC_DD_I  = D6;
    int CC_DD_O  = D4; 

    Then, look for the first delay()  at approx. line 98 and increase the initial value (50) to 1000:

    Again. this is needed for the ESP8266 / wemos d1 mini / nodeMCU to get it working

    at approx. line 98:

      // Wait for chip to initialize

    When using an arduino uno/nano/... you probably don't have to change the delay.

    Once you have modified the code, compile and upload it.

  • 3
    Connect your CC2531 Adapter

    Once you've compiled and  uploaded the CCLib_proxy to your wemos d1 mini board, unplug it from the USB bus.

    Now, get some (actually 5) jumper wires and connect your ESP board to the debug port of your CC2531 adapter. Since  the ESP uses 3.3v, you don't need a voltage divider!

    Please note:

    In contrast to your common breadboard / connector, the debug port on the CC2531 has a smaller spacing of 1mm. In order to connect your wires, you can either use the linked Debugger Cable or carefully connect your SMD probes to the tiny pins. I've seen a couple of people destroy their debug port / breaking pins by handling it too rough. These small pins are really pretty fragile! So take care when not using the small spaced connector cable.

    Note, that on the wemos/ESP side, D6 ( DD_I ) and D4 ( DD_O ) are connected together and go to Pin 4 ( DD / Debug Data ) on the CC2531 debug port.

    You only need to connect these four Pins on the CC2531:

    1 - GND

    3 - DC (Debug Clock)

    4 - DD (Debug Data)

    7 - Reset 

    If the stick lies in front of you, the USB-Port facing to the left, Pin 1 is the one on the top right of the 10 Pin programming header.

View all 6 instructions

Enjoy this project?



nico.wasserman wrote 12/20/2020 at 15:51 point

can i do this with a raspberry pi 4b 8gb as well?

  Are you sure? yes | no

marc wrote 09/11/2019 at 12:54 point

Wiring for Programming -

Would programming via a Esp8266 (or any other device with SPI pins) work with a wiring as shown on the linked image?

  Are you sure? yes | no

Vijay wrote 08/01/2019 at 21:37 point

I know there hasn't been many comments here but I didn't know where else to ask for help. I followed the instructions and everything seemed to be working but the information I gotten from the CC2531 was different to everyone else's. Is this likely a faulty unit or is there something I'm missing? I am using a nodemcu 8266 board.

C:\CCLib-master\Python>python -E -p com16

INFO: Found a CC2531 chip on com16

Chip information:
Chip ID : 0xb524
Flash size : 16 Kb
Page size : 2 Kb
SRAM size : 1 Kb
USB : No

Device information:
IEEE Address : 000000000000
PC : 0000

Debug status:

Debug config:

  Are you sure? yes | no

hubert wrote 02/08/2019 at 10:27 point

Ok, it works with CCLib from

  Are you sure? yes | no

hubert wrote 02/08/2019 at 10:05 point

Hi, i've followed your instruction.

I'm facing this problem when flashing :

./ -i ./CC2531ZNP-Pro-Secure_LinkKeyJoin_mod.hex -p /dev/ttyUSB0 -e
INFO: Found a CC2531 chip on /dev/ttyUSB0

Chip information:
      Chip ID : 0xb524
   Flash size : 256 Kb
    Page size : 2 Kb
    SRAM size : 8 Kb
          USB : Yes
Sections in ./CC2531ZNP-Pro-Secure_LinkKeyJoin_mod.hex:

 Addr.    Size
-------- -------------
 0x0000   8176 B
 0x1ff6   10 B
 0x3fff0   1 B
 0x2000   239616 B

This is going to ERASE and REPROGRAM the chip. Are you sure? <y/N>:  y

 - Chip erase...
 - Flashing 4 memory blocks...
 -> 0x0000 : 8176 bytes
    Progress 100%... OK
 -> 0x1ff6 : 10 bytes
    Progress 0%...  ERROR: Flash verification error on offset 0x1ff6
 -> 0x3fff0 : 1 bytes
    Progress 0%...  ERROR: Flash verification error on offset 0x3fff0
 -> 0x2000 : 239616 bytes
    Progress 100%... OK


I've removed the sys.exit() to continue flashing even there's an exception...

  Are you sure? yes | no

data wrote 02/11/2019 at 18:57 point

What errors did you get before?

  Are you sure? yes | no

Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates