Getting Connected to Mesh-Plug!

Mesh-Plug connects your Meshtastic network to WordPress using MQTT. Once connected, your site can receive and display mesh traffic such as node information, chat messages, telemetry, and location data.

You do not need to be an IoT engineer to use Mesh-Plug, but setup is smoother if you are comfortable with basic WordPress administration, MQTT broker settings, and the difference between native MQTT and MQTT over WebSockets.

This guide reflects Mesh-Plug 1.3.2 and newer, including current Meshtastic protobuf MQTT support, legacy JSON support, observer mode, live mode, and server-side snapshots.

What Mesh-Plug Does

Meshtastic devices and apps publish packets to an MQTT broker.

Mesh-Plug subscribes to those MQTT topics and renders the traffic inside WordPress.

Depending on your configuration, Mesh-Plug can show:

• Live packet logs
• Nodes
• Chat messages
• Map positions
• Telemetry charts
• Server-cached observer dashboards

Mesh-Plug 1.3.2 supports current Meshtastic protobuf MQTT traffic and older JSON MQTT traffic.

Skills and Tools You Should Be Comfortable With

Recommended:

• Installing and configuring WordPress plugins
• Editing WordPress pages and shortcodes
• Understanding domains, ports, and TLS
• Knowing whether a page is public or admin-only

Helpful but optional:

• MQTT Explorer
• mosquitto_sub / mosquitto_pub
• Meshtastic CLI
• A self-hosted broker such as Mosquitto, EMQX, or HiveMQ

Requirements

Required:

• One or more Meshtastic devices running current firmware
• Mesh-Plug installed and activated on a WordPress site
• An MQTT broker reachable from your Meshtastic gateway
• A WebSocket MQTT endpoint reachable from the browser for live mode

Optional but useful:

• A private MQTT broker
• MQTT Explorer for diagnostics
• Server cache enabled in Mesh-Plug for public observer dashboards
• Map Reporting enabled on your Meshtastic node if you want map-report style public location updates

Important: Devices and Browsers Use Different MQTT Transports

This is the most common point of confusion.

Meshtastic devices and mobile apps usually connect to MQTT using native MQTT over TLS:

mqtt.example.com:8883

Mesh-Plug runs in a web browser for live mode, so it must use MQTT over WebSockets:

wss://mqtt.example.com:9001/mqtt

Same broker. Same topics. Different transport.

mosquitto_sub is useful for testing native MQTT on port 8883. It does not test your browser WebSocket URL.

Step 1: Confirm Your Meshtastic MQTT Setup

In your Meshtastic app, enable MQTT and configure your broker.

Typical broker settings:

Host: mqtt.example.com
Port: 8883
TLS: enabled
Username: your broker username
Password: your broker password
Root topic: msh

Your channel must also allow uplink if you want packets from your mesh to reach MQTT.

For public or shared channels, remember that current Meshtastic behavior may reduce position precision or require explicit location/telemetry opt-in. That is expected.

Step 2: Choose the Right MQTT Topic

Mesh-Plug 1.3.2 defaults new installs to:

msh/2/e/#

Common topic options:

msh/2/e/#
msh/2/c/#
msh/2/map/#
msh/2/json/#
msh/#

Use msh/2/e/# or msh/2/c/# for current Meshtastic protobuf MQTT traffic.

Use msh/2/map/# if you only want Meshtastic map-report packets.

Use msh/2/json/# only if your gateway still publishes legacy JSON MQTT packets.

Use msh/# while troubleshooting mixed traffic, then narrow the topic once you know what your broker is receiving.

Busy public topics can create a lot of browser work, so avoid broad subscriptions on production dashboards unless you really need them.

Step 3: Configure Mesh-Plug

In WordPress, go to:

Settings → Mesh-Plug

Set:

Broker WebSocket URL: wss://mqtt.example.com:9001/mqtt
Topic filter: msh/2/e/#
Username: your broker username
Password: your broker password

Recommended baseline:

Keepalive: 20
Reconnect delay: 5000
Auto-connect: enabled for admin/operator live pages
Server cache: enabled for public observer dashboards
Observer refresh: 5000
Offline after: 300

Save the settings.

