Hermes Meshtastic Adapter - Full Setup Guide¶
Repo: amscotti/hermes-meshtastic-adapter | ⭐ 4 Author: amscotti | Language: Python License: MIT
The Hermes Meshtastic Adapter is a Hermes Agent plugin that bridges your agent to a Meshtastic LoRa mesh network. It receives plain-text messages from the mesh and can send responses back - enabling Hermes interaction over long-range, low-power radio networks that operate without cell towers or WiFi.
Prerequisites¶
Hardware¶
- Meshtastic-compatible device (LilyGo T-Beam, Heltec LoRa 32, RAK Wireless, etc.)
- USB connection to your Hermes host machine
Software¶
- Python 3.11+
- Hermes Agent
- Meshtastic Python library
Installation¶
git clone https://github.com/amscotti/hermes-meshtastic-adapter.git
cd hermes-meshtastic-adapter
pip install -r requirements.txt
Hardware Setup¶
1. Flash Meshtastic Firmware¶
Follow the Meshtastic Flashing Guide for your device.
2. Connect Device¶
Connect your Meshtastic device via USB. Verify it's detected:
ls /dev/ttyUSB* # Linux
ls /dev/cu.* # macOS
3. Configure Meshtastic¶
Using the Meshtastic Python CLI:
pip install meshtastic
meshtastic --info # Verify connection
# Set a short name for your node
meshtastic --set-owner "Hermes-Node"
# Configure channel (must match your mesh)
meshtastic --setchan name "HermesMesh" --setchan psk "base64:your-preshared-key"
Configuration¶
Adapter Config¶
Edit config.yaml:
meshtastic:
port: "/dev/ttyUSB0" # Serial port for device
# or use TCP for network-connected devices:
# host: "agent-a.local"
hermes:
message_format: "plain" # "plain" or "json"
respond_to_all: false # Only respond to messages prefixed with "Hermes:"
response_prefix: "🤖 " # Prefix for all bot responses
max_message_length: 200 # Meshtastic has message size limits
filters:
allowed_nodes: [] # Empty = respond to all. List node IDs to restrict.
blocked_nodes: [] # Never respond to these nodes
require_prefix: "Hermes:" # Messages must start with this to trigger response
logging:
file: "meshtastic_adapter.log"
level: "INFO"
Hermes Integration¶
Register as a Hermes plugin:
# In ~/.hermes/config.yaml
plugins:
meshtastic:
path: "/path/to/hermes-meshtastic-adapter"
enabled: true
config:
port: "/dev/ttyUSB0"
Usage¶
Running Standalone¶
# Start the adapter
python3 adapter.py
# Output:
# [INFO] Connected to Meshtastic device on /dev/ttyUSB0
# [INFO] Listening for messages on channel 'HermesMesh'
# [INFO] Node ID: !a1b2c3d4
Message Flow¶
- User sends a text message from their Meshtastic device
- Adapter receives it via the mesh
- If message matches prefix filter, it's forwarded to Hermes
- Hermes processes and responds
- Adapter sends response back over the mesh
User (LoRa Device) --[radio]--> Mesh --[radio]--> Your Node --[USB]--> Adapter --> Hermes Agent
|
User (LoRa Device) <--[radio]-- Mesh <--[radio]-- Your Node <--[USB]-- Adapter <--+
Example Interaction¶
User (on Meshtastic device):
Hermes: What's the weather forecast for tomorrow?
Hermes (response over mesh):
🤖 Tomorrow: Partly cloudy, high of 72°F, low of 55°F. 15% chance of rain.
Integration with Hermes Agent¶
As a Plugin¶
The adapter registers with Hermes as a plugin, making it available as a tool:
# From within Hermes:
# The adapter exposes these tools:
# - meshtastic_send(message, node_id=None)
# - meshtastic_broadcast(message)
# - meshtastic_status()
Use Cases¶
| Use Case | Description |
|---|---|
| Off-grid assistant | Query your Hermes agent from remote locations without cell service |
| Field research | Send observations, get analysis back over mesh |
| Emergency comms | Agent can relay information during network outages |
| Sensor monitoring | Mesh-connected sensors report to Hermes for analysis |
| Community mesh | Shared Hermes access for a local mesh network |
Troubleshooting¶
"Device not found on /dev/ttyUSB0"¶
# Check connected USB devices
lsusb
dmesg | grep -i usb
# Try different port
meshtastic --port /dev/ttyACM0 --info
"No messages received"¶
- Verify channel name and PSK match your mesh
- Check that your node is in range of at least one other node
- Ensure the region/frequency matches (US: 915MHz, EU: 868MHz)
"Messages are truncated"¶
Meshtastic has a ~200 byte payload limit. The adapter splits long messages automatically, but very long Hermes responses will be trimmed:
hermes:
max_message_length: 180 # Leave room for prefix + metadata
"Response prefix not working"¶
Check the exact prefix in config - it's case-sensitive:
filters:
require_prefix: "Hermes:" # Must match exactly
Range & Performance¶
| Environment | Typical Range |
|---|---|
| Urban (buildings) | 1-3 km |
| Suburban | 3-8 km |
| Rural / open | 10-20 km |
| Elevated / line-of-sight | 50+ km |
Factors affecting range: antenna quality, elevation, terrain, weather, interference.
Alternatives¶
| Tool | Range | Power | Notes |
|---|---|---|---|
| Meshtastic LoRa | 1-50km | Battery | Off-grid, no infrastructure |
| WiFi | 50m | Wall power | Requires network |
| Bluetooth | 10m | Battery | Short range, low power |
| Satellite (Iridium) | Global | Battery | Expensive, high latency |
Guide last updated: July 4, 2026 | Repo | Report issue
Integration with CorpusIQ¶
CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.
This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.