Intervalo de Keep Alive MQTT: Como Escolher o Valor Certo

O intervalo de keep alive MQTT é o número de segundos durante os quais um cliente promete nunca ficar em silêncio, e é a principal ferramenta que um broker tem para identificar conexões mortas. Neste guia você vai entender exatamente como funcionam o PINGREQ, o PINGRESP e a regra de timeout de 1,5x, como o keep alive interage com roteadores NAT, links celulares e duração da bateria e com quais valores começar nos seus dispositivos.

O Que o Intervalo de Keep Alive MQTT Realmente Faz

Quando um cliente envia o CONNECT, ele inclui um campo Keep Alive de dois bytes, medido em segundos. O valor é um contrato: "vou enviar algum pacote de controle para você pelo menos uma vez nesse período". Qualquer pacote conta, seja um PUBLISH, um SUBSCRIBE ou um PUBACK. Só quando o cliente não tem mais nada para enviar ele recorre a um pequeno pacote PINGREQ, e o broker responde com PINGRESP.

O keep alive existe porque o próprio TCP é ruim em perceber pares mortos. Se um dispositivo perde energia ou o modem celular sai da rede, nenhum pacote FIN ou RST é enviado. Do ponto de vista do broker, o socket continua "aberto" para sempre, e qualquer assinante esperando o Last Will and Testament do dispositivo também espera para sempre. O keep alive dá um prazo aos dois lados.

A Regra de Timeout de 1,5x

A especificação MQTT diz que, se o broker não receber nada de um cliente dentro de uma vez e meia o intervalo de keep alive, ele deve fechar a conexão de rede como se ela tivesse falhado. Isso significa:

O cliente também tem a sua parte do acordo. Se ele envia PINGREQ e não recebe PINGRESP dentro de um "tempo razoável" (a maioria das bibliotecas usa o próprio valor de keep alive ou um timeout fixo), deve considerar a conexão quebrada e reconectar. É assim que um cliente descobre um socket meio aberto do seu lado.

O Que Acontece Quando o Timeout Dispara

Quando o broker fecha uma conexão por causa do keep alive, ele a trata como uma desconexão anormal. Consequências práticas:

1. A mensagem de will do cliente é publicada (depois do will delay, se você definiu um no MQTT 5; veja will delay interval MQTT).
2. Se o cliente tinha uma sessão persistente, o broker mantém as assinaturas dele e começa a enfileirar mensagens QoS 1 e QoS 2 para ele.
3. Topics de status online e dashboards passam para "offline".

O keep alive, portanto, controla diretamente a rapidez com que o seu sistema descobre que algo deu errado.

Escolhendo um Valor de Keep Alive MQTT

Não existe um número universalmente correto. Você está trocando velocidade de detecção por tráfego e energia.

Velocidade de Detecção

Um intervalo menor significa que o broker e os assinantes ficam sabendo das falhas mais rápido. Se um dashboard de operação precisa mostrar uma máquina como offline em até meio minuto, um keep alive de 60 segundos (detecção em 90 segundos) não atende ao requisito, enquanto 15 ou 20 segundos atendem.

Timeouts de Ociosidade de NAT e Firewall

Esta é a armadilha que pega a maioria das equipes. Roteadores domésticos, firewalls corporativos, load balancers na nuvem e principalmente os gateways NAT das operadoras móveis descartam mapeamentos TCP que ficaram ociosos por algum tempo. Quando o mapeamento some, o próximo pacote do cliente não chega a lugar nenhum, e o broker só percebe no prazo de 1,5x. Se o seu keep alive for maior do que o menor timeout de ociosidade de NAT no caminho, você terá desconexões misteriosas a cada poucos minutos. Os timeouts de NAT das operadoras variam muito e nem sempre são documentados, então em links celulares é mais seguro ficar bem abaixo de alguns minutos.

Bateria e Consumo de Dados

