# Temperate Mesh — MQTT Explained (Plain Language)

**Document purpose:** Customer-facing guide to MQTT in Meshtastic—suitable for inclusion in manuals or as a standalone handout.  
**Audience:** Anyone new to MQTT; no networking background required.  
**Policy:** The **public Temperate MQTT broker is free**. We charge for **help setting up your own private broker** at home.

---

## What is MQTT? (30-second version)

**MQTT** is a lightweight way for devices to **publish messages to a server on the internet** (called a **broker**), where other apps can **subscribe** and read them.

For Meshtastic, MQTT is the **bridge between the local LoRa mesh and the internet**:

```
Your mesh (LoRa)  ◄──►  Gateway node (Wi-Fi)  ◄──►  MQTT broker  ◄──►  Maps, phones, home servers
```

**Think of it like a post office for radio messages:**

- Your gateway **drops off** mesh traffic at the broker (uplink)
- Maps and tools **pick up** copies to display (subscribe)
- Downlink **delivers internet traffic back** onto the mesh (use carefully)

---

## Why would I want MQTT?

| Benefit | Plain explanation |
|---------|-------------------|
| **See the mesh on a map** | Your node can appear on [map.meshtastic.org](https://map.meshtastic.org) when uplinked |
| **Monitor from home** | Watch mesh activity while away (if a gateway is online) |
| **Regional visibility** | Temperate Mesh community can see gateway health (when broker is live) |
| **Integrations** | Home automation, logging, custom dashboards (advanced) |

**What MQTT does NOT do:**

- It does **not** replace LoRa between handhelds in the field
- It does **not** give you cell-phone coverage everywhere
- It does **not** make public channels private—see Privacy below

---

## Key concepts (simple glossary)

| Term | Meaning |
|------|---------|
| **Broker** | Internet server that receives and routes MQTT messages |
| **Topic** | Address/label for a message (like a folder path) |
| **Publish / Uplink** | Send mesh traffic to the broker |
| **Subscribe** | Listen for messages on a topic |
| **Downlink** | Broker sends internet traffic onto the LoRa mesh |
| **Gateway node** | Meshtastic device with Wi-Fi (or phone proxy) connected to broker |
| **Root topic** | Base path for all Meshtastic messages (US region: `msh/US/...`) |

---

## How it works step by step

### Step 1 — Local mesh

Two hunters message each other over LoRa. No MQTT needed for that conversation.

### Step 2 — Gateway hears mesh traffic

A home Heltec or RAK on Wi-Fi runs MQTT enabled. It hears LoRa packets.

### Step 3 — Uplink to broker

If **uplink** is enabled on that channel, the gateway publishes JSON to the broker, e.g.:

```
msh/US/2/json/LongFast/!abc123
```

### Step 4 — Subscribers consume

The public map, logging tools, or your home dashboard subscribe and display data.

### Step 5 — Downlink (optional, caution)

If **downlink** is on, messages from the internet can be injected onto LoRa. On **public LongFast**, this can add RF congestion—Temperate Mesh recommends **uplink only** for most home gateways.

---

## Temperate Mesh broker policy

| Service | Cost | Purpose |
|---------|------|---------|
| **Temperate public broker** | **Free** | Regional SE Alaska community bridge when live (see [temperate.app](https://temperate.app)) |
| **Meshtastic public broker** | Free (third-party) | `mqtt.meshtastic.org` — works today worldwide |
| **Private home broker setup** | **Paid service ($200–500)** | We help you run **your own** broker for family/friends/team |

### Why keep Temperate public broker free?

- Encourages mesh growth and map visibility
- Aligns business profit with **setup, education, and installs**—not tolling community traffic
- Builds goodwill and referrals

### When to pay for private broker help

- You want **family-only** or **team-only** MQTT without sharing a public server
- You want messages stored on **your** Raspberry Pi / NAS / home server
- You run **ATAK/iTAK** or custom tools against your own topics
- You understand downlink risks and want controlled policies

**We do not sell access to the free Temperate broker—we sell expertise to run yours safely.**

---

## Public broker settings (reference)

Use these until Temperate regional broker is live. Documented on temperate.app.

| Setting | Value |
|---------|-------|
| Enabled | `true` |
| Address | `mqtt.meshtastic.org` |
| Root topic | `msh/US` |
| Port (MQTT) | `1883` |
| Port (TLS) | `8883` |
| Username / password | Blank (public broker) |

**In the app:** Settings → MQTT  
**CLI example:**

```bash
meshtastic --set mqtt.enabled true
meshtastic --set mqtt.address mqtt.meshtastic.org
meshtastic --ch-index 0 --ch-set uplink_enabled true
```

---

## Gateway best practices (Temperate Mesh recommendations)

1. **Who runs MQTT:** Home nodes with stable power + Wi-Fi—not battery field trackers
2. **Public LongFast:** Prefer **uplink ON, downlink OFF**
3. **Firmware:** Use current Meshtastic firmware (2.2.0+ for best MQTT features)
4. **Map reporting:** Enable only if customer understands location sharing
5. **Position precision:** Reduce precision on public channels if privacy matters
6. **One gateway is enough** for many neighborhoods—don't duplicate unnecessarily

---

## Privacy & security (read this)

| Fact | Implication |
|------|-------------|
| LongFast uses a **public** PSK | Anyone can read traffic on that channel |
| MQTT uplink copies mesh traffic to internet | Treat public channel like a **public bulletin board** |
| Private channel + private broker | Stronger privacy—but still not military-grade; know your threat model |
| QR codes contain keys | Hand deliver only; never post online |

**Temperate Mesh will not publish customer keys, QR codes, or broker passwords.**

---

## Map reporting (optional)

To appear on the public map when uplinked:

```bash
meshtastic --set mqtt.mapReportingEnabled true
meshtastic --set mqtt.mapReportPublishInterval 300
```

Explain to customers:

- Fixed repeaters: OK to show approximate fixed position
- Mobile hunters: consider **lower precision** or disable map reporting

---

## Troubleshooting MQTT

| Problem | Check |
|---------|-------|
| Not on map | Uplink enabled? Gateway online? Wi-Fi working? |
| Gateway offline | Power, Wi-Fi password, broker address typo |
| Duplicate messages | Multiple gateways uplinking same traffic—normal; apps dedupe |
| High mesh airtime | Downlink enabled on busy channel—turn off |

---

## Paid service: Private MQTT broker setup

**What we deliver:**

1. Requirements call (who needs access, privacy level, hardware at home)
2. Choose platform: Raspberry Pi 4, mini PC, NAS Docker, etc.
3. Install broker software (e.g. Mosquitto) with TLS and authentication
4. Configure Meshtastic gateway to use **your** broker
5. Document credentials in **private** handout (not email unencrypted if avoidable)
6. 30-minute walkthrough + 30-day support window for broker questions

**What we don't deliver:**

- 24/7 hosted SLA on your home internet (unless separate hosting contract)
- Guaranteed map presence on meshtastic.org (that's public infrastructure)

**Price guidance:** $200 basic (single home, one gateway) · $350–500 multi-user/ATAK integration

---

## FAQ

**Does MQTT cost monthly?**  
The public brokers don't charge. Your home internet and power are your ongoing costs.

**Can I use my phone as gateway?**  
Yes—the app can proxy MQTT when connected. Good for testing; not ideal 24/7.

**Will MQTT work on T1000-E alone?**  
No Wi-Fi on T1000-E—it needs another gateway node or phone proxy.

**Is MQTT required to use Meshtastic?**  
No. Many users never enable it. Mesh texting works purely over LoRa.

**When will Temperate broker be live?**  
Watch temperate.app—until then use `mqtt.meshtastic.org`.

---

*Related: customer manual Section 5.3 in `03-customer-manual-outline.md` · ATAK integration `05-atak-itak-guide.md`*