Exemplos de mosquitto_pub e mosquitto_sub: 25 Comandos Práticos para Testar MQTT

Estes exemplos de mosquitto_pub e mosquitto_sub são os comandos que você vai realmente usar ao testar dispositivos, depurar topics e automatizar MQTT com scripts. Cada um está pronto para copiar e colar e roda no servidor MQTT público (gratuito) broker.connectmq.com, então você pode verificar o comportamento por conta própria em segundos. Ao final, você saberá exercitar QoS, mensagens retidas, Last Will, TLS e propriedades do MQTT 5 pela linha de comando.

Antes de começar

Instale os clientes do Mosquitto:

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

# macOS
brew install mosquitto

# Windows: instale o Mosquitto a partir de mosquitto.org; o instalador inclui mosquitto_pub.exe e mosquitto_sub.exe

Confira com mosquitto_pub --help; a primeira linha mostra a versão. Vários exemplos abaixo exigem a versão 2.x (para -x, saída %j e algumas opções do MQTT 5). A referência completa das opções está no manual oficial do mosquitto_pub.

Três regras para o servidor MQTT público:

• Sempre informe um client ID único e não vazio com -i. Dois clientes com o mesmo ID desconectam um ao outro.
• Use um prefixo de topic exclusivo. Os exemplos usam connectmq/demo/x7q2/; troque x7q2 por uma string aleatória sua.
• O servidor MQTT público pode ser lido por qualquer pessoa e serve para testes e protótipos, não para dados de produção. Nunca publique credenciais nem dados pessoais (lembre-se da LGPD).

Para deixar os comandos curtos, defina duas variáveis de shell (bash/zsh):

H="-h broker.connectmq.com -p 1883"
T="connectmq/demo/x7q2"

Abra dois terminais: um para o mosquitto_sub e outro para o mosquitto_pub.

Exemplos básicos de mosquitto_pub e mosquitto_sub

1. Assinar um topic

mosquitto_sub $H -i sub-x7q2 -t "$T/hello"

2. Publicar uma mensagem

mosquitto_pub $H -i pub-x7q2 -t "$T/hello" -m "hello from the CLI"

3. Assinar tudo sob o seu prefixo e imprimir os topics (-v imprime o topic antes do payload)

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v

4. Curinga de nível único: todos os topics de temperatura, de qualquer cômodo

mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -v

5. Vários filtros de topic em um único cliente

mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -t "$T/+/humidity" -v

6. Publicar JSON (as aspas simples impedem que o shell interprete as chaves e as aspas)

mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 21.8, "unit": "C"}'

No cmd.exe do Windows, escape as aspas internas: -m "{\"value\": 21.8}".

QoS e sessões

7. Publicar e assinar com QoS 1

mosquitto_sub $H -i sub-x7q2 -t "$T/alarms" -q 1 -v
mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 1 -m "door open"

O QoS efetivo é o menor entre o QoS da publicação e o da assinatura. Para o quadro completo, veja níveis de QoS do MQTT explicados.

8. Acompanhar a troca de pacotes com -d (o debug mostra CONNECT, PUBLISH, PUBACK e companhia)

mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 2 -m "test" -d

Você verá PUBLISH, PUBREC, PUBREL e PUBCOMP no QoS 2. Essa é a forma mais rápida de provar o que um broker realmente faz.

9. Sessão persistente: receber mensagens publicadas enquanto você estava offline

# Assine uma vez com um ID fixo e clean session desativada, depois Ctrl+C
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v
# Com ele parado, publique com QoS 1
mosquitto_pub $H -i pub-x7q2 -q 1 -t "$T/queue" -m "queued while offline"
# Reconecte com o mesmo ID e -c: a mensagem é entregue
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v

10. Expiração de sessão do MQTT 5 (mantém a sessão por 300 segundos após a desconexão)

mosquitto_sub $H -V 5 -i sub-persist-x7q2 -c -x 300 -q 1 -t "$T/queue" -v

