> 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/devices/payload-decoding.md).
# Decodificação de Payload e Chaves do Connector
Descubra quais os campos que o seu dispositivo comunica e que valores transportam, e como esses nomes de campo se tornam as métricas que vê em todo o Kilo IoT Server.
Um dispositivo transmite uma carga útil compacta — um punhado de bytes, ou uma pequena mensagem JSON. Um **decodificador** transforma essa carga útil em campos nomeados, e são esses campos que o restante da plataforma usa. Ao escrever uma regra, criar um widget de dashboard ou indicar a um comando qual sensor verificar, você está a trabalhar com valores que saíram do decodificador.
Estão envolvidos dois nomes, e normalmente não são os mesmos:
* Um **chave do conector** é o nome do campo que o seu decodificador produz — `t`, `socket_status`, `humidity_pct`. Vem do firmware do dispositivo e do seu codec.
* Um **métrica** é o nome que você deu a esse campo quando o mapeou — *Temperatura*, *Estado da tomada*. Este é o nome mostrado nos dashboards, nas regras e no editor de comandos.
Saber qual chave do conector está por trás de qual métrica — e quais valores ela realmente contém — é o que permite escrever uma condição ou uma verificação que funcione à primeira.
## Veja o que o seu dispositivo está a reportar
Abra o dispositivo e vá para a sua **Métricas** aba (**Mapping** para dispositivos MQTT). O quadro de chaves do conector lista todos os campos que o dispositivo realmente enviou, com:
* a **nome do campo** exatamente como o dispositivo o envia
* o seu **valor atual**
* a **hora da última atualização** hora
São dados em tempo real do dispositivo, atualizados à medida que novas mensagens chegam, e é a forma mais rápida de responder a "o que este dispositivo reporta, e em que formato?". Copie daqui o valor quando precisar de o comparar noutro local — numa condição de regra, numa condição de dashboard, ou no valor esperado num comando.
Um dispositivo que ainda não transmitiu não mostra nada. Aguarde pela próxima mensagem agendada ou dispare uma a partir do próprio dispositivo.
## Onde o decodificador vive
O decodificador é o **funções de código** campo no **Ligação** aba do dispositivo. Selecionar um modelo de perfil de dispositivo preenche-o por si; configurar um dispositivo manualmente deixa-o vazio, e você cola o codec da documentação do fabricante ou de um repositório comunitário de codecs.
Pode editá-lo a qualquer momento. Se a saída decodificada estiver a faltar campos, produzir valores errados ou usar nomes que não correspondem à documentação do fabricante, altere o código e guarde — a próxima mensagem que o dispositivo enviar será decodificada com a sua versão.
Para o passo a passo completo da configuração do dispositivo, consulte [Registar dispositivos](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md).
## Mapear chaves para métricas
O mapeamento é o que liga uma chave do conector a um modelo de métrica, dando ao campo bruto um nome legível, uma unidade e um tipo. Depois de mapeada, essa medição aparece em toda a plataforma sob o nome da sua métrica.
Faça isto a partir do mesmo separador Métricas ou Mapeamento — veja [Registar dispositivos](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md#mapping-raw-fields-to-metric-templates) para o passo a passo, e [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md) para criar um modelo que ainda não exista.
Uma chave do conector que nunca é mapeada continua a chegar, mas não tem para onde ir: não aparecerá em regras, dashboards ou verificação de comandos.
## Os valores mantêm a forma que o dispositivo enviou
A plataforma guarda o valor que o decodificador produziu, sem alterações. Se o seu decodificador devolver o texto `ligado`, a métrica guarda o texto `ligado` — não `verdadeiro`, e não `1`. Se devolver o número `1`, a métrica guarda um número.
Isso importa em qualquer lugar onde compare um valor:
* **Numa regra**, uma condição que compara texto tem de comparar com texto: `vars.socket_status == "on"`.
* **Num comando**, o valor esperado que escreve tem de corresponder à forma como o sensor o reporta. Veja [Confirmar comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md#expected-value).
* **Numa condição de dashboard**, aplica-se a mesma regra.
Quando uma comparação nunca coincide, leia o valor atual na tabela de chaves do conector e escreva a sua comparação para corresponder ao que lá está.
## Testar um decodificador mioty antes de confiar nele
Os dispositivos MIOTY são decodificados através de uma blueprint e não de uma função de código, e as blueprints vêm com **Pré-visualização da descodificação** — execute o decodificador num payload de exemplo e inspecione os campos que ele produz antes de o ligar a dispositivos reais. Veja [Blueprints MIOTY](/kilo-docs-pt/kilo-iot-server/devices/mioty-blueprints.md).
Para dispositivos LoRaWAN e MQTT, a tabela de chaves do conector é onde verifica o resultado: guarde o codec, aguarde pela próxima mensagem e leia os campos que ele produziu.
## Quando os campos não são o que esperava
**As chaves estão a chegar, mas nada aparece nas regras ou nos dashboards.** As chaves ainda não foram mapeadas para métricas. Abra o separador Métricas ou Mapeamento e mapeie as que quer usar.
**As chaves não são as que esperava.** O decodificador está a produzir nomes de campo diferentes daqueles que os sensores do dispositivo estão à procura — um resultado comum de um codec escrito para uma versão diferente de firmware ou hardware. Compare os nomes na tabela de chaves do conector com os seus mapeamentos e atualize os mapeamentos ou substitua o codec.
**Não é decodificado absolutamente nada.** Verifique se o dispositivo está a transmitir e depois verifique o próprio codec. [Diagnóstico do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md) mostra quantas chaves foram decodificadas das mensagens mais recentes.
## Relacionado
* [Registar dispositivos](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md) — Configuração do dispositivo, codecs e o fluxo de mapeamento
* [Métricas](/kilo-docs-pt/kilo-iot-server/devices/metric-templates.md) — Nomes normalizados, unidades e tipos de valor
* [Diagnóstico do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md) — O que o dispositivo enviou por último e se foi decodificado
* [Confirmar comandos](/kilo-docs-pt/kilo-iot-server/devices/commands/verification.md) — Utilizar uma métrica e o seu valor para verificar um comando
---
# 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/devices/payload-decoding.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.
