> 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.md).
# Conector MQTT
Traga dispositivos compatíveis com MQTT para o Kilo IoT — Cloud MQTT (broker provisionado pela plataforma) ou External MQTT (faça a ponte do seu).
O conector MQTT permite-lhe trazer qualquer dispositivo capaz de MQTT para o Kilo IoT Server sem passar por LoRaWAN. PLCs de fábrica, controladores HVAC, contadores de energia de edifícios, gateways de edge que produzem MQTT (pontes Modbus-to-MQTT, BACnet-to-MQTT, OPC-UA-to-MQTT) e sensores com firmware personalizado que já publicam dados via MQTT podem todos ser ligados diretamente. Uma vez ligados, os seus dados fluem pelo mesmo pipeline de normalização, acionam o mesmo motor de regras e aparecem nos mesmos dashboards que todos os outros dispositivos no servidor.
Estão disponíveis duas variantes:
| Variante | Como o broker é fornecido | Limite | Ideal para |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **External MQTT** | O seu próprio broker — alojado na cloud, no local ou numa rede da instalação, desde que seja alcançável pela plataforma | Até 10 por organização | Ligação de infraestrutura existente que já publica para MQTT |
| **Cloud MQTT** | Fornecido pela plataforma — o servidor disponibiliza um endpoint de broker dedicado e credenciais por conector | Ilimitado | Novas implementações, pilotos e locais remotos onde quer ingestão MQTT sem operar você próprio a infraestrutura do broker |
Use External MQTT quando já tiver um broker em execução. Use Cloud MQTT quando quiser que a plataforma forneça um — dá um nome ao conector, a plataforma trata do resto.
> **Âmbito.** Esta documentação abrange a ingestão de telemetria MQTT e o mapeamento de dispositivos. O envio de comandos no sentido inverso — controlar um dispositivo ligado com downlinks — é configurado por dispositivo em [Comandos do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md).
## Nesta secção
* [O que é o MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/what-is-mqtt.md) — Introdução ao protocolo para engenheiros novos no MQTT ou para refrescar o modelo.
* [Cloud MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/cloud-mqtt.md) — Aprovisionamento de um broker gerido pela plataforma para um conector.
* [External MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — Ligação de um broker existente, incluindo alcance de rede, autenticação e verificação.
* [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — Como os padrões de tópicos, a extração do ID do dispositivo e o separador Mapping funcionam em conjunto. Leia antes de registar dispositivos.
* [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — Diagnosticar problemas de ligação, correspondência de tópicos e do separador Logs.
Para o lado de hardware/gateway de edge da integração — pontes Modbus, BACnet, OPC-UA, Sparkplug B e Zigbee2MQTT que publicam MQTT no conector — veja [Gateways de Edge MQTT](/kilo-docs-pt/kilo-iot-server/gateways/mqtt-edge-gateways.md) em Gateways.
***
## Adicionar um conector MQTT externo
1. Navegue para **Conectores** na barra lateral.
2. Clica em **Adicionar conector**.
3. Seleciona **External MQTT** a partir do **Tipo de conector** menu suspenso.
4. Preencha o formulário de configuração:
| Campo | Obrigatório | Detalhes |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Sim | Nome de apresentação para este conector |
| **URL do broker** | Sim | URL completa com esquema e porta. O broker tem de ser alcançável pela rede a partir da plataforma — um broker acessível apenas numa rede local isolada não ligará. Esquemas aceites: `mqtt://`, `mqtts://`, `tcp://`, `ssl://`. Exemplo: `mqtts://broker.facility.example.com:8883` |
5. Escolha um **método de autenticação** nos separadores:
| Método | O que preencher |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Anónimo** | Não são necessárias credenciais |
| **Básico** | Nome de utilizador e palavra-passe (a palavra-passe tem um alternar mostrar/ocultar) |
| **Certificado** | Três botões de carregamento de ficheiros: **Certificado CA**, **Certificado de cliente**, **Chave privada**. Carregue cada ficheiro — não cole o conteúdo PEM |
| **Token JWT** | Campo de token (mostrar/ocultar + copiar). O token é a credencial JWT necessária. No formulário aparece um campo de carregamento de Certificado — é opcional; a plataforma envia apenas o token para autenticação JWT |
6. Clica em **Adicione**.
O conector aparece na tabela de conectores. Clique na sua linha para abrir a página de detalhes do conector.
***
## Adicionar um conector Cloud MQTT
1. Navegue para **Conectores** na barra lateral.
2. Clica em **Adicionar conector**.
3. Seleciona **Cloud MQTT** a partir do **Tipo de conector** menu suspenso.
4. Introduza um **Nome** para o conector.
5. Clica em **Adicione**.
A plataforma aprovisiona um endpoint de broker dedicado e apresenta as credenciais geradas:
| Credencial | Detalhes |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **URL do broker** | O endpoint MQTT gerido. Copie-o usando o botão de cópia. |
| **Prefixo do tópico** | Todas as mensagens publicadas para este conector têm de usar este prefixo. Mantém os seus dados organizados sob o namespace atribuído ao conector. Copie-o usando o botão de cópia. |
| **Nome de utilizador** | Atribuído automaticamente. Copie-o usando o botão de cópia. |
| **campo Palavra-passe** | Mostrado uma vez. **Copie-o imediatamente.** Se o perder, rode as credenciais nas definições do conector — os dispositivos terão de ser reconfigurados com a nova palavra-passe. No modo de edição, está disponível um botão de regeneração. |
#### Ligar dispositivos ao Cloud MQTT
Configure os seus dispositivos ou o software do gateway para publicar para o endpoint fornecido. Detalhes importantes antes de ligar:
* **O URL do Broker é o endpoint completo** — copie-o exatamente como mostrado. Utiliza MQTTS (TLS) na porta 1884. Configure os seus dispositivos em conformidade; esta não é a porta padrão 1883.
* **Todos os tópicos publicados têm de começar com o prefixo do tópico.** O tópico completo para o qual o seu dispositivo publica é `{Prefixo do tópico}/{tópico do dispositivo}` — por exemplo, se o prefixo for `iot/abc123/xyz789` e o seu dispositivo publicar leituras de potência, poderá publicar para `iot/abc123/xyz789/EM-4492/power`.
* **Os modelos de encaminhamento no dispositivo não incluem o prefixo.** Ao configurar o Device ID Topic no separador Topic, introduza apenas a parte ao nível do dispositivo — por exemplo `{{deviceId}}/power`. A plataforma remove o prefixo antes do encaminhamento.
Não é necessária qualquer infraestrutura de broker da sua parte — a plataforma gere o broker.
***
## Registar um dispositivo no MQTT
Cada dispositivo que publica através de um conector MQTT tem de ser registado individualmente. O registo mapeia a estrutura de tópicos MQTT e o formato do payload para o modelo de dispositivo do servidor.
1. Na página de detalhes do conector, clique em **Adicionar dispositivo** — ou navegue para **Dispositivos → Registar dispositivos** e selecione este conector.
2. Preencha os campos padrão do dispositivo (nome, conector, modelo).
> **Device ID = segmento do tópico, à letra.** Tudo o que introduzir como identificador do dispositivo tem de corresponder exatamente ao segmento de tópico ao nível do dispositivo que o seu hardware publica. O campo Device ID remove espaços em branco, pelo que identificadores como `EM 4492` irão falhar silenciosamente ao corresponder a um dispositivo que publica em `EM-4492`. Use a mesma string exata no registo do dispositivo e no lado de publicação; a capitalização é preservada e tem significado.
3. O dispositivo abre com um separador **Mapping** Dentro de Mapping existem dois sub-separadores: **Topic** (onde a plataforma aprende a localizar o dispositivo no fluxo de tópicos) e **Mapping** (onde mapeia chaves do payload para métricas normalizadas). Selecionar **Mapping** abre o **Topic** subseparador primeiro; clique em **Seguinte** ou no rótulo interno **Mapping** para chegar às linhas por chave.
### Separador Topic
O separador Topic indica ao conector onde encontrar o identificador do dispositivo em cada mensagem MQTT, e quais tópicos transportam dados de telemetria.
#### Device ID Topic *(obrigatório)*
O padrão de tópico MQTT para o qual este dispositivo publica. Use `{{deviceId}}` para marcar o segmento do tópico que contém o identificador do dispositivo.
**Exemplo:** Se o seu contador de energia publica para `facility/meters/EM-4492/power`, introduza:
```
facility/meters/{{deviceId}}/power
```
O servidor extrai `EM-4492` desse segmento e encaminha todas as mensagens correspondentes para o Digital Twin deste dispositivo.
#### Onde obter o ID do dispositivo
* **Topic** *(predefinição)* — O ID é extraído do `{{deviceId}}` segmento do tópico.
* **Payload** — O ID é obtido de um campo dentro do payload JSON. Quando selecionado, o **Device ID Payload Path** torna-se obrigatório.
#### Device ID Payload Path *(apresentado quando source = Payload)*
Um caminho em notação de pontos para o campo de ID do dispositivo dentro do payload JSON.
**Exemplo:** Para um payload `{"device": {"id": "EM-4492"}, "power": 4.2}`, introduza:
```
device.id
```
#### Tópicos de telemetria *(opcional)*
As linhas de tópico de telemetria definem como medições individuais são extraídas das mensagens MQTT. São opcionais.
Para dispositivos que publicam um payload JSON plano num único tópico — como sistemas de gestão de edifícios ou PLCs que publicam um objeto de estado — pode ignorar totalmente esta secção. O servidor analisa automaticamente todas as chaves do payload JSON, incluindo objetos aninhados, que são achatados em caminhos em notação de pontos (por exemplo, `{"device": {"temperature": 22.5}}` torna-se acessível como `device.temperature`). O separador Mapping continua a ser necessário — cada chave do payload precisa de uma linha correspondente com uma Chave do conector correspondente para se tornar uma métrica normalizada da plataforma. Adicione linhas de tópico de telemetria apenas quando precisar de controlo explícito por tópico: por exemplo, quando os valores das métricas estão embutidos no caminho do tópico em vez de no payload, ou quando pretende renomear métricas específicas.
| Campo | Detalhes |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MQTT Topic para telemetria** | Padrão de tópico para esta linha de métrica, usando `{{deviceId}}` marcador |
| **Chave do conector** | Nomeia a chave de origem recebida do MQTT. Esta chave tem de corresponder ao que o dispositivo publica. A Chave do conector não cria por si só uma métrica da plataforma — é no separador Mapping que ela é ligada a uma métrica normalizada. |
**Adicionar novo tópico** — adiciona uma linha de tópico de telemetria.
**Aplicar a tudo** — usa o padrão de tópico do ID do dispositivo como prefixo para gerar modelos de tópico de telemetria para linhas que já tenham uma Chave do conector preenchida. Gera padrões por tópico com base no tópico do ID do dispositivo — não copia o valor do tópico do ID do dispositivo literalmente.
#### Referência de marcadores
| marcador | Onde é usado | O que faz |
| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `{{deviceId}}` | Tópico do ID do dispositivo, modelos de tópico de telemetria | Marca o segmento do tópico que contém o identificador do dispositivo |
| `{{value}}` | Modelos de tópico de telemetria | Marca um segmento de tópico cujo conteúdo é o próprio valor da medição — por exemplo, `meters/EM-4492/230.5` onde `230.5` é a leitura. Não use `{{value}}` para segmentos de tópico que nomeiam a métrica (como `potência` ou `tensão`) — se o segmento for um rótulo em vez de um valor, use antes a abordagem estilo payload |
***
### Separador Mapping
O separador Mapping liga os dados MQTT recebidos a métricas normalizadas da plataforma. É aqui que os valores brutos do dispositivo se tornam dados de sensor consultáveis no Digital Twin.
A Chave do conector no separador Mapping tem de corresponder à chave publicada na mensagem MQTT (ou à Chave do conector definida no separador Topic). Sem correspondência, os dados são ignorados silenciosamente — o texto de ajuda acima da tabela confirma-o: **"Se a chave do conector não estiver preenchida, os dados serão ignorados."**
A tabela tem 8 colunas:
| Coluna | Tipo | Detalhes |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| **Chave normalizada** | Lista pendente | Selecione a partir de modelos de sensores; inclui uma opção "+ Adicionar nova métrica" |
| **Unidade** | Só de leitura | Derivada do modelo selecionado |
| **Tipo** | Só de leitura | Inteiro, Float, String ou Boolean — derivado do modelo |
| **Tipo de dados** | Lista pendente | Estado reportado, Telemetria ou Metadados do dispositivo |
| **Chave do conector** | Lista pendente | Lista as chaves recebidas do payload deste dispositivo. Vazia até ter chegado pelo menos uma publicação |
| **Valor** | Só de leitura | Valor ativo atual recebido do broker |
| **Última atualização** | Só de leitura | Carimbo de data/hora do valor mais recentemente recebido |
| **Ações** | Ícone | O ícone do caixote do lixo remove a linha |
**Adicionar chave** — adiciona uma nova linha de mapeamento vazia.
#### Estado reportado vs Telemetria
A **Tipo de dados** a lista pendente distingue duas categorias operacionais:
* **Estado reportado** — propriedades controláveis do dispositivo cujo valor atual o dispositivo publica. O ponto de ajuste de um controlador HVAC, o estado ligado/desligado de um atuador inteligente, o estado aberto/fechado de uma válvula. Estes são valores que o dispositivo também pode ser comandado a alterar.
* **Telemetria** — medições só de leitura. Sondas de temperatura, leituras de contador de energia, valores RMS de vibração, qualidade da ligação. Estas são observações que o dispositivo faz sobre si próprio ou sobre o seu ambiente.
Escolha o tipo que se adequa à intenção operacional do valor. Estado reportado é apropriado para campos de máquina de estados e pontos de ajuste configuráveis; Telemetria é apropriada para leituras de sensores e diagnósticos.
#### A lista pendente Chave do conector fica vazia até o dispositivo publicar uma vez
A **Chave do conector** a coluna é uma lista pendente preenchida a partir de chaves de payload realmente recebidas do dispositivo — não é um campo de texto livre. Antes de chegar a primeira publicação, a lista pendente está vazia e as linhas não podem ser preenchidas.
Registar um dispositivo MQTT é, portanto, um fluxo de trabalho em duas passagens:
1. Adicione uma linha por métrica, selecione a **Chave normalizada** no menu suspenso de modelos (ou use **+ Adicionar nova métrica** para criar uma), defina a **Tipo de dados**, e deixe o **Chave do conector** em branco.
2. Clica em **Guardar**. O registo do dispositivo é persistido.
3. Confirme que o dispositivo está a publicar — no caso de um gateway de edge que produz MQTT, que o processo do gateway está em execução e que o dispositivo emitiu pelo menos uma mensagem.
4. Reabra o dispositivo. A **Chave do conector** lista pendente agora lista as chaves recebidas nas publicações mais recentes.
5. Associe uma chave a cada linha de mapeamento.
6. Clica em **Guardar** novamente.
#### Coluna Value do separador Mapping vs histórico do separador Logs
A coluna Value do separador Mapping **Valor** reflete o payload mais recente — uma captura em tempo real. Os valores aparecem aqui assim que a correspondência de tópicos é bem-sucedida, mesmo antes de as Chaves do conector serem preenchidas.
A **Registos** separador é histórico por sensor. É preenchido apenas pelas publicações que chegam *depois de* as Chaves do conector serem guardadas. Depois da segunda passagem do fluxo de trabalho acima, gere uma nova publicação (um wake-on-event do dispositivo, um relatório agendado, ou, para gateways de desenvolvimento, uma consulta /get) para confirmar que o separador Logs está a receber registos.
#### O mapeamento é iterativo — volte a ele depois de os dados chegarem
O mapeamento MQTT não é uma operação única. O registo inicial baseia-se muitas vezes na expectativa do operador sobre o que o dispositivo ou gateway de edge irá publicar; o primeiro payload real revela frequentemente chaves adicionais — campos de diagnóstico definidos pelo fornecedor, campos de estado não documentados, objetos aninhados com subcaminhos úteis. Trate o separador Mapping como um lugar a revisitar:
1. Depois de os dados em tempo real terem estado a chegar durante um período representativo, reabra o registo do dispositivo.
2. Inspecione a **Chave do conector** lista pendente e a **Valor** coluna para ver o que o dispositivo está realmente a publicar.
3. Adicione linhas de Mapping para os campos que a implementação agora quer monitorizar (um campo de diagnóstico para manutenção preditiva, um campo de estado que se tornou operacionalmente relevante, uma submétrica de vibração aninhada, e assim por diante).
4. Escolha a Chave normalizada e o tipo de dados corretos para cada nova linha.
5. Guardar.
6. Acione uma nova publicação para que o separador Logs comece a recolher histórico para os novos mapeamentos.
Este refinamento iterativo é o fluxo de trabalho esperado, especialmente para frotas mistas de fornecedores onde os esquemas de payload variam subtilmente entre revisões de firmware de dispositivos nominalmente idênticos.
#### Translação de tipo de payload → tipo de métrica
Quando um dispositivo publica um estado enumerado como string (por exemplo, um atuador a publicar `"OPEN"`/`"CLOSED"`, ou um campo Zigbee `state` com `"ON"`/`"OFF"`), o valor chega como uma string — embora o tipo conceptual seja binário. Mapeie estes para o **Texto** Tipo no modelo da métrica, não Boolean. Selecionar Boolean para uma enumeração codificada como string resultará em valores nulos.
Para dispositivos ligados através de Zigbee2MQTT, especificamente, as páginas de dispositivos em [zigbee2mqtt.io](https://www.zigbee2mqtt.io/supported-devices/) listam cada funcionalidade com um tipo — traduza da seguinte forma:
| Tipo de funcionalidade Z2M | Tipo de métrica | Observações |
| -------------------------- | --------------- | ---------------------------------------------------- |
| `binário` | **Texto** | Os valores são `"ON"`/`"OFF"` strings, não booleanos |
| `numérico` | **Número** | Intervalos numéricos mapeados diretamente |
| `enum` | **Texto** | Os valores enumerados chegam como strings |
| `valor de` | **Texto** | Texto livre |
#### Como descobrir que chaves um dispositivo publica
O separador Mapping não deteta chaves automaticamente. Três métodos de descoberta, por ordem de praticidade:
1. **A documentação do dispositivo ou a ficha técnica do fornecedor.** Os dispositivos industriais normalmente são fornecidos com um esquema de payload ou um catálogo de tópicos.
2. **Para dispositivos ligados via Zigbee2MQTT**, a página do dispositivo em `https://www.zigbee2mqtt.io/devices/{modelId}.html` lista o conjunto Exposes. Note que os payloads reais podem incluir chaves que não estão na página do dispositivo — confie no payload em tempo real em vez da documentação quando divergirem.
3. **Subscreva o broker e inspecione o payload em tempo real** — `mosquitto_sub` junto ao broker (ou no separador Logs, assim que pelo menos uma linha de mapeamento corresponda) mostra o payload JSON diretamente. Cada chave de topo é uma Chave do conector válida.
***
## Resultados esperados
Depois de o conector estar configurado e os dispositivos registados:
* A linha do conector na **Conectores** página mostra **Últimos dados recebidos** a atualizar à medida que as mensagens chegam.
* A **Dispositivos ligados** a contagem reflete os dispositivos registados.
* O Digital Twin de cada dispositivo atualiza-se com a telemetria recebida — visível na página de detalhes do dispositivo e nos painéis.
* As condições do motor de regras que referenciam estas métricas do dispositivo são avaliadas em tempo real.
***
## Resolução de problemas
Uma lista curta — veja [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) para receitas de diagnóstico que cobrem falhas de autenticação, incompatibilidades de certificados, o padrão do separador Logs vazio e ferramentas de verificação.
**Não chegam dados após a ligação:**
* Para External MQTT: verifique o esquema do URL do broker (`mqtt://`, `mqtts://`, `tcp://`, ou `ssl://`), confirme que o broker é alcançável a partir da Internet pública (o Kilo IoT Server liga-se ao seu broker de fora para dentro) e volte a verificar as credenciais.
* Para TLS (autenticação por certificado): verifique se o certificado CA corresponde à cadeia de certificados do broker e se o certificado do cliente e a chave privada formam um par correspondente.
* Para Cloud MQTT: confirme que os seus dispositivos estão a publicar para o URL do Broker e o prefixo de tópico corretos, e que o nome de utilizador e a palavra-passe estão corretos. Se a palavra-passe foi perdida, rode-a nas definições do conector.
**O dispositivo está registado mas não aparecem dados:**
* Compare o Device ID Topic registado com o tópico exato para o qual o dispositivo publica. Os tópicos são sensíveis a maiúsculas/minúsculas e têm de corresponder exatamente.
* Confirme o `{{deviceId}}` a posição do marcador alinha com o segmento real do ID do dispositivo no tópico.
* Confirme que o campo Device ID é idêntico, byte por byte, ao segmento ao nível do dispositivo — os espaços em branco são removidos na entrada e quebram a correspondência.
* Se usar a origem Payload: verifique se o caminho do payload do Device ID resolve corretamente face à estrutura real do payload.
**A coluna Value do separador Mapping atualiza-se mas o separador Logs está vazio:** Este é o padrão mais comum quando as Chaves do conector são guardadas depois de a publicação mais recente ter chegado. O separador Logs é preenchido apenas por publicações recebidas *depois de* as Chaves do conector são guardadas. Acione uma nova publicação — um despertar do dispositivo, um relatório agendado, ou uma `/get` consulta para gateways de desenvolvimento — e o separador Logs será preenchido.
**Valores das métricas em falta ou a mostrar chaves erradas:**
* Verifique se a Chave do conector no separador Mapping corresponde exatamente à chave no payload MQTT (sensível a maiúsculas/minúsculas).
* Se estiver a depender da análise automática de JSON (sem tópicos de telemetria definidos): a plataforma achata todo o payload JSON, incluindo objetos aninhados, em chaves com notação de pontos — por exemplo, `{"device": {"temperature": 22.5}}` torna-se acessível como `device.temperature`. Use estes caminhos em notação de pontos na coluna Chave do conector do separador Mapping.
**Palavra-passe do Cloud MQTT perdida:** A palavra-passe não pode ser recuperada após a criação. Rode as credenciais nas definições do conector e reconfigure os dispositivos com a nova palavra-passe.
**Falha ao guardar o dispositivo num conector Cloud MQTT:** Se a gravação de um dispositivo num conector Cloud MQTT falhar, contacte o suporte. O suporte pode ajudar a concluir o registo através do caminho suportado assistido por API.
***
## Exemplos operacionais
**PLC de fábrica — telemetria por tópico:** Um PLC publica medições discretas em tópicos MQTT separados num broker no chão de fábrica (`mqtts://plc-broker.plant.example.com:8883`). Conector External MQTT, autenticação por nome de utilizador/palavra-passe. Device ID Topic: `plant/line-a/{{deviceId}}/data`. Uma linha de tópico de telemetria por medição (cycle\_time, reject\_count, temperature). Cada linha mapeia para uma métrica normalizada da plataforma no separador Mapping.
**Sistema HVAC de edifício — payload JSON plano:** Um sistema de gestão de edifícios publica um objeto de estado JSON por dispositivo num único tópico. O payload é JSON plano, pelo que não são necessárias linhas de tópico de telemetria — todas as chaves são analisadas automaticamente. O ID do dispositivo está no segmento do tópico. O separador Mapping mapeia cada chave JSON para a métrica normalizada adequada.
**Implementação de novo site — Cloud MQTT:** Um site de instalação remota precisa de ingestão MQTT mas a equipa não quer operar um broker. É criado um conector Cloud MQTT; a plataforma aprovisiona um endpoint de broker. Os contadores de energia e os sensores ambientais são configurados para publicar para o endpoint e o prefixo de tópico fornecidos. Não há infraestrutura de broker para gerir — a plataforma trata disso.
**Sistema de submedição de energia:** Os contadores de energia publicam leituras individuais (kWh, kW, tensão, corrente) em tópicos separados. As linhas de tópico de telemetria mapeiam cada tópico para uma Chave do conector nomeada. O separador Mapping liga cada Chave do conector a métricas normalizadas da plataforma. Todas as leituras agregam-se num único Digital Twin de dispositivo.
***
## O que se segue
* [Registro de dispositivos](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md) — Conclusão do registo do dispositivo e configuração do Digital Twin.
* [Conectores](/kilo-docs-pt/kilo-iot-server/connectors.md) — Visão geral de todos os tipos de conector.
---
# 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.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.
