Gateway Setup Guides

Step-by-step setup guides for Raspberry Pi MQTT gateways and MeshCore Linux room servers.

Raspberry Pi MQTT Gateway Setup

What This Achieves

The Meshtastic node acts as the MQTT gateway, bridging LoRa packets to an MQTT broker (it uplinks/downlinks LoRa<->MQTT using its own network connection or the connected client's). Mosquitto running on the Raspberry Pi is just the broker: it provides a persistent, always-on broker and host so you do not need a phone or laptop running the Meshtastic app. The node must have mqtt.enabled set and point at the broker for any bridging to happen - running Mosquitto alone does not bridge the mesh. Once configured it forwards mesh packets to MQTT (locally and/or to a cloud broker), enables remote monitoring of all nodes on your mesh, and allows the node to relay messages between the mesh and internet-connected services.

Hardware Requirements

ComponentNotes
Raspberry Pi 3B+, 4, or Zero 2W3B+ or 4 for comfort; Zero 2W for power-constrained installs. All run Pi OS Lite adequately.
MicroSD card (16 GB+)Class 10 / A1 rated. Use a quality brand - SD card failures are the #1 Pi reliability issue.
Meshtastic USB nodeT-Beam, Heltec V3, RAK WisBlock, or any supported device that presents a USB serial port (native CDC-ACM, or via a CP210x/CH340 USB-UART bridge that appears as a ttyUSB device). See meshtastic.org/docs/hardware for supported devices.
USB cableData-capable USB-A to USB-C (or micro, depending on node).
Case and power supplyOfficial Pi PSU or PoE HAT for rooftop deployments.

Software Setup

Step 1 - Flash the OS

Use Raspberry Pi Imager to flash Raspberry Pi OS Lite (64-bit) to the SD card. In the imager's Advanced Options, pre-configure:

Step 2 - Install dependencies

sudo apt update && sudo apt upgrade -y
sudo apt install -y mosquitto mosquitto-clients python3-pip
pip3 install meshtastic

Step 3 - Configure Mosquitto

Edit /etc/mosquitto/mosquitto.conf (or create a file in /etc/mosquitto/conf.d/). Mosquitto 2.0+ (the version shipped by apt) defaults allow_anonymous to false and, with no listener defined, binds to localhost only - a bare install rejects LAN clients until you add a listener and either allow anonymous access or a password file:

# Allow anonymous local connections (safe for LAN-only installs)
listener 1883
allow_anonymous true

# For remote access, use authentication instead:
# listener 1883 0.0.0.0
# allow_anonymous false
# password_file /etc/mosquitto/passwd
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

Step 4 - Configure the Meshtastic node

Connect to the node via the Meshtastic app or CLI and set:

Via CLI:

meshtastic --set mqtt.address localhost --set mqtt.enabled true --set mqtt.json_enabled true
# uplink is per-channel and defaults to off - enable it on the channel you want bridged:
meshtastic --ch-index 0 --ch-set uplink_enabled true

Step 5 - Verify packets are flowing

mosquitto_sub -h localhost -t 'msh/#' -v

With JSON enabled (mqtt.json_enabled true), text, position, and telemetry packets appear as readable JSON under msh/REGION/2/json/.... Without JSON, the payload under msh/REGION/2/e/... is raw protobuf (encrypted or unencrypted) and mosquitto_sub displays it as binary, not readable separate messages. If mosquitto_sub returns immediately or hangs with nothing at all, confirm allow_anonymous true is actually applied - Mosquitto 2.0 refuses anonymous connections by default; add -u/-P if you set a password.

Remote Access Options

systemd Service for the Meshtastic Connection

If you run a Python script to bridge or monitor the mesh, create /etc/systemd/system/mesh-bridge.service. Replace youruser below with the actual username you created when imaging - since Pi OS Bookworm there is no default pi account, and the unit will fail to start if the user does not exist:

[Unit]
Description=Meshtastic mesh bridge
After=network.target mosquitto.service

[Service]
User=youruser
ExecStart=/usr/bin/python3 /home/youruser/mesh_bridge.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
sudo systemctl enable mesh-bridge
sudo systemctl start mesh-bridge

Node-RED on the Same Pi

Install Node-RED for visual flow-based packet processing with zero additional cloud dependency:

bash <(curl -sL https://github.com/node-red/linux-installers/releases/latest/download/update-nodejs-and-nodered-deb)

Use the MQTT-in node subscribed to msh/# to receive all mesh packets, then add function nodes to parse JSON, filter by type, and push to dashboards, databases, or notification services. The Node-RED UI dashboard module provides a web-accessible map and message log without any external services.

Power Budget

BoardIdle / light-load powerNotes
Raspberry Pi 4 (2 GB)~3.4 WIdle/light-load figure, not peak. PoE HAT adds ~1 W; suitable for rooftop enclosure with PoE switch
Raspberry Pi 3B+~2.9 WIdle/light-load figure. Good balance of capability and power
Raspberry Pi Zero 2W~0.9 WIdle/light-load figure. Best for solar/battery; limited to single USB device, requires USB OTG adapter

Add ~0.5 - 1 W (average) for the connected Meshtastic node; TX bursts at +22 dBm draw more momentarily. The figures above are idle/light-load estimates, not peak. A 12 V/7 Ah SLA battery is ~84 Wh nominal, but SLA chemistry should only be discharged to ~50% depth to avoid damage (~42 Wh usable), and a 12 V->5 V buck converter loses ~10-15%. Against a Zero 2W + node load of roughly 1.5-1.9 W, expect about 20-25 hours of runtime, not 40+. Reaching 40+ hours would require deep discharge that shortens SLA lifespan.

Setting Up a Meshtastic MQTT-to-Internet Gateway

An MQTT gateway connects your Meshtastic mesh to the internet, enabling message delivery to non-LoRa clients, integration with home automation, and connection to the global Meshtastic MQTT network.

What the MQTT Gateway Does

A Meshtastic node in "MQTT gateway" mode:

Requirements

Configuration Steps

Option A: Using the Meshtastic Public MQTT Server

The public broker mqtt.meshtastic.org is not anonymous - it requires username meshdev / password large4cats (these are also the firmware's built-in defaults).

# Configure via CLI:
meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address mqtt.meshtastic.org
meshtastic --set mqtt.username meshdev
meshtastic --set mqtt.password large4cats

# Configure which channels to bridge (uplink/downlink are per-channel and default OFF)
meshtastic --ch-index 0 --ch-set uplink_enabled true
meshtastic --ch-index 0 --ch-set downlink_enabled true

# Configure WiFi (if not already done)
meshtastic --set network.wifi_ssid "YourSSID"
meshtastic --set network.wifi_psk "YourPassword"

Privacy note: The public MQTT server relays messages globally. Only use it for the default (unencrypted) channel unless you want your encrypted channel traffic relayed globally.

Option B: Self-Hosted Mosquitto MQTT Broker

# Install Mosquitto on Raspberry Pi or VPS:
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto

# Mosquitto 2.0+ defaults allow_anonymous to FALSE and binds localhost-only.
# A bare install rejects LAN clients until you define a listener. Create
# /etc/mosquitto/conf.d/local.conf with:
#   listener 1883 0.0.0.0
#   allow_anonymous true   # trusted LAN only; otherwise use a password_file
# For authentication instead of anonymous access:
#   mosquitto_passwd -c /etc/mosquitto/passwd youruser
#   password_file /etc/mosquitto/passwd
#   allow_anonymous false
sudo systemctl restart mosquitto

# Configure node to use your local broker:
meshtastic --set mqtt.address 192.168.1.100
meshtastic --set mqtt.enabled true

Verifying the Gateway is Working

# Subscribe to all Meshtastic MQTT topics and watch for packets
# (the public broker requires credentials):
mosquitto_sub -h mqtt.meshtastic.org -u meshdev -P large4cats -t "msh/US/2/e/#" -v

# Or on your local broker:
mosquitto_sub -h 192.168.1.100 -t "msh/#" -v

You should see packets appearing as mesh traffic is received. On the /e/ (encrypted) topic these are raw binary protobuf-encoded ServiceEnvelope messages, not base64 text.

MQTT Packet Decoding

Meshtastic MQTT packets on the /e/ topic are protobuf-encoded. The Python meshtastic package has no turnkey MQTT class - the documented approach is to subscribe with paho-mqtt and decode the payload with the bundled protobuf bindings (meshtastic.protobuf):

pip install meshtastic paho-mqtt

import paho.mqtt.client as mqtt
from meshtastic.protobuf import mqtt_pb2  # ServiceEnvelope lives in mqtt.proto

def on_message(client, userdata, msg):
    # The /e/ payload is RAW BINARY protobuf - feed it straight in, do not base64-decode it
    envelope = mqtt_pb2.ServiceEnvelope()
    envelope.ParseFromString(msg.payload)
    print(envelope)

client = mqtt.Client()
client.username_pw_set("meshdev", "large4cats")
client.on_message = on_message
client.connect("mqtt.meshtastic.org", 1883)
client.subscribe("msh/US/2/e/#")
client.loop_forever()

Note: from meshtastic.mqtt import MQTT does not exist - there is no built-in MQTT client class in the library.