Tutorial MQTT: O Guia Completo de MQTT para Iniciantes

Este tutorial MQTT leva você do zero a uma configuração publish/subscribe funcionando em uma única sessão. Você vai aprender os poucos conceitos que fazem o MQTT funcionar e, em seguida, executar cada etapa de verdade no servidor MQTT público gratuito broker.connectmq.com usando a linha de comando, Python e um navegador. No final, você saberá projetar topics, escolher um nível de QoS, usar retained messages e Last Will e reconhecer o momento de migrar para um broker privado.

O Que É MQTT e Por Que Aprendê-lo?

MQTT é um protocolo de mensageria publish/subscribe leve que roda sobre TCP. Ele foi projetado para redes pouco confiáveis e dispositivos pequenos, e é por isso que hoje é a língua padrão da IoT: sensores, gateways, adaptadores de CLP, aplicativos móveis e serviços de backend falam MQTT, seja em uma usina, em uma fazenda ou em uma planta em Manaus. As versões atuais são MQTT 3.1.1 e MQTT 5.0, ambas padronizadas pela OASIS (o texto completo está publicado em mqtt.org).

Três características explicam sua popularidade:

• Overhead mínimo. O cabeçalho fixo de um pacote pode ter apenas dois bytes, então o MQTT funciona em links celulares, satélite e Wi-Fi congestionado.
• Desacoplamento. Publishers nunca falam diretamente com subscribers. Eles não precisam conhecer o endereço IP um do outro e nem precisam estar online ao mesmo tempo.
• Push, não polling. Depois que um cliente assina um topic, os dados chegam no instante em que são publicados. Não existe um loop de requisições gastando bateria e banda.

Se quiser entender o fluxo de pacotes em detalhes antes de colocar a mão na massa, leia como o MQTT funciona por dentro. Caso contrário, siga em frente: os conceitos abaixo bastam para construir sistemas reais.

Os Conceitos Essenciais em Cinco Minutos

Broker

O broker é o servidor no meio do caminho. Cada cliente abre uma conexão TCP de longa duração com ele, e o broker roteia cada mensagem publicada para todos os clientes cuja assinatura corresponde. Ele também controla sessões, guarda retained messages e dispara mensagens de Last Will. Para uma explicação completa sobre o que um broker MQTT faz, incluindo como ele difere de uma fila de mensagens, veja nosso guia dedicado.

Clientes

Tudo o que se conecta ao broker é um cliente: um ESP32, um script Python, um fluxo do Node-RED, um dashboard no navegador. Um cliente pode publicar, assinar ou ambos. Cada conexão carrega um client ID, que o broker usa para identificar a sessão. Dois clientes com o mesmo ID derrubam um ao outro, então sempre use um ID único.

Topics

Um topic é uma string UTF-8 com níveis separados por barras, por exemplo factory1/line2/press3/temperature. Topics não são criados previamente; eles passam a existir no momento em que alguém publica neles. Um bom projeto de topics é a decisão mais importante de um projeto MQTT, por isso tratamos do assunto em detalhes em convenções de nomenclatura de topics MQTT.

Publish e Subscribe

Um publisher envia uma mensagem para um topic. Um subscriber registra interesse em um filtro de topic. O broker faz a correspondência entre os dois. Esse é o modelo publish/subscribe, e é ele que permite adicionar um novo dashboard ou um novo gravador de banco de dados sem mexer em um único dispositivo.

Wildcards

Subscribers podem usar dois wildcards:

• + corresponde a exatamente um nível: factory1/+/press3/temperature
• # corresponde a todos os níveis restantes e deve ser o último: factory1/#

Publishers nunca podem usar wildcards. As regras completas de correspondência, incluindo casos especiais dos topics $SYS, estão no nosso guia sobre wildcards MQTT.

Passo 1: Escolha um Broker para Este Tutorial MQTT

Você precisa de um broker para conversar. Instalar um localmente funciona, mas acrescenta firewall, portas e gerenciamento de serviços à sua primeira hora. O caminho mais rápido é um servidor MQTT público. Neste tutorial usamos o broker.connectmq.com, o servidor MQTT público (gratuito) mantido pela ConnectMQ. Ele aceita conexões anônimas em todas as portas padrão:

