Uno de los puntos débiles habituales en instalaciones de Home Assistant con Zigbee2MQTT es la ubicación física del coordinador Zigbee. Cuando usamos un dongle USB conectado directamente al servidor, dependemos de que el servidor esté en una zona adecuada para la cobertura Zigbee y, además, podemos sufrir interferencias por USB 3.0, mala ubicación del equipo, reinicios del host o problemas al mover Home Assistant entre máquinas.
Para resolver este problema, he cambiado el coordinador Zigbee USB de Sonoff por un Sonoff Dongle-M, un coordinador Zigbee/Thread que puede funcionar por Ethernet, WiFi o USB, alimentarse por PoE y conectarse a Zigbee2MQTT por TCP. El modelo Dongle-M aparece documentado por Zigbee2MQTT como un adaptador basado en EFR32MG24, con consola web integrada y posibilidad de conexión por Ethernet/WiFi/USB.
La idea es muy interesante: el coordinador Zigbee deja de estar atado físicamente al servidor de Home Assistant y puede colocarse en una zona más adecuada de la vivienda, alimentado por red y PoE.
El objetivo de este manual es documentar el cambio desde un dongle Sonoff USB a un Sonoff Dongle-M por TCP, manteniendo los dispositivos existentes en Zigbee2MQTT y evitando tener que reemparejar toda la red.
Tabla de contenidos
Objetivo de la migración
El objetivo es sustituir un coordinador Zigbee USB conectado directamente al servidor por un coordinador Zigbee conectado por red.
En mi caso, el cambio ha sido:
Coordinador antiguo:
Sonoff Zigbee USB DongleCoordinador nuevo:
Sonoff Dongle-M por TCP/PoE
Con esto se consigue:
- Mejor ubicación física del coordinador Zigbee.
- Menos dependencia del puerto USB del servidor.
- Posibilidad de alimentar el coordinador por PoE.
- Menos problemas si Home Assistant se mueve de máquina.
- Conexión por TCP mediante la red local.
Zigbee2MQTT permite usar adaptadores por red mediante una ruta de tipo tcp://IP:PUERTO. En su documentación indica expresamente que, para adaptadores Ethernet, el formato puede ser tcp://192.168.1.12:6638 y recomienda asignar IP estática al adaptador.
Antes de empezar
Antes de cambiar nada, es fundamental entender una cosa: los dispositivos Zigbee están asociados a una red Zigbee concreta. Esa red depende de varios datos importantes:
- IEEE address del coordinador.
- PAN ID.
- Extended PAN ID.
- Network key.
- Canal Zigbee.
- Base de datos de Zigbee2MQTT.
Si alguno de esos datos cambia incorrectamente, Zigbee2MQTT puede arrancar como si fuera una red nueva y los dispositivos dejarán de aparecer o dejarán de responder.
Zigbee2MQTT advierte que cambiar la network_key obliga a reemparejar todos los dispositivos, y que cambiar el canal puede requerir reemparejar algunos dispositivos si no soportan bien el cambio.
Por eso, antes de empezar:
- No borres database.db.
- No borres configuration.yaml.
- No cambies network_key.
- No cambies pan_id.
- No cambies ext_pan_id.
- No cambies el canal Zigbee si no es necesario.
- Haz copia de seguridad antes de tocar nada.
Paso 1: comprobar la IEEE del coordinador antiguo
Para que la migración sea limpia, el nuevo coordinador debe usar la misma IEEE address que el coordinador antiguo.
Zigbee2MQTT documenta que, al migrar de un coordinador a otro, es importante que el nuevo use la misma IEEE address, porque algunos dispositivos buscan al coordinador por esa dirección. También indica que se puede consultar desde el frontend de Zigbee2MQTT o en la primera línea de database.db.
Podemos verla desde el frontend de Zigbee2MQTT:
Zigbee2MQTT → Settings → About → Coordinator IEEE Address
O desde terminal, revisando el archivo database.db:
head -n 1 database.db
La salida será parecida a esta:
{"id":1,"type":"Coordinator","ieeeAddr":"0x00124b000e89686d","nwkAddr":0}
La dirección importante es esta:
0x00124b000e89686d
Esa es la IEEE del coordinador antiguo.
Paso 2: copiar la IEEE al Dongle-M
El siguiente paso es entrar en la interfaz web del Dongle-M y copiar la IEEE del coordinador antiguo al nuevo.
En mi caso, el Dongle-M se puede administrar desde su propia interfaz web. Dependiendo de la red, puede aparecer como:
http://Dongle-M.local
o directamente mediante su dirección IP:
http://192.168.1.X
Desde la interfaz del Dongle-M hay que localizar la opción de configuración Zigbee/Zigbee2MQTT/ZHA y cambiar la IEEE address por la del coordinador antiguo.
El objetivo es que el Dongle-M tenga la misma IEEE que tenía el dongle USB anterior.
Esto es muy importante. Si el Dongle-M arranca con una IEEE distinta, Zigbee2MQTT puede funcionar, pero los dispositivos pueden interpretar que están ante otro coordinador.
Paso 3: hacer copia completa de Zigbee2MQTT
Antes de modificar nada, hay que parar Zigbee2MQTT.
Desde Home Assistant:
Ajustes → Complementos → Zigbee2MQTT → Detener
Después hay que localizar la carpeta de configuración de Zigbee2MQTT.
Según la instalación, puede estar en una ruta parecida a:
/homeassistant/zigbee2mqtt
o:
/config/zigbee2mqtt
o en instalaciones recientes del add-on:
/addon_configs/45df7312_zigbee2mqtt
Desde terminal podemos localizarla así:
find /config /homeassistant /addon_configs -name database.db -o -name configuration.yaml -o -name coordinator_backup.json 2>/dev/null
Una vez localizada la carpeta correcta, hacemos una copia completa:
cd /addon_configs/45df7312_zigbee2mqtttar czvf /config/zigbee2mqtt-backup-antes-dongle-m-$(date +%F-%H%M).tar.gz .
Los archivos más importantes son:
configuration.yaml
database.db
coordinator_backup.json
devices.yaml
groups.yaml
state.json
El archivo más crítico para conservar dispositivos y nombres es:
database.db
Paso 4: configurar el Dongle-M con IP fija
Antes de tocar Zigbee2MQTT, conviene dejar el Dongle-M con IP fija.
Esto puede hacerse de dos formas:
- Reserva DHCP en el router/controlador de red.
- IP fija configurada en el propio Dongle-M.
Personalmente prefiero reserva DHCP en el router o controlador, porque centraliza la configuración de red y evita conflictos.
Ejemplo:
Dongle-M
IP: 192.168.1.50
Puerto TCP: 6638
La ruta TCP quedaría así:
tcp://192.168.1.50:6638
También se puede usar el nombre mDNS:
tcp://Dongle-M.local:6638
Pero para una instalación estable prefiero usar IP fija. Zigbee2MQTT recomienda que los adaptadores de red tengan IP estática.
Paso 5: cambiar la configuración en configuration.yaml
Con Zigbee2MQTT parado, editamos el archivo:
nano configuration.yaml
La configuración antigua podía ser algo parecido a esto:
serial:
port: /dev/serial/by-id/usb-SONOFF_Zigbee_3.0_USB_Dongle_Plus_xxxxx
adapter: zstack
o, según el modelo de dongle USB:
serial:
port: /dev/serial/by-id/usb-SONOFF_Zigbee_3.0_USB_Dongle_Plus_xxxxx
adapter: ember
Para el Sonoff Dongle-M por TCP, la configuración debe quedar de este estilo:
serial:
port: tcp://192.168.1.50:6638
adapter: ember
baudrate: 115200
rtscts: false
También se puede usar:
serial:
port: tcp://Dongle-M.local:6638
adapter: ember
baudrate: 115200
rtscts: false
La propia documentación de Sonoff para Dongle-M muestra una configuración de ejemplo con:
port: tcp://Dongle-M.local:6638
baudrate: 115200
adapter: ember
rtscts: false
Y Zigbee2MQTT documenta ember como uno de los tipos válidos de adaptador, junto con zstack, deconz, zigate y zboss.
Paso 6: cambiar también la configuración del add-on en Home Assistant
Este ha sido el punto clave de la migración.
No basta con cambiar únicamente el archivo:
configuration.yaml
En mi caso, también ha sido necesario cambiar la configuración del propio add-on de Zigbee2MQTT dentro de Home Assistant.
Si solo se cambia en un sitio, Home Assistant/Zigbee2MQTT puede seguir usando parte de la configuración anterior o interpretar el coordinador como un dispositivo nuevo. El resultado puede ser que los dispositivos desaparezcan o que parezca que se ha creado una red Zigbee nueva.
Por tanto, hay que revisar también:
Home Assistant → Ajustes → Complementos → Zigbee2MQTT → Configuración
Y en la sección correspondiente al puerto/adaptador serie hay que poner los mismos datos:
serial:
port: tcp://192.168.1.50:6638
adapter: ember
baudrate: 115200
rtscts: false
Este punto es especialmente importante.
La regla práctica es:
La configuración del archivo configuration.yaml
y la configuración del add-on en Home Assistant
deben apuntar al mismo coordinador.
En mi caso, hasta que no cambié ambas configuraciones, Zigbee2MQTT no conservó correctamente todos los dispositivos.
Paso 7: revisar coordinator_backup.json
Si se cambia de un coordinador de tipo zstack a uno de tipo ember, puede aparecer un error como este:
Error: [BACKUP] Current backup file is not for EmberZNet stack.
En ese caso, Zigbee2MQTT está intentando usar un backup de coordinador que no corresponde al stack del nuevo adaptador.
La solución prudente no es borrar directamente el archivo, sino renombrarlo:
mv coordinator_backup.json coordinator_backup.json.antiguo
Después se puede volver a arrancar Zigbee2MQTT.
Si el coordinador antiguo y el nuevo son de la misma familia, este paso puede no ser necesario. Pero si aparece ese error, conviene recordar que el problema no está en MQTT ni en Home Assistant, sino en el backup del coordinador.
Paso 8: arrancar Zigbee2MQTT
Una vez cambiada la configuración en los dos sitios:
- configuration.yaml
- configuración del add-on de Home Assistant
arrancamos Zigbee2MQTT:
Home Assistant → Ajustes → Complementos → Zigbee2MQTT → Iniciar
En el log deberíamos ver algo parecido a:
Starting Zigbee2MQTT
Starting zigbee-herdsman
zh:ember
Socket ready
ASH connected
EZSP started
Adapter version info
Zigbee2MQTT started
Si aparece algo como esto, la conexión TCP con el Dongle-M está funcionando:
Socket ready
ASH connected
EZSP started
Después entramos en el frontend de Zigbee2MQTT y comprobamos que siguen apareciendo los dispositivos.
Paso 9: comprobaciones finales
Una vez iniciado Zigbee2MQTT, conviene comprobar varias cosas.
Primero, que los dispositivos aparecen:
Zigbee2MQTT → Devices
Después, que responden:
- Probar enchufes Zigbee.
- Probar relés.
- Probar bombillas.
- Probar sensores de apertura.
- Probar sensores de temperatura.
Si algunos sensores de pila no responden inmediatamente, no hay que alarmarse. Muchos dispositivos a batería duermen y tardan en actualizar.
También conviene revisar en Home Assistant:
Ajustes → Dispositivos y servicios → MQTT
y comprobar que las entidades siguen asociadas correctamente.
Problema habitual: han desaparecido todos los dispositivos
Si al arrancar Zigbee2MQTT desaparecen todos los dispositivos, no hay que empezar a reemparejar a lo loco.
Primero hay que parar Zigbee2MQTT y revisar:
1. ¿Se ha restaurado el database.db correcto?
2. ¿La IEEE del Dongle-M coincide con la del coordinador antiguo?
3. ¿configuration.yaml apunta al Dongle-M?
4. ¿La configuración del add-on de Home Assistant también apunta al Dongle-M?
5. ¿Se ha cambiado por error network_key, pan_id, ext_pan_id o channel?
En mi caso, el problema estaba en que había cambiado la configuración en un sitio, pero no en el otro.
El aprendizaje importante es este:
No basta con cambiar configuration.yaml.
También hay que cambiar la configuración del propio add-on de Zigbee2MQTT en Home Assistant.
Cuando ambas configuraciones apuntaron al Dongle-M, todos los dispositivos volvieron a aparecer correctamente.
Comandos útiles de comprobación
Para localizar archivos de Zigbee2MQTT:
find /config /homeassistant /addon_configs -name database.db -o -name configuration.yaml -o -name coordinator_backup.json 2>/dev/null
Para comprobar la primera línea de database.db:
head -n 1 database.db
Para contar dispositivos en la base de datos:
grep -c '"ieeeAddr"' database.db
Para buscar la configuración Zigbee importante:
grep -E 'port|adapter|baudrate|rtscts|pan_id|ext_pan_id|network_key|channel' configuration.yaml
Para hacer copia completa de la carpeta actual:
tar czvf /config/zigbee2mqtt-backup-$(date +%F-%H%M).tar.gz .
Configuración final usada
En mi caso, la configuración final para el Dongle-M por TCP/PoE quedó de este estilo:
serial:
port: tcp://192.168.1.50:6638
adapter: ember
baudrate: 115200
rtscts: false
Manteniendo sin cambios la parte de red Zigbee:
advanced:
channel: XX
pan_id: XXXXX
ext_pan_id:
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
network_key:
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
- XX
Los valores reales de network_key, pan_id y ext_pan_id no deben publicarse ni compartirse.
Conclusión
La migración de un dongle Zigbee USB a un Sonoff Dongle-M por TCP/PoE merece mucho la pena si queremos mejorar la ubicación del coordinador y separar la red Zigbee del servidor donde corre Home Assistant.
El cambio permite colocar el coordinador en una zona con mejor cobertura, alimentarlo por PoE y evitar depender de un puerto USB concreto.
Pero hay tres puntos críticos:
1. Copiar la IEEE del coordinador antiguo al Dongle-M.
2. Mantener intactos database.db, network_key, pan_id, ext_pan_id y channel.
3. Cambiar la configuración tanto en configuration.yaml como en el add-on de Home Assistant.
El tercer punto ha sido el más importante en mi caso. Si solo se cambia configuration.yaml, Zigbee2MQTT puede arrancar como si estuviera usando un coordinador nuevo y los dispositivos pueden desaparecer. Al cambiar también la configuración del add-on en Home Assistant, la migración se realizó correctamente y todos los dispositivos Zigbee se conservaron.
Por tanto, el resumen sería:
Copiar IEEE.
Hacer backup.
Cambiar configuration.yaml.
Cambiar configuración del add-on.
Arrancar Zigbee2MQTT.
Comprobar dispositivos.
Con esos pasos, el cambio de Sonoff USB Dongle a Sonoff Dongle-M por TCP/PoE puede hacerse sin perder la red Zigbee ni tener que reemparejar todos los dispositivos.
Fuentes técnicas consultadas
- Zigbee2MQTT documenta el uso de adaptadores Ethernet mediante rutas
tcp://IP:PUERTOy recomienda IP estática para adaptadores de red. - Zigbee2MQTT explica que, al migrar de coordinador, es importante copiar la IEEE address del coordinador antiguo al nuevo para evitar problemas con dispositivos que buscan al coordinador por esa dirección.
- Zigbee2MQTT advierte que cambiar la
network_keyobliga a reemparejar todos los dispositivos, y que cambiar el canal puede requerir reemparejar algunos. - Sonoff documenta para Dongle-M una configuración Zigbee2MQTT por TCP con
tcp://Dongle-M.local:6638,adapter: ember,baudrate: 115200yrtscts: false. - Experiencia práctica contrastada con ChatGPT durante la migración.
