Configuração de bridge Mosquitto: encaminhe topics locais para um broker na nuvem via TLS

Uma boa configuração de bridge Mosquitto permite que um broker local em um Raspberry Pi continue atendendo os dispositivos da rede local enquanto encaminha exatamente os topics que você escolher para um broker na nuvem. Neste tutorial você vai montar uma bridge que se conecta ao ConnectMQ via TLS com as credenciais do portal, remapeia os topics para que cada site tenha seu próprio namespace, envia comandos de volta, enfileira mensagens durante quedas de internet e evita o clássico loop de mensagens. Cada opção é explicada, para que você adapte o arquivo em vez de copiá-lo às cegas.

Como funciona uma bridge Mosquitto

Uma bridge não é um protocolo especial. O broker Mosquitto local abre uma conexão de saída para o broker remoto e se comporta como um cliente MQTT comum: assina de um lado e republica do outro, de acordo com as linhas topic da sua configuração. Isso tem três consequências úteis:

• Nenhuma porta de entrada. O Pi se conecta para fora pela porta 8883, assim como um navegador acessando um site. Seu roteador continua fechado.
• O broker remoto não precisa de nada especial. Qualquer broker compatível com o padrão aceita uma bridge, porque ele simplesmente vê um cliente fazendo login com username, password e client ID.
• Você escolhe o que atravessa a fronteira. Somente os topics que casam com uma linha topic saem ou entram no site.

Nesta configuração, o lado remoto é o ConnectMQ, um broker MQTT gerenciado. A bridge se autentica com as credenciais geradas no portal, como qualquer outro dispositivo. Se você ainda não configurou o broker local, siga antes instalar o Mosquitto no Raspberry Pi.

 Sensors / PLC gateway / Node-RED (LAN)
          |  mqtt://pi:1883  (local users)
          v
 +---------------------------+
 |  Mosquitto on Raspberry Pi |
 |  bridge "connectmq"        |
 +---------------------------+
          |  mqtts://broker.connectmq.com:8883
          |  remote_username / remote_password / remote_clientid
          v
 +---------------------------+
 |  ConnectMQ cloud broker    |  dashboards, phones, other sites
 +---------------------------+

Antes de começar

1. Um Raspberry Pi com Mosquitto 2.0 rodando e pelo menos um listener local autenticado.
2. Um broker na nuvem com credenciais. Cadastre-se no portal, escolha um plano, crie um broker e copie o username, o password e o client ID gerados. O client ID está vinculado a essas credenciais, então a bridge precisa usá-lo exatamente como foi gerado.
3. Um plano para os nomes dos topics. Decida como os topics locais devem aparecer na nuvem. Um prefixo de site como site1/ evita que vários Pis colidam.

Para um teste rápido sem conta, você pode fazer a bridge com o servidor MQTT público na porta 1883, sem credenciais e com qualquer client ID único, usando um prefixo aleatório como connectmq/demo/3c7d52/. Tudo ali pode ser lido publicamente e serve apenas para testes, então use somente dados fictícios.

A configuração completa da bridge Mosquitto

Crie /etc/mosquitto/conf.d/bridge-connectmq.conf:

# ---- Connection ----
connection connectmq
address broker.connectmq.com:8883
bridge_protocol_version mqttv311
try_private false
start_type automatic
restart_timeout 5 60
keepalive_interval 60

# ---- TLS ----
bridge_capath /etc/ssl/certs
bridge_insecure false

# ---- Credentials from the ConnectMQ portal ----
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD

# ---- Session and queueing ----
cleansession false
local_clientid bridge-connectmq-local

# ---- Status topic (published on the remote side) ----
notifications true
notifications_local_only false
notification_topic site1/bridge/state

# ---- Topic mapping ----
# Telemetry up: local "sensors/#" -> remote "site1/sensors/#"
topic sensors/# out 1 "" site1/
# Machine states up, retained values preserved
topic machines/+/state out 1 "" site1/
# Commands down: remote "site1/cmd/#" -> local "cmd/#"
topic cmd/# in 1 "" site1/

Reinicie e acompanhe o log:

sudo chmod 0640 /etc/mosquitto/conf.d/bridge-connectmq.conf
sudo chown root:mosquitto /etc/mosquitto/conf.d/bridge-connectmq.conf
sudo systemctl restart mosquitto
sudo journalctl -u mosquitto -f

Você deve ver Connecting bridge connectmq (broker.connectmq.com:8883) sem erros em seguida. A alteração de permissões é importante porque o arquivo contém a senha remota.

Opção por opção

Entendendo a linha topic

A sintaxe é topic <pattern> <direction> <qos> <local-prefix> <remote-prefix>. O Mosquitto remove o prefixo local de um topic local e adiciona o prefixo remoto ao encaminhar para fora (out), e faz o inverso para in. Com prefixo local vazio (escrito como "") e prefixo remoto site1/:

• O topic local sensors/boiler/temp vira o remoto site1/sensors/boiler/temp.
• O topic remoto site1/cmd/pump1/set vira o local cmd/pump1/set.

Repare que o prefixo remoto termina com barra. Sem ela, você obtém site1sensors/..., um erro fácil de cometer e difícil de perceber.

QoS na bridge

