meshtastic – OpenClaw Skill

---

name: meshtastic description: Send and receive messages via Meshtastic LoRa mesh network. Use for off-grid messaging, mesh network status, reading recent mesh messages, or sending texts via LoRa radio.

Meshtastic Skill

Control a Meshtastic node via USB for off-grid LoRa mesh communication.

Prerequisites

• Meshtastic-compatible hardware (RAK4631, T-Beam, Heltec, LilyGo, etc.)
• USB connection to host machine
• Python 3.9+ with meshtastic and paho-mqtt packages
• See references/SETUP.md for full installation guide

Configuration

Edit CONFIG.md with your node details, MQTT settings, and alert destinations.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    MQTT Bridge                               │
├─────────────────────────────────────────────────────────────┤
│  RECEIVE: mqtt.meshtastic.org (global JSON traffic)         │
│  PUBLISH: optional map broker (protobuf)                    │
│  SOCKET:  localhost:7331 (commands: send, status, toggle)   │
├─────────────────────────────────────────────────────────────┤
│  Files:                                                      │
│  • /tmp/mesh_messages.txt - received messages log           │
│  • /tmp/mesh_nodes.json   - cached node positions           │
└─────────────────────────────────────────────────────────────┘

┌─────────────┐     USB      ┌─────────────┐
│  LoRa Node  │◄────────────►│ Bridge.py   │
│  (Radio)    │              │  - Serial   │
└─────────────┘              │  - Socket   │
                             │  - MQTT     │
                             └──────┬──────┘
                                    │
           ┌────────────────────────┼────────────────────────┐
           │                        │                        │
           ▼                        ▼                        ▼
    localhost:7331           /tmp/mesh_*            MQTT Broker
    (send commands)          (message logs)         (mesh traffic)

Quick Reference

Send Messages

# Via socket (preferred - works while bridge running)
echo '{"cmd":"send","text":"Hello mesh!"}' | nc -w 2 127.0.0.1 7331

# Direct message to specific node
echo '{"cmd":"send","text":"Hey!","to":"!abcd1234"}' | nc -w 2 127.0.0.1 7331

# Check status
echo '{"cmd":"status"}' | nc -w 2 127.0.0.1 7331

# List RF nodes (seen via radio)
echo '{"cmd":"nodes"}' | nc -w 2 127.0.0.1 7331

Map Visibility (if configured)

# Toggle map publishing on/off
echo '{"cmd":"map"}' | nc -w 2 127.0.0.1 7331

# Explicitly enable/disable
echo '{"cmd":"map","enable":true}' | nc -w 2 127.0.0.1 7331
echo '{"cmd":"map","enable":false}' | nc -w 2 127.0.0.1 7331

# Force immediate position report
echo '{"cmd":"map_now"}' | nc -w 2 127.0.0.1 7331

Read Messages

# Recent messages (last 20)
tail -20 /tmp/mesh_messages.txt

# Filter common noise
tail -50 /tmp/mesh_messages.txt | grep -v -E "(Hello!|hey|mqtt-test)"

Message Log Format

TIMESTAMP|CHANNEL|SENDER|DISTANCE|TEXT
2026-02-02T12:43:59|LongFast|!433bf114|1572km|Moin moin!

Bridge Service

# Status
sudo systemctl status meshtastic-bridge

# Restart
sudo systemctl restart meshtastic-bridge

# View logs
sudo journalctl -u meshtastic-bridge -f

# Stop (needed for direct CLI access)
sudo systemctl stop meshtastic-bridge

Monitoring & Alerts

Option 1: Cron Job (Recommended)

cron.add({
  name: "mesh-monitor",
  schedule: { kind: "every", everyMs: 300000 },  // 5 min
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "Check /tmp/mesh_messages.txt for new messages. Filter out noise (test messages, 'Hello!', 'hey'). Alert me of interesting ones with translations if non-English.",
    timeoutSeconds: 60,
    deliver: true,
    channel: "telegram"  // or your channel
  }
})

Option 2: Digest Summary

cron.add({
  name: "mesh-digest",
  schedule: { kind: "cron", expr: "0 8,14,20 * * *", tz: "Europe/Madrid" },
  sessionTarget: "isolated",
  payload: {
    kind: "agentTurn",
    message: "Read /tmp/mesh_messages.txt. Create a digest of interesting messages from the last 6 hours. Translate non-English, guess country from distance. Post summary.",
    timeoutSeconds: 120,
    deliver: true,
    channel: "telegram"
  }
})

Option 3: Spawned Monitor Agent

sessions_spawn({
  task: "Monitor /tmp/mesh_messages.txt every 30 seconds. Alert me for interesting messages (not noise). Run for 1 hour.",
  label: "mesh-monitor",
  runTimeoutSeconds: 3600
})

Distance Reference

Approximate distances for country guessing (adjust for your location):

Distance	Typical Regions
<500km	Neighboring countries/regions
500-1000km	Medium range
1000-1500km	Long range
1500-2000km	Very long range (likely MQTT relay)
>2000km	MQTT-bridged traffic

