Meshtastic Guide - Meshtastic MQTT Module Configuration

If your device is connected to the Internet via Wi-Fi or Ethernet, you can enable it to forward packets to an MQTT server. This allows users on the local mesh to communicate with users on the Internet. One or more channels must also be enabled as uplink and/or downlink for packets to be transmitted from and/or to your mesh (see channels).

The MQTT module configuration options include: Enabled, Server Address, Username, Password, Encryption Enabled, JSON Enabled, TLS Enabled, Root Topic, Client Proxy Enabled, Map Reporting Enabled (with Position Precision and Publish Interval), and Okay to MQTT. The MQTT module config uses an admin message that sends a ConfigModule.MQTT protobuf.

MQTT Module Configuration Values

Enabled: Enables the MQTT module.
Server Address: The server to be used for MQTT. If not set, the default public server will be utilized.
Username: The MQTT Server username to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default public server, it will only be honored if set; otherwise, the device will use the default username.
Password: The MQTT password to use (most useful for a custom MQTT server). If using a custom server, this will be honored even if empty. If using the default server, it will only be honored if set; otherwise, the device will use the default password.
Encryption Enabled: Whether to send encrypted or unencrypted packets to the MQTT server is configurable. Unencrypted packets may be useful for external systems that wish to consume Meshtastic packets. Note: All messages are sent to the MQTT broker unencrypted if this option is not enabled, even when your uplink channels have encryption keys set.
JSON Enabled: JSON is not supported on the nRF52 platform. You can enable the sending and consumption of JSON packets on MQTT. These packets are not encrypted but provide an easy way to integrate with systems that can read JSON.
TLS Enabled: If set to true, we will attempt to establish a secure connection using TLS.
Root Topic: The root topic to use for MQTT messages is important. This is useful if you want to utilize a single MQTT server for multiple Meshtastic networks and separate them via ACLs.
Client Proxy Enabled: If set to true, the device will use the client's (e.g., your phone's) network connection to connect to the MQTT server. If set to false, it will use the device's own network connection, which must be enabled through the network settings.

Map Reporting Enabled

Available from firmware version 2.3.2 and onwards, if set to true, your node will periodically send an unencrypted map report to the MQTT server for display on online maps that support this packet. This report includes the following information:

The node's long and short name and ID
The node's position (with configurable precision) and altitude
The node's hardware model and role
The node's firmware version
The node's LoRa region, modem preset, and primary channel name
Whether the node can be reached on the default channel with a known key
Number of local online nodes (heard in the last 2 hours, excluding those heard via MQTT)

Map Report Position Precision refers to the precision used for the position in the map report, with a default maximum deviation of around 1459m.

Map Report Publish Interval specifies how often the map report should be published to the MQTT server in seconds, with a default setting of 900 seconds (15 minutes).

MQTT Module Configuration Client

Android

MQTT Config options are available for Android.

open the Meshtastic App
Navigate to: Vertical Ellipsis (3 dots at the top right) > Radio Configuration > MQTT.

Apple

All MQTT config options are available on iOS, iPadOS, and macOS. To access them, go to: Settings > Module Configuration > MQTT.

CLI

The following configuration options are available in the Python CLI:

Setting	Acceptable Values	Default
mqtt.enabled	true, false	FALSE
mqtt.address	string	mqtt.meshtastic.org
mqtt.username	string	meshdev
mqtt.password	string	large4cats
mqtt.encryption_enabled	true, false	FALSE
mqtt.json_enabled	true, false	FALSE
mqtt.tls_enabled	true, false	FALSE
mqtt.root	string
mqtt.proxy_to_client_enabled	true, false	FALSE
mqtt.map_reporting_enabled	true, false	FALSE

Enable/Disable MQTT Module

meshtastic --set mqtt.enabled true meshtastic --set mqtt.enabled false

Enable/Disable MQTT JSON

meshtastic --set mqtt.json_enabled true meshtastic --set mqtt.json_enabled false

NOTE: Since the device will reboot after each command is sent via the CLI, it is recommended to chain commands together as one when setting multiple values in a config section. For example:

meshtastic --set mqtt.enabled true --set mqtt.json_enabled true

Web

All MQTT module config options are available for the Web UI.

Access the Default Public Server

Android

Enable the MQTT Module

Navigate to: Vertical Ellipsis (3 dots in the top right) > Radio Configuration > MQTT: Turn on the slider for MQTT enabled and tap Send.

Optional: To use your phone's internet connection to send and receive packets over the web, also enable the slider for MQTT Client Proxy and skip the Configure Network Settings step below.

Enable Channel Uplink & Downlink

Navigate to: Vertical Ellipsis (3 dots in the top right) > Radio Configuration > Channels > LongFast: Turn on the sliders for Uplink enabled and Downlink enabled, then tap Save and tap Send.

Configure Network Settings

Navigate to: Vertical Ellipsis (3 dots in the top right) > Radio Configuration > Network: Turn on the slider for WiFi enabled, enter the SSID and PSK for your network, then tap Send.

Apple

Activate the MQTT Module Go to Settings > MQTT: Toggle the MQTT enabled switch to the ON position and then tap Save.

Optional: If you want to use your phone's internet connection to send and receive packets online, enable the MQTT Client Proxy toggle as well and bypass the Configure Network Settings step below.

Activate Channel Uplink & Downlink Go to Settings > Channels > Primary Channel: Toggle the Uplink enabled and Downlink enabled switches to the ON position, then tap Save.

Set Up Network Settings Go to Settings > Network: Toggle the WiFi enabled switch to ON, then enter your SSID and PSK for the network, and tap Save.

CLI

Enable the MQTT Module

meshtastic --set mqtt.enabled true

Enable Channel Uplink & Downlink

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

or chained together:

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

Configure Network Settings

meshtastic --set network.wifi_enabled true meshtastic --set network.wifi_ssid "your network" meshtastic --set network.wifi_psk yourpassword

or chained together:

meshtastic --set network.wifi_enabled true --set network.wifi_ssid "your network" --set network.wifi_psk yourpassword

Web

Activate the MQTT Module Go to Config > Module Config > MQTT - Toggle the MQTT enabled switch to ON - Click the Save icon.

Optional: If you want to use your client's internet connection for sending and receiving packets online, enable the Proxy to Client Enabled slider as well and skip the Configure Network Settings step below.

NOTE: Although this option might be visible in your UI, the Client Proxy is not currently operational with the Web Client.

Activate Channel Uplink & Downlink Go to Channels > Primary: Toggle the switches for Uplink Enabled and Downlink Enabled to the ON position - Click the Save icon.

Set Up Network Settings Go to Radio Config > Device > Network: Toggle the Enabled switch to the ON position, enter your SSID and PSK for the network, and click the Save icon.