meshtastic – OpenClaw Skill

---

name: meshtastic description: Comprehensive Meshtastic LoRa mesh network control via Mesh Master API. Send messages to nodes/groups, manage channels, configure radio settings, view network topology, request telemetry, and control every aspect of the mesh network. Integrates with Mesh Master running on local network or Tailscale VPN. Use when user says "send message", "check nodes", "configure channel", "what's the mesh status", or any mesh network operation.

Meshtastic Skill

Complete Meshtastic LoRa mesh network control through Mesh Master API integration.

Overview

This skill provides comprehensive mesh network control by communicating with Mesh Master (running on Raspberry Pi or other device). Mesh Master handles the actual Meshtastic device connection; this skill provides the natural language interface.

Architecture

Clawdbot (this skill)
    ↓ HTTP API calls
Mesh Master (RPi, Flask app)
    ↓ Python meshtastic library
Meshtastic Device (LoRa radio)

Connection Methods

1. Local Network (Recommended)

MESH_MASTER_URL=http://192.168.1.100:5000

• Fast, direct communication
• No VPN overhead
• Requires both on same WiFi

2. Tailscale VPN (Remote)

MESH_MASTER_URL=http://100.64.x.x:5000

• Secure, works remotely
• Uses Tailscale private network
• Slightly higher latency

3. USB Serial (Direct)

MESHTASTIC_PORT=/dev/ttyUSB0

• Direct connection to Meshtastic device
• Runs Meshtastic CLI locally
• No Mesh Master required

Commands & Capabilities

Messaging

Send Message to Node

"send a message to bob: hello there"
"msg @snmo thanks for the update"
"/snmo how's the weather?"

Sends via Mesh Master relay system with ACK tracking.

Send to Channel/Group

"broadcast: emergency shelter needed"
"send to camping group: dinner at 7pm"
"ch 1 everyone gather at base"

Sends to entire channel, respects quiet hours.

Network Status

View All Nodes

"show me all nodes"
"who's on the mesh?"
"list network nodes"

Returns formatted table with signal strength, battery, location.

Node Details

"show info for node WH3R"
"what's the signal to brian?"
"node details for !ba4bf9d0"

Returns signal, battery, telemetry, position, last seen.

Network Metrics

"mesh health"
"network status"
"how many nodes online?"

Returns hop count, air utilization, message throughput.

Channel Management

List Channels

"show channels"
"what channels are active?"
"list all channels"

Switch Channel

"use channel camping"
"switch to ch 2"
"primary channel"

Create Channel

"add channel hiking"
"new channel for rescue-ops"
"create channel with name scout-ops"

Configure Channel

"set channel 1 name to hiking"
"configure camping channel encryption random"
"change modem preset to long-slow"

Delete Channel

"remove channel 2"
"delete camping channel"

Radio Settings

View Settings

"show radio config"
"what's the lora settings?"
"get device settings"

Change Settings

"set lora region to US"
"change device role to repeater"
"set power mode to always on"
"configure wifi ssid mywifi password mypass"

Export/Import Config

"export configuration"
"save config to file"
"load configuration from backup.yaml"

Telemetry & Requests

Request Telemetry

"get telemetry from bob"
"request position from WH3R"
"battery status for all nodes"

Traceroute

"traceroute to !ba4bf9d0"
"how do i reach node camping?"

Position & Location

Set Position

"set my location to 40.7128 -74.0060"
"location 39.7392 -104.9903 1234m"
"my coordinates 25.2 -16.8"

View Positions

"show all locations"
"where's bob?"
"node positions map"

Ham Radio

Enable Ham Mode

"enable ham mode with callsign KI1345"
"set ham radio KI1345"

Enables unencrypted operation for licensed operators.

Disable Ham Mode

"disable ham mode"
"back to normal encryption"

Device Management

Rename Device

"rename myself to Snail"
"set owner John Smith"
"short name JS"

Get Info

"show device info"
"radio status"
"firmware version"

Reboot Device

"reboot radio"
"restart meshtastic"

Advanced

QR Code

"show channel qr"
"generate qr for all channels"
"qr code"

Canned Messages

"set canned messages: hello | busy | brb"
"get canned messages"

Ringtone

"set ringtone <rtttl-string>"
"get ringtone"