Cada ida e volta de PINGREQ/PINGRESP tem apenas 2 bytes de MQTT em cada sentido, mais o overhead de TCP/IP (e de registro TLS). Em Wi-Fi isso é irrelevante. Em um dispositivo celular alimentado por bateria, o custo está principalmente nos despertares do rádio, não nos bytes: cada ping pode manter o modem em estado de alto consumo por segundos. Para esses dispositivos, avalie se você realmente precisa de uma conexão permanente ou se é melhor acordar, publicar e desconectar usando uma sessão persistente.

Um Ponto de Partida Prático

• Dispositivos ligados à tomada em Wi-Fi ou Ethernet: 60 segundos.
• Dashboards e clientes de navegador via WebSocket: 30 segundos.
• Gateways celulares, comuns em fazendas, mineradoras e estações de saneamento: 60 a 120 segundos, reduzindo se aparecerem quedas inexplicáveis.
• Serviços de backend na mesma região de nuvem: 30 a 60 segundos.
• Nunca use 0 em produção; isso elimina totalmente a detecção de conexões mortas.

Configurando o Intervalo de Keep Alive nos Clientes Mais Comuns

Você pode testar todos estes exemplos no servidor MQTT público em broker.connectmq.com. Use um client ID único e um prefixo de topic único, e lembre-se de que a área pública pode ser lida por qualquer pessoa.

mosquitto_sub e mosquitto_pub

# Assina com keep alive de 30 segundos e saída de depuração para ver PINGREQ/PINGRESP
mosquitto_sub -h broker.connectmq.com -p 1883 -i ka-demo-7f3a \
  -k 30 -d -t 'connectmq/demo/7f3a/#'

Com -d você verá linhas como Client ka-demo-7f3a sending PINGREQ e received PINGRESP a cada 30 segundos enquanto o topic estiver em silêncio.

Python (paho-mqtt 2.x)

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    print("Connected:", reason_code)
    client.subscribe("connectmq/demo/7f3a/#", qos=1)

def on_disconnect(client, userdata, flags, reason_code, properties):
    print("Disconnected:", reason_code)

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="ka-python-7f3a",
    protocol=mqtt.MQTTv5,
)
client.on_connect = on_connect
client.on_disconnect = on_disconnect

# keepalive é o terceiro argumento, em segundos
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_forever()

O paho envia PINGREQ automaticamente a partir do seu loop de rede. Se você bloquear o loop (por exemplo, com um time.sleep longo dentro de um callback), os pings param e o broker derruba você depois de 1,5x o intervalo.

Node.js (MQTT.js v5)

const mqtt = require("mqtt");

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "ka-node-7f3a",
  protocolVersion: 5,
  keepalive: 45,          // segundos
  reconnectPeriod: 5000,  // ms entre tentativas de reconexão
});

client.on("connect", () => console.log("connected"));
client.on("close", () => console.log("connection closed"));
client.on("error", (err) => console.error(err.message));

ESP32 (PubSubClient)

O PubSubClient usa 15 segundos por padrão. Altere esse valor antes de chamar connect() com client.setKeepAlive(60); e garanta que client.loop() seja executado com frequência no seu sketch, porque os pings só são enviados de dentro de loop(). Chamadas longas de delay() são o motivo mais comum para placas ESP32 caírem em intervalos regulares. Um sketch de ESP32 bem estruturado usa um loop não bloqueante com timers baseados em millis() para evitar isso.

Server Keep Alive no MQTT 5

O MQTT 5 permite que o broker substitua o valor pedido pelo cliente. Se o CONNACK contiver uma property Server Keep Alive, o cliente deve usar esse valor em vez do seu. Os brokers fazem isso para impor um intervalo mínimo ou máximo em uma plataforma compartilhada. A maioria das bibliotecas aplica o valor silenciosamente, então, se você notar pings em uma frequência diferente da configurada, registre as properties do CONNACK no log. No paho você pode imprimir properties em on_connect; o MQTT.js as expõe no pacote connack passado ao evento connect.

Resolvendo Problemas de Keep Alive

Use este checklist quando os clientes desconectarem em intervalos suspeitamente regulares:

