Solvedzigbee2mqtt Instruction - how to migrate from CC2531 to another (better) Zigbee dongle

Bug Report

Please, write Instructions/documentation on, how to migrate from CC2531 to another (better) dongle

What happened

I am planning make upgrade from CC2531 (source routing) to CC2652RB stick with 23 Zigbeee devices and i am finding the best Solution how to perform without nerve loss

What did you expect to happen

I expect help, what all i need change in section "advanced" - configuration. yaml
Now i have:
advanced: pan_id: 6754 channel: 11 network_key: - 1 - 3 - 5 - 7 - 9 - 11 - 13 - 15 - 0 - 2 - 4 - 6 - 8 - 10 - 12 - 13

How to reproduce it (minimal and precise)

I know, pan_id have to change, but is only possible example from 6754 to 6760? And is better change the network_key (due to a Wifi 2.4Ghz) collision/interference)? Or if is some Solution like Cloning Coordinator from old to new without new Pairing devices?
Thank you

Debug Info

Zigbee2MQTT version: 1.14.13
Adapter hardware: CC2531
Adapter firmware version: last

59 Answers

✔️Accepted Answer

Hi there,

Just received my zzh and it works perfectly well !
It took me around 2 hours to update it and repair my 50 devices... it's quite easy as the device configuration is kept and the pairing with the zzh is incredibly fast and stable.

Here is a step by step procedure to update an existing configuration with CC2531 adapter to zzh (CC26X2R1) adapter if it can helps.

Here is my configuration prior the update :

  • Raspberrypi 3B+ with raspbian stretch
  • zigbee2mqtt already configured with a CC2531 adapter and source routing firmware (Zigbee 1.2)

PART 1. Flash the zzh (CC26X2R1)

Note : your zzh stick might not be on the same port (eg, /dev/ttyACM0 for CC2531 and /dev/USB0 for zzh). use following command to know your configuration

pi@raspberry:/ $ ls -l /dev/serial/by-id

  • Download and unzip the Z-Stack firmware for your coordinator
    wget && unzip

Note : this link is for the current firmware (2020-08-05), check firmware version on following page :

Now, you should have a file named CC26X2R1_20200805.hex

  • Flash your coordinator with this firmware
    ./ -p /dev/ttyUSB0 -evw CC26X2R1_20200805.hex

You should see something like that :
pi@raspberrypi:~/cc2538-bsl-master $ ./ -p /dev/ttyUSB0 -evw CC26X2R1_20200805.hex Opening port /dev/ttyUSB0, baud 500000 Reading data from CC26X2R1_20200805.hex Your firmware looks like an Intel Hex file Connecting to target... CC1350 PG2.0 (7x7mm): 352KB Flash, 20KB SRAM, CCFG.BL_CONFIG at 0x00057FD8 Primary IEEE Address: xxxxx Performing mass erase Erasing all main bank flash sectors Erase done Writing 360448 bytes starting at address 0x00000000 Write 104 bytes at 0x00057F980 Write done Verifying by comparing CRC32 calculations. Verified (match: 0x1aded532)

Note : I had to try many times to have a correct flash. In case of wrong flash, then you might have following error message while launching zigbee2mqtt
Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms)

Now your coordinator is ready. The LED should be turned off (seems normal).

PART 2. Update Zigbee2mqtt configuration

  • Ensure that you have the latest version of zigbee2mqtt (for update, see :

  • Go to the zigbee2mqtt folder
    cd /opt/zigbee2mqtt/

  • Backup your data folder in case of issue
    cp -R data data-backup

  • Remove you data/database.db file
    rm data/database.db

  • Edit your configuration file (eg.
    vi data/configuration.yaml

  • under section serial : If needed, update your Serial (eg. Port : /dev/ttyUSB0)

  • under section advanced: (to create is not present), add or edit pan_id to 0x1a63 (or higher if you already update it)

  • OPTIONAL : As you'll have to repair all devices, if not already done, you can add more security by adding a network key. Always under section advanced, add : network_key: GENERATE

  • Set the permit_join to true

  • Save your configuration file

PART 3. Validation and new pairing

  • Start zigbee2mqtt
    systemctl stop zigbee2mqtt
  • You should see that you have currently 0 devices joined (as we deletes database.db file)
  • For each device you have, follow the pairing procedure. You only have to pair the device, then the friendly name and all associated parameters will be automatically recovered (configuration.yalm wasn't removed).

Note : If you have groups. repairs all device from the group and simply restart zigbee2mqtt for have them working again.

Let me know if you have any question. And thanks for your advices @Koenkk

Other Answers:

You're all going to hate me, but with 60+ zigbee devices I did not feel like repairing them all! And neither do you have to...

Below I migrated a CC2521 to a zzh (CC2652R) without repairing/re-adding devices:

  1. Follow the instructions here:
  2. Shutdown z2m.
  3. Plug in both old and new adapters
  4. Run the following commands:
python3 -m /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018E1F3C2-if00 -o network_backup.json

python3 -m /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0 -i network_backup.json

(or replace Texas_Instruments_TI and usb-1a86_USB with your old and new devices, found by doing sudo ls /dev/serial/by-id) took me 30 seconds to switch from old stick to new stick.

The FAQ about "what requires repairing" is now officially out of date ;)

why does the panid/epanid have to change and what happens if it doesn't?

Zigbee2MQTT will probably refuse to start (the error message indicates that you have to change the panid).

Does anyone know the best procedure to repair all devices ? Do I need to first remove all devices (using CC2531 and command zigbee2mqtt/bridge/config/remove), then install the zzh and pair again the devices ? Or is there any faster solution ?

Remove data/databse.db and change the panid in configuration.yaml.

And last question :-) I’m using the source firmware with my CC2531. I only see one firmware for the zzh. How this firmware works compared to the standard or sources firmwares of the CC2531 ?

CC2652R firmware is a source routing firmware.

Whats the technical reason why repairing is needed?

  • The data inside the adapter is incompatible between CC2531 and CC2652R
  • Since CC2652R firmware is Zigbee 3.0, it has additional security requirements. One of them is a persistent key which is only shared during pairing (which we don't have with the 1.2 CC2531).

Also can I keep the friendly names in configuration.yaml?

Yes, to resart remove data/databse.db and change the panid in configuration.yaml.

I can also confirm successful restore using zigpy_znp method. Everything gets exported to JSON and imported to new stick's memory.

@remedix this is not needed anymore, starting from z2m 1.21.0 you can just replug as explained in the FAQ: