El puente MQTT de Meshtastic

1. Qué es MQTT en realidad

MQTT es una oficina de correos para mensajes. Hay un servidor en el medio llamado broker. Cualquiera puede publicar un mensaje en una casilla con nombre —un tópico (topic)— y cualquier otro puede suscribirse a ese tópico y recibir todo lo que se deje en él.

Nada se conecta directamente con nada más. Ese es todo el modelo, y es la razón por la que MQTT le queda bien a Meshtastic: dos mallas separadas por cientos de kilómetros pueden intercambiar paquetes por internet en lugar de por radio, con un broker como punto de encuentro.

2. Proxy de cliente vs. gateway

Ambos aparecen bajo «MQTT» en la app. No son lo mismo, y aquí empieza casi toda la confusión.

Configurar el modo proxy de cliente

Esto es lo que quieres si tu objetivo es ver tus propios nodos en un mapa o alimentar un tablero. Es la configuración segura.

mqtt.enabled = true
mqtt.proxy_to_client_enabled = true
mqtt.address = tu.broker.ejemplo
# deja uplink_enabled / downlink_enabled APAGADOS en cada canal

Tu nodo igual se reporta al broker. No empieza a empujar el tráfico de todos los demás hacia internet.

Configurar el modo gateway

network.wifi_enabled = true
mqtt.enabled = true
mqtt.proxy_to_client_enabled = false
mqtt.tls_enabled = true
mqtt.root = msh/TU_REGION

Apagar proxy_to_client_enabled es el interruptor que dice «yo manejo mi propia conexión». El nodo ahora habla con el broker haya o no un teléfono presente.

Ser gateway todavía no significa que estés puenteando nada. Por defecto el nodo publica solo sus propios paquetes y nada más. Retransmitir el tráfico de otros nodos es un ajuste aparte.

3. Uplink, downlink y por qué vienen apagados

Estas dos banderas se configuran por canal, en el gateway. Son las que de verdad unen dos mallas.

Hay una buena razón para encenderlas: tienes dos mallas lejanas y quieres enlazarlas deliberadamente en un canal compartido. Si ese no es tu objetivo, deja ambas apagadas. Vienen apagadas por algo.

Si sí vas a puentear, activa uplink y downlink solo en el canal específico que estás compartiendo —no en tu canal primario, y no en todos.

4. «OK to MQTT» — el asesino silencioso de paquetes

Cada nodo lleva un ajuste llamado lora.config_ok_to_mqtt. Por defecto es false.

Cuando está en false, el nodo marca una bandera dentro de cada paquete que origina que significa «no me pongas en MQTT», y los gateways la respetan. Puedes tener el uplink activado, un broker sano y un gateway que te escucha perfectamente —y tus mensajes aún así nunca se publicarán.

meshtastic --port COM11 --set lora.config_ok_to_mqtt true

# luego confirma que quedó
meshtastic --port COM11 --info | grep configOkToMqtt

En la app está bajo LoRa → Avanzado; el texto cambia entre versiones, así que busca «OK to MQTT» o «MQTT OK». Vuelve a leerlo después de configurarlo, y revísalo otra vez tras una actualización de firmware —a mí se me revirtió a mitad de sesión y perdí veinte minutos echándole la culpa al gateway.

5. Tópicos protobuf y JSON

Bajo tu tópico raíz hay dos ramas, y saber cuál estás mirando explica la mayoría de los reportes de «mi tablero no muestra nada».

Protobuf es el valor por defecto y casi siempre la opción correcta: compacto, cifrado de extremo a extremo, y legible por toda herramienta de Meshtastic. JSON es cómodo para Node-RED o Home Assistant porque no hay que decodificar nada —pero producirlo obliga al gateway a descifrar primero, así que tu texto plano termina en el broker.

6. El firmware 2.8 rompe los DM a través de un gateway

Los mensajes directos van cifrados de extremo a extremo entre dos nodos. Un gateway que transporta el DM de otra persona genuinamente no puede leerlo —el mensaje no está dirigido al gateway.

En 2.7 esto no importaba. El gateway reenviaba el bloque cifrado a MQTT sin leerlo, y el otro extremo lo descifraba. Así cruzaban los DM un puente.

En 2.8 un paquete que el gateway no puede descifrar se clasifica como opaco (opaque), y el tráfico opaco se excluye deliberadamente de MQTT.

El firmware declara la intención sin rodeos, en NextHopRouter.cpp:

// Opaque traffic is never admitted to PacketHistory, NodeDB,
// modules, phone, MQTT, or ACK handling.

Introducido por el PR #10967, «feat(security): enforce packet authenticity policies». Ningún ajuste de configuración lo sortea —la opción packet_signature_policy gobierna cómo se reciben los paquetes y solo aplica al tráfico que el nodo ya puede descifrar. Compatible, Balanced y Strict toman todos el mismo camino opaco.

7. El firmware 2.8 casi duplica tu tiempo en el aire

El mismo PR agregó una firma XEdDSA a cada transmisión (broadcast): 64 bytes, más dos bytes de sobrecarga de protobuf, en cada paquete sin importar el largo del mensaje.

La firma solo está condicionada por !pki_encrypted && isBroadcast(to) —no hay ajuste en tiempo de ejecución. Desactivarla significa una compilación personalizada con MESHTASTIC_EXCLUDE_XEDDSA. En un canal concurrido, esto conviene saberlo antes de actualizar una flota.

8. Qué se rompe de verdad entre versiones

Circula la afirmación de que los nodos 2.7 no pueden recibir de nodos 2.8. Yo me la creí, luego revisé el código fuente —no es cierto. Protobuf está hecho para esto: nanopb llega al campo de firma desconocido, lo salta y sigue (pb_decode.c, «No match found, skip data»).

Si tu síntoma es «ellos me ven pero yo no los veo», o al revés, la causa abrumadoramente probable es la bandera ok_to_mqtt o un canal con el uplink desactivado —no un desajuste de versión.

9. Lista de verificación

1. ¿Estás en modo proxy o gateway? Confirma que proxy_to_client_enabled coincide con tu intención.
2. ¿Está uplink_enabled activado para el canal específico que estás probando —no solo el primario?
3. ¿Está lora.config_ok_to_mqtt en true en el nodo que envía? Vuelve a leerlo.
4. ¿Acabas de cambiar downlink? Reinicia el gateway. Las suscripciones se construyen solo cuando la sesión MQTT se conecta, así que publicar funcionará mientras que recibir, en silencio, nunca lo hará.
5. ¿Estás mirando el tópico correcto? El protobuf cae bajo /2/e/; la rama /2/json/ está vacía a menos que json_enabled esté encendido.
6. ¿Esperas que un DM cruce el puente? En 2.8 no lo hará. Usa un mensaje de canal, o corre 2.7.26.
7. ¿Sigues atascado? Suscríbete tú mismo a msh/# y observa. Si aparecen los paquetes de tu propio gateway pero no los retransmitidos, es la bandera del paso 3.