1. Meça o intervalo. Se as desconexões acontecem cerca de 1,5x o seu keep alive após a última atividade, o cliente não está enviando pings. Procure um loop de rede bloqueado.
2. Verifique uma queda fixa por ociosidade. Se as quedas acontecem após um número constante de minutos, independentemente do keep alive, um NAT ou firewall está expirando a conexão. Reduza o intervalo para abaixo desse valor.
3. Procure client IDs duplicados. Dois clientes com o mesmo ID derrubam um ao outro, o que parece um problema de keep alive, mas não é. Veja boas práticas de client ID MQTT.
4. Fique atento a callbacks single-thread. Trabalho pesado dentro de on_message atrasa o PINGREQ. Mova o processamento para uma thread de trabalho ou fila.
5. Confirme que os handshakes TLS terminam. Em dispositivos limitados, uma reconexão TLS lenta pode empurrar o próximo ping para além do prazo.
6. Ative o log de depuração na sua biblioteca e compare os timestamps do cliente com os eventos de conexão do broker.

Em um broker ConnectMQ você também pode acompanhar $SYS/broker/connection/{clientId}/state para ver exatamente quando o broker considera um cliente conectado ou desconectado, o que facilita correlacionar com os logs do dispositivo. O cliente MQTT no navegador do portal é uma forma rápida de assinar esse topic sem instalar nada.

Keep Alive, Sessões e Last Will Trabalhando Juntos

O keep alive é uma peça de um design de confiabilidade maior. Um padrão sensato para produção é assim:

• Um keep alive curto o bastante para vencer os timeouts de NAT e atender à sua meta de detecção.
• Uma mensagem retida "online" publicada na conexão, mais uma mensagem de will retida "offline".
• Uma sessão persistente para que mensagens QoS 1 publicadas enquanto o dispositivo reconecta não se percam.
• Backoff exponencial na reconexão, para que um reinício do broker não vire uma avalanche de reconexões simultâneas.

O tutorial de MQTT cobre esses blocos desde o início, se você quiser o contexto mais amplo.

Comece com a ConnectMQ

A ConnectMQ é um broker MQTT gerenciado que suporta MQTT 3.1.1 e 5.0 sobre TCP, TLS, WebSocket e WebSocket seguro, então você pode testar qualquer estratégia de keep alive nos mesmos endpoints que usará em produção. Quando estiver pronto para ir além do servidor MQTT público, crie um broker Serverless gratuito sem cartão de crédito, copie as credenciais geradas e acompanhe o estado das conexões ao vivo no portal. Se ainda estiver comparando opções, nosso guia sobre como escolher um broker MQTT na nuvem analisa os prós e contras.

Perguntas frequentes

Qual é um bom intervalo de keep alive MQTT padrão?

60 segundos é um bom padrão para a maioria dos dispositivos ligados à tomada. Reduza para 15 a 30 segundos se precisar de detecção de offline mais rápida ou se um dispositivo NAT no caminho derrubar conexões ociosas antes disso.

Qualquer pacote MQTT reinicia o timer de keep alive?

Sim. Qualquer pacote de controle que o cliente envia, incluindo PUBLISH e PUBACK, conta como atividade. O PINGREQ só é enviado quando o cliente ficou ocioso durante todo o intervalo.

O que acontece se eu definir o keep alive como 0?

O keep alive fica desativado, então o broker nunca fecha por conta própria uma conexão silenciosa. Dispositivos mortos podem aparecer como conectados indefinidamente e as mensagens de will deles podem nunca ser enviadas, por isso evite 0 em produção.

Por que meu cliente desconecta exatamente a cada poucos minutos?

Um intervalo constante, independentemente da configuração de keep alive, normalmente aponta para um timeout de ociosidade de NAT ou firewall. Defina o keep alive abaixo desse timeout para que os pings mantenham o mapeamento ativo.

O broker pode alterar meu valor de keep alive?

No MQTT 5, sim. O broker pode retornar uma property Server Keep Alive no CONNACK, e o cliente deve usar esse valor em vez do que solicitou.