Overview
Mesh-Plug connects your Meshtastic network to WordPress using MQTT; a lightweight, event-driven messaging protocol designed for low-power and intermittent devices. Once connected, your site can receive, visualize, and optionally archive mesh telemetry, messages, and node metadata in near real time.
You do not need to be an IoT engineer to use Mesh-Plug; however, a basic understanding of networking and WordPress administration will make setup smoother.
This guide reflects the current Mesh-Plug architecture, including auto-configured brokers, WebSocket support, NodeDB handling, and optional archival features.
Skills and Tools You Should Be Comfortable With
Recommended knowledge
- Basic WordPress administration; installing plugins, navigating settings pages, and inserting shortcodes
- Networking fundamentals; domains, ports, LAN vs public access
- IoT data flow concepts; devices publish data, applications subscribe to it
Helpful but optional
- Command-line usage (macOS, Linux, or Windows PowerShell)
- Familiarity with Mosquitto or another MQTT broker
- Experience with Meshtastic CLI for node configuration
Software and Hardware Requirements
Required
- One or more Meshtastic devices (ESP32, T-Beam, Heltec, etc.) running current firmware
- Mesh-Plug installed and activated on a WordPress site
- An MQTT broker, either:
- Automatically managed or proxied; or
- Self-hosted (Mosquitto, EMQX, HiveMQ, Adafruit IO)
Optional but useful
- Meshtastic CLI (
pip install meshtastic) - MQTT Explorer or similar client for diagnostics
Once these pieces are in place, your mesh can bridge from radio to web without custom code.
What MQTT Does in Mesh-Plug
MQTT uses a publish/subscribe model:
- Meshtastic nodes publish data such as telemetry, GPS, and messages to topics
- Mesh-Plug subscribes to those topics and renders the data inside WordPress
Mesh-Plug handles:
- WebSocket connections
- Topic subscriptions
- Message decoding and normalization
- Optional NodeDB and message archiving
Your WordPress site effectively becomes a live dashboard for your mesh.
Step 1: Choose Your MQTT Connection Mode
Option A: Auto (Recommended)
This is the default and preferred setup for most users.
Mesh-Plug can automatically resolve and connect to an MQTT broker using your site’s domain, typically via WebSockets and a reverse proxy or tunnel.
Typical configuration
- Mode:
MQTT - Broker URL:
auto - Client ID: auto-generated
- Topic:
msh/# - Authentication: none, unless your broker requires it
Mesh-Plug will attempt to connect using:
ws://yourdomain.com:9001for HTTP; orwss://yourdomain.com/mqttfor HTTPS environments
No code edits are required. Once enabled, Mesh-Plug subscribes and begins listening immediately.
This mode is ideal for:
- Local brokers behind a tunnel
- Managed MQTT services
- Quick demos and production dashboards
Option B: Manual / Advanced Configuration
Use this option if you are running a dedicated broker, require authentication, or manage multiple feeds.
Broker setup example (Mosquitto)
Verify your broker is working:
# Terminal 1
mosquitto_sub -h 127.0.0.1 -t "test/topic" -v
# Terminal 2
mosquitto_pub -h 127.0.0.1 -t "test/topic" -m "Hello MQTT"
If the message appears, the broker is running correctly.
Configure your Meshtastic node
meshtastic --port /dev/cu.usbmodemXXXX \
--set mqtt.enabled true \
--set mqtt.address 192.168.0.110 \
--set mqtt.username mqttuser \
--set mqtt.password 'YourPasswordHere' \
--set mqtt.json_enabled true \
--set mqtt.tls_enabled false
meshtastic --reboot
Replace the address and credentials as needed.
Verify live data
mosquitto_sub -h 127.0.0.1 \
-u mqttuser \
-P 'YourPasswordHere' \
-t 'msh/#' -v
You should see structured JSON packets from active nodes.
Step 2: Connect Mesh-Plug to the Broker
Navigate to:
WordPress → Settings → Mesh-Plug
Configure the following fields:
| Setting | Auto Mode | Advanced Mode |
|---|---|---|
| Mode | MQTT | MQTT |
| Broker URL | auto | wss://broker.example.com:9001/mqtt |
| Client ID | Auto | Custom |
| Topic | msh/# | Custom |
| Username / Password | Optional | Required if broker enforces auth |
| TLS | Auto | Enable for wss:// |
| NodeDB | Optional | Optional |
| Archive | Optional | Optional |
Save settings and reload the dashboard.
Once messages are flowing, Mesh-Plug begins populating node and telemetry data automatically.
Step 3: Displaying MQTT Data on Your Site
Mesh-Plug exposes data via shortcodes.
Basic example
[mesh_plug_display topic="msh/#"]
Common display formats
format="log"; live message streamformat="map"; node locations if GPS data existsformat="nodes"; NodeDB summaryformat="chart"; telemetry graphs (archive required)
Shortcodes can be placed in pages, posts, widgets, or custom templates.
Step 4: Troubleshooting
| Issue | What to Check |
|---|---|
| No data visible | Confirm broker connection in Mesh-Plug logs |
| Connection errors | Verify broker URL, port, and protocol |
| Auth failures | Test credentials with MQTT Explorer |
| Topic mismatch | Ensure node and plugin use same prefix |
| Nodes missing | Wait for first transmission; NodeDB builds dynamically |
| Disconnects | Increase keepalive or review broker limits |
Step 5: Going Further
Once your baseline setup is working, Mesh-Plug supports:
- Multiple broker subscriptions
- NodeDB enrichment and persistence
- Telemetry charts and historical analysis
- Message archiving in WordPress
- Alerting and automation hooks
- TLS, ACLs, and hardened production brokers
These features can be layered in gradually without reworking your base configuration.
These features can be layered in gradually without reworking your base configuration.
Final Notes
Mesh-Plug is designed to scale from a single demo node to full mesh monitoring systems.
Start with auto mode for speed and reliability; move to manual broker control when you need advanced routing, authentication, or data retention.
Within minutes, your WordPress site can become a live interface for off-grid networks; powered by MQTT, driven by Meshtastic, and fully web-accessible.
Leave a Reply