Meshtastic Detection
v0.1.1Receive DETECTION_SENSOR_APP alerts from Meshtastic LoRa devices via USB. When the remote sensor GPIO triggers (preset target detected), store the event and...
Like a lobster shell, security has layers — review code before you run it.
Runtime requirements
Meshtastic Detection Skill
Receive detection sensor alerts from a remote Meshtastic device over LoRa. When the remote device's GPIO pin triggers (preset target detected), the event is stored locally and requires immediate user notification via feishu.
Prerequisites
- Meshtastic-compatible hardware connected via USB (RAK4631, T-Beam, Heltec, etc.)
- Python 3.10+ with
meshtasticandpypubsubpackages (venv at{baseDir}/venv) usb_receiver.pydaemon running- Quick setup:
cd {baseDir} && ./setup.sh - Detailed guide:
{baseDir}/references/SETUP.md
Architecture
┌──────────────────────────────────────────────────────────────┐
│ USB Receiver Daemon │
├──────────────────────────────────────────────────────────────┤
│ LISTEN: DETECTION_SENSOR_APP only (GPIO trigger events) │
│ STORE: data/sensor_data.jsonl (append per detection) │
│ LATEST: data/latest.json (most recent detection) │
└──────────────────────────────────────────────────────────────┘
┌─────────────┐ USB ┌──────────────┐
│ LoRa Node │◄────────────►│ usb_receiver │
│ (Radio) │ │ daemon │
└─────────────┘ └──────┬───────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
sensor_cli.py event_monitor.py OpenClaw cron
(query data) (check alerts) (feishu alert)
Quick Reference
Run the Receiver
cd {baseDir}
source venv/bin/activate
python scripts/usb_receiver.py --port /dev/cu.usbmodem1CDBD4A896441
Check for New Alerts
cd {baseDir}
./venv/bin/python scripts/event_monitor.py
Every DETECTION_SENSOR_APP record = high-priority alert. Output:
{
"alerts": [{"priority": "high", "sender": "!1dd29c50", "text": "alert detected", "received_at": "...", "channel": "ch0", "portnum": "DETECTION_SENSOR_APP"}],
"summary": "🚨 3 new detection alert(s) from 3 record(s)",
"alert_count": 3,
"new_records": 3
}
Query Historical Data
python scripts/sensor_cli.py latest
python scripts/sensor_cli.py stats --since 24h
python scripts/sensor_cli.py query --since 1h
Data Format
Each record in data/sensor_data.jsonl:
{"received_at": "2026-03-04T11:07:06+00:00", "sender": "!1dd29c50", "channel": "ch0", "portnum": "DETECTION_SENSOR_APP", "data": {"type": "detection", "text": "alert detected"}}
Only DETECTION_SENSOR_APP messages are captured. This portnum means the remote sensor's GPIO pin was triggered — a preset target has been detected. Every detection event requires immediate user alert.
All other message types (TEXT_MESSAGE_APP, telemetry, position, etc.) are ignored.
Log Rotation
sensor_data.jsonl is automatically rotated at 5 MB (keeps 2 archive files, total max ~15 MB). Rotation is transparent — event_monitor auto-resets offset, sensor_cli reads across archives.
Monitoring & Alerts
Cron Job (Active)
The cron job runs event_monitor.py every 60 seconds and delivers alerts to feishu:
# Check status
openclaw cron list
# View run history
openclaw cron runs --id <job-id>
# Manual test
openclaw cron run <job-id>
# Edit config
openclaw cron edit <id> --timeout-seconds 60 --to <feishu-open-id>
Cron message template (for reference):
Run this command and report the output:
cd {baseDir} && ./venv/bin/python scripts/event_monitor.py
— If alert_count > 0, tell me how many alerts, the latest sender and time.
If alert_count is 0, reply: 暂无新告警。
Key settings:
timeoutSeconds: 60(agent needs ~20-40s)channel: feishudelivery.to: ou_16c6dc8bda8ac97abfd0194568edee59
Alert Behavior
All DETECTION_SENSOR_APP events are treated as high priority. No rule configuration needed — every detection triggers an immediate alert. The alert message includes:
- Sender device ID
- Detection text (from remote sensor config)
- Timestamp
Configuration
Edit CONFIG.md to customize:
- Serial port — USB device path
- Notification channel —
feishu(configured in OpenClaw)
Common Conversation Patterns
User asks about recent detections:
"What was detected in the last hour?"
Run: cd {baseDir} && ./venv/bin/python scripts/sensor_cli.py query --since 1h
User asks for statistics:
"Give me a summary of detections today"
Run: cd {baseDir} && ./venv/bin/python scripts/sensor_cli.py stats --since 24h
User asks about system status:
"Is the sensor still working?"
Run: cd {baseDir} && ./venv/bin/python scripts/sensor_cli.py status
Files
{baseDir}/
├── SKILL.md # This file (agent instructions + metadata)
├── CONFIG.md # User configuration
├── setup.sh # One-click setup
├── scripts/
│ ├── usb_receiver.py # USB serial daemon (DETECTION_SENSOR_APP only)
│ ├── event_monitor.py # Incremental alert monitor
│ └── sensor_cli.py # Query CLI
├── data/
│ ├── sensor_data.jsonl # Detection records (auto-rotated at 5 MB)
│ ├── latest.json # Most recent detection
│ └── monitor_state.json # Monitor byte offset + seen hashes
└── references/
└── SETUP.md # Detailed installation guide
Troubleshooting
"No records found"
- Check that
usb_receiver.pyis running - Verify USB device:
ls /dev/cu.usb*
"Resource temporarily unavailable"
- Only one process can use the serial port. Check:
lsof /dev/cu.usbmodem*
Receiver connects but no data appears
- The receiver only captures
DETECTION_SENSOR_APPmessages (other types are ignored) - Run with
--debugto see all packets:python scripts/usb_receiver.py --port ... --debug - Verify the remote device is on the same channel and frequency
- Confirm the remote device has Detection Sensor Settings configured (GPIO pin monitoring)
Cron job times out or fails delivery
- Check:
openclaw cron runs --id <job-id> - Fix timeout:
openclaw cron edit <id> --timeout-seconds 60 - Fix delivery:
openclaw cron edit <id> --to <feishu-open-id>
Comments
Loading comments...