Step 4: Add the Mesh-Plug Shortcode

Use the main shortcode:

[mesh_plug]

For a public dashboard, use observer mode:

[mesh_plug mode="observer" height="600px" map_tiles="voyager" fit="1"]

For an admin/operator dashboard, use live mode on a restricted page:

[mesh_plug mode="live" height="700px" map_tiles="dark" fit="once"]

Observer mode reads from the server snapshot API. It is the best choice for public pages because visitors do not connect directly to your MQTT broker.

Live mode connects directly from your browser to the MQTT broker over WebSockets. Use it for operations, diagnostics, and admin-only pages.

Step 5: Verify Traffic

First, verify native MQTT traffic from your gateway:

mosquitto_sub -v \
  -h mqtt.example.com \
  -p 8883 \
  -u YOUR_USER \
  -P 'YOUR_PASSWORD' \
  -t 'msh/#'

Trigger activity from the Meshtastic app:

• Exchange user info
• Send a chat message
• Send position
• Wait for telemetry or map report intervals

You may see protobuf/binary traffic instead of JSON. That is normal on current Meshtastic setups.

Then open your WordPress page with the Mesh-Plug shortcode.

Healthy behavior:

• Status shows connected in live mode
• Log shows MQTT traffic
• Nodes appear after node info, position, or map reports arrive
• Chat appears when text messages are received
• Map positions appear when valid position or map-report packets are available

Step 6: Public Dashboard Best Practice

For public pages:

1. Enable server cache in Mesh-Plug settings.
2. Use one private/admin live page to ingest MQTT.
3. Use observer mode on public pages.

Example public shortcode:

[mesh_plug mode="observer" height="600px" map_tiles="voyager" fit="1"]

This avoids exposing broker credentials or direct MQTT behavior to public visitors.

Troubleshooting

Connected but No Nodes

Check:

• Are you subscribed to the right topic?
• Is your Meshtastic gateway publishing MQTT uplinks?
• Are you receiving encrypted packets only?
• Is position or telemetry disabled on the node?
• Are map reports enabled if you are relying on msh/2/map/#?

Try temporarily subscribing to:

msh/#

If traffic appears, narrow the topic afterward.

Log Shows Encrypted Protobuf Payloads

That means Mesh-Plug can see packets, but the packet contents are encrypted.

This is expected for channel-encrypted traffic. Mesh-Plug cannot decode protected packet contents from the broker without the channel keys.

Use unencrypted map reports or an appropriate gateway/translator if you need public dashboard data.

mosquitto_sub Works but Mesh-Plug Does Not

You may have confirmed native MQTT on port 8883, but Mesh-Plug live mode needs WebSockets.

Check:

wss://mqtt.example.com:9001/mqtt

Your broker or reverse proxy must support WebSocket upgrades.

Mesh-Plug Connects, Then Disconnects

Check:

• Broker WebSocket path
• Username/password
• TLS certificate
• Broker ACLs
• Client connection limits
• Topic permissions

Mesh-Plug logs WebSocket close codes to help diagnose broker compatibility issues.

Positions Look Approximate

That may be correct.

Current Meshtastic behavior may reduce position precision for privacy, especially on public or known-key channels. Mesh-Plug now displays coarse positions with an approximate radius instead of silently dropping them.

Recommended Baseline

Start simple:

Broker WebSocket URL: wss://mqtt.example.com:9001/mqtt
Topic: msh/2/e/#
Shortcode: [mesh_plug mode="live" height="600px"]

Once live mode works, add a public observer page:

[mesh_plug mode="observer" height="600px" map_tiles="voyager" fit="1"]

Then layer in:

• Server cache
• Packet history
• Map reports
• Telemetry charts
• Narrower topic filters
• Broker ACLs

Final Notes

Mesh-Plug is designed to scale from a single demo node to a shareable mesh dashboard.

The most reliable setup is:

• Meshtastic gateway publishes to a broker over native MQTT/TLS.
• Mesh-Plug live mode connects to the same broker over WebSockets for admin/operator use.
• Mesh-Plug observer mode serves public dashboards from WordPress snapshots.

Start with a known-good topic, confirm traffic, then narrow and harden the setup once it works.