MQTT

MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. bridges your Meshtastic mesh network to the internet, enabling long-range communication beyond radio range.

Overview

The MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. module connects your node to an MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. broker, allowing:

• Messages to reach nodes on different physical meshes via the internet
• Integration with home automation and monitoring systems
• Publishing node positions to the public Meshtastic map
• Custom data pipelines for logging and alerting

How It Works

[Your Node] → Radio → [Gateway Node with WiFi] → MQTT Broker → [Remote Gateway] → Radio → [Remote Node]

A gateway node with internet access (WiFi or Ethernet) publishes mesh messages to an MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. topic. Remote gateways subscribed to the same topic inject those messages into their local mesh.

Configuration

Enabling MQTT

1. Navigate to Settings → Module Config → MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other..
2. Enable the MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. module.
3. Configure the broker connection:

Setting	Description	Default
Server Address	MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. broker hostname	mqttMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other..meshtastic.org
Username	Broker authentication	meshdev
Password	Broker authentication	large4cats
Root Topic	Base topic for messages	msh
Encryption	Encrypt MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. payload	Enabled
JSON Output	⚠️ Deprecated — JSON packet support has been removed from firmware; this field is ignored	Disabled
TLS	Secure connection to broker	Disabled
Map Reporting	Report position to public map	Disabled

MQTT Proxy on This Phone

If your node has no internet access of its own, it can use the connected phone as its MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. gateway: enable MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. and Proxy to client enabled in the module config, and the app relays MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. traffic between the radio and the broker over your phone's internet connection.

The MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. proxy on this phone toggle at the top of the MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. settings screen shows whether this relay is currently running and lets you cut it off (or restart it) immediately — without editing and re-saving the device's MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. configuration.

Default Meshtastic Broker

The community maintains a public broker at mqtt.meshtastic.org. This is intended for general use and testing.

ℹ️ Note: Connections to mqtt.meshtastic.org always use TLS (port 8883), even if the TLS toggle is off. For any other broker, TLS is used only when you enable it (port 8883 with TLS, 1883 without).

🔒 Privacy: Messages on the public broker are readable by anyone subscribed. Always use channel encryption for private communications.

Private Broker

For better privacy and control, you can run your own MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. broker:

• Mosquitto (lightweight, open-source)
• HiveMQ
• EMQX

Configure your node to point to your private broker with appropriate credentials.

Map Reporting

When Map Reporting is enabled, your node publishes its position to the Meshtastic community map:

• Visible at meshmap.net and similar community map services
• Only position and node info are shared
• Disable this if you don't want your location publicly visible

Uplink vs Downlink

Direction	Description
Uplink	Messages from mesh → MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. broker
Downlink	Messages from MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. broker → mesh

Configure per-channel which directions are active to control message flow and airtime usage.

Message Formats

MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. uses protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. message format:

Format	Description	Use case
ProtobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices.	Binary Meshtastic protobufProtobuf (Protocol Buffers). A method developed by Google for serializing structured data, used in Meshtastic for efficient communication protocol between devices. encoding	Node-to-node mesh bridging

⚠️ Note: JSON output support was removed from firmware. The json_enabled setting is still visible in the app for legacy compatibility but has no effect on current firmware versions.

Encryption & Privacy

Understanding the layered encryption model:

1. Channel encryption happens on the mesh before MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other.. If your channel has a PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel., the MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. payload is already encrypted — the broker and any subscribers see only the ciphertext.
2. MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. encryption (the module setting) adds an additional encryption layer for transit to the broker. This protects metadata and routing information.
3. TLS encrypts the TCPTCP (Transmission Control Protocol). One of the three ways a client reaches a node, alongside serial and Bluetooth. Clients connect over TCP on port 4403. connection to the broker itself, preventing network-level eavesdropping.

🔒 Important: The default public channel has a well-known key. Messages on the default channel sent via MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. are effectively unencrypted — anyone can decode them. Always use a custom PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. for private communications.

Best Practices

• Use channel-level encryption (PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel.) on channels that bridge to MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other.
• Don't enable MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. on nodes without internet access (it will buffer and waste memory)
• Use a private broker for sensitive deployments
• Be mindful of airtime when downlinking messages from busy MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. topics — every downlinked message consumes radio airtime on your local mesh
• Consider enabling uplink-only if you only need to monitor your mesh remotely without injecting messages back

Troubleshooting

MQTT Not Connecting

• Check WiFi — the gateway node must have an active internet connection (WiFi or Ethernet). MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. does not work over the LoRaLoRaA low-power, long-range wireless communication technology used by Meshtastic devices to enable communication over distances of several kilometers without the need for cellular, Wi-Fi, or other traditional network infrastructures. radio link itself.
• Verify credentials — incorrect username or password will silently fail on most brokers. Double-check for trailing spaces.
• Firewall — port 1883 (MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other.) or 8883 (MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other.+TLS) must be open. Some networks block non-standard ports.
• DNS resolution — if using a custom broker hostname, verify the node can resolve it. Try the broker's IP address directly.

Messages Not Bridging

• Check uplink/downlink settings — if only uplink is enabled, messages flow from mesh to MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. but not back. Enable downlink on the receiving gateway.
• Channel mismatch — both gateways must share the same channel with the same PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel.. A mismatch means messages are encrypted with different keys and appear as garbage.
• Topic mismatch — ensure both gateways use the same root topic. The default msh works for the public broker.

Related Topics

• Settings — Modules & Admin — MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. module configuration reference
• Messages & Channels — channel encryption and PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. setup
• MQTT integration guide — detailed MQTTMQTT (Message Queuing Telemetry Transport). A lightweight messaging protocol designed for small sensors and mobile devices, enabling efficient data transmission in the Meshtastic network for Internet connectivity and integration with IoT platforms. See https://en.wikipedia.org/wiki/MQTT. In Meshtastic, MQTT is used to connect a node to the internet, and can be used to connect multiple meshes to each other. documentation on meshtastic.org

---