> 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/troubleshooting.md).
# Resolução de problemas
Resolva problemas de integrações MQTT por fase de falha — ligação ao broker, TLS, autenticação, encaminhamento de tópicos, último dado.
Receitas de diagnóstico para integrações MQTT no Kilo IoT Server, organizadas por onde a falha se manifesta. Siga-as por esta ordem — a maioria dos problemas enquadra-se numa das três primeiras fases, e a sequência de diagnóstico reduz eficientemente a causa raiz.
Antes de passar pelas fases abaixo, deixe que a plataforma lhe diga em qual delas está. Um único dispositivo silencioso reporta o seu próprio estado no seu **Ligação** separador — se o broker está acessível, se um publish chegou num tópico inesperado e se os seus valores foram armazenados; veja [Diagnóstico do dispositivo](/kilo-docs-pt/kilo-iot-server/devices/device-diagnostics.md). Quando vários dispositivos ficam em silêncio ao mesmo tempo, abra a **diagnósticos do conector** área — **Saúde da origem** resume a subscrição do broker, **Entrada** mostra o que está a chegar, e **Atividade** mostra o histórico recente de eventos do conector. Essa leitura normalmente aponta diretamente para a fase por onde começar.
## Fase 1 — Falhas de ligação ao broker
**Sintoma:** o emissor (um gateway de edge, uma instância Zigbee2MQTT, firmware personalizado) indica que não consegue ligar-se ao broker. **Últimos dados recebidos** nunca é atualizado.
| Padrão de falha | Causa raiz | Resolução |
| ---------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ligação recusada` / `rede inacessível` (Cloud MQTT) | Host, porta ou esquema incorretos | Verifique se o emissor usa `mqtts://` na porta 1884 — e não a predefinida 1883. Volte a copiar o URL do broker a partir da página do conector. |
| `ligação recusada` / `rede inacessível` (External MQTT) | Acessibilidade da rede | A plataforma liga-se ao seu broker. Verifique se o broker é acessível a partir da Internet pública (o nome de anfitrião DDNS resolve, o redirecionamento de porta está ativo, a firewall permite o intervalo de saída da plataforma). |
| `handshake TLS inválido` / `falha na verificação do certificado` | Configuração TLS | Para Cloud MQTT, o certificado é de confiança pública — verifique se o emissor usa o armazenamento CA do sistema. Para External MQTT, verifique se os ficheiros do Certificado CA, Certificado do Cliente e Chave Privada foram carregados como ficheiros separados (não como conteúdo PEM colado) e que a Chave Privada estava sem encriptação no carregamento. |
| `autenticação falhou` / `não autorizado` | Credenciais incorretas | Volte a verificar o Nome de utilizador e a Palavra-passe. Para Cloud MQTT, se a palavra-passe se perdeu, altere-a nas definições do conector (a original não pode ser recuperada). Para autenticação Basic em External MQTT, confirme que o ficheiro de palavra-passe do broker está correto. |
| `autenticação falhou (JWT)` | Problemas com o token | Verifique se o JWT é válido (não expirado), assinado com a chave correta para o validador do broker e com as claims necessárias (subject, permissões de tópicos). |
Especificamente para configurações com ponte Z2M, o registo do Z2M mostra explicitamente o estado da ligação:
```
docker compose logs zigbee2mqtt | grep -E "Connecting|Connected|MQTT|Error"
```
`Ligado ao servidor MQTT` confirma o lado do emissor. A ausência dessa linha indica uma falha da Fase 1, independentemente do que a plataforma mostre.
## Fase 2 — A ligação é bem-sucedida, mas o Últimos dados recebidos não é atualizado
**Sintoma:** o emissor reporta uma ligação bem-sucedida ao broker. Os registos mostram publishes bem-sucedidos. **Últimos dados recebidos** na página do conector Kilo permanece vazio.
Para Cloud MQTT, trata-se de uma incompatibilidade do prefixo do tópico. Todos os tópicos publicados têm de começar exatamente com o prefixo de tópico do conector. Verifique:
* A configuração de tópicos do emissor usa o **completo** prefixo de tópico da página do conector (tipicamente `iot/{org}/{connection}`).
* Para Z2M, `mqtt.base_topic` em `configuration.yaml` é `{Topic prefix}/zigbee2mqtt`.
* Para firmware personalizado, cada chamada publish antepõe o prefixo.
Para External MQTT, trata-se de uma incompatibilidade de acessibilidade ou de subscrição:
* Execute um publish de teste único a partir de um anfitrião que consiga alcançar o seu broker:
```bash
mosquitto_pub -h {broker-host} -p {port} \
--cafile {ca-bundle} \
-u {username} -P {password} \
-t "test/connectivity" -m '{"hello":"world"}'
```
Se **Últimos dados recebidos** ainda não for atualizado, a plataforma não consegue alcançar o seu broker. Investigue regras de firewall, listas de permissões de IP ou sessões de túnel expiradas quando usar ngrok para testes.
* Para brokers atrás de NAT com redirecionamento de porta, verifique se a porta externa está aberta e encaminhada para a porta anfitriã do broker. Configurações incorretas comuns incluem encaminhar para o IP de anfitrião errado, bloquear o IP de origem ou ter uma regra de firewall que se sobrepõe ao redirecionamento de porta.
## Fase 3 — Últimos dados recebidos é atualizado, mas o separador Mapping do dispositivo está vazio
**Sintoma:** o conector recebe mensagens (Últimos dados recebidos estão atualizados), mas a coluna Valor do separador Mapping de um dispositivo registado não mostra nada.
São comuns duas causas:
* **O padrão de tópico do ID do dispositivo não corresponde ao tópico publicado.** Verifique o padrão comparando-o byte a byte com um tópico dos registos do emissor. Erros comuns: barra inicial, segmentos intermédios em falta, maiúsculas/minúsculas diferentes, pluralidade incompatível (`metro` vs `metros`).
* **O ID do dispositivo é diferente, byte a byte, do segmento extraído.** A remoção de espaços em branco na entrada do ID do dispositivo é o assassino silencioso aqui. Se o tópico do emissor for `plant-3/line-a/EM 4492/data` (contendo um espaço) e o ID do dispositivo foi introduzido como `EM 4492`, a plataforma armazenou uma string normalizada que já não corresponde. Elimine espaços em branco dos identificadores de dispositivos — use hífenes ou underscores. Recrie o registo do dispositivo com o identificador normalizado.
Para verificar o que o emissor está realmente a enviar:
```bash
# Para Z2M:
docker compose logs zigbee2mqtt | grep "MQTT publish" | grep -v bridge | tail -5
# Para outros gateways: subscreva-se diretamente no broker
mosquitto_sub -h {broker} -p {port} -t '#' -v
```
O tópico mostrado nessas linhas de saída é o tópico com o qual o seu padrão de tópico do ID do dispositivo e o campo ID do dispositivo têm de corresponder.
## Fase 4 — A coluna Value do separador Mapping é atualizada, mas o separador Logs está vazio
**Sintoma:** Abra um dispositivo registado. O separador Mapping mostra valores em tempo real e carimbos de data/hora da Última atualização. O separador Logs está vazio.
Esta é a confusão operacional mais comum ao colocar em funcionamento um novo dispositivo MQTT. Os dois separadores leem de armazenamentos diferentes:
* **coluna Valor do separador Mapping** = instantâneo em tempo real da carga útil mais recente. Atualiza a cada publish aceite, independentemente de as chaves do Conector estarem preenchidas.
* **Separador Registos** = histórico por sensor, preenchido apenas pelos publishes recebidos *depois* as chaves do Conector são guardadas.
Se o publish mais recente chegou antes de as chaves do Conector serem guardadas, esse publish nunca chega aos Logs. Os publishes mais antigos não são normalizados retroativamente.
Resolução: gere um publish novo depois de guardar as chaves do Conector. Métodos:
* **Aguarde o próximo relatório agendado do dispositivo** — para sensores com uma cadência periódica de publish.
* **Acione uma alteração de estado no dispositivo** — para atuadores com semântica COV na alteração de estado.
* **Emita um pedido de poll a partir do gateway** — para gateways com um `/get`mecanismo de leitura/poll do tipo.
* **Envie um publish de teste a partir do lado do broker** — para cenários de desenvolvimento, `mosquitto_pub` para o tópico do dispositivo com uma carga útil representativa.
Depois de pelo menos um publish chegar após o guardado, o separador Logs é preenchido e continua a receber tráfego subsequente.
## Fase 5 — valores nulos na coluna Valor do separador Mapping
**Sintoma:** As chaves do Conector estão mapeadas, o separador Logs está a receber dados, mas valores de métricas específicos aparecem como nulos no separador Mapping.
A causa mais comum: o Tipo do modelo de métrica não corresponde ao tipo do valor publicado. Por exemplo, mapear um campo Z2M `estado` campo (`"ON"`/`"OFF"` strings) para um modelo de métrica tipado como Boolean resulta em nulos — a plataforma não consegue analisar a string como booleano.
Verifique o separador [tradução de tipo de carga útil → Tipo de métrica](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md#payload-type--metric-type-translation):
* Enums codificados como string (p. ex., `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`) → **String**, e não Boolean.
* Z2M `binárias` funcionalidades → String. Z2M `numéricas` funcionalidades → Number. Z2M `enum` funcionalidades → String.
Resolução: edite o modelo de métrica (ou substitua a linha Mapping por uma linha que use o tipo de modelo correto) para que o Tipo corresponda ao tipo real do valor da carga útil.
## Fase 6 — Valores de métricas inconsistentes ou duplicados em vários dispositivos
**Sintoma:** parece que dois registos de dispositivos recebem a telemetria um do outro, ou um único dispositivo mostra valores alternados de diferentes origens.
Trata-se de uma colisão do padrão de tópico do ID do dispositivo. Se dois dispositivos publicam para tópicos que ambos correspondem a um único padrão de tópico do ID do dispositivo em diferentes `{{deviceId}}` valores, mas o campo ID do dispositivo num registo de dispositivo corresponde a ambos, ambos os publishes são encaminhados para esse registo.
Verifique:
* Cada registo de dispositivo tem um ID do dispositivo único.
* Os tópicos do lado do emissor produzem valores únicos na `{{deviceId}}` posição do marcador.
* Nenhum emissor está mal configurado para publicar sob o identificador de outro dispositivo.
## Repor credenciais do Cloud MQTT
Quando uma credencial precisa de ser alterada:
1. Abra a página de detalhes do conector.
2. No modo de edição, regenere a palavra-passe.
3. Registe a nova palavra-passe imediatamente; a original não pode ser recuperada após a regeneração.
4. Atualize todos os clientes emissores (configuração do firmware, Z2M `configuration.yaml`, configuração do gateway de edge) com a nova palavra-passe.
5. Reinicie os emissores para aplicarem a alteração.
O nome de utilizador e o prefixo de tópico não mudam com a alteração.
## Repor credenciais do External MQTT
Para autenticação Basic, altere a palavra-passe no lado do broker e atualize a configuração de autenticação do conector. Para Certificate (certificado de cliente TLS), volte a emitir o certificado do cliente e carregue-o novamente. Para JWT, regenere o token e atualize o conector. Em todos os casos, não existe um fluxo de rotação de credenciais do lado da plataforma — a credencial está no broker; a plataforma armazena uma referência.
## Para onde ir a seguir
* [Tópicos e encaminhamento de dispositivos](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — para detalhes da configuração de roteamento.
* [MQTT Externo](/kilo-docs-pt/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — para a configuração do broker em brokers autoalojados.
* [Gateways de edge MQTT](/kilo-docs-pt/kilo-iot-server/gateways/mqtt-edge-gateways.md) — para padrões de integração de gateways de edge industriais (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/troubleshooting.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.
