Meshtastic MQTT Setup: Bridge Your Mesh to the Internet

MQTT is the most powerful advanced feature in Meshtastic and one of the least documented. It bridges your LoRa mesh to the internet, unlocking remote monitoring, mesh-to-mesh bridging, Home Assistant integration, and custom dashboards.

The config is straightforward once you know the moving parts. Most people get tripped up on uplink vs. downlink and whether to use the public broker or run their own.

What Is MQTT and Why Does It Matter

MQTT (Message Queuing Telemetry Transport) is a lightweight messaging protocol designed for constrained devices and unreliable networks. It uses a publish/subscribe model: devices publish messages to topics on a broker, and other devices subscribe to those topics to receive them.

For Meshtastic, MQTT means your LoRa mesh can talk to the internet. A node with Wi-Fi connectivity (ESP32 devices) publishes mesh traffic to an MQTT broker, making that data available to any internet-connected system.

What You Can Do With It

Once MQTT is running, you can track node positions and battery levels from your couch, bridge two mesh networks in different towns through the internet, pipe sensor data into Home Assistant for automations, or build Grafana dashboards that show signal quality trends over weeks. Some people build custom bots that respond to mesh messages via MQTT. The possibilities open up fast once the data is flowing to a broker.

How It Works

The data flow is straightforward:

1. Uplink: A Wi-Fi-enabled node receives a LoRa packet and publishes it to the MQTT broker
2. Broker: The MQTT broker stores and distributes the message to all subscribers
3. Downlink: The same (or different) Wi-Fi-enabled node subscribes to the broker and injects received messages back into the LoRa mesh

This creates a bidirectional bridge. Messages can flow from LoRa to internet and back.

Prerequisites

Before setting up MQTT, you need:

• An ESP32-based Meshtastic device — MQTT requires Wi-Fi, which is only available on ESP32 hardware (Heltec V3/V4, T-Beam, T-Deck, Station G2). nRF52 devices (RAK4631, T-Echo) don’t have Wi-Fi and cannot run MQTT.
• A Wi-Fi network — The device needs internet access through a 2.4 GHz Wi-Fi network.
• Current firmware — Update to the latest stable firmware. See our firmware guide.
• An MQTT broker — Either the public Meshtastic broker or your own self-hosted broker.

Step 1: Enable Wi-Fi on Your Device

Your Meshtastic device needs Wi-Fi to reach the MQTT broker.

Via the Meshtastic App

1. Connect to your device via Bluetooth
2. Go to Settings > Network
3. Enable Wi-Fi
4. Enter your Wi-Fi SSID and password
5. Save and reboot

Via CLI

meshtastic --set network.wifi_enabled true
meshtastic --set network.wifi_ssid "YourNetworkName"
meshtastic --set network.wifi_psk "YourPassword"

After reboot, verify the device connected to Wi-Fi by checking the device info screen (it should show an IP address) or run meshtastic --info.

Step 2: Enable MQTT

Via the App

1. Go to Settings > MQTT
2. Enable MQTT
3. Set the broker address:
   • Public broker: mqtt.meshtastic.org (default)
   • Self-hosted: Your broker’s IP or hostname
4. Leave username and password blank for the public broker
5. Save

Via CLI

meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address mqtt.meshtastic.org

For a self-hosted broker with authentication:

meshtastic --set mqtt.address 192.168.1.50
meshtastic --set mqtt.username meshuser
meshtastic --set mqtt.password yourpassword

Step 3: Configure Channel Uplink/Downlink

MQTT is enabled per-channel. You decide which channels publish to MQTT (uplink) and which accept messages from MQTT (downlink).

Enable Uplink on Your Primary Channel

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

This publishes all traffic on channel 0 to the MQTT broker.

Enable Downlink (Optional)

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

This injects MQTT messages back into the LoRa mesh. Use with caution — if multiple nodes have downlink enabled, the same message gets injected multiple times, causing duplicates and wasting airtime.

Best practice: Enable uplink on multiple nodes for redundancy, but enable downlink on only one node per mesh to avoid duplicate injections.

Step 4: Choose JSON or Protobuf Encoding

Meshtastic publishes to MQTT in two formats:

• JSON — Human-readable, easy to work with in Node-RED and Home Assistant. Slightly larger messages.
• Protobuf — Compact binary format. Better for high-traffic meshes. Requires decoding.

Enable JSON (Recommended for Most Users)

meshtastic --set mqtt.json_enabled true

JSON messages look like this on the broker:

{
  "channel": 0,
  "from": 1234567890,
  "id": 12345,
  "payload": {
    "text": "Hello from the mesh!"
  },
  "sender": "!abcdef01",
  "timestamp": 1712505600,
  "to": 4294967295,
  "type": "text"
}

MQTT Topic Structure

Meshtastic publishes to topics following this pattern:

msh/{region}/{channel_index}/{encoding}/{channel_name}/{node_id}

For example:

msh/US/2/json/LongFast/!abcdef01

