The definitive protocol migration guide to transferring network keys, PAN IDs, and channel allocations from Home Assistant ZHA to Zigbee2MQTT seamlessly.
Why Migrate from ZHA to Zigbee2MQTT?
While ZHA (Zigbee Home Automation) offers plug-and-play simplicity inside Home Assistant, Zigbee2MQTT (Z2M) provides deeper OTA firmware updates, granular cluster attribute tuning, direct MQTT decoupling from HA core restarts, and support for over 3,200 specialized commercial devices.
Extracting Cryptographic Secrets from ZHA Database
The secret to hitless migration lies in preserving the exact IEEE coordinator address, PAN ID, Extended PAN ID, and 128-bit Network Encryption Key. Open the ZHA network settings in Home Assistant to copy these parameters, or extract them directly from the zigbee.db SQLite database using Python sqlite3 utilities.
Injecting Parameters into Zigbee2MQTT and Verifying Re-Join
Stop the ZHA integration and immediately disable the integration. Paste the captured cryptographic credentials into Zigbee2MQTT configuration.yaml under the advanced section. Start Zigbee2MQTT; as devices wake from their periodic polling intervals, they discover the identical cryptographic network identity and resume communication with zero physical re-pairing.
Technical Specifications & Engineering Matrix
| Parameter | ZHA Origin Location | Zigbee2MQTT YAML Target | Importance |
|---|---|---|---|
| Network Key | ZHA Network Configuration GUI | advanced.network_key | Critical: Must Match Exactly |
| PAN ID | ZHA Radios Settings | advanced.pan_id | Critical: 16-Bit Hex Identifier |
| Extended PAN ID | ZHA Extended Configuration | advanced.ext_pan_id | Critical: 64-Bit Network Identity |
| Channel | ZHA Radio Channel | advanced.channel | Must Match Operating Frequency |
💡 Expert Field Recommendation
Take a full snapshot backup of your Home Assistant instance immediately prior to migration so you can revert in one click if a serial port lock error occurs.
Diagnostic Troubleshooting Checklist
- Zigbee2MQTT Fails with Error: Coordinator PAN ID Mismatch: Ensure the coordinator firmware was reset or flash memory cleared; if using an existing coordinator, set the configuration to force the stored parameters.
- Battery Sensors Taking Hours to Appear: Battery sensors sleep to preserve power; either wait for their periodic check-in (up to 4 hours) or press their physical button once to wake them instantly.
- Entities Disappear from Home Assistant Dashboards: Enable the Home Assistant MQTT Discovery feature in Zigbee2MQTT settings to automatically generate identical entity IDs in Home Assistant.
Frequently Asked Questions
Can I run ZHA and Zigbee2MQTT simultaneously on one dongle?
No, a physical USB radio can only communicate with a single software host driver at a time.
Will my Zigbee groups and scenes transfer over?
Groups and scenes stored in device hardware memory transfer over, while software-based automations must have their entity references updated in Home Assistant.
Article researched, lab-tested, and verified by Marcus Vance, dedicated technical specialist and editorial contributor.