Regras que vale conhecer antes de começar:

1. Use um client ID não vazio e único em cada conexão.
2. Prefixe todos os topics com algo que ninguém mais vá usar, como connectmq/demo/<random-id>/. Escolha seu ID aleatório agora, por exemplo a7k2q9.
3. Tudo na área pública pode ser lido por qualquer pessoa. Nunca publique senhas, dados pessoais ou qualquer informação sensível.
4. O servidor MQTT público tem limites: 64 KB por mensagem, 10 mensagens por segundo por cliente, 10 assinaturas por cliente, até 8 níveis de topic e sessões que expiram em no máximo 30 minutos. São generosos para aprender e intencionalmente pequenos demais para produção.

Se quiser entender por que essas quatro portas existem e qual escolher atrás de um firewall corporativo, leia portas MQTT explicadas.

Passo 2: Seu Primeiro Publish e Subscribe pela Linha de Comando

Os clientes de linha de comando do Mosquitto são a forma mais simples de ver o MQTT funcionando. Instale-os com o seu gerenciador de pacotes:

# Debian / Ubuntu / Raspberry Pi OS
sudo apt install mosquitto-clients

# macOS (Homebrew)
brew install mosquitto

No Windows, o instalador do projeto Mosquitto inclui mosquitto_pub.exe e mosquitto_sub.exe.

Abra um terminal e assine tudo sob o seu prefixo. A flag -v imprime o topic ao lado de cada payload:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/#" -v

Abra um segundo terminal e publique:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/temperature" -m "21.5"

O primeiro terminal imprime connectmq/demo/a7k2q9/room1/temperature 21.5 imediatamente. Esse é todo o ciclo do MQTT: conectar, assinar, publicar, receber.

Agora teste a porta criptografada. Como o broker.connectmq.com usa um certificado Let's Encrypt, o pacote de CAs do seu sistema consegue validá-lo:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i pub-tls-a7k2q9 -t "connectmq/demo/a7k2q9/room1/humidity" -m "48"

No macOS ou no Windows, aponte --cafile para um arquivo de pacote de CAs em vez de usar --capath.

Passo 3: QoS, Retained Messages e Last Will

Esses três recursos são o que diferencia o MQTT de um socket simples. Experimente cada um agora.

Quality of Service

Cada publish e cada assinatura carregam um nível de QoS:

O QoS efetivo para um subscriber é o menor entre o QoS do publish e o QoS da assinatura. Publique com -q 1 e assine com -q 1 para ver a entrega confirmada. Nosso guia sobre como escolher entre QoS 0, 1 e 2 analisa os trade-offs com cenários reais de falha.

Retained Messages

Uma retained message é armazenada pelo broker como o "último valor conhecido" de um topic e entregue instantaneamente a qualquer novo subscriber. Publique uma:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 -r \
  -t "connectmq/demo/a7k2q9/room1/setpoint" -m "22"

Agora inicie um novo subscriber. Ele recebe 22 imediatamente, mesmo que nada tenha sido publicado depois que ele se conectou. Para limpar uma retained message, publique um payload vazio com a flag retain: -r -n. Mais padrões, incluindo quando retained messages causam confusão, estão em retained messages MQTT.

Last Will and Testament

Quando um cliente se conecta, ele pode registrar uma mensagem de "testamento". Se o cliente desaparecer sem uma desconexão limpa (queda de energia, perda de rede, travamento), o broker publica o testamento em nome dele. Combine isso com uma mensagem "online" retida e você terá uma detecção de presença de dispositivos confiável:

mosquitto_sub -h broker.connectmq.com -p 1883 -i dev-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/cmd" \
  --will-topic "connectmq/demo/a7k2q9/room1/status" \
  --will-payload "offline" --will-retain --will-qos 1 -k 10

Encerre esse processo pelo botão de fechar do terminal (não com Ctrl+C, que em algumas builds ainda pode enviar uma desconexão limpa) e veja offline chegar ao seu subscriber com wildcard depois de aproximadamente um intervalo e meio de keep-alive.

Passo 4: O Mesmo Tutorial MQTT em Python

