> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md).
# Hubs Zigbee2MQTT
Ejecuta un hub Zigbee2MQTT como una pasarela perimetral MQTT — radio coordinadora, software Z2M y flujo de topics JSON plano.
Zigbee2MQTT (Z2M) es un patrón de pasarela perimetral MQTT disponible para implementaciones de Kilo que incluyen hardware de campo Zigbee. No es la ruta de ingesta predeterminada, y no es adecuado para todos los despliegues — los puentes Modbus, BACnet, OPC-UA y Sparkplug B siguen siendo las opciones convencionales para la telemetría industrial. Pero allí donde el hardware Zigbee encaja realmente en el panorama operativo — programas piloto, instrumentación de laboratorio y oficina, sensores ambientales a escala de edificio, ocupación y conteo de personas, telemetría de enchufes inteligentes, iluminación de gestión de edificios y presencia — Z2M proporciona un puente de código abierto bien soportado que convierte una malla Zigbee en publicaciones MQTT que el conector de la plataforma puede consumir.
Esta página cubre Z2M como un patrón de pasarela. El registro del lado MQTT de los dispositivos resultantes (Tema de ID de dispositivo, pestaña de Mapeo, claves del conector) está documentado en [Tópicos y enrutamiento de dispositivos](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — ese flujo es idéntico independientemente de qué pasarela perimetral MQTT esté produciendo el flujo de tópicos.
## Qué es un hub Z2M
Un hub Z2M es tres cosas que trabajan juntas:
1. **Una máquina anfitriona** en el borde de la red — normalmente un pequeño dispositivo Linux (mini-PC industrial, NUC, Raspberry Pi, equipo del proveedor) con USB o Ethernet hacia el coordinador y una ruta de red estable hacia el broker. Operativamente se ejecuta como un servicio del sistema con semántica de reinicio ante fallo.
2. **Un coordinador Zigbee** — una radio USB (por ejemplo, Sonoff ZBDongle-E con EFR32MG24, una opción de uso común) o un coordinador conectado a la red (por ejemplo, SMLIGHT SLZB-06). El coordinador es el puente de radio entre la malla Zigbee y Z2M; no ejecuta MQTT por sí mismo.
3. **El software Zigbee2MQTT** — abre el transporte del coordinador, incorpora dispositivos Zigbee a la malla y publica el estado y la telemetría de cada dispositivo como JSON plano en `zigbee2mqtt/{friendlyName}`.
La secuencia MQTT resultante se ve, desde la perspectiva de la plataforma, como cualquier otra pasarela perimetral con carga útil JSON.
## Dónde encaja Z2M en despliegues comerciales
Z2M es apropiado cuando los dispositivos finales Zigbee son operativamente útiles y la escala del despliegue coincide con aquello para lo que está construido el proyecto Z2M de código abierto:
* **Programas piloto** evaluando tipos de sensores o combinaciones de proveedores antes de comprometerse con una infraestructura de radio dedicada.
* **Instrumentación de oficina, laboratorio y instalaciones** — sensores de temperatura, humedad, CO₂, presencia, nivel de luz, enchufes inteligentes, contadores de ocupación.
* **Complementos de gestión de edificios** — sensores complementarios que se suman a un BMS existente en lugar de sustituirlo.
* **Iluminación comercial dirigida** escenarios en los que las bombillas y enchufes Zigbee son el hardware elegido.
Z2M no es la herramienta adecuada para telemetría de procesos de alto rendimiento, automatización en planta o escenarios en los que se requieren operativamente garantías de tiempo real estricto, latencia determinista o arquitecturas formales de redundancia. Esos casos de uso se sirven mejor con puentes Modbus, OPC-UA, BACnet o Sparkplug B — vea la [visión general de pasarelas perimetrales MQTT](/kilo-docs-es/kilo-iot-server/gateways/mqtt-edge-gateways.md) para el mapa general de categorías.
## Capacidad y recuperación — valide, no suponga
Z2M es el vínculo activo entre la malla Zigbee y el broker. Si el host o el contenedor se reinicia, el enrutamiento de la malla Zigbee se detiene durante ese tiempo. La capacidad del coordinador, el manejo del tráfico y el comportamiento de recuperación deben validarse frente al número específico de dispositivos y al patrón de tráfico de su despliegue antes de comprometer el diseño. Las ventanas de inactividad aceptables, la frecuencia de reinicio y la tolerancia operativa a interrupciones transitorias son decisiones específicas del despliegue, no orientación genérica — confírmelas con una prueba de fallo deliberada antes de confiar en Z2M para cualquier telemetría relevante desde el punto de vista operativo.
Esta guía no prescribe patrones de redundancia para Z2M. La redundancia de Z2M no es trivial y depende de supuestos sobre el proveedor del coordinador, la topología de la malla y cómo toleran los clientes las interrupciones breves; trate la redundancia como una cuestión de diseño del despliegue, no como un patrón documentado.
## Advertencias de proveedor y firmware
* **La interoperabilidad de Zigbee 3.0 es buena, pero no perfecta.** Es posible que modelos específicos de dispositivos necesiten un manejo específico según la versión de firmware. Valide el conjunto de dispositivos previsto frente a la [lista de dispositivos compatibles con Zigbee2MQTT](https://www.zigbee2mqtt.io/supported-devices/) antes de la adquisición.
* **Sparkplug B no es nativo de Z2M.** Z2M publica JSON plano, no Sparkplug. Para despliegues estandarizados en Sparkplug, un puente adicional de codificación Sparkplug se sitúa entre Z2M y el broker.
* **Compatibilidad del firmware del coordinador.** El `serial.adapter` configuración en `configuration.yaml` debe coincidir con la familia del chip del coordinador — `ezsp` para EFR32MG (Sonoff ZBDongle-E y similares), `zstack` para CC2652P (Sonoff ZBDongle-P). Los valores no coincidentes hacen que Z2M no arranque.
## Traspaso de enrutamiento al conector MQTT
Una vez que Z2M está publicando, cada dispositivo Zigbee se convierte en un publicador MQTT normal desde la perspectiva de la plataforma. El trabajo del lado del conector es el mismo que para cualquier otra pasarela que publique por MQTT:
1. Configure el [conector MQTT](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector.md) (Cloud MQTT o External MQTT) y apunte Z2M hacia él mediante `mqtt.server` y `mqtt.base_topic` en `configuration.yaml`.
2. Para cada dispositivo Zigbee, registre un registro de dispositivo con **ID de dispositivo** igual al nombre amigable de Z2M (byte a byte; la plataforma elimina los espacios en blanco, así que use nombres sin espacios como `LineA-Sensor-12` o `lab_temp_03`).
3. Configura el **Tema de ID de dispositivo** a `zigbee2mqtt/{{deviceId}}`.
4. Asigne las claves de la carga útil siguiendo el patrón de guardado en dos pasadas documentado en [Tópicos y enrutamiento de dispositivos](/kilo-docs-es/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md), y revise el Mapeo de forma iterativa a medida que aparecen campos adicionales en las cargas útiles en vivo.
Para una referencia completa de la configuración de Z2M (`docker-compose.yml`, `configuration.yaml` plantilla, selección del coordinador, elección del canal), consulte la documentación propia del proyecto Zigbee2MQTT. La secuencia de tópicos publicada por Z2M llega al conector MQTT de la plataforma de forma idéntica a cualquier otra pasarela perimetral MQTT que produzca JSON plano en el broker.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-es/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