Configure MQTT

"enable mqtt server.com:1883"
"set mqtt username user password pass"

Configuration

Environment Variables

# Mesh Master location
export MESH_MASTER_URL="http://192.168.1.100:5000"
# or
export MESH_MASTER_URL="http://100.64.x.x:5000"  # Tailscale

# Direct Meshtastic connection (optional)
export MESHTASTIC_PORT="/dev/ttyUSB0"

# Timeouts
export MESH_TIMEOUT=10  # seconds

# Debug logging
export MESH_DEBUG=true

Local Development

For testing without Mesh Master:

# Mock mode (simulates responses)
export MESH_MOCK=true

Performance

• Message send: 0.5-2s (depends on mesh)
• Node list: 1-3s
• Configuration: 1-5s (device reboot)
• Telemetry request: 2-10s (varies with distance)

Error Handling

The skill handles:

• Mesh Master connection failures → Clear error message + retry option
• Invalid node IDs → Searches for partial match or suggests valid nodes
• Network timeout → Waits with "mesh is slow" message
• Malformed input → Clarifies what you meant with examples

References

• cli-commands.md - Complete Meshtastic CLI command reference
• mesh-master-api.md - Mesh Master API endpoints and examples
• networking.md - Tailscale setup & network troubleshooting
• examples.md - Real-world usage scenarios

Troubleshooting

"Can't reach Mesh Master"

• Check MESH_MASTER_URL is correct
• Verify Mesh Master is running on RPi
• Check network/WiFi/Tailscale connectivity
• Firewall port 5000 access

"Node not found"

• Verify node is on mesh (use /nodes command)
• Try using node's short name instead of ID
• May need to wait for node to join network

"Message failed to send"

• Check destination node is reachable
• Verify channel encryption matches
• Try broadcasting instead (reaches more nodes)
• Check quiet hours setting

"Settings change didn't apply"

• Device may need reboot
• Some settings require channel reconfiguration
• Check device firmware compatibility

GitHub & Deployment

This skill is published to GitHub with full security review:

• ✅ .gitignore prevents credential leakage
• ✅ No hardcoded API keys
• ✅ All sensitive values from environment
• ✅ Configuration templates provided

To integrate with Mesh Master:

1. Clone skill into ~/Mesh-Master/mesh_master/skills/meshtastic/
2. Add to Mesh Master's command registry
3. Restart Mesh Master
4. Commands available in dashboard & Telegram bot

Security

• API calls use environment-based credentials only
• No logs contain actual message content
• Respects user privacy & mesh encryption
• Compatible with Mesh Master's security model

Meshtastic Skill for Clawdbot

Complete natural language control of your Meshtastic LoRa mesh network through Clawdbot, integrated with Mesh Master running on your Raspberry Pi.

Quick Start

1. Find Your Serial Port

Connect Meshtastic device via USB and find the port:

ls /dev/tty.usbmodem* /dev/tty.usbserial* /dev/cu.* 2>/dev/null

Should show something like /dev/tty.usbmodem21201

2. Set Environment Variable

export MESHTASTIC_PORT=/dev/tty.usbmodem21201

Or add to ~/.bashrc or ~/.zshrc:

echo 'export MESHTASTIC_PORT=/dev/tty.usbmodem21201' >> ~/.zshrc

3. Try a Command

node scripts/meshtastic-direct.js "show nodes"

Or start interactive mode:

node scripts/meshtastic-direct.js

Then type commands like: show nodes, send: hello, info

Architecture

Clawdbot (your computer)
    ↓
Meshtastic Skill (natural language processor)
    ↓ HTTP API
Mesh Master (RPi:5000)
    ↓ Python meshtastic library
Meshtastic Device (LoRa radio)
    ↓ Mesh Network

Why this design?

• Single Meshtastic device connection (on RPi)
• Mesh Master handles all radio communication
• Clawdbot just sends API requests
• No need to run Meshtastic locally
• Works over WiFi or Tailscale

Usage Examples

Send Messages

"send a message to bob: hello there"
"msg @snmo thanks for the update"
"/brian how's the weather?"
"broadcast: emergency shelter at base camp"

Check Network

"show me all nodes"
"node info for WH3R"
"who's on the mesh?"
"mesh status"

Configure Channels

