# Raspberry Pi MQTT Gateway Setup

## What This Achieves

Connecting a Meshtastic USB device to a Raspberry Pi and running Mosquitto turns the Pi into a persistent internet gateway. 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 - all without leaving the [Meshtastic app](https://wiki.meshamerica.com/books/hardware-guide/page/meshtastic-app) running on a laptop.

## Hardware Requirements

<table id="bkmrk-componentnotes-raspb"> <thead> <tr><th>Component</th><th>Notes</th></tr> </thead> <tbody> <tr><td>Raspberry Pi 3B+, 4, or Zero 2W</td><td>3B+ or 4 for comfort; Zero 2W for power-constrained installs. All run Pi OS Lite adequately.</td></tr> <tr><td>MicroSD card (16 GB+)</td><td>Class 10 / A1 rated. Use a quality brand - SD card failures are the #1 Pi reliability issue.</td></tr> <tr><td>Meshtastic USB node</td><td>T-Beam, Heltec V3, RAK WisBlock, or any device that enumerates as a serial CDC ACM device.</td></tr> <tr><td>USB cable</td><td>Data-capable USB-A to USB-C (or micro, depending on node).</td></tr> <tr><td>Case and power supply</td><td>Official Pi PSU or PoE HAT for rooftop deployments.</td></tr> </tbody></table>

## 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:

- Hostname (e.g. `mesh-gw-01`)
- SSH enabled with your public key
- WiFi credentials (or leave blank if using Ethernet)

### 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/`):

```
# 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:

- **MQTT server**: `localhost` (if running on the same Pi) or the Pi's LAN IP from another device.
- **MQTT port**: 1883
- **Uplink enabled**: Yes (for the channels you want to bridge)
- **Downlink enabled**: Yes (to receive messages from MQTT back to the mesh)
- **Encryption passthrough**: Disabled unless you want encrypted payloads in MQTT (disable for plaintext JSON)

Via CLI:

```
meshtastic --set mqtt.address localhost --set mqtt.enabled true --set mqtt.json_enabled true
```

### Step 5 - Verify packets are flowing

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

You should see topic/payload pairs appear each time a mesh packet is received by your gateway node. Position packets, text messages, and telemetry all appear as separate topics.

## Remote Access Options

- **LAN only**: Listen on `127.0.0.1` or LAN IP. Accessible only within your local network - simplest and most secure.
- **Internet-exposed with auth**: Set `listener 1883 0.0.0.0` with a password file. Open port 1883 in your router/firewall only if you need external access. Consider using TLS (Mosquitto supports it natively).
- **Cloud MQTT broker**: Point your nodes at EMQX Cloud, HiveMQ Cloud, or a self-hosted Mosquitto VPS. Multiple Pi gateways in different locations all publish to the same broker - gives you a unified view of all gateways from anywhere.

## 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`:

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

[Service]
User=pi
ExecStart=/usr/bin/python3 /home/pi/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://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)
```

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

<table id="bkmrk-boardidle-powernotes"> <thead> <tr><th>Board</th><th>Idle power</th><th>Notes</th></tr> </thead> <tbody> <tr><td>Raspberry Pi 4 (2 GB)</td><td>~3.4 W</td><td>PoE HAT adds ~1 W; suitable for rooftop enclosure with PoE switch</td></tr> <tr><td>Raspberry Pi 3B+</td><td>~2.9 W</td><td>Good balance of capability and power</td></tr> <tr><td>Raspberry Pi Zero 2W</td><td>~0.9 W</td><td>Best for solar/battery; limited to single USB device, requires USB OTG adapter</td></tr> </tbody></table>

Add ~0.5 - 1 W for the connected Meshtastic node. A small 12 V/7 Ah SLA battery can sustain a Zero 2W + node gateway for 40+ hours without solar input.