Skip to main content
Pitch In Subscribe

MQTT Overview & Setup

Meshtastic MQTT Gateway Overview

MQTT allows Meshtastic nodes to bridge the local LoRa mesh to the internet, enabling mesh messages to travel between physically separated mesh islands and feeding data into monitoring dashboards.

Hardware Requirements

OnlyA device can gateway to MQTT in several ways:

    ESP32-basedOnboard Wi-Fi (ESP32 only) devices- the device connects to a Wi-Fi network directly. ESP32 boards with Wi-Fi can act as MQTT gateways:include:
    • Heltec V3 / V4
    • T-Beam
    • T-Deck
    • Station G2
    Ethernet - the nRF52-based RAK4631 with the RAK13800 Ethernet module. MQTT Client Proxy - the node uses the connected phone app's internet connection, so it needs no onboard internet hardware at all. This works on any node, including nRF52 boards.

    nRF52-based devices cannot use MQTT - they lack Wi-Fi hardware. This includes (most RAK Wireless modulesWisBlock cores, e.g. the RAK4631, and some Lilygo variants.

    variants)

    Thelack onboard Wi-Fi, so they cannot gateway nodeover musttheir also have access to aown Wi-FiFi. networkThey atcan itsstill location.use MQTT via Ethernet (RAK4631 + RAK13800) or via MQTT Client Proxy. The one caveat is that nRF52 platforms cannot emit JSON over MQTT - JSON output requires an ESP32 gateway.

    Public MQTT Broker

    The Meshtastic project operates a free public broker:

    mqtt.meshtastic.org

    The public broker is not anonymous. It requires credentials - the built-in defaults are username meshdev / password large4cats. The firmware auto-fills these when the fields are left blank, but external clients (MQTT Explorer, mosquitto_sub, Node-RED, Home Assistant) must supply them explicitly. The public broker also enforces restrictions (e.g., zero-hop, no broad # subscriptions, location-precision limits).

    Topic Structure

    msh/{region}/REGION/2/{encoding}/{channel_name}/{node_id}e/CHANNELNAME/USERID

    The 2 segment is a fixed value in the Meshtastic MQTT protocol and does not change per channel. The {encoding}encoding fieldsegment is eitherthe literal value e (for encrypted protobuf,protobuf (the default) or json (for human-readable JSON)JSON. (Firmware before 2.3.0 used /c/ instead of /e/.

    )

    ExampleThe forfinal segment is the gateway node's USERID. For example, a US node on channel 0 usingpublishing JSON encoding on the LongFast channel:

    msh/US/2/json/LongFast/!a1b2c3d4

    Configuration via Meshtastic CLI

    Enable JSON encoding (human-readable messages on the broker):

    meshtastic --set mqtt.json_enabled true
    meshtastic --ch-index 0 --ch-set uplink_enabled true
    meshtastic --ch-index 0 --ch-set downlink_enabled true

    CriticalBest Warning:practice: Only enableEnable downlink on only ONE node on your local mesh. IfBecause multiple gateway nodes havecan downlinkbe enabled,connected to a single mesh, the same MQTT message willcan be injected into the mesh multiple times,times if several nodes have downlink enabled, causing duplicate messages and unnecessary channel congestion.

    App Configuration Path

    In the Meshtastic app: RadioSettings Config →> MQTT (Android) or Settings > Module Configuration > MQTT (Apple)

    • Enable MQTT: on
    • Address: mqtt.meshtastic.org
    • Root topic: msh/US (replace US with your region code)
    • Username / Password: optionalfor the public broker, leave blank to use the built-in defaults (meshdev / large4cats), or set them explicitly. The public broker acceptsis anonymous)not anonymous.
    • TLS: enabled recommended
    Back to top