Privacy Notes

• Map reports can use fuzzy positioning (~2km precision)
• Position publishing can be toggled off entirely
• Local RF messages are logged but not shared externally by default
• Never broadcast precise location in messages

Supported Hardware

Device	Notes
RAK4631	Recommended, reliable USB
T-Beam	Popular, has GPS
Heltec V3	Budget option
LilyGo T-Echo	E-paper display

See references/SETUP.md for hardware-specific setup.

Regional Frequencies

Region	Frequency	Topic Root
Europe	868 MHz	msh/EU_868/2/json
Americas	915 MHz	msh/US/2/json
Australia/NZ	915 MHz	msh/ANZ/2/json

Files

~/.openclaw/skills/meshtastic/
├── SKILL.md           # This file
├── CONFIG.md          # Your configuration
├── scripts/
│   └── mesh.py        # CLI wrapper
└── references/
    └── SETUP.md       # Installation guide

Troubleshooting

"Resource temporarily unavailable"

• Only one process can use serial port at a time
• Stop bridge before direct CLI: sudo systemctl stop meshtastic-bridge

No messages appearing

• Check MQTT subscription topic matches your region
• Verify firewall allows outbound port 1883
• Check journalctl -u meshtastic-bridge for errors

Can't send messages

• Ensure bridge is running (socket server)
• Check serial port path in config
• Try: echo '{"cmd":"status"}' | nc -w 2 127.0.0.1 7331

Considering BLE instead of USB?

• Don't. USB is far more reliable on Linux.
• BLE on Linux (BlueZ/bleak) has notification bugs, pairing inconsistencies, and random disconnects.
• See references/SETUP.md for detailed findings.

Further Reading

• Meshtastic Docs
• MQTT Integration
• Hardware Options

meshtastic-skill

Off-grid radio for sovereign AI. LoRa mesh comms via Meshtastic — no internet required.

Raspberry Pi 5 + RAK4631 Meshtastic node — the sovereign radio stack

Overview

Connect AI agents to Meshtastic LoRa mesh networks. Send messages, monitor traffic, and stay connected when the internet isn't an option.

• 📡 Send/receive via LoRa mesh
• 🌐 Global traffic via MQTT bridge
• 🗺️ Map integration with privacy fuzzing
• 🔔 Alerts & digests for interesting messages
• 🛠️ Framework-agnostic core, AI-native design

Architecture

                         MQTT Broker
                    (mqtt.meshtastic.org)
                            |
                            | Global mesh traffic
                            v
+----------------------------------------------------------+
|                      Your Machine                        |
|                                                          |
|  +-----------+    +----------------+    +-------------+  |
|  | AI Agent  |<-->|  MQTT Bridge   |<-->|  LoRa Node  |  |
|  | (OpenClaw)|    |                |    | (USB/Serial)|  |
|  +-----------+    | - MQTT client  |    +-------------+  |
|       |           | - Socket :7331 |          |          |
|       |           | - Message log  |          |          |
|       v           +----------------+          v          |
|  localhost:7331         |              Radio Waves       |
|  (send commands)        v              (915/868 MHz)     |
|                  /tmp/mesh_*.txt                         |
+----------------------------------------------------------+
                                                |
                                                v
                                        +-------------+
                                        | Mesh Network|
                                        | (The World) |
                                        +-------------+

Data Flow

Outbound (AI → Mesh):

Agent calls mesh.py send "hello"
  → Socket command to bridge (:7331)
  → Bridge sends via Meshtastic serial
  → Node transmits over LoRa
  → Mesh receives worldwide

Inbound (Mesh → AI):

Mesh message broadcast
  → MQTT broker receives
  → Bridge subscribes & logs to /tmp/mesh_messages.txt
  → Agent reads via mesh.py messages
  → Process, filter, respond

Components

Component	Purpose	Location
mesh.py	CLI for agents	scripts/mesh.py
mcp_server.py	MCP server for Claude Desktop	scripts/mcp_server.py
mqtt_bridge.py	MQTT↔Socket↔Serial bridge	scripts/mqtt_bridge.py
mesh_monitor.py	Alert filtering	scripts/mesh_monitor.py
mesh_digest.py	Periodic summaries	scripts/mesh_digest.py

Design Principles

1. Async by default — LoRa is slow (seconds to minutes). Fire-and-forget sends, queue-based receives.

2. Socket API — Simple JSON over TCP. Language-agnostic. Any agent framework can integrate.

3. File-based logs — /tmp/mesh_messages.txt is the inbox. Easy to tail, grep, or parse.

4. Privacy-first — Position fuzzing, no precise coords in broadcasts, map publishing is opt-in.

5. Offline-capable — Works without internet if you have local mesh peers.

Quick Start

# Check bridge status
./scripts/mesh.py status

# View recent messages
./scripts/mesh.py messages

# Send to mesh
./scripts/mesh.py send "Hello from the sovereign zone!"

# List known nodes
./scripts/mesh.py nodes

Installation

See references/SETUP.md for complete guide.