"show channels"
"set channel 1 name to hiking"
"create channel camping"

Radio Settings

"show radio config"
"set lora region to US"
"set device role to repeater"

Telemetry

"get telemetry from bob"
"request position from WH3R"
"battery status"

Device Management

"rename myself to Snail"
"set owner John Smith"
"device info"

Configuration

Environment Variables

# REQUIRED
MESH_MASTER_URL=http://192.168.1.100:5000

# OPTIONAL
MESH_TIMEOUT=10              # Request timeout (seconds)
MESH_DEBUG=false             # Enable debug logging
MESHTASTIC_PORT=/dev/ttyUSB0 # Direct connection (use OR Mesh Master, not both)

Copy Template

cp .env.example .env
# Edit .env with your values

Troubleshooting

"Can't reach Mesh Master"

Checklist:

1. ✅ Mesh Master is running on RPi

   # On RPi:
   ps aux | grep mesh-master
   

2. ✅ Get correct RPi IP address

   # On RPi:
   hostname -I
   

3. ✅ MESH_MASTER_URL is correct

   # On your computer:
   echo $MESH_MASTER_URL
   

4. ✅ Can ping from your computer

   ping 192.168.1.100
   

5. ✅ Port 5000 is accessible

   curl http://192.168.1.100:5000/api/version
   

"Node not found"

• Use /nodes command to see exact short names
• Nodes must be online and in range
• May need to wait for discovery

"Message failed to send"

• Check destination node is reachable
• Verify both nodes use same channel encryption
• Try broadcasting instead (reaches more nodes)

Files

meshtastic-skill/
├── SKILL.md                    # Full skill documentation
├── README.md                   # This file
├── package.json                # Node.js metadata
├── .env.example               # Configuration template
├── .gitignore                 # Git security (no secrets)
│
├── scripts/
│   ├── meshtastic-agent.js    # Core API client
│   └── meshtastic-cli.js      # Natural language processor
│
├── tests/
│   └── test-connection.js     # Connectivity tests
│
└── references/
    ├── cli-commands.md        # Meshtastic CLI reference
    ├── mesh-master-api.md     # Mesh Master API docs
    └── examples.md            # Usage examples

Security

What's Protected

• ✅ .gitignore prevents secrets leakage
• ✅ No hardcoded API keys or credentials
• ✅ All sensitive values from environment only
• ✅ Configuration templates use .example suffix
• ✅ Compatible with Mesh Master's security model

What You Should Do

1. Never commit .env to git
2. Use .env.example as template
3. Keep MESH_MASTER_URL in environment
4. Use strong Mesh Master authentication
5. Enable firewall (port 5000 only to trusted IPs)

Deployment to Mesh Master

To integrate this skill permanently with Mesh Master:

1. Copy to Mesh Master repo

   cp -r ~/clawd/meshtastic-skill ~/Mesh-Master/mesh_master/skills/
   

2. Register commands in Mesh Master Add to mesh-master.py:

   from mesh_master.skills.meshtastic import MeshtasticSkill
   

3. Restart Mesh Master

   # On RPi:
   systemctl restart mesh-master
   

4. Commands now available via:

   • Web dashboard
   • Telegram bot
   • Mesh network DM
   • HTTP API

Advanced

Using Tailscale (Remote Access)

If you want to control your mesh remotely:

# Install Tailscale on RPi and your computer
# Then use Tailscale IP instead:
export MESH_MASTER_URL=http://100.64.x.x:5000

Direct Meshtastic Connection

If not using Mesh Master:

export MESHTASTIC_PORT=/dev/ttyUSB0
# This mode uses Meshtastic CLI directly (no Mesh Master)

Custom API Server

If you build your own Meshtastic server:

export MESH_MASTER_URL=http://your-server:port

Development

Run Tests

npm test

Interactive Mode

npm start
# or
node scripts/meshtastic-cli.js

Add New Commands

Edit scripts/meshtastic-cli.js - add handler for new command type:

async handleMyCommand(input) {
  // Parse input
  // Call agent method
  // Return formatted result
}

License

MIT

Support

• Issue: GitHub issues on Snail3D/meshtastic-skill
• Docs: See SKILL.md for comprehensive reference
• Mesh Master: https://github.com/Snail3D/Mesh-Master