> 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-pt/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md).
# Hubs Zigbee2MQTT
Execute um hub Zigbee2MQTT como gateway edge MQTT — rádio coordenador, software Z2M, fluxo de tópicos JSON simples.
O Zigbee2MQTT (Z2M) é um dos padrões de gateway MQTT de borda disponíveis para implementações Kilo que incluem hardware Zigbee de campo. Não é o caminho de ingestão predefinido, e não serve para todas as implementações — as pontes Modbus, BACnet, OPC-UA e Sparkplug B continuam a ser as escolhas convencionais para telemetria industrial. Mas, quando o hardware Zigbee se encaixa genuinamente no cenário operacional — programas-piloto, instrumentação de laboratório e escritório, sensores ambientais em toda a instalação, sensores de ocupação e contagem de pessoas, telemetria de tomadas inteligentes, iluminação e presença de gestão predial — o Z2M fornece uma ponte open source bem suportada que transforma uma malha Zigbee em publicações MQTT que o conector da plataforma pode consumir.
Esta página aborda o Z2M como um padrão de gateway. O registo do lado MQTT dos dispositivos resultantes (Device ID Topic, separador Mapping, chaves do Connector) está documentado em [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — esse fluxo é idêntico, independentemente de qual gateway MQTT de borda está a produzir o fluxo de tópicos.
## O que é um hub Z2M
Um hub Z2M é a combinação de três elementos:
1. **Uma máquina anfitriã** na borda da rede — normalmente um pequeno dispositivo Linux (mini-PC industrial, NUC, Raspberry Pi, equipamento do fornecedor) com USB ou Ethernet para o coordenador e um caminho de rede estável para o broker. Operacionalmente, funciona como um serviço do sistema com semântica de reinício em caso de falha.
2. **Um coordenador Zigbee** — um rádio USB (por exemplo, o Sonoff ZBDongle-E com EFR32MG24, uma opção muito usada) ou um coordenador ligado à rede (por exemplo, o SMLIGHT SLZB-06). O coordenador é a ponte de rádio entre a malha Zigbee e o Z2M; ele próprio não executa MQTT.
3. **O software Zigbee2MQTT** — abre o transporte do coordenador, liga dispositivos Zigbee à malha e publica o estado e a telemetria de cada dispositivo como JSON simples em `zigbee2mqtt/{friendlyName}`.
O fluxo MQTT resultante parece, do ponto de vista da plataforma, qualquer outro gateway de borda com payload JSON.
## Onde o Z2M se enquadra em implementações comerciais
O Z2M é apropriado quando os dispositivos Zigbee finais são operacionalmente úteis e a escala da implementação corresponde ao que o projeto open source Z2M foi concebido para suportar:
* **Programas-piloto** a avaliar tipos de sensores ou misturas de fornecedores antes de investir em infraestrutura de rádio dedicada.
* **Instrumentação de escritório, laboratório e instalações** — sensores de temperatura, humidade, CO₂, presença e nível de luz, tomadas inteligentes, contadores de ocupação.
* **Complementos de gestão predial** — sensores suplementares que complementam um BMS existente em vez de o substituir.
* **Iluminação comercial direcionada** cenários em que lâmpadas e tomadas Zigbee são o hardware escolhido.
O Z2M não é a ferramenta certa para telemetria de processo de alto débito, automação no piso de fábrica ou cenários em que garantias de tempo real rigorosas, latência determinística ou arquiteturas formais de redundância são operacionalmente necessárias. Esses casos de utilização são melhor servidos por pontes Modbus, OPC-UA, BACnet ou Sparkplug B — veja a [visão geral dos gateways MQTT de borda](/kilo-docs-pt/kilo-iot-server/gateways/mqtt-edge-gateways.md) para o mapa geral da categoria.
## Capacidade e recuperação — valide, não assuma
O Z2M é a ligação ativa entre a malha Zigbee e o broker. Se o anfitrião ou o contentor reiniciar, o encaminhamento da malha Zigbee fica em pausa durante esse período. A capacidade do coordenador, a gestão de tráfego e o comportamento de recuperação devem ser validados face ao número específico de dispositivos e ao padrão de tráfego da sua implementação antes de fechar o desenho. As janelas de indisponibilidade aceitáveis, a frequência de reinício e a tolerância operacional a interrupções transitórias são decisões específicas da implementação, não orientação genérica — confirme-as com um teste de falha deliberado antes de confiar no Z2M para qualquer telemetria operacionalmente relevante.
Este guia não prescreve padrões de redundância para o Z2M. A redundância do Z2M não é trivial e depende de pressupostos sobre o fornecedor do coordenador, a topologia da malha e a forma como os clientes toleram interrupções breves; trate a redundância como uma questão de conceção da implementação, não como um padrão documentado.
## Avisos sobre fornecedor e firmware
* **A interoperabilidade Zigbee 3.0 é boa, mas não é perfeita.** Modelos de dispositivos específicos podem exigir tratamento específico para a versão do firmware. Valide o conjunto de dispositivos planeado face à [lista de dispositivos suportados pelo Zigbee2MQTT](https://www.zigbee2mqtt.io/supported-devices/) antes da aquisição.
* **O Sparkplug B não é nativo do Z2M.** O Z2M publica JSON simples, não Sparkplug. Para implementações padronizadas em Sparkplug, existe uma ponte adicional de codificação Sparkplug entre o Z2M e o broker.
* **Compatibilidade do firmware do coordenador.** A `serial.adapter` definição em `configuration.yaml` do Z2M tem de corresponder à família do chip do coordenador — `ezsp` para EFR32MG (Sonoff ZBDongle-E e semelhantes), `zstack` para CC2652P (Sonoff ZBDongle-P). Valores incompatíveis fazem com que o Z2M falhe ao arrancar.
## Transferência de encaminhamento para o conector MQTT
Assim que o Z2M começa a publicar, cada dispositivo Zigbee torna-se, do ponto de vista da plataforma, um publicador MQTT normal. O trabalho do lado do conector é o mesmo que para qualquer outro gateway que publique em MQTT:
1. Configure o [conector MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector.md) (Cloud MQTT ou MQTT Externo) e aponte o Z2M para ele através de `mqtt.server` e `mqtt.base_topic` em `configuration.yaml`.
2. Para cada dispositivo Zigbee, registe um registo de dispositivo com **ID do dispositivo** igual ao nome amigável do Z2M (byte a byte; os espaços em branco são removidos do lado da plataforma, por isso use nomes sem espaços, como `LineA-Sensor-12` ou `lab_temp_03`).
3. Defina a **Tópico do ID do dispositivo** para `zigbee2mqtt/{{deviceId}}`.
4. Mapeie as chaves do payload seguindo o padrão de gravação em duas passagens documentado em [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md), e reveja o Mapeamento iterativamente à medida que campos adicionais aparecem nos payloads em tempo real.
Para uma referência completa de configuração do Z2M (`docker-compose.yml`, `configuration.yaml` modelo, seleção do coordenador, escolha do canal), consulte a documentação própria do projeto Zigbee2MQTT. O fluxo de tópicos publicado pelo Z2M chega ao conector MQTT da plataforma de forma idêntica a qualquer outro gateway MQTT de borda que produza JSON simples no 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-pt/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.
