Mesh-Plug Connectivity Checklist

(Meshtastic + MQTT + WordPress)

This checklist verifies that Meshtastic devices, your MQTT broker, and Mesh-Plug are all connected using the correct transport.

Key rule:
Devices/apps use MQTT over TLS (8883); browsers use MQTT over WebSockets (9001).

1. Port & Transport Map (Read This First)

Component	Port	Transport	Why
Meshtastic Android	8883	MQTT over TLS	Native MQTT client
Meshtastic Devices	8883	MQTT over TLS	Standard IoT transport
Mesh-Plug (WordPress)	9001	MQTT over WebSockets (WSS)	Required by browsers
`mosquitto_sub/pub`	8883 only	MQTT over TLS	CLI does not support WSS

⚠️ mosquitto_sub will never work on port 9001; protocol errors are expected.

2. Android Meshtastic Settings (Publisher)

MQTT Settings

Host: mqtt.your-domain.com
Port: 8883
TLS: ON
Username / Password: (your broker creds)
Root topic: msh
JSON output: ON

After changing settings

Toggle MQTT OFF → ON
Send:
- Exchange User Info
- Send Position
- Chat message

3. Mesh-Plug Settings (Subscriber)

Broker

URL: wss://mqtt.your-domain.com:9001/mqtt

Topics

Subscribe topic: msh/#
Publish prefix (if enabled): msh

Important stability setting

Gateway Hex:
Set this explicitly (example: !b2a7c7a8)
Do not rely on auto-learn once your system is stable.

4. Broker Sanity Checks (Server)

Confirm ports are listening

nc -vz mqtt.your-domain.com 8883
nc -vz mqtt.your-domain.com 9001

Both should succeed.

Confirm 9001 is WebSockets

curl -i -k --http1.1 \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  https://mqtt.your-domain.com:9001/mqtt

Expected:

HTTP/1.1 101 Switching Protocols

5. Verify Meshtastic Traffic (CLI Test)

Run this before checking WordPress:

mosquitto_sub -v \
  -h mqtt.your-domain.com \
  -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u YOUR_USER \
  -P 'YOUR_PASSWORD' \
  -t 'msh/#'

Then trigger actions in the Android app.

You should see messages like:

msh/2/json/... {"type":"nodeinfo"...}
msh/2/json/... {"type":"position"...}
msh/2/json/... {"payload":{"text":"hello"}}

If you see traffic here but not in Mesh-Plug, the issue is browser/WSS config.
If you see nothing, Android is not publishing.

6. Common Failure Modes (and Fixes)

❌ No data anywhere

Android accidentally set to 9001
Root topic doubled (msh/msh)
MQTT toggled on but never reconnected

Fix: Android → port 8883, toggle MQTT off/on.

❌ Mesh-Plug connected but no chat or nodes

Gateway Hex auto-learn polluted by client swapping

Fix: Set Gateway Hex explicitly and reload dashboard.

❌ `mosquitto_sub` protocol error

Attempting to test 9001

Fix: Use 8883 only for CLI testing.

7. Golden Rule (Pin This)

Devices publish on 8883.
Browsers subscribe on 9001.
Same broker. Same topics. Different transports.

Connectivity Checklist