O QoS em uma linha topic é o máximo usado através da bridge. QoS 1 é a escolha prática: garante a entrega com confirmações e é suportado em todos os planos, inclusive no plano Serverless gratuito, que limita o QoS a 1. Use QoS 2 apenas se você estiver em um plano que o suporte e os dados realmente não tolerarem duplicatas. O artigo níveis de QoS do MQTT explicados aborda os trade-offs.

Fila durante quedas de internet

Com cleansession false, o broker local mantém a sessão da bridge enquanto a conexão está fora e enfileira as mensagens QoS 1 para ela. Quando o link volta, o acúmulo é escoado para a nuvem. A fila é limitada por max_queued_messages (e opcionalmente max_queued_bytes) na sua configuração principal. Dimensione-a para a maior queda que você quer cobrir, algo comum em fazendas e usinas com link de internet instável; em um Pi com cartão SD, mantenha-a moderada, porque as filas persistidas são gravadas em disco a cada autosave. Mensagens QoS 0 não são enfileiradas, o que é mais um motivo para fazer a bridge da telemetria com QoS 1.

Lembre-se de que o lado da nuvem também aplica seus próprios limites. Se um grande acúmulo chegar de uma vez, um broker com cotas por plano e proteção contra flood pode limitá-lo, então quedas muito longas são melhor tratadas por um buffer na aplicação, como o do guia de buffer de mensagens offline.

Testando a bridge de ponta a ponta

Assine no lado da nuvem. Com o servidor público você pode usar mosquitto_sub diretamente; com um broker privado, use um segundo conjunto de credenciais ou o cliente MQTT no navegador do portal:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME_2 -P YOUR_PASSWORD_2 -i YOUR_CLIENT_ID_2 \
  -t 'site1/#' -v

Publique localmente no Pi:

mosquitto_pub -h localhost -u sensors -P 'sensors-password' -i t1 -q 1 \
  -t sensors/boiler/temp -m 64.2

O assinante na nuvem imprime site1/sensors/boiler/temp 64.2 e site1/bridge/state 1. Agora teste o sentido de descida. Assine localmente cmd/# e publique do lado da nuvem em site1/cmd/pump1/set. A mensagem chega localmente como cmd/pump1/set.

Por fim, teste uma queda: desligue a rede no Pi (sudo nmcli networking off), publique algumas mensagens QoS 1 localmente, religue a rede e veja-as chegarem à nuvem. O topic de estado da bridge vai para 0 enquanto o link está fora, entregue pelo broker como last will da bridge.

Evitando loops na sua configuração de bridge Mosquitto

Um loop acontece quando uma mensagem encaminhada para fora volta para dentro e é encaminhada para fora de novo. A causa mais comum é uma regra both, ou padrões in e out sobrepostos, nos mesmos topics:

# Dangerous: anything under site1/ bounces back and forth
topic # both 1 "" site1/

Mantenha cada direção em subárvores separadas: telemetria e estados vão para out, comandos entram por in em outro ramo (cmd/). Se você realmente precisar de both, prefira bridge MQTT 5 com assinaturas no-local onde sua versão do Mosquitto suportar, e teste com cuidado. Nunca faça bridge de # sem prefixo, em nenhuma direção.

Vários sites, um broker na nuvem

Cada Pi recebe suas próprias credenciais e seu próprio prefixo (site1/, site2/, ...). Os dashboards assinam +/sensors/# para ver todos os sites, ou um único prefixo para um site só. Como cada bridge tem um client ID único vinculado às suas credenciais, revogar um site nunca afeta os outros. Os planos Serverless pagos adicionam shared subscriptions, que ajudam quando vários consumidores na nuvem precisam dividir o fluxo combinado. Sites industriais podem ir além e adotar uma hierarquia no estilo ISA-95, como enterprise/site/area/line/cell, que o portal detecta e exibe na visão de dispositivos.

Solução de problemas

Conecte seu Pi ao ConnectMQ

Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, cole o username, o password e o client ID gerados no arquivo da bridge e veja os topics do seu site aparecerem no explorador de topics ao vivo do portal. Para o projeto de gateway mais amplo em torno dessa bridge, leia Raspberry Pi como gateway IoT e, para a série completa sobre o Pi, o tutorial MQTT com Raspberry Pi.

Perguntas frequentes

O ConnectMQ precisa de algum recurso especial de bridge para o Mosquitto?

Não. A bridge Mosquitto se conecta como um cliente MQTT comum usando o username, o password e o client ID do portal, então qualquer plano funciona.

Devo fazer a bridge com MQTT 3.1.1 ou MQTT 5?

O MQTT 3.1.1 é a escolha mais simples e mais testada para bridges. Versões recentes do Mosquitto suportam bridge mqttv50 se você precisar de recursos do MQTT 5 no link da bridge.

Por que definir try_private como false?

Quando ativado, o Mosquitto sinaliza que é uma bridge usando um flag de protocolo não padrão, pensado para links entre Mosquittos. Desativá-lo mantém a conexão totalmente padrão para outros brokers.

Quantas mensagens a bridge enfileira durante uma queda?

Tantas quanto max_queued_messages e max_queued_bytes permitirem, para mensagens QoS 1 e 2 com cleansession false. Mensagens QoS 0 são descartadas enquanto o link está fora.