Known-Good Baseline Checklist

Mesh-Plug + Meshtastic

Known-Good Baseline Checklist

(with Hard Reset Playbook) Download PDF

Part 1; Known-Good Baseline (start here)

Use this baseline whenever you want predictable behavior.

Hardware

  • One Meshtastic radio acting as gateway (Heltec v4, RAK, etc.)
  • GPS optional but recommended
  • Stable power source (USB or battery)

Controller App (IMPORTANT)

  • Use Android as the authoritative controller
  • Do not run macOS and Android simultaneously
  • Fully close unused Meshtastic apps

Why: Meshtastic gateways do not reliably support multi-controller MQTT sessions yet.

MQTT Broker

  • Broker reachable via WSS or TLS
  • No auth errors
  • Root topic is consistent (example: msh)
  • No retained test junk from previous experiments

Recommended:

msh/#

Radio Configuration (via Android)

MQTT

  • Enabled: ✅
  • Root topic: msh
  • JSON enabled: ✅
  • Downlink enabled: ✅
  • TLS / WSS configured correctly

Channels

Create a channel with exact name:

mqtt

Settings:

  • Uplink: ✅
  • Downlink: ✅
  • Encryption: default (does not matter for JSON)

Mesh-Plug Settings

  • MQTT URL correct (example: wss://mqtt.example.com:9001)
  • Root topic: msh
  • Gateway Hex set manually if on macOS or if auto-detect fails
  • Charts / maps enabled

Expected “Healthy” Behavior

Within 30–60 seconds you should see:

  • NodeInfo packets
  • Nodes table populated
  • Chat messages flowing
  • Position updates visible on map

If this happens, stop changing things. This is your baseline.

Part 2; Hard Reset Playbook (use when things go weird)

Use this any time you see:

  • Connected but no nodes
  • Chat not responding
  • Send Position ignored
  • Switching Android ↔ macOS breaks everything

STEP 1; Power-cycle the radio (mandatory)

This is not optional.

  • Unplug USB or disconnect battery
  • Wait 10–15 seconds
  • Plug back in

Why:

  • Clears stale MQTT session state
  • Resets gateway role
  • Forces fresh NodeInfo broadcast

STEP 2; Choose ONE controller

  • Pick Android OR macOS
  • Close the other app completely
  • Do not background it

Rule:

One radio, one controller, one MQTT brain

STEP 3; Let the controller fully initialize

After reconnect:

  • Wait at least 30 seconds
  • Watch for:
    • NodeInfo
    • User info
    • Position packets

Do not open Mesh-Plug yet.

STEP 4; Verify MQTT traffic (optional but helpful)

Use MQTT Explorer or mosquitto_sub:

  • Confirm uplinks appear under: msh/+/json/#
  • Confirm NodeInfo is present

If NodeInfo is missing; stop and repeat Step 1.

STEP 5; Open Mesh-Plug

Now load the WordPress page:

  • Nodes should populate immediately
  • Map should no longer be blank
  • Chat should render

If Mesh-Plug does not populate now, the problem is upstream.

Part 3; macOS-Specific Reality Check

macOS Meshtastic app quirks:

  • NodeInfo often not broadcast
  • Downlink unreliable
  • Send Position frequently ignored
  • Gateway hex often unknown

Workaround:

  • Manually set Gateway Hex in Mesh-Plug
  • Treat macOS as:
    • Viewer
    • Config editor
    • NOT the primary gateway controller

Part 4; Rules That Prevent 90% of Problems

  • ❌ Do not hot-swap Android ↔ macOS without rebooting the radio
  • ❌ Do not change root topics mid-session
  • ❌ Do not rely on retained NodeInfo
  • ✅ Always power-cycle when changing roles
  • ✅ Keep one “known-good” config and return to it

Part 5; Why Mesh-Plug Feels “Strict” (and why that’s good)

Mesh-Plug intentionally:

  • Refuses ghost nodes
  • Requires NodeInfo trust
  • Blocks ambiguous downlink
  • Avoids MQTT replay pollution

This prevents:

  • Node drift
  • Jumping markers
  • Incorrect chat attribution
  • Security issues on shared brokers

It surfaces Meshtastic edge cases instead of hiding them.

TL;DR Quick Recovery

If anything breaks:

  1. Power-cycle radio
  2. Use Android only
  3. Wait for NodeInfo
  4. Then open Mesh-Plug