A linha de comando é ótima para explorar; projetos reais usam uma biblioteca. Instale o paho-mqtt 2.x:

pip install "paho-mqtt>=2.0"

Este script se conecta com MQTT 5, assina seu próprio topic de comandos, publica uma leitura a cada cinco segundos e anuncia sua presença com um status retido e um Last Will:

import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

BROKER = "broker.connectmq.com"
PREFIX = "connectmq/demo/a7k2q9"
CLIENT_ID = f"tutorial-py-{uuid.uuid4().hex[:8]}"


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Connect failed: {reason_code}")
        return
    print("Connected as", CLIENT_ID)
    client.publish(f"{PREFIX}/room1/status", "online", qos=1, retain=True)
    client.subscribe(f"{PREFIX}/room1/cmd", qos=1)


def on_message(client, userdata, msg):
    print(f"Command on {msg.topic}: {msg.payload.decode()}")


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


client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id=CLIENT_ID,
    protocol=mqtt.MQTTv5,
)
client.will_set(f"{PREFIX}/room1/status", "offline", qos=1, retain=True)
client.on_connect = on_connect
client.on_message = on_message
client.on_disconnect = on_disconnect

client.tls_set()  # valida o certificado Let's Encrypt com as CAs do sistema
client.connect(BROKER, 8883, keepalive=30)
client.loop_start()

try:
    while True:
        reading = {"temperature": round(random.uniform(19, 24), 2), "ts": int(time.time())}
        client.publish(f"{PREFIX}/room1/telemetry", json.dumps(reading), qos=1)
        time.sleep(5)
except KeyboardInterrupt:
    client.publish(f"{PREFIX}/room1/status", "offline", qos=1, retain=True).wait_for_publish()
    client.disconnect()
    client.loop_stop()

Deixe o terminal do mosquitto_sub rodando e você verá a telemetria chegando. Envie um comando de volta com mosquitto_pub -t "connectmq/demo/a7k2q9/room1/cmd" -m "reboot" e o script vai imprimi-lo. Repare nos detalhes do paho 2.x: CallbackAPIVersion.VERSION2 é obrigatório, e os callbacks recebem os argumentos reason_code e properties. Misturar exemplos antigos da versão 1.x é a causa de erro mais comum aqui.

Passo 5: MQTT no Navegador com WebSocket

Navegadores não conseguem abrir sockets TCP puros, então falam MQTT sobre WebSocket. Salve isto como index.html e abra em qualquer navegador moderno:

// Carregue primeiro o MQTT.js a partir de uma CDN no seu HTML:
// <script src="https://unpkg.com/mqtt@5.10.1/dist/mqtt.min.js"></script>

const clientId = "tutorial-web-" + Math.random().toString(16).slice(2, 10);
const prefix = "connectmq/demo/a7k2q9";

const client = mqtt.connect("wss://broker.connectmq.com:8084/mqtt", {
  clientId,
  protocolVersion: 5,
  clean: true,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected", clientId);
  client.subscribe(`${prefix}/#`, { qos: 1 });
  client.publish(`${prefix}/room1/cmd`, "hello from the browser", { qos: 1 });
});

client.on("message", (topic, payload) => {
  console.log(topic, payload.toString());
});

client.on("error", (err) => console.error("MQTT error", err.message));

Abra o console do desenvolvedor e você verá a telemetria do Python, o setpoint e o status retidos e o seu próprio comando ecoado de volta. A porta 8084 com o caminho /mqtt é a que deve ser usada em páginas HTTPS, porque os navegadores bloqueiam conexões WebSocket inseguras a partir de origens seguras. Nosso guia de MQTT sobre WebSocket aborda proxies, frameworks e autenticação no navegador.

Projetando Topics e Payloads que Escalam

Depois que as mensagens começam a fluir, é o projeto que decide se o sistema continuará fácil de manter. Algumas regras que se sustentam na prática:

