> 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.md). # Gateways Edge MQTT Gateways edge MQTT para o Kilo IoT — Modbus, BACnet, OPC-UA, Sparkplug B, Zigbee2MQTT para MQTT. Em implementações comerciais, o conector MQTT é frequentemente a interface de integração para **gateways de borda** — pequenos computadores ou equipamentos industriais que traduzem protocolos não-MQTT em publicações MQTT. PLCs Modbus, sistemas de gestão de edifícios BACnet, sistemas de controlo expostos via OPC-UA, automação com Sparkplug B e malhas Zigbee não falam MQTT nativamente, mas software de gateway bem suportado pode ligar cada um destes ao conector da plataforma com um modelo uniforme de tópicos e payloads. Esta página aborda os padrões arquiteturais para gateways de borda MQTT e as escolhas de design que afetam o quão limpidamente se integram. Não é um guia passo a passo de configuração para um produto de gateway específico — a documentação do fornecedor trata da instalação; esta página é a referência de integração. ## O que faz um gateway de borda MQTT O gateway de borda fica entre o equipamento de campo não-MQTT e o broker MQTT. As suas responsabilidades: 1. **Ler do protocolo de origem** — ciclos de polling Modbus RTU/TCP, subscrições COV BACnet, subscrições OPC-UA, sessões de nó Sparkplug B, participação em malhas Zigbee. 2. **Normalizar valores** — aplicar fatores de escala, converter unidades para um conjunto consistente, descodificar bitfields e enumerações em valores legíveis por humanos. 3. **Publicar em MQTT** — emitir payloads JSON para uma estrutura de tópicos consumível pelos subscritores a jusante. (Os Protocol Buffers do Sparkplug B têm de ser traduzidos para JSON antes de publicar nos tópicos que o conector MQTT da plataforma consome — veja "Categorias comuns de gateway" abaixo.) 4. **Opcionalmente, aceitar comandos** — subscrever tópicos de controlo (`/set`, `/cmd`, específicos do fornecedor) e escrever de volta para o protocolo de origem. (O conector da plataforma consome telemetria; os fluxos de controlo ficam do lado do gateway.) O gateway é tipicamente um pequeno dispositivo Linux perto do equipamento de campo — um PC industrial, um computador para calha DIN, um Raspberry Pi ou um equipamento do fornecedor. Operacionalmente, executa como um serviço de sistema com semântica de reinício em caso de falha. ## Categorias comuns de gateway | Categoria | Software / equipamentos típicos | Estrutura do tópico | Formato do payload | | ------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Modbus → MQTT** | Modbus2MQTT, gateways fornecidos pelo fabricante (Advantech, Moxa), fluxos personalizados do Node-RED | `{site}/{plc}/{deviceId}/data` ou tópicos por registo | objeto JSON ou um valor por tópico | | **BACnet → MQTT** | pontes BMS do fornecedor, EasyIO, plataformas de integração personalizadas | `building/{floor}/{ahu-id}/{point}` | JSON com mapeamento de ponto para valor | | **OPC-UA → MQTT** | OPC Router, FactoryStudio, nós de borda Sparkplug B | Sparkplug `spBv1.0/{group}/DDATA/{node}/{device}` ou personalizado | **Tem de ser JSON para o conector da plataforma o ingerir.** Os Protocol Buffers do Sparkplug B têm de ser traduzidos para JSON pelo gateway de borda antes de publicar. | | **Nativo do Sparkplug B** | Inductive Automation Ignition Edge, gateways de borda Cirrus Link | `spBv1.0/{group}/DDATA/{node}/{device}` | **Tem de ser traduzido para JSON pelo gateway de borda antes da ingestão pelo conector MQTT.** O conector MQTT da plataforma não descodifica os Protocol Buffers do Sparkplug B. | | **Zigbee → MQTT** | Zigbee2MQTT (código aberto, comum em pilotos e pequenas implementações comerciais) | `zigbee2mqtt/{friendlyName}` | JSON plano | | **Pontes personalizadas** | Pontes Python/Node.js feitas à mão sobre APIs de fornecedores | O que quer que o autor da ponte tenha escolhido | Normalmente JSON | A plataforma consome qualquer um destes — o conector é agnóstico ao protocolo. O que importa na integração é corresponder a estrutura de tópicos do gateway no campo Device ID Topic e a estrutura do payload do gateway no separador Mapping. Veja [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) para os detalhes de encaminhamento. ## Considerações de design para novas integrações de gateways de borda Ao escolher ou configurar um gateway de borda para uma nova integração comercial, quatro decisões de design afetam a qualidade da ingestão: ### Estrutura do tópico Uma estrutura de tópicos hierárquica e previsível simplifica o registo de dispositivos e torna os padrões de tópicos reutilizáveis entre dispositivos semelhantes. Recomendado: ``` {site}/{system}/{deviceId}/{metric-or-data} ``` Por exemplo, `plant-3/line-a/extruder-04/data` para um objeto de estado em JSON plano, ou `plant-3/line-a/extruder-04/temperature` para um valor por tópico. Estruturas compatíveis com padrões permitem que um padrão de Device ID Topic cubra muitos dispositivos da mesma família — `plant-3/line-a/{{deviceId}}/data` funciona para todos os dispositivos na Linha A. Evite: * Espaços em branco em qualquer segmento, particularmente no segmento do identificador do dispositivo. O campo Device ID remove espaços em branco. * Misturar convenções de identificação numa única integração. Se alguns dispositivos usam hífens e outros usam underscores, documente a escolha e aplique-a de forma consistente. * Incorporar metadados em texto livre no tópico (nomes de operadores, datas, números de ordens de trabalho). Os tópicos são chaves de encaminhamento, não anotações — coloque os metadados no payload. ### Formato do payload JSON plano ou pouco aninhado simplifica o separador Mapping. A plataforma aplaina automaticamente objetos aninhados para caminhos em notação de pontos, por isso `{"vibration": {"rms": 0.42, "peak": 1.8}}` torna-se `vibration.rms` e `vibration.peak` como candidatos a Connector Key. Hierarquias profundamente aninhadas continuam a funcionar, mas são menos ergonómicas para os operadores que revêem os mapeamentos. **O Sparkplug B requer tradução para JSON na borda.** O conector MQTT da plataforma consome payloads JSON — não descodifica nativamente os Protocol Buffers do Sparkplug B. Gateways de borda que usam Sparkplug B (Inductive Automation Ignition Edge, Cirrus Link MQTT Modules, OPC Router com saída Sparkplug) têm de ser configurados para traduzir Protocol Buffers para JSON antes de publicar nos tópicos a que o conector se subscreve. A maioria dos gateways de borda comerciais compatíveis com Sparkplug fornece esta tradução como uma opção de configuração standard. ### Cadência de publicação A cadência de publicação é uma decisão específica da implementação, impulsionada por metas de tempo de resposta do motor de regras, capacidade do broker e capacidade do firmware do dispositivo. A configuração COV / dead-band do gateway de borda é a alavanca para reduzir publicações redundantes depois de escolhida uma cadência de base para uma determinada classe de dispositivos. Valide a cadência que o gateway de borda consegue suportar face às regras e dashboards que consomem os dados, e ajuste-a à medida que a implementação amadurece. ### Fiabilidade e comportamento em caso de desconexão Para telemetria relevante para a missão, configure o gateway com: * **MQTT QoS 1** para tópicos de telemetria — entrega pelo menos uma vez; o gateway volta a tentar na reconexão ao broker. * **MQTT Last Will and Testament (LWT)** — o anúncio do gateway de «desliguei-me inesperadamente», tipicamente publicado como uma mensagem retida para um tópico de estado. Se o seu broker entregar a mensagem LWT ao conector como uma publicação subscrita normal, um `estado` campo pode ser mapeado para refletir a conectividade do gateway — valide o caminho com um teste deliberado de desconexão antes de confiar nele operacionalmente. * **Mensagens "online" retidas** — publicadas na ligação, substituídas pelo LWT na desconexão. Os subscritores (incluindo novos que se liguem mais tarde) veem imediatamente o estado de conectividade atual. * **Armazenamento local persistente** — o gateway armazena em buffer a telemetria enquanto está desligado do broker e reprodu-la na reconexão. A maioria dos gateways de borda comerciais suporta isto; verifique o tamanho do buffer face às janelas de desconexão esperadas. ## Nesta secção * [**Hubs Zigbee2MQTT**](/kilo-docs-pt/kilo-iot-server/gateways/mqtt-edge-gateways/zigbee2mqtt-hubs.md) — Zigbee2MQTT como um padrão de gateway de borda MQTT: topologia em hub, adequação à implementação, orientação para validação de capacidade e como o fluxo MQTT resultante alimenta o fluxo standard de encaminhamento de dispositivos. ## Para onde ir a seguir * [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — registar dispositivos por detrás de qualquer um destes gateways. * [MQTT na Cloud](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/cloud-mqtt.md) e [MQTT Externo](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — escolher o lado do broker. * [Resolução de Problemas](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — diagnosticar problemas de ingestão. --- # 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.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.