> 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/device-diagnostics.md).
# Diagnósticos do Dispositivo
Leia o estado de receção, o pipeline e o feed de eventos de um dispositivo para descobrir por que motivo a telemetria não está a chegar.
Comissionar um sensor é o momento em que uma implementação tem maior probabilidade de ficar em silêncio. O dispositivo está registado, o perfil parece correto, a tabela de mapeamento está preenchida — e nada aparece no painel. A pergunta que se segue é sempre a mesma: o hardware está inativo, a rádio está fora de alcance, a carga útil está a chegar mas a não ser entregue em lado nenhum, ou está tudo a funcionar e o dispositivo simplesmente ainda não atingiu o seu próximo relatório agendado?
Os diagnósticos do dispositivo respondem a essa pergunta diretamente. Em vez de o deixar inferir o estado da integração a partir de um gráfico vazio, a plataforma mostra o que realmente viu do dispositivo — se uma mensagem chegou ao servidor, se as chaves dentro dela corresponderam aos seus sensores e se os valores resultantes foram escritos no histórico. Cada estado não saudável vem com o elemento específico a verificar e um atalho para o ecrã onde o corrige.
## Porque é importante
Sem diagnósticos, um dispositivo silencioso é indistinguível de um mal configurado. Um engenheiro a comissionar cinquenta sondas de cadeia de frio num centro de distribuição não tem forma de distinguir entre uma sonda fora do alcance do gateway e uma sonda que está a transmitir perfeitamente para um mapeamento que nunca foi concluído. Ambas parecem um painel vazio, e ambas custam uma visita ao local.
Os diagnósticos separam esses casos na origem. Uma sonda que se juntou à rede mas não enviou uplinks é uma questão de rádio ou de agendamento. Uma sonda cujo payload está a ser decodificado em chaves que nunca foram mapeadas é uma correção de dois minutos a partir da sua secretária. Saber qual está a ver é esse o objetivo.
## Onde encontrá-la
Abra o dispositivo e mude para o **separador Conexão** separador. Os diagnósticos aparecem ao lado das definições de ligação, em três blocos:
| Bloco | O que responde |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| **Estado de receção** | Os dados estão a chegar neste momento e estão a ser guardados? |
| **Pipeline** | Ao longo da janela recente, até onde chegaram as mensagens — encaminhadas, mapeadas, armazenadas? |
| **Feed de eventos** | Mensagem por mensagem, o que aconteceu e quando? |
Leia-os por esta ordem. O estado de receção dá-lhe o veredito, o Pipeline dá-lhe o padrão e o feed de eventos dá-lhe as provas individuais.
## Estado de receção
O bloco do estado de receção resume todo o caminho de ingestão do dispositivo num único estado, com uma breve linha de detalhe de apoio por baixo. Um **RECEÇÃO** cabeçalho assinala o bloco, e um indicador **ATIVO** ou **SEM DADOS** (mostrado como **Ativo** ou **Inativo** em forma compacta) reflete se o tráfego está atualmente a fluir.
Enquanto o bloco está a carregar, vê **A carregar o estado de receção…**. Se os dados de diagnóstico não puderem ser obtidos, o bloco mostra **Diagnósticos indisponíveis** — o dispositivo em si não é afetado; tente novamente no separador.
### Os estados e o que fazer em cada um
| Estado | O que significa | O seu próximo passo |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A receber e a armazenar** | O estado saudável. A linha de apoio diz `{{count}} sensores mapeados · último valor {{last}}`. As mensagens chegam, as chaves correspondem aos seus sensores e os valores estão a ser escritos no histórico. | Nada. Se a linha também disser `{{count}} chaves adicionais disponíveis, não mapeadas`, o dispositivo está a enviar campos que ainda não mapeou — vale a pena rever se os quer nos painéis. |
| **A enviar dados — configure o mapeamento para os manter** | O dispositivo está a transmitir e o seu payload é decodificado corretamente — `{{count}} chaves decodificadas · nenhuma mapeada ainda` — mas nenhuma chave está ligada a um sensor, por isso nada é retido. | Use **Configurar mapeamento** ou **Mapear uma chave** para abrir o mapeamento e ligar pelo menos uma chave de entrada a um sensor. Os valores começam a acumular-se a partir da próxima mensagem. |
| **Os dados chegam mas nada é armazenado** | *"Os dados estão a chegar, mas nada foi ainda armazenado."* As mensagens chegam à plataforma, mas nenhum valor chega ao histórico — tipicamente uma lacuna no mapeamento ou um descodificador a produzir chaves diferentes daquelas que os seus sensores esperam. | Clica em **Corrigir mapeamento**. Compare as chaves no feed de eventos com os sensores mapeados. Se as chaves parecerem erradas e não apenas não mapeadas, verifique o descodificador de payload neste separador. |
| **Não reportou — o dispositivo parece offline** | *"O dispositivo estava a reportar, mas ficou em silêncio."* O dispositivo funcionava antes e parou. A linha de apoio — `Esperado a cada {{interval}} {{unit}} · última vez visto {{last}}` — indica-lhe o agendamento com que a plataforma está a comparar. | Isto é trabalho de campo: verifique a alimentação ou a bateria do dispositivo, confirme que ainda está ao alcance de um gateway e certifique-se de que o agendamento de envio não mudou. Se o agendamento real do dispositivo mudou, corrija **Intervalo de envio de dados** neste separador para que não seja assinalado desnecessariamente. |
| **A aguardar os primeiros dados** / **A aguardar o primeiro uplink** / **Ainda não foram recebidos uplinks** | O registo do dispositivo existe, mas a plataforma nunca recebeu nada dele. | Dê-lhe um intervalo de relatórios para transmitir. Se a janela passar, analise **O QUE VERIFICAR** abaixo — e se a unidade foi alguma vez usada noutra rede, consulte [Antes de chegar qualquer coisa: entrada na rede](#before-anything-arrives-joining-the-network). |
| **Ligado à rede — à espera de dados** | `Ligado à rede · ainda sem uplinks`. Para um dispositivo LoRaWAN isto é uma boa notícia: as credenciais estão corretas e a ligação rádio funciona. O dispositivo simplesmente ainda não enviou um payload. | Espere um intervalo de relatório. Se permanecer aqui, o dispositivo está ligado mas não está a transmitir — verifique o agendamento de envio e o estado de alimentação. |
Surge outra linha de apoio quando um dispositivo está configurado mas inativo: `{{count}} sensores configurados · 0 a receber valores`. Os seus sensores existem, mas nenhum deles está a ser alimentado. Trate-o da mesma forma que *Os dados chegam mas nada é armazenado* — o mapeamento é o ponto a verificar.
### Antes de chegar qualquer coisa: entrada na rede
Os estados de receção acima descrevem um ciclo de vida, e vale a pena lê-los por ordem:
**A aguardar os primeiros dados** → **Ligado à rede — à espera de dados** → **A receber e a armazenar**
O passo entre os dois primeiros é o que apanha as pessoas desprevenidas, porque acontece inteiramente do lado do dispositivo e a plataforma só pode esperar por ele.
Um dispositivo LPWAN não está simplesmente "configurado" numa rede — tem de **entrar** nela. Um dispositivo LoRaWAN envia um **pedido de entrada**, o servidor de rede valida-o em relação ao DevEUI e AppKey que registou e responde com uma aceitação de entrada. Só então o dispositivo tem uma sessão e começa a enviar uplinks. Um endpoint MIOTY faz o equivalente: **associa-se** através de uma estação base, o que move a plataforma para *Ligado à rede — à espera de dados*. Até esse handshake acontecer, um registo de dispositivo na plataforma é apenas um registo — com credenciais corretas e tudo.
**Um dispositivo pertence a uma rede de cada vez.** Esta é a parte que surpreende as pessoas. Um dispositivo que foi anteriormente comissionado noutro lugar — uma unidade devolvida de outro local, hardware comprado em segunda mão, um sensor que estava noutra plataforma ou na rede de um operador anterior, ou uma unidade de demonstração que regressou de uma feira — continua ligado a essa rede. Não se vai ligar à sua só porque o registou aqui. Não está à procura de uma nova rede; no que toca ao firmware, já tem uma.
O sintoma é distintivo: o dispositivo fica em **A aguardar os primeiros dados** indefinidamente enquanto todas as definições que pode verificar estão corretas. O DevEUI corresponde. O AppKey corresponde. Está ligado, está ao alcance e o intervalo de relatório passou várias vezes. Nada em **O QUE VERIFICAR** resolve isso, porque nada disso está errado.
A correção é **repor o dispositivo** para que envie um novo pedido de entrada. O procedimento é específico do fabricante — um deslizar de íman, manter um botão premido, um interruptor reed, um ciclo de energia de uma duração específica ou um comando downlink — por isso consulte as instruções do fornecedor para o seu modelo em vez de adivinhar. Alguns dispositivos distinguem entre um simples reinício e uma reentrada completa, e só esta última limpa a sessão anterior.
Assim que volta a ligar-se, o estado passa para *Ligado à rede — à espera de dados* e depois para *A receber e a armazenar* na próxima transmissão agendada do dispositivo.
Dois casos relacionados que vale a pena reconhecer:
* **Um dispositivo que se ligou uma vez e depois parou** é um problema diferente. Isso é *Não reportou — o dispositivo parece offline*, e aponta para alimentação, alcance ou agendamento — não para entrada na rede. Um dispositivo não se desliga silenciosamente.
* **Um dispositivo que continua a regressar a *****A aguardar os primeiros dados*** após uma entrada bem-sucedida geralmente significa que as credenciais na plataforma e as credenciais gravadas no dispositivo discordam de uma forma que permite que a entrada falhe em silêncio. Volte a introduzir o DevEUI e o AppKey — [Digitalizar código QR](/kilo-docs-pt/kilo-iot-server/devices/registering-devices.md) remove o risco de transcrição — e volte a repor o dispositivo.
### O QUE VERIFICAR e ENQUANTO ESPERA
Junto a um estado não saudável ou pendente, a plataforma lista as verificações relevantes sob um cabeçalho **O QUE VERIFICAR** , e — quando o estado é simplesmente inicial — a lista mais curta **ENQUANTO ESPERA** . Os itens que verá incluem:
* Confirme que o dispositivo está ligado e a transmitir
* Verifique a alimentação ou a bateria do dispositivo
* Certifique-se de que está ao alcance de um gateway / Confirme que ainda está ao alcance de um gateway
* Verifique se o AppKey e o DevEUI correspondem ao dispositivo
* Verifique se o descodificador de payload corresponde a este dispositivo
* Verifique se as definições de ligação estão corretas
* Confirme que o dispositivo está a enviar conforme o seu agendamento
* Certifique-se de que o agendamento de envio não mudou
* Dê-lhe um intervalo de relatórios para transmitir
* Mapeie pelo menos uma chave de entrada para um sensor
A lista é sensível ao estado, por isso vale a pena lê-la e não apenas passar os olhos: um dispositivo que já se ligou à rede não será questionado sobre o AppKey e o DevEUI, porque essa pergunta já está respondida.
Uma coisa que a lista não lhe consegue dizer é se o dispositivo continua ligado a uma rede em que foi usado antes da sua — isso é invisível do lado da plataforma. Se tudo aqui estiver correto e o dispositivo ainda nunca tiver reportado, essa é a hipótese a suspeitar: consulte [Antes de chegar qualquer coisa: entrada na rede](#before-anything-arrives-joining-the-network).
Cada item aponta para uma definição que controla. AppKey, DevEUI, o descodificador de payload e as definições de ligação vivem todos neste mesmo **separador Conexão** separador. O agendamento de envio é definido no próprio dispositivo e espelhado em **Intervalo de envio de dados** — consulte [Gestão de dispositivos](/kilo-docs-pt/kilo-iot-server/devices/device-management.md). O mapeamento vive no **Métricas** separador, e as ações de **Corrigir**, **Corrigir mapeamento**, **Configurar mapeamento** e **Mapear uma chave** levam-no diretamente para lá.
### Dispositivos MQTT
As integrações MQTT têm os seus próprios estados de receção, porque há duas ligações a verificar — a ligação da plataforma ao seu broker e o comportamento de publicação do dispositivo nele. Dois campos enquadram o diagnóstico: **Tópico esperado** mostra o tópico para o qual o registo do dispositivo está configurado, e **Publicado em** mostra o tópico em que uma mensagem realmente chegou.
| O que vê | O que significa | O seu próximo passo |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Broker ligado** — *"O seu broker está acessível e o Kilo está subscrito"* | O lado do conector está saudável. | Passe para o lado do dispositivo. |
| **A ligar ao seu broker…** | A subscrição está a ser estabelecida. | Dê-lhe um momento. Se persistir, verifique as definições do conector. |
| **O Kilo não consegue alcançar o seu broker** — *"Verifique o URL do broker e as credenciais nas definições do conector."* | A plataforma não consegue estabelecer a subscrição, por isso nenhum dispositivo neste conector pode entregar dados. | Abra o conector e corrija o URL do broker e as credenciais. Consulte [Resolução de problemas MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md). |
| **A aguardar que o dispositivo publique no broker Kilo…** | A subscrição está ativa; este dispositivo ainda não publicou. | Espere um intervalo de relatório e confirme então que o dispositivo está a funcionar e apontado para o broker correto. |
| **Chegou uma mensagem num tópico para o qual este dispositivo não está configurado** — *"Atualize o tópico acima ou altere onde o dispositivo publica."* | Uma publicação chegou à plataforma, mas o seu tópico não corresponde a este registo de dispositivo. Compare **Publicado em** com **Tópico esperado**. | Corrija o tópico neste separador para corresponder ao que o dispositivo realmente publica, ou reconfigure o dispositivo para publicar no tópico esperado. |
| **Ainda não há tópico de publicação configurado — defina um acima.** | O registo do dispositivo não tem nenhum tópico com o qual comparar. | Defina o tópico de publicação neste separador. |
Quando o dispositivo está a publicar corretamente, o bloco confirma as condições que tinham de ser verdadeiras para a mensagem chegar: *"O dispositivo publica no tópico esperado"*, *"O payload é JSON válido"*, *"O ID do dispositivo resolve conforme configurado"*, e — para dispositivos que usam credenciais emitidas pela plataforma — *"Está ligado com as credenciais MQTT geradas"*.
## Pipeline
O bloco Pipeline conta até onde as mensagens chegaram durante o período recente, dividido em **Encaminhadas**, **Mapeadas** e **Armazenadas**.
Estes contadores correspondem a uma janela recente deslizante, não a um total acumulado para toda a vida. A janela é indicada no próprio rótulo do bloco — **Estatísticas nos últimos {{days}} dias** — por isso leia esse rótulo antes de tirar conclusões. Um dispositivo que estava mal configurado no trimestre passado e foi corrigido na semana passada mostrará contagens limpas aqui; a janela já passou o incidente.
Leia os três números como um funil:
* **Encaminhadas altas, Mapeadas zero** — as mensagens estão a chegar e a ser associadas a este dispositivo, mas nenhuma chave está ligada a um sensor. O mapeamento é a correção.
* **Mapeadas altas, Armazenadas zero** — chaves correspondidas, mas os valores não persistiram. Verifique as linhas de mapeamento e os tipos de sensor a que apontam.
* **Todos os três a zero** — nada chegou a este registo de dispositivo. Isto é um problema de receção, não de mapeamento; volte ao bloco de estado de receção.
* **Todos os três a acompanhar** — a integração está saudável.
Se o bloco mostrar **Sem dados de pipeline**, a plataforma não tem nada para contar para este dispositivo na janela atual — a mesma conclusão que todos os três em zero.
## Feed de eventos
O feed de eventos é o registo mensagem a mensagem por trás do resumo. Onde os contadores de pipeline lhe dizem *com que frequência*, o feed diz-lhe *qual mensagem, quando e porquê*.
| Coluna | O que mostra |
| ------------- | --------------------------------------------------------------------------- |
| **Hora** | Quando a plataforma processou o evento |
| **Etapa** | Que passo do pipeline a linha descreve — Encaminhada, Mapeada ou Armazenada |
| **Resultado** | Se esse passo teve sucesso — OK, Ignorado ou Erro |
| **Detalhe** | Os pormenores desse passo |
Antes de existir qualquer dado, vê **Ainda sem eventos** e *"Os eventos aparecerão aqui assim que o dispositivo enviar dados."* — esperado para um dispositivo que não transmitiu.
O feed carrega em páginas. Clique **Carregar mais** para obter a página seguinte; mostra **A carregar…** enquanto carrega e **Todos os registos carregados** quando tiver chegado ao fim do histórico disponível. As linhas individuais oferecem **Detalhes** para expandir o contexto completo de um evento e **Ocultar** para o recolher novamente. **Ver estado de receção** leva-o de volta ao bloco de resumo no topo.
### O que significam estes estados
O feed inclui a sua própria legenda sob o cabeçalho **O que significam estes estados**:
| Termo | Significado |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Encaminhadas** | A mensagem chegou à plataforma e foi associada a este dispositivo. |
| **Mapeadas** | As chaves de entrada foram associadas aos seus sensores configurados. |
| **Armazenadas** | Os valores dos sensores foram guardados no histórico. |
| **OK** | Este passo foi concluído com sucesso. |
| **Ignorado** | Não processado intencionalmente (por exemplo, sem mapeamento correspondente ou um tópico inesperado). Não é necessariamente um erro. |
| **Erro** | Este passo falhou e precisa de atenção. |
**Ignorado é a linha que induz as pessoas em erro.** Não é uma falha — é a plataforma a dizer-lhe que tomou uma decisão deliberada. Uma `Mapeada / Ignorada` linha significa que chegou uma chave que nenhum sensor reivindica; se essa chave lhe interessa, mapeie-a. Se não, a linha é o comportamento correto e pode ignorá-la. Uma `Erro` linha **Detalhes** é o oposto: algo falhou e a mensagem não concluiu o seu passo. Expanda-a com
## Ler o feed para corrigir um dispositivo
Uma sequência prática quando um dispositivo não está a entregar dados:
1. Abra o dispositivo e vá para o **separador Conexão** separador.
2. Leia o estado de receção. Se nomear um problema específico — chaves não mapeadas, um tópico inesperado, um broker inacessível — use o botão de ação junto dele (**Corrigir**, **Corrigir mapeamento**, **Configurar mapeamento**, **Mapear uma chave**) e resolva-o aí.
3. Se o estado disser que o dispositivo está à espera ou em silêncio, verifique a linha de apoio para o intervalo e a hora da última vez vista, depois siga **O QUE VERIFICAR**.
4. Observe as contagens do Pipeline para ver em que ponto do funil as mensagens param, tendo em conta a janela no rótulo **Estatísticas nos últimos {{days}} dias** .
5. Abra o feed de eventos e encontre as linhas mais recentes nessa etapa. Expanda uma linha com **Detalhes** para ver exatamente qual a chave ou tópico envolvido.
6. Aplique a correção, depois espere um intervalo de relatório e releia o bloco. Os valores são armazenados a partir da próxima mensagem elegível — as mensagens anteriores não são reprocessadas, por isso uma nova transmissão é o que confirma a correção.
As chaves do conector aparecem no mapeamento automaticamente assim que o dispositivo transmite — não precisa de as escrever. É por isso que a ordem importa: faça primeiro o dispositivo transmitir e depois mapeie o que realmente chegou.
## Diagnósticos do conector
Os diagnósticos também existem um nível acima. Abra um conector e encontrará uma área **Diagnósticos do conector** que abrange todos os dispositivos nele, com um **Saúde da origem** e dois separadores:
* **Entrada** — o que está a chegar ao conector, com uma contagem de `{{count}} vistos` .
* **Atividade** — o histórico recente de eventos do conector. Antes de qualquer tráfego, lê-se **Ainda sem atividade**. Se os dados de diagnóstico não puderem ser carregados, lê-se **Diagnósticos indisponíveis**.
Um **Ligar dispositivo** a ação permite-lhe registar aqui um dispositivo no conector.
Use os diagnósticos do conector quando *vários* dispositivos estiverem em silêncio ao mesmo tempo — esse padrão normalmente aponta para o conector ou o broker, não para o hardware. Use os diagnósticos do dispositivo quando um dispositivo estiver em silêncio enquanto os seus vizinhos estão bem. Os diagnósticos do conector estão limitados a conectores MQTT; outros tipos de conector mostram apenas as suas definições.
Para problemas do lado do broker, TLS, autenticação e encaminhamento de tópicos, consulte [Resolução de problemas MQTT](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md).
## Sugestões
* **Defina o intervalo de envio de dados com honestidade.** Os diagnósticos medem o "ficou em silêncio" em relação ao intervalo que introduziu. Uma sonda que reporta uma vez por dia mas está configurada como horária será sinalizada como offline vinte e três vezes por dia, e um sensor verdadeiramente morto configurado como mensal permanecerá verde durante semanas.
* **Verifique o estado de receção antes de abrir um ticket.** *A enviar dados — configure o mapeamento para os manter* é uma correção de secretária. *Não reportou — o dispositivo parece offline* é uma visita ao local. A distinção vale trinta segundos.
* **Observe a janela do pipeline durante o comissionamento.** As contagens abrangem os dias indicados no rótulo **Estatísticas nos últimos {{days}} dias** , por isso um dispositivo corrigido há uma hora ainda inclui as suas mensagens falhadas na contagem. Avalie uma correção recente pelas linhas mais recentes do feed de eventos, não pelos totais.
* **Chaves não mapeadas são uma oportunidade, não um erro.** Quando um dispositivo saudável reporta `{{count}} chaves adicionais disponíveis, não mapeadas`, o hardware está a enviar medições que ainda não está a usar — um sensor de vibração pode estar a reportar temperatura em simultâneo, sem custo adicional em bateria ou tempo de transmissão.
* **Os diagnósticos complementam o separador de registos, não o substituem.** Os diagnósticos explicam *porquê* porque o processamento correu da forma como correu. O separador de registos mostra as leituras brutas propriamente ditas. Consulte [Gestão de dispositivos](/kilo-docs-pt/kilo-iot-server/devices/device-management.md).
---
# 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/device-diagnostics.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.
