Una buena configuración de bridge Mosquitto permite que un broker local en una Raspberry Pi siga atendiendo a los dispositivos de la LAN mientras reenvía exactamente los topics que elijas a un broker en la nube. En este tutorial construirás un bridge que se conecta a ConnectMQ por TLS con las credenciales del portal, remapea los topics para que cada sitio tenga su propio namespace, envía comandos de vuelta hacia abajo, encola mensajes durante los cortes de internet y evita el clásico bucle de mensajes. Cada opción se explica, para que puedas adaptar el archivo en lugar de copiarlo a ciegas.
Cómo funciona un bridge Mosquitto
Un bridge no es un protocolo especial. El broker Mosquitto local abre una conexión saliente hacia el broker remoto y se comporta como un cliente MQTT normal: se suscribe en un lado y vuelve a publicar en el otro, según las líneas topic de su configuración. Eso tiene tres consecuencias útiles:
- Sin puertos de entrada. La Pi se conecta hacia fuera por el puerto 8883, igual que un navegador que abre un sitio web. Tu router permanece cerrado.
- El broker remoto no necesita nada especial. Cualquier broker que cumpla el estándar acepta un bridge, porque simplemente ve a un cliente que inicia sesión con usuario, contraseña y client ID.
- Tú eliges qué cruza la frontera. Solo los topics que coinciden con una línea
topicsalen del sitio o entran en él.
En esta configuración, el lado remoto es ConnectMQ, un broker MQTT gestionado. El bridge se autentica con las credenciales generadas en el portal como cualquier otro dispositivo. Si todavía no has configurado el broker local, sigue primero instalar Mosquitto en 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 empezar
- Una Raspberry Pi con Mosquitto 2.0 en marcha y al menos un listener local autenticado.
- Un broker en la nube con credenciales. Regístrate en el portal, elige un plan, crea un broker y copia el username, la password y el client ID generados. El client ID está vinculado a esas credenciales, así que el bridge debe usarlo exactamente.
- Un plan para los nombres de topic. Decide cómo deben verse los topics locales en la nube. Un prefijo de sitio como
site1/evita que varias Pi colisionen.
Para un experimento rápido sin cuenta, puedes hacer el bridge hacia el servidor MQTT público gratuito en el puerto 1883, sin credenciales y con cualquier client ID único, usando un prefijo aleatorio como connectmq/demo/3c7d52/. Todo lo que hay allí es de lectura pública, así que usa solo datos ficticios, nunca datos de producción.
La configuración completa del bridge Mosquitto
Crea /etc/mosquitto/conf.d/bridge-connectmq.conf:
# ---- Conexión ----
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
# ---- Credenciales del portal de ConnectMQ ----
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
# ---- Sesión y cola ----
cleansession false
local_clientid bridge-connectmq-local
# ---- Topic de estado (publicado en el lado remoto) ----
notifications true
notifications_local_only false
notification_topic site1/bridge/state
# ---- Mapeo de topics ----
# Telemetría hacia arriba: local "sensors/#" -> remoto "site1/sensors/#"
topic sensors/# out 1 "" site1/
# Estados de máquina hacia arriba, se conservan los valores retenidos
topic machines/+/state out 1 "" site1/
# Comandos hacia abajo: remoto "site1/cmd/#" -> local "cmd/#"
topic cmd/# in 1 "" site1/
Reinicia y sigue el 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
Deberías ver Connecting bridge connectmq (broker.connectmq.com:8883) sin errores a continuación. El cambio de permisos es importante porque el archivo contiene la contraseña remota.
Opción por opción
| Opción | Valor aquí | Por qué |
|---|---|---|
address |
broker.connectmq.com:8883 |
Puerto TLS del broker en la nube |
bridge_protocol_version |
mqttv311 |
Ampliamente soportado; en versiones recientes de Mosquitto también es posible el bridge con MQTT 5 |
try_private |
false |
Evita un flag de bridge exclusivo de Mosquitto que otros brokers pueden rechazar |
restart_timeout |
5 60 |
Espera progresiva de 5 s a 60 s entre intentos de reconexión |
bridge_capath |
/etc/ssl/certs |
El almacén de CA del sistema valida el certificado Let's Encrypt del broker |
bridge_insecure |
false |
Mantén siempre activa la verificación del nombre de host |
remote_clientid |
Client ID del portal | Debe coincidir con las credenciales emitidas |
cleansession |
false |
Conserva las sesiones para que los mensajes QoS 1 se encolen durante los cortes |
notifications |
true |
Publica 1 cuando el bridge se conecta y 0 (como last will) cuando se cae |
notification_topic |
site1/bridge/state |
Mantiene el estado dentro de tu propio namespace |
Entender la línea topic
La sintaxis es topic <pattern> <direction> <qos> <local-prefix> <remote-prefix>. Al reenviar hacia fuera, Mosquitto quita el prefijo local de un topic local y añade el prefijo remoto; con in hace lo contrario. Con un prefijo local vacío (escrito como "") y el prefijo remoto site1/:
- El topic local
sensors/boiler/tempse convierte en el remotosite1/sensors/boiler/temp. - El topic remoto
site1/cmd/pump1/setse convierte en el localcmd/pump1/set.
Fíjate en que el prefijo remoto termina en barra. Sin ella obtienes site1sensors/..., un error fácil de cometer y difícil de detectar.
QoS en el bridge
El QoS de una línea topic es el máximo que se usa a través del bridge. QoS 1 es la opción práctica: garantiza la entrega con confirmaciones y está disponible en todos los planes, incluido el plan gratuito Serverless, que limita el QoS a 1. Usa QoS 2 solo si tu plan lo admite y los datos realmente no toleran duplicados. El artículo niveles de QoS de MQTT explicados analiza las ventajas y desventajas.
Cola durante los cortes de internet
Con cleansession false, el broker local conserva la sesión del bridge mientras la conexión está caída y encola para él los mensajes QoS 1. Cuando vuelve el enlace, la acumulación se vacía hacia la nube. La cola está limitada por max_queued_messages (y opcionalmente max_queued_bytes) en tu configuración principal. Dimensiónala para el corte más largo que quieras cubrir; en una Pi con tarjeta SD, mantenla moderada, porque las colas persistidas se escriben en disco en cada autoguardado. Los mensajes QoS 0 no se encolan, otra razón más para hacer el bridge de la telemetría con QoS 1.
Recuerda que el lado de la nube también aplica sus propios límites. Si una larga acumulación llega de golpe, un broker con cuotas por plan y protección contra flooding puede limitarla, así que los cortes muy largos se gestionan mejor con un buffer a nivel de aplicación como el de la guía de buffering de mensajes sin conexión.
Probar el bridge de extremo a extremo
Suscríbete en el lado de la nube. Con el servidor público puedes usar mosquitto_sub directamente; con un broker privado, usa un segundo juego de credenciales o el cliente MQTT del portal en el navegador:
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
Publica localmente en la Pi:
mosquitto_pub -h localhost -u sensors -P 'sensors-password' -i t1 -q 1 \
-t sensors/boiler/temp -m 64.2
El suscriptor en la nube muestra site1/sensors/boiler/temp 64.2 y site1/bridge/state 1. Ahora prueba el enlace descendente. Suscríbete localmente a cmd/# y publica desde el lado de la nube en site1/cmd/pump1/set. El mensaje llega localmente como cmd/pump1/set.
Por último, prueba un corte: detén la red en la Pi (sudo nmcli networking off), publica localmente algunos mensajes QoS 1, vuelve a activar la red y observa cómo llegan a la nube. El topic de estado del bridge pasa a 0 mientras el enlace está caído, entregado por el broker como last will del bridge.
Evitar bucles en la configuración del bridge Mosquitto
Un bucle se produce cuando un mensaje reenviado hacia fuera vuelve a entrar y se reenvía de nuevo hacia fuera. La causa más habitual es una regla both, o patrones in y out que se solapan sobre los mismos topics:
# Peligroso: todo lo que hay bajo site1/ rebota de un lado a otro
topic # both 1 "" site1/
Mantén cada dirección en subárboles separados: la telemetría y los estados van out, los comandos entran in bajo otra rama (cmd/). Si de verdad necesitas both, prefiere el bridge con MQTT 5 y suscripciones no-local cuando tu versión de Mosquitto lo admita, y prueba con cuidado. Nunca hagas bridge de # sin prefijo en ninguna dirección.
Varios sitios, un único broker en la nube
Cada Pi recibe sus propias credenciales y su propio prefijo (site1/, site2/, ...). Los dashboards se suscriben a +/sensors/# para ver todos los sitios, o a un prefijo concreto para un único sitio. Como cada bridge tiene un client ID único ligado a sus credenciales, revocar un sitio nunca afecta a los demás. Los planes Serverless de pago añaden shared subscriptions, útiles cuando varios consumidores en la nube necesitan repartirse el flujo combinado. Los sitios industriales, por ejemplo plantas en Querétaro o Bilbao, pueden ir más allá y adoptar una jerarquía al estilo ISA-95 como enterprise/site/area/line/cell, que el portal detecta y muestra en su vista de dispositivos.
Solución de problemas
| Mensaje del log o síntoma | Causa | Solución |
|---|---|---|
Connection Refused: not authorised |
Credenciales o client ID incorrectos | Vuelve a copiar los tres valores desde el portal |
certificate verify failed |
Falta el almacén de CA o la hora es incorrecta | Instala ca-certificates y comprueba NTP con timedatectl |
| El bridge se conecta, pero no llega nada | El patrón de topic o el prefijo no coinciden | Recuerda la barra final en los prefijos |
| La conexión se cae cada pocos segundos | Otro cliente usa el mismo client ID | Un client ID por conexión |
| Se pierden mensajes durante los cortes | QoS 0 o cleansession true |
Usa QoS 1 y cleansession false |
| Tormenta de mensajes al activar el bridge | Bucle por reglas in/out solapadas | Subárboles separados para cada dirección |
Conecta tu Pi a ConnectMQ con un bridge
Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, pega en el archivo del bridge el username, la password y el client ID generados y observa cómo aparecen los topics de tu sitio en el explorador de topics en vivo del portal. Para el diseño de gateway más amplio en torno a este bridge, lee Raspberry Pi como gateway IoT, y para la serie completa sobre la Pi, el tutorial de MQTT con Raspberry Pi.
Preguntas frecuentes
¿Necesita ConnectMQ una función especial de bridge para Mosquitto?
No. El bridge de Mosquitto se conecta como un cliente MQTT normal con el username, la password y el client ID del portal, así que funciona con cualquier plan.
¿Debo hacer el bridge con MQTT 3.1.1 o con MQTT 5?
MQTT 3.1.1 es la opción más sencilla y más probada para los bridges. Las versiones recientes de Mosquitto admiten bridge con mqttv50 si necesitas funciones de MQTT 5 en el enlace del bridge.
¿Por qué poner try_private en false?
Cuando está activado, Mosquitto indica que es un bridge mediante un flag de protocolo no estándar pensado para enlaces de Mosquitto a Mosquitto. Desactivarlo mantiene la conexión totalmente estándar para otros brokers.
¿Cuántos mensajes encola el bridge durante un corte?
Tantos como permitan max_queued_messages y max_queued_bytes, para mensajes QoS 1 y 2 con cleansession false. Los mensajes QoS 0 se descartan mientras el enlace está caído.
