Setting Up a Meshtastic MQTT Gateway

Any Meshtastic device with Wi-Fi capability (ESP32-based boards such as the LILYGO T-Beam, Heltec WiFi LoRa 32, RAK4631 with Ethernet module, etc.) can act as an MQTT gateway. This guide covers enabling MQTT through the official Meshtastic app and verifying the connection with MQTT Explorer.

Prerequisites

• A Meshtastic node with Wi-Fi or Ethernet (ESP32, nRF52 + Ethernet module).
• The Meshtastic Android / iOS app, or the Meshtastic Web Client.
• The node already joined to a Wi-Fi network (configure in Radio Config → Wi-Fi).
• An MQTT broker - either the public mqtt.meshtastic.org or your own Mosquitto instance.

Step 1 - Connect the Node to Wi-Fi

In the Meshtastic app, open the device's config:

1. Navigate to Radio Config → Network.
2. Toggle Wi-Fi Enabled on.
3. Enter your SSID and WPA2 passphrase.
4. Tap Send. The device will reboot and connect to Wi-Fi; confirm by checking the IP address shown on the device's OLED display or in the app's Node Info panel.

Step 2 - Enable the MQTT Module

1. In the app, open Radio Config → MQTT.
2. Toggle MQTT Enabled on.
3. Set MQTT Server Address:
   • Public broker: mqtt.meshtastic.org
   • Self-hosted: 192.168.1.50 or mqtt.mynetwork.local
4. Leave Username and Password blank for the public broker (anonymous access). Fill them in for an authenticated self-hosted broker.
5. Set Root Topic - this prefixes all published/subscribed topics. Default: msh. Change only if you are segregating traffic (e.g., a private regional prefix like msh/myregion).
6. Toggle Uplink Enabled on.
7. Toggle Downlink Enabled on or off (see cautions in the Overview page).
8. Toggle JSON Output Enabled if you intend to consume messages from Node-RED, Home Assistant, or custom scripts. Leave off for device-to-device bridging.
9. Toggle TLS Enabled on if connecting to port 8883 (required for TLS brokers).
10. Tap Send. The device will apply the config and initiate MQTT connection.

Step 3 - Configure Channel Encryption Key Handling

Messages are encrypted with the channel key on the LoRa air interface. The same encrypted payload is published to MQTT. The gateway does not decrypt messages before uplinking - it forwards the ciphertext as-is. This means:

• Subscribers on the MQTT broker who do not know the channel key see only opaque binary blobs.
• Remote Meshtastic devices with the same channel key can decrypt messages downlinked from the broker.
• For JSON mode, the gateway does decrypt before serialising to JSON. JSON output therefore exposes plaintext to whoever can subscribe on the broker - use a private broker with ACLs for JSON mode.

To share a channel key with a remote user, use the channel QR code or URL share feature in the app: Channels → Share produces a deep link containing the encoded key.

Step 4 - Verify with MQTT Explorer

MQTT Explorer is a free, cross-platform GUI client for exploring broker traffic.

1. Download from mqtt-explorer.com.
2. Create a new connection:
   • Protocol: mqtt:// (port 1883) or mqtts:// (port 8883).
   • Host: mqtt.meshtastic.org (or your broker).
   • Leave Username/Password blank for public broker.
3. Connect and expand the msh topic tree. Within seconds you should see topics appearing as your gateway uplinks packets.
4. Click a leaf topic to see the raw payload (base64 protobuf) and, for JSON topics, the decoded JSON object.

# Alternatively, use the mosquitto_sub CLI tool:
mosquitto_sub -h mqtt.meshtastic.org -p 1883 -t "msh/#" -v

Advanced: Uplink/Downlink per Channel

Meshtastic 2.x allows per-channel MQTT uplink/downlink settings, so you can uplink a private community channel while keeping a sensitive channel (e.g., encrypted tactical) RF-only:

1. In the app, navigate to Channels.
2. Edit the channel you want to configure.
3. Under Uplink Enabled / Downlink Enabled, set the per-channel overrides.
4. The global MQTT module toggle still acts as a master switch.

Common Issues and Fixes