• msh — Meshtastic prefix
• US — Region code
• 2 — Channel index
• json — Encoding (json or proto)
• LongFast — Channel name
• !abcdef01 — Sender node ID

Subscribe to msh/US/2/json/# to receive all JSON traffic from your region.

Public vs Self-Hosted Broker

Use the public broker while you’re getting started. It works immediately with zero setup. The downside is that anyone can subscribe to the same topics and see your traffic — metadata and encrypted payloads both. Rate limits and occasional downtime are also real.

Once you have more than a handful of nodes or you’re passing anything you’d rather keep private, spin up Mosquitto on a Raspberry Pi or cheap VPS. It takes 10 minutes and you’ll never go back.

Setting Up Mosquitto (Self-Hosted)

Mosquitto is the most popular open-source MQTT broker.

Install on Ubuntu/Debian:

sudo apt update
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

Configure authentication:

sudo mosquitto_passwd -c /etc/mosquitto/passwd meshuser

Create /etc/mosquitto/conf.d/meshtastic.conf:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Restart Mosquitto:

sudo systemctl restart mosquitto

Then point your Meshtastic device to your broker:

meshtastic --set mqtt.address your-server-ip
meshtastic --set mqtt.username meshuser
meshtastic --set mqtt.password yourpassword

Home Assistant Integration

Home Assistant can subscribe to Meshtastic MQTT topics to create sensors, automations, and dashboards.

Add MQTT Integration

1. Go to Settings > Devices & Services > Add Integration
2. Search for MQTT
3. Enter your broker details

Create Sensors from Mesh Data

Add to your configuration.yaml:

mqtt:
  sensor:
    - name: "Mesh Node Battery"
      state_topic: "msh/US/2/json/LongFast/!abcdef01"
      value_template: "{{ value_json.payload.battery_level }}"
      unit_of_measurement: "%"
      device_class: battery

    - name: "Mesh Node Temperature"
      state_topic: "msh/US/2/json/LongFast/!abcdef01"
      value_template: "{{ value_json.payload.temperature }}"
      unit_of_measurement: "C"
      device_class: temperature

Automation Examples

Alert when a node goes offline (no message in 30 minutes):

automation:
  - alias: "Mesh Node Offline Alert"
    trigger:
      platform: state
      entity_id: sensor.mesh_node_battery
      to: "unavailable"
      for: "00:30:00"
    action:
      service: notify.mobile_app
      data:
        message: "Mesh node !abcdef01 has been offline for 30 minutes"

Grafana Dashboards

Want graphs? Set up the Prometheus exporter and point Grafana at it.

Quick Stack Setup

1. Meshtastic Exporter — Subscribes to MQTT and exposes Prometheus metrics
2. Prometheus — Scrapes and stores time-series data
3. Grafana — Visualizes the data in dashboards

Community-maintained exporters are available on GitHub. Search for “meshtastic prometheus exporter” for the latest options.

What to Watch

The most useful metrics are battery levels (catches dying nodes before they go dark), SNR trends (tells you if antenna performance is degrading), and channel utilization (shows when your mesh is getting congested). Node count and message rate are nice for dashboards but rarely actionable.

Troubleshooting

Device Doesn’t Connect to MQTT

1. Verify Wi-Fi is connected (check for an IP address on the device screen)
2. Confirm the broker address is correct and reachable from your network
3. Check broker logs for connection attempts
4. If using authentication, verify username/password are correct

Messages Not Appearing on Broker

1. Confirm uplink is enabled on the channel: meshtastic --ch-index 0 --ch-get uplink_enabled
2. Verify JSON encoding is enabled: meshtastic --get mqtt.json_enabled
3. Subscribe to a wildcard topic to see all traffic: mosquitto_sub -h broker-ip -t "msh/#" -v

Duplicate Messages on the Mesh

Multiple nodes with downlink enabled inject the same MQTT message into the mesh. Only enable downlink on one node per mesh.

High Airtime After Enabling MQTT

MQTT downlink can flood the mesh with internet traffic. Be selective about what you downlink. Consider enabling uplink only (no downlink) if you just want monitoring.

Security Considerations

• Use a private broker for anything beyond casual experimentation
• Enable TLS on your broker for encrypted connections (port 8883)
• Use strong passwords for broker authentication
• Don’t publish sensitive data on the public Meshtastic broker
• Be aware of channel encryption: MQTT traffic includes encrypted LoRa payloads. Without the channel PSK, an MQTT subscriber can see metadata (node IDs, timestamps) but not message content

Summary

One node with Wi-Fi and JSON uplink enabled is all you need to start seeing traffic on the broker. Here’s the shortest path to a working setup:

1. Enable Wi-Fi and MQTT on one ESP32 node
2. Enable JSON uplink on your primary channel
3. Subscribe with mosquitto_sub to see traffic flowing
4. Build from there — Home Assistant, Grafana, or custom apps

For channel configuration details, see our channels & MQTT guide. For CLI commands, see the CLI guide. For firmware updates, see the firmware guide.