O servidor MQTT público mantém as sessões por no máximo 30 minutos.

Mensagens retidas

11. Publicar um estado retido

mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -m "running"

Qualquer novo assinante recebe running imediatamente, sem esperar a próxima publicação.

12. Mostrar apenas as mensagens retidas e sair

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v --retained-only -W 3

-W 3 sai após 3 segundos, prático para scripts que tiram um retrato do estado atual.

13. Ignorar mensagens retidas antigas (-R descarta mensagens que chegam com a flag retain ativa)

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v -R

14. Apagar uma mensagem retida (publique um payload retido vazio)

mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -n

15. Limpar todas as mensagens retidas sob o seu prefixo

mosquitto_sub $H -i cleaner-x7q2 -t "$T/#" --remove-retained --retained-only -W 3

Use com cuidado em qualquer broker; isso remove o estado retido de tudo o que o filtro corresponder.

Last Will and Testament

16. Registrar um Last Will que marca o cliente como offline

mosquitto_sub $H -i device-x7q2 -t "$T/device1/cmd" \
  --will-topic "$T/device1/status" --will-payload "offline" --will-retain --will-qos 1

Em outro terminal, acompanhe o status com mosquitto_sub $H -i watch-x7q2 -t "$T/device1/status" -v e depois mate o primeiro processo de forma abrupta (feche o terminal ou use kill -9). Quando o keep-alive expirar, o broker publica offline. Um Ctrl+C limpo envia DISCONNECT e não dispara a Will. Defina um keep-alive curto com -k 10 para ver isso mais rápido.

Scripts e controle da saída

17. Receber exatamente N mensagens e sair

mosquitto_sub $H -i sub-x7q2 -t "$T/kitchen/temperature" -C 1

Ótimo em scripts de shell: TEMP=$(mosquitto_sub ... -C 1).

18. Formato de saída personalizado com timestamps

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "@Y-@m-@dT@H:@M:@S %t %p"

19. Saída JSON para encaminhar ao jq

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "%j" | jq -c '{topic, payload}'

20. Publicar cada linha de um arquivo ou do stdin como uma mensagem separada

printf '20.1\n20.4\n20.9\n' | mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -l

Use -f firmware.bin para enviar um arquivo inteiro como uma única mensagem, ou -s para enviar todo o stdin como uma única mensagem. O servidor MQTT público limita as mensagens a 64 KB.

21. Um pequeno simulador de sensor (respeite o limite público de 10 mensagens por segundo por cliente)

while true; do
  mosquitto_pub $H -i sim-x7q2 -t "$T/lab/temperature" \
    -m "{\"value\": $((RANDOM % 10 + 20)), \"ts\": $(date +%s)}"
  sleep 1
done

TLS e autenticação

22. Conexão criptografada na porta 8883

# Linux: use o bundle de CA do sistema
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i tls-x7q2 -t "$T/#" -v

No macOS ou no Windows, aponte --cafile para um arquivo PEM com o certificado ISRG Root X1 (Let's Encrypt), já que esses sistemas não expõem um diretório PEM. Se aparecer Error: A TLS error occurred, confira o caminho do arquivo de CA e o relógio do sistema.

23. Broker privado com credenciais

mosquitto_pub -h YOUR_BROKER_HOST -p 8883 --capath /etc/ssl/certs \
  -i YOUR_CLIENT_ID -u YOUR_USERNAME -P YOUR_PASSWORD \
  -t "factory1/line1/cnc1/telemetry" -q 1 -m '{"spindle_rpm": 8000}'

Evite deixar senhas no histórico do shell em ambientes compartilhados. O Mosquitto 2.x lê opções de um arquivo de configuração: coloque as linhas -u e -P em ~/.config/mosquitto_pub (e mosquitto_sub) com permissões restritas.

Propriedades do MQTT 5

24. Content type, user property e expiração de mensagem

mosquitto_pub $H -V 5 -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 22}' \
  -D PUBLISH content-type application/json \
  -D PUBLISH user-property source cli-test \
  -D PUBLISH message-expiry-interval 60

