Skip to main content

Meshtastic MQTT Setup

MQTT lets a Meshtastic node forward all mesh traffic to the internet, making your local mesh visible on the network map, bridging messages to internet clients, and enabling monitoring and logging. This is what puts your nodes on meshmap.net.

How MQTT works in Meshtastic

When MQTT is enabled on a node:

  1. Every mesh packet received by the node is forwarded to an MQTT broker over WiFi or TCP
  2. The MQTT broker stores and redistributes the messages to other subscribers
  3. The public Meshtastic MQTT broker (mqtt.meshtastic.org) accepts messages from anyone and shares them publicly — this is how meshmap.net gets its data
  4. Optionally, messages from the internet (MQTT) can be injected back into the local radio mesh

Hardware requirement: MQTT requires a WiFi-capable device (ESP32-based: Heltec V3/V4, T-Beam, etc.). nRF52840 devices (T-Echo, T-Deck, RAK4631) do not have WiFi and cannot connect to MQTT directly.

Connecting to the public Meshtastic MQTT broker

Via the Meshtastic app

  1. Go to Settings → Module Config → MQTT
  2. Enable MQTT: toggle ON
  3. MQTT Server Address: mqtt.meshtastic.org
  4. Username: meshdev
  5. Password: large4cats
  6. TLS Enabled: toggle ON (recommended)
  7. Map Reporting Enabled: toggle ON (to appear on meshmap.net)
  8. Save

Via CLI

meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address mqtt.meshtastic.org
meshtastic --set mqtt.username meshdev
meshtastic --set mqtt.password large4cats
meshtastic --set mqtt.tls_enabled true
meshtastic --set mqtt.map_reporting_enabled true

Channel settings for MQTT

MQTT is enabled per channel. By default, the primary channel (channel 0) is configured to uplink to MQTT. Verify that your channel has Uplink Enabled set to ON:

meshtastic --ch-index 0 --ch-set uplink_enabled true

Important: If your channel uses a non-default PSK, messages are uploaded encrypted. The public meshmap.net can still see node positions (which are unencrypted) but cannot read message content.

Downlink: receiving messages from the internet

meshtastic --ch-index 0 --ch-set downlink_enabled true

Security note: Only enable downlink on channels with PSK authentication if you want to control who can inject messages into your local mesh. The public LongFast channel has no authentication — anyone on the public MQTT broker can inject messages into your mesh if downlink is enabled on the default channel.

Running a private MQTT broker

For a community or organizational network, run your own Mosquitto broker instead of using the public one:

# Install Mosquitto
sudo apt install mosquitto mosquitto-clients

# Basic config: /etc/mosquitto/mosquitto.conf
listener 1883 localhost        # Local only (use nginx/TLS for external)
listener 8883                  # TLS port for internet clients
cafile /path/to/ca.crt
certfile /path/to/server.crt
keyfile /path/to/server.key
allow_anonymous false
password_file /etc/mosquitto/passwd

Point your Meshtastic nodes to your broker's address instead of mqtt.meshtastic.org.

MQTT topic structure

Meshtastic publishes to topics of the form:

msh/{region}/{channel_name}/2/json/{packet_type}/{node_id}

Examples:
msh/US/LongFast/2/json/nodeinfo/!abcd1234
msh/US/LongFast/2/json/position/!abcd1234
msh/US/LongFast/2/json/text/!abcd1234

Subscribe to msh/US/# to receive all US region traffic. The payload is JSON-encoded packet data.

No comments to display

Back to top