1. Vá do geral para o específico. site/area/line/device/measurement permite assinar uma linha inteira com um único wildcard.
2. Não comece com barra. /factory/line1 cria um primeiro nível vazio que complica todos os filtros.
3. Mantenha os identificadores estáveis. Use IDs de dispositivo, não nomes amigáveis que vão mudar.
4. Separe dados de comandos. .../telemetry, .../status e .../cmd devem ser topics distintos, para que permissões e QoS possam ser diferentes.
5. Escolha um único formato de payload. JSON é legível e fácil de depurar; formatos binários como Protobuf economizam banda em links limitados. Seja qual for a escolha, inclua timestamp e unidades.
6. Evite um topic por leitura. Publicar dez valores em dez topics a cada segundo multiplica o overhead de pacotes; um pequeno objeto JSON costuma ser melhor.

Em sistemas industriais, uma hierarquia alinhada à ISA-95 (empresa, site, área, linha, célula) virou uma convenção comum, e ela é a base do padrão Unified Namespace explicado em Sparkplug B e o Unified Namespace.

Erros Comuns de Iniciantes e Como Corrigi-los

Do Tutorial à Produção

Um servidor MQTT público é ideal para aprender e nada mais. Antes de colocar dispositivos reais no ar, você precisa de credenciais privadas, TLS em tudo, isolamento em relação a outros usuários e limites dimensionados para a sua frota. Você pode operar o seu próprio broker, mas aí passa a ser responsável por patches, certificados, monitoramento e planejamento de capacidade. Um broker MQTT gerenciado transfere esse trabalho para o provedor.

Com a ConnectMQ, a migração é basicamente uma mudança de configuração. Cadastre-se, escolha um plano, crie um broker e o portal gera para você um nome de usuário, uma senha e um client ID. O mesmo código deste tutorial funciona depois que você adiciona as credenciais:

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="YOUR_CLIENT_ID",
    protocol=mqtt.MQTTv5,
)
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.connect("broker.connectmq.com", 8883, keepalive=30)

O portal também inclui um cliente MQTT no navegador e um explorador de topics em tempo real, para que você possa repetir cada etapa deste tutorial no seu broker privado sem instalar nada. Para comparar as opções de implantação, de um nível serverless compartilhado a um cluster dedicado ou à sua própria conta de nuvem, leia nosso guia sobre como escolher um broker MQTT na nuvem. Depois, siga as boas práticas de segurança MQTT antes de conectar o primeiro dispositivo em campo.

Sua Trilha de Aprendizado Depois Deste Tutorial

Comece com a ConnectMQ

Você acabou de usar todos os recursos essenciais do MQTT no servidor MQTT público. Quando estiver pronto para topics privados e dispositivos reais, crie um broker MQTT gerenciado gratuito em app.connectmq.com. O plano Serverless (Free) não exige cartão de crédito, suporta MQTT 3.1.1 e 5.0 sobre TCP, TLS e WebSocket e oferece até 25 conexões para você construir seu primeiro projeto. Suas credenciais da ConnectMQ entram diretamente no código acima.

Perguntas frequentes

MQTT é difícil de aprender?

Não. O modelo central se resume a clientes, um broker, topics e publish/subscribe, e você consegue enviar sua primeira mensagem em menos de cinco minutos com a CLI. A profundidade vem depois, com sessões, trade-offs de QoS e projeto de topics.

Preciso instalar um broker para seguir este tutorial MQTT?

Não. Todas as etapas rodam no broker.connectmq.com, que aceita conexões anônimas. Você só precisa das ferramentas de cliente do Mosquitto, de Python ou de um navegador.

Devo aprender MQTT 3.1.1 ou MQTT 5?

Aprenda os conceitos uma vez; eles são os mesmos nas duas versões. Use MQTT 5 em projetos novos, porque ele adiciona reason codes, expiração de mensagens, assinaturas compartilhadas e user properties, mantendo a compatibilidade com brokers que suportam as duas versões.

O servidor MQTT público é seguro para dados reais?

Não. Qualquer coisa na área pública pode ser lida por qualquer pessoa, então use-o apenas para testes e demonstrações. Dados reais devem ficar em um broker privado com credenciais e TLS.

O que devo construir depois deste tutorial?

Conecte um sensor real com um ESP32 ou um Raspberry Pi, armazene as leituras em um banco de dados com um pequeno script subscriber e construa um dashboard sobre WebSocket. Cada uma dessas etapas reutiliza exatamente o que você aprendeu aqui.