> 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/topics-and-device-routing.md).
# Tópicos e Encaminhamento de Dispositivos
Estrutura de tópicos MQTT e encaminhamento por Device ID no Kilo IoT — marcadores de padrão, separadores Mapping/Topic, gravação em duas passagens.
Esta página aborda como o Kilo IoT Server resolve uma mensagem MQTT de entrada para um Digital Twin específico: a estrutura dos tópicos de entrada, a **Tópico do ID do dispositivo** semântica do padrão do campo, as subabas internas Mapping/Topic, a correspondência byte a byte entre a entrada do ID do dispositivo e o segmento de tópico ao nível do dispositivo, e o fluxo de salvamento em duas passagens exigido pela aba Mapping. Leia isto antes de registrar dispositivos MQTT em implantações de produção — a maioria dos chamados de suporte de "dispositivo registrado, mas sem telemetria" resolve-se em um dos padrões documentados aqui.
## Forma do tópico após o processamento do lado do broker
O broker da plataforma expõe mensagens MQTT de entrada com um prefixo no escopo do conector. Para Cloud MQTT, o prefixo é o prefixo de tópico do conector (`iot/{org}/{connection}`). Para External MQTT, a ponte de saída da plataforma republica as mensagens de entrada do seu broker em um namespace interno; a forma do tópico ao nível do dispositivo é preservada.
Após a remoção interna do prefixo, o tópico visto para o roteamento do dispositivo é o segmento ao nível do dispositivo:
```
Cloud MQTT: plant-3/line-a/EM-4492/data (após a remoção do prefixo)
External MQTT: plant-3/line-a/EM-4492/data (após a remoção do namespace da ponte)
```
O campo Tópico do ID do dispositivo descreve apenas esta forma ao nível do dispositivo. O tratamento do prefixo do conector é interno à plataforma; o operador não o configura.
## Construindo o Tópico do ID do dispositivo
**Tópico MQTT para o ID do dispositivo** na aba Connection do dispositivo não é uma caixa de texto livre — é um construtor de segmentos. O prefixo de tópico do conector já está definido e bloqueado, e você adiciona um segmento de cada vez com o **+** botão. Cada segmento é de um de dois tipos:
| Segmento | O que faz |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Segmento de texto** | Uma parte literal do tópico, digitada — `meters`, `line-a`, `SENSOR`. Correspondência exata com o tópico de entrada. |
| **ID do dispositivo** | Marca o segmento cujo valor *é* o identificador do dispositivo. Exatamente um é necessário, e o valor encontrado nessa posição é comparado com o **ID do dispositivo** campo acima. |
Um **Pré-visualização resolvida** abaixo do construtor mostra o tópico completo que o padrão produz para este dispositivo, para que você possa compará-lo com o que o seu publicador realmente envia antes de salvar. Arraste o chip do ID do dispositivo para movê-lo para uma posição diferente.
**Onde obter o ID do dispositivo** ao lado do construtor decide de onde o identificador é lido — **Tópico** (a posição que você marcou) é a escolha mais comum.
Exemplos de formas de tópico e os segmentos a adicionar após o prefixo:
| Tópico de publicação | Segmentos |
| ------------------------------- | ----------------------------------------------------- |
| `plant-3/line-a/EM-4492/data` | `plant-3` · `line-a` · **ID do dispositivo** · `data` |
| `tasmota/PlugKitchen/SENSOR` | `tasmota` · **ID do dispositivo** · `SENSOR` |
| `zigbee2mqtt/LivingRoomSensor` | `zigbee2mqtt` · **ID do dispositivo** |
| `home/sensors/esp-kitchen/data` | `home` · `sensors` · **ID do dispositivo** · `data` |
Para formas de tópico industriais aninhadas, como Sparkplug B (`spBv1.0/{group}/DDATA/{node}/{device}`), adicione o contexto hierárquico como segmentos de texto e coloque o ID do dispositivo no segmento que identifica de forma única o registro do dispositivo que está sendo registrado.
## A entrada do ID do dispositivo deve corresponder ao segmento extraído byte a byte
O campo ID do dispositivo no registro do dispositivo armazena o identificador canônico que a plataforma procura no segmento ID do dispositivo. A correspondência é byte a byte: sensível a maiúsculas e minúsculas, sensível a espaços em branco e sensível a Unicode.
Um padrão que costuma pegar integradores de surpresa: **a entrada do ID do dispositivo remove espaços em branco ao salvar.** Um dispositivo publicando em `plant-3/line-a/EM 4492/data` (com um espaço no ID do dispositivo) não corresponderá a um ID do dispositivo digitado como `EM 4492` — a entrada é normalizada para `EM4492` (ou parcialmente aparada; o comportamento exato não é garantido). A discrepância é silenciosa — não aparece erro ao salvar e não aparece erro quando a telemetria chega. A aba Mapping simplesmente permanece vazia.
A recomendação em implantações de produção: evite totalmente espaços em branco nos identificadores de dispositivos. Use hífens (`EM-4492`), sublinhados (`EM_4492`), ou nenhum separador (`EM4492`). Seja qual for a sua escolha, o lado da publicação e o campo ID do dispositivo devem produzir a mesma string exata.
## A aba Mapping tem duas subabas
Quando você abre a aba Mapping de um dispositivo, a interface apresenta uma aba externa rotulada **Mapping** contendo duas subabas: **Tópico** e **Mapping**. Ao selecionar a aba externa, você cai por padrão na subaba **Tópico** subaba.
* **Subaba Topic** — Tópico do ID do dispositivo, Onde obter o ID do dispositivo, Caminho do payload do ID do dispositivo (quando a origem é Payload), Tópicos de telemetria (definições de métricas por tópico para esquemas de publicação com uma métrica por tópico).
* **Subaba Mapping** — linhas de chave do conector que vinculam chaves do payload a métricas normalizadas.
Um dispositivo registrado sem visitar a subaba interna Mapping tem configuração de Topic, mas nenhuma correspondência de métricas — então, mesmo que a correspondência de tópico funcione e Last data received seja atualizado, o registro do dispositivo não contém telemetria. Clique **Seguinte** na parte inferior da subaba Topic ou clique no rótulo interno **Mapping** para chegar às linhas por chave.
## Tópicos de telemetria: quando configurá-los
A **Tópicos de telemetria** as linhas na subaba Topic são para esquemas de publicação em que cada métrica tem seu próprio tópico MQTT — por exemplo, uma ponte PLC publicando potência em `meters/{deviceId}/power`, tensão em `meters/{deviceId}/voltage`, corrente em `meters/{deviceId}/current`, cada um com um único valor numérico como payload.
Para esquemas modernos de publicação com JSON plano — Zigbee2MQTT, Tasmota com um objeto SENSOR, firmware personalizado que emite um objeto JSON de estado — as linhas de Tópicos de telemetria não são necessárias. A plataforma analisa automaticamente cada chave no payload JSON e as expõe como candidatas a Chave do conector. Objetos aninhados são achatados em caminhos com notação de ponto (`{"vibration": {"rms": 0.42}}` torna-se `vibration.rms`).
Configure as linhas de tópico de Telemetria apenas quando você realmente tiver publicação de uma métrica por tópico ou quando quiser substituir o analisador automático para uma forma específica de tópico.
## Menu suspenso de chave do conector: o fluxo de salvamento em duas passagens
A **Chave do conector** coluna da subaba Mapping é um menu suspenso. As opções do menu são obtidas das chaves do payload realmente recebidas do dispositivo — não de uma entrada de texto livre.
Para um dispositivo novo, sem tráfego histórico, o menu suspenso está vazio. A plataforma ainda não sabe o que o dispositivo envia, então não tem com o que preencher as opções. Isso é intencional, mas significa que o fluxo de registro tem duas passagens:
**Passagem 1:**
1. Adicione uma linha de Mapping por métrica produzida pelo dispositivo.
2. Selecione o **Chave normalizada** no menu suspenso de modelos. Use **+ Adicionar nova métrica** para criar um novo modelo de sensor, se necessário. (A modal cuida da criação tanto do nome normalizado quanto do modelo de sensor — pré-criar nomes pela aba Metrics é opcional.)
3. Defina **Tipo de dados** (Estado relatado, Telemetria ou Metadados do dispositivo — veja abaixo).
4. Deixe **Chave do conector** em branco.
5. Salve o registro do dispositivo.
**Passagem 2:**
6. Confirme que o dispositivo está publicando — para um dispositivo com ponte Z2M, que a ponte está em execução e que o dispositivo relatou pelo menos uma vez. Para uma ponte PLC, que o processo da ponte está publicando dados.
7. Reabra o registro do dispositivo. O **Chave do conector** menu suspenso agora lista as chaves recebidas do dispositivo.
8. Associe uma chave de payload a cada linha de Mapping.
9. Salve novamente.
Publicações subsequentes para as chaves mapeadas fluem para a aba Logs.
## Estado relatado vs Telemetria vs Metadados do dispositivo
A **Tipo de dados** menu suspenso classifica cada métrica:
* **Estado relatado** — propriedades controláveis do dispositivo cujo valor atual o dispositivo publica. O ponto de ajuste de um controlador HVAC, o estado aberto/fechado de uma válvula, o estado ligado/desligado de um atuador. Valores que o dispositivo também pode ser comandado a alterar.
* **Telemetria** — medições somente leitura. Variáveis de processo, leituras de medidor de energia, valores RMS de vibração, qualidade do link, medições ambientais. O dispositivo observa; não altera isso.
* **Metadados do dispositivo** — valores que descrevem o próprio dispositivo, e não seu estado operacional. Versão do firmware, modelo do hardware, número de série, data de calibração.
Escolha o tipo que corresponda à intenção operacional. Estado relatado é apropriado para campos de máquina de estados e pontos de ajuste configuráveis; Telemetria é apropriada para leituras de sensores e diagnósticos; Metadados do dispositivo é apropriado para campos estáticos de identidade do dispositivo.
## Tradução de tipo de payload → tipo de métrica
O Tipo do modelo de métrica (Integer, Float, String, Boolean) é definido pelo modelo escolhido para a Chave normalizada. Faça o Tipo do modelo corresponder aos dados que o dispositivo realmente envia:
* **Enums e estados binários codificados como string** — valores como `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`, `"running"`/`"stopped"` chegam como strings JSON. Mapeie para um Tipo **String** . Não selecione Boolean — isso resultará em valores nulos.
* **Escalares numéricos** — Integer ou Float, dependendo de o dispositivo produzir decimais.
* **Texto livre** — String.
Para dispositivos com ponte Zigbee2MQTT, as [zigbee2mqtt.io](https://www.zigbee2mqtt.io/supported-devices/) páginas de dispositivos listam cada recurso com um tipo — traduza assim:
| Tipo de recurso Z2M | Tipo de métrica | Exemplo |
| ------------------- | --------------- | --------------------------------- |
| `binary` | **String** | `state` (`"ON"`/`"OFF"`) |
| `numeric` | **Número** | `brightness`, `linkquality` |
| `enum` | **String** | `power_on_behavior`, `color_mode` |
| `text` | **String** | Campos de texto livre |
## Coluna Valor da aba Mapping vs histórico da aba Logs
Após a Passagem 2 do fluxo de salvamento:
* A **Valor** coluna na aba Mapping é atualizada com o payload mais recente — um instantâneo ao vivo. Os valores aparecem assim que a correspondência de tópico é bem-sucedida, mesmo antes de todas as chaves do conector serem preenchidas.
* A **Logs** aba é o histórico por sensor. Ela é preenchida apenas pelas publicações que chegam *após* as chaves do conector são salvas. Publicações antigas não são normalizadas retroativamente.
Operacionalmente: depois de concluir a Passagem 2, gere uma nova publicação (um wake-on-event do dispositivo, um relatório agendado, uma solicitação de polling da ponte) para confirmar que a aba Logs está recebendo registros. Se o dispositivo só relata em agenda ou por mudança de estado, planeje a validação em torno dessa cadência.
### Refinamento iterativo do mapeamento
O mapeamento inicial raramente cobre todos os campos úteis que um dispositivo expõe. Os operadores costumam descobrir, após a implantação, que o dispositivo publica chaves adicionais — campos de diagnóstico do fornecedor, valores de estado não documentados, subobjetos aninhados com caminhos relevantes para a operação. O padrão recomendado é revisitar a aba Mapping depois que os dados estiverem chegando por um período representativo:
* Inspecione o **Chave do conector** menu suspenso e a **Valor** coluna para ver exatamente o que o dispositivo está publicando em produção.
* Adicione novas linhas de Mapping para campos que a implantação agora deseja no Digital Twin.
* Defina a Chave normalizada e o Tipo de dados apropriados por linha.
* Salve.
* Gere uma nova publicação para que a aba Logs comece a registrar histórico para os campos recém-mapeados.
Para frotas de dispositivos nominalmente idênticos, execute esse refinamento em uma amostra representativa antes de aplicar as mudanças de mapeamento ao restante da frota — revisões de firmware podem introduzir diferenças sutis nas chaves.
## Para onde ir a seguir
* [Resolução de problemas](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — receitas de diagnóstico para falhas de correspondência de tópico e para o padrão de aba Logs vazia.
* [MQTT Edge Gateways](/kilo-docs-pt/kilo-iot-server/gateways/mqtt-edge-gateways.md) — padrões para pontes industriais produtoras de MQTT que alimentam este pipeline de roteamento (em Gateways).
---
# 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/topics-and-device-routing.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.