Summary:

1. Connect Meshtastic hardware (RAK4631, T-Beam, etc.) via USB
2. Create Python venv, install dependencies:

   pip install meshtastic paho-mqtt
   pip install mcp  # optional, for MCP integration
   

3. Configure and start mqtt_bridge.py as systemd service
4. Edit CONFIG.md with your settings
5. Test with mesh.py status

Configuration

Edit CONFIG.md:

• Node identity (name, short name)
• Serial port (/dev/ttyACM0, etc.)
• MQTT broker settings
• Socket port (default: 7331)
• Privacy settings (position fuzzing level)

Socket API

Send JSON commands to localhost:7331:

# Status
echo '{"cmd":"status"}' | nc -w2 localhost 7331

# Send message
echo '{"cmd":"send","text":"Hello mesh!"}' | nc -w2 localhost 7331

# Send to specific node
echo '{"cmd":"send","text":"Hi","to":"!abcd1234"}' | nc -w2 localhost 7331

Response format:

{"ok": true, "sent": "Hello mesh!"}
{"ok": false, "error": "No connection"}

Message Log Format

/tmp/mesh_messages.txt:

2026-02-03T12:34:56|LongFast|!abc123|1542km|Hello world!
2026-02-03T12:35:01|ShortFast|!def456|892km|Testing 123

Fields: timestamp|channel|sender|distance|text

Supported Hardware

Device	Connection	Notes
RAK4631	USB	Recommended, reliable
T-Beam	USB	Built-in GPS
Heltec V3	USB	Budget-friendly
LilyGo T-Echo	USB	E-paper display

⚠️ BLE not recommended on Linux/Pi — BlueZ has known issues with Meshtastic (notification bugs, random disconnects, device stops advertising). Use USB serial instead.

AI Framework Integration

OpenClaw

Use SKILL.md directly — it's written for OpenClaw agents.

MCP (Model Context Protocol)

For Claude Desktop and other MCP-compatible clients:

# Install dependencies
pip install mcp meshtastic

# Test connections (bridge + device)
python scripts/mcp_server.py --test

Add to Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "meshtastic": {
      "command": "python",
      "args": ["/path/to/meshtastic-skill/scripts/mcp_server.py"]
    }
  }
}

See references/claude_desktop_config.json for example.

MCP Tools

Messaging (via bridge):

Tool	Description
mesh_send	Send message to mesh (broadcast or DM)
mesh_send_alert	Send high-priority alert message
mesh_messages	Get recent messages with filtering

Network Info (via bridge):

Tool	Description
mesh_status	Check bridge connection status
mesh_nodes	List all discovered mesh nodes

Device Info (direct connection):

Tool	Description
mesh_device_info	Get local device details (battery, hardware, etc.)
mesh_channels	List configured channels
mesh_node_info	Get detailed info about a specific node

Location (direct connection):

Tool	Description
mesh_send_position	Broadcast GPS position (use fuzzy coords!)

Telemetry & Diagnostics (direct connection):

Tool	Description
mesh_request_telemetry	Request battery/metrics from nodes
mesh_traceroute	Trace route and signal quality to a node

Device Management (direct connection):

Tool	Description
mesh_reboot	Reboot the connected device

The MCP server uses hybrid architecture: messaging goes through the socket bridge (for MQTT integration), while device operations connect directly to the Meshtastic hardware.

Other Frameworks

The core is framework-agnostic:

• mesh.py — standard CLI tool
• Socket API — JSON over TCP, works from any language
• MCP server — for MCP-compatible agents
• Adapt SKILL.md patterns to your agent's instruction format

Privacy & Security

• Position fuzzing: Configurable ~2km grid snapping
• Map opt-in: Disabled by default, toggle with mesh.py map
• No PII in code: All personal data in CONFIG.md (gitignored)
• Local logs: Message history stays on your machine

Commands Reference

Command	Description
mesh.py status	Bridge & node status
mesh.py messages [-l N]	Last N messages (default 20)
mesh.py send "text"	Broadcast to default channel
mesh.py send "text" -c 1	Send to channel 1
mesh.py send "text" -t !id	Direct message
mesh.py nodes	List discovered nodes
mesh.py map [--on/--off]	Toggle map visibility
mesh.py setup	Interactive setup wizard

File Structure

meshtastic-skill/
├── README.md                 # This file
├── SKILL.md                  # AI agent instructions (OpenClaw)
├── CONFIG.md                 # User configuration template
├── scripts/
│   ├── mesh.py               # CLI tool
│   ├── mcp_server.py         # MCP server for Claude Desktop etc.
│   ├── mqtt_bridge.py        # MQTT↔Socket bridge
│   ├── mesh_monitor.py       # Alert filtering
│   └── mesh_digest.py        # Digest generator
└── references/
    ├── SETUP.md              # Installation guide
    ├── meshtastic-bridge.service  # systemd template
    └── claude_desktop_config.json # MCP config example

License

MIT

Links

• Meshtastic Docs
• OpenClaw
• ClawdHub