Veja as propriedades no lado do assinante com -V 5 -F "%t %p | %P" (%P imprime as user properties). O guia de recursos do MQTT 5 explica quando cada propriedade é útil.

25. Requisição/resposta com mosquitto_rr

# Responder: lê o response topic (%R) de cada requisição e responde
while true; do
  RT=$(mosquitto_sub $H -V 5 -i resp-x7q2 -t "$T/rpc/time" -C 1 -F "%R")
  mosquitto_pub $H -V 5 -i resp-pub-x7q2 -t "$RT" -m "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
done &

# Requester: define o response topic, espera uma resposta e a imprime
mosquitto_rr $H -V 5 -i req-x7q2 -t "$T/rpc/time" -e "$T/rpc/time/reply" -m "now?" -W 5

O mosquitto_rr define o response topic do MQTT 5 na requisição, assina esse topic e imprime a primeira resposta. O responder em shell basta para uma demonstração; um serviço real em Python ou Node também devolveria os correlation data para que requisições simultâneas pudessem ser associadas às respostas.

Referência rápida de opções

Solução de problemas

• Connection Refused: identifier rejected: client ID vazio ou inválido. Informe -i com um valor único.
• A conexão cai logo após conectar: outro processo está usando o mesmo client ID.
• Error: Connection refused na porta 8883: você esqueceu --capath ou --cafile, então o cliente tentou TCP simples em uma porta TLS.
• Nada chega: compare o filtro de assinatura e o topic de publicação caractere por caractere; topics MQTT diferenciam maiúsculas de minúsculas, e uma / inicial cria um nível vazio extra.
• As mensagens param após uma rajada: limites do servidor MQTT público (10 mensagens por segundo por cliente, 10 assinaturas por cliente, 8 níveis de topic).

Dos testes à produção

O servidor MQTT público é perfeito para aprender esses comandos, mas dispositivos em campo, seja numa usina ou numa fazenda, precisam de credenciais privadas e isolamento. Um broker MQTT gerenciado da ConnectMQ oferece TLS na 8883, WebSocket na 8083 e 8084, MQTT 3.1.1 e 5.0 e credenciais geradas por broker; todos os comandos acima funcionam trocando pelas flags do exemplo 23. Para outras opções de linha de comando, leia a comparação de ferramentas CLI para MQTT e, se preferir uma interface gráfica, veja os apps desktop de exploração MQTT. O guia de bibliotecas de cliente MQTT mostra como levar esses testes para o código.

Comece a usar a ConnectMQ

Crie um broker privado em app.connectmq.com no plano Serverless gratuito, sem cartão de crédito. Copie o usuário, a senha e o client ID gerados para os exemplos 22 e 23 e use o explorador de topics em tempo real do portal junto com o mosquitto_sub para confirmar cada mensagem.

Perguntas frequentes

Por que o mosquitto_sub não mostra nada quando eu publico?

Na maioria das vezes o filtro de topic não corresponde: confira maiúsculas e minúsculas, barras e curingas. Garanta também que os dois clientes usem client IDs diferentes e adicione -d para ver se a assinatura foi concedida.

Como envio uma mensagem sem payload com o mosquitto_pub?

Use -n. Combinado com -r, ele apaga a mensagem retida daquele topic.

O mosquitto_pub pode usar MQTT 5?

Sim, a partir do Mosquitto 1.6. Adicione -V 5 (ou -V mqttv5) e defina as propriedades com -D <command> <property> <value>.

Preciso do broker Mosquitto instalado para usar esses comandos?

Não. O pacote mosquitto-clients contém apenas os clientes de linha de comando, e eles funcionam com qualquer broker MQTT, incluindo a ConnectMQ.