> 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/connectors/mqtt-connector/what-is-mqtt.md).
# O Que é MQTT
O que é MQTT? Um protocolo IoT leve de publicação-subscrição — brokers, tópicos, QoS — e como se mapeia para o conector Kilo.
MQTT é um protocolo de mensagens leve de publicação-subscrição, concebido para redes e dispositivos com recursos limitados, originalmente especificado pela IBM em 1999 para SCADA sobre ligações por satélite e agora normalizado como ISO/IEC 20922. Três propriedades fazem dele o protocolo dominante de IIoT industrial hoje: pequena sobrecarga no formato de transmissão, adequada para endpoints celulares e alimentados por bateria, produtores e consumidores desacoplados através de um broker central, e garantias de entrega bem definidas (QoS 0/1/2) que permitem aos integradores trocar throughput por fiabilidade por tópico.
Se estiver a integrar um sistema existente que produz MQTT — um sistema de gestão de edifícios, uma frota de contadores ligados por rede celular, uma frota de PLCs ligados por uma ponte MQTT — no Kilo IoT Server, a orientação abaixo cobre o modelo que a plataforma assume. Se já opera MQTT em produção e quer avançar, [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) descreva diretamente a configuração do conector.
## Funções arquiteturais
Três funções participam em qualquer troca MQTT:
* **Broker** — a malha de encaminhamento. Dispositivos e aplicações ligam-se ao broker; o broker faz corresponder publicadores a subscritores com base em padrões de tópico e gere a entrega de acordo com o nível de QoS solicitado. O broker é o único ponto de ligação para todos os participantes MQTT; não existe alternativa ponto-a-ponto.
* **Publicadores** — produzem mensagens para tópicos. Em termos práticos, os publicadores industriais incluem PLCs com firmware MQTT, gateways de borda que traduzem Modbus / BACnet / OPC-UA para MQTT, pontes específicas de fornecedor (Zigbee2MQTT, ESPHome) e firmware embebido personalizado em dispositivos de campo.
* **Subscritores** — consomem mensagens. O conector MQTT do Kilo IoT Server é um subscritor. Vários subscritores podem consumir os mesmos tópicos de forma independente — o seu dashboard existente, o historiador on-premises e a plataforma podem todos receber os mesmos dados sem coordenação.
```
Dispositivos de campo ──┐
PLCs ───────────┤
Pontes ────────┼──> Broker ──> Subscritores (Kilo, historiador, painéis, ...)
Gateways de borda ──┘
```
Os dispositivos são normalmente tanto publicadores (a reportar telemetria) como subscritores (a receber setpoints, configuração, downlinks). O broker é o intermediário sempre presente.
## Tópicos: a chave de roteamento
Cada mensagem MQTT transporta um **tópico** — uma string UTF-8 separada por barras. O broker usa tópicos para fazer corresponder publicadores a subscritores; os subscritores registam interesse em padrões usando `+` (coringa de um nível) `#` e (coringa multi-nível no final). Os tópicos não são predefinidos; a parte publicadora escolhe o tópico, e um catálogo de tópicos é estabelecido por convenção ou acordo do fornecedor.
Convenções comuns em implementações industriais:
* **Estrutura hierárquica de tópicos por local/ativo/métrica** — por exemplo, `plant-3/line-a/extruder-04/temperature` ou `building-12/floor-2/ahu-1/setpoint`. Isto torna as subscrições com wildcard naturais para agregação em todo o local.
* **Esquemas com prefixo do fornecedor** para pontes de protocolo — p. ex. `zigbee2mqtt/{friendlyName}`, `tasmota/{deviceName}/SENSOR`, `mosquitto/+/state`. O Kilo IoT Server suporta qualquer formato de tópico através do **Tópico do ID do dispositivo** campo pattern — veja [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md).
* **espaços de nomes Sparkplug B** para hierarquias ao estilo OPC-UA — p. ex. `spBv1.0/{group}/DDATA/{node}/{device}`. A plataforma consome estes como tópicos MQTT normais; a descodificação específica de Sparkplug é tratada pelo gateway de borda de publicação.
A configuração do conector da plataforma trata os tópicos como padrões: em cada dispositivo, você constrói o tópico a partir de segmentos e marca o segmento que transporta o identificador do dispositivo, e a plataforma extrai o identificador dessa posição quando cada mensagem chega.
## Cargas úteis: JSON estruturado na prática
O protocolo MQTT em si é agnóstico quanto à carga útil — entram bytes, saem bytes. Em implementações de produção, o JSON é de longe o formato de eleição para sistemas novos, com ocorrência ocasional de Sparkplug B (Protocol Buffers) e formatos binários proprietários para pontes legadas. O conector MQTT do Kilo IoT Server analisa automaticamente cargas úteis JSON — objetos planos, objetos aninhados (achatados em caminhos com notação por pontos) e valores primitivos são todos suportados.
Uma carga útil típica de telemetria industrial:
```json
{
"timestamp": "2026-01-15T14:32:18Z",
"temperature": 78.4,
"pressure": 4.21,
"vibration": {"rms": 0.42, "peak": 1.8},
"status": "running"
}
```
Quando mapeado para métricas da plataforma, `temperatura`, `pressão`, `vibration.rms`, `vibration.peak`, e `estado` cada um torna-se uma Connector Key endereçável. O separador Mapping liga cada Connector Key a uma métrica normalizada, que é então encaminhada para o Digital Twin, o motor de regras e o armazenamento histórico.
Para esquemas de uma métrica por tópico (pontes legadas, padrões de alias OPC-UA), as **Tópicos de telemetria** linhas na subaba Topic permitem mapear explicitamente cada tópico para uma Connector Key com nome.
## QoS, mensagens retidas, última vontade
Três funcionalidades do protocolo surgem com frequência suficiente em implementações industriais para valer a pena enunciá-las explicitamente:
* **Níveis de QoS** — 0 (no máximo uma vez), 1 (pelo menos uma vez), 2 (exatamente uma vez). O conector da plataforma trata qualquer QoS que o publicador use; escolha o nível que corresponda à sua tolerância operacional para duplicados vs. perdas. QoS 2 tem a maior sobrecarga no broker e normalmente é reservado para comandos de controlo ou alterações críticas de estado.
* **Mensagens retidas** — mensagens sinalizadas que o broker armazena e reencaminha para novos subscritores quando estes se ligam. Úteis para divulgação do estado atual (por exemplo, anúncios de "online/offline"). Se o broker entregar mensagens retidas à plataforma como publicações MQTT subscritas padrão, elas podem ser mapeadas como qualquer outro payload — confirme o comportamento do seu broker.
* **Última vontade e testamento (LWT)** — uma mensagem que o broker publica em nome do publicador se este se desligar inesperadamente. Padrão comum: o LWT de um dispositivo publica `"offline"` ao seu tópico de estado, para que os subscritores vejam alterações no estado de desconexão sem sondagem. Se o seu broker entregar mensagens LWT ao conector como publicações MQTT normais, elas podem ser mapeadas como qualquer outro payload.
Estas funcionalidades são configuradas pela parte publicadora, não pelo conector. O conector aceita o que quer que o broker entregue.
## Porquê MQTT para IIoT industrial
A adoção do protocolo em implementações comerciais é impulsionada por três propriedades que se alinham claramente com os requisitos operacionais:
* **Eficiência de largura de banda.** A sobrecarga do formato de transmissão é suficientemente pequena para dispositivos de campo ligados por rede celular e implementações wireless de alta densidade. Keep-alives e pings são configuráveis para se adequarem às janelas de conectividade disponíveis.
* **Produtores e consumidores desacoplados.** Adicionar um novo subscritor (um historiador, uma plataforma de analytics de terceiros, o Kilo IoT Server) não exige reconfigurar os publicadores. As equipas de operações podem lançar novos consumidores sem mexer nos dispositivos de campo.
* **Ecossistema maduro.** Existem Mosquitto, HiveMQ, AWS IoT Core, Azure IoT Hub e muitos outros brokers. A maioria das pontes de protocolo industriais modernas (Modbus-para-MQTT, BACnet-para-MQTT, gateways de borda Sparkplug B) vem com publicação MQTT nativa.
Para configuração específica da implementação, continue para [MQTT na Cloud](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/cloud-mqtt.md) para brokers geridos pela plataforma, ou [MQTT Externo](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) para ligar um broker existente.
---
# 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/connectors/mqtt-connector/what-is-mqtt.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.
