meshtastic-detection

# 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 `meshtastic` and `pypubsub` packages (venv at `{baseDir}/venv`)
- `usb_receiver.py` daemon 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

```bash
cd {baseDir}
source venv/bin/activate
python scripts/usb_receiver.py --port /dev/cu.usbmodem1CDBD4A896441
```

### Check for New Alerts

```bash
cd {baseDir}
./venv/bin/python scripts/event_monitor.py
```

Every `DETECTION_SENSOR_APP` record = high-priority alert. Output:

```json
{
  "alerts": [{"priority": "high", "sender": "!1dd29c50", "text": "alert detected", "received_at": "...",...

# meshtastic-detection

Meshtastic Detection Sensor alert receiver via LoRa -- USB serial, local JSONL storage, feishu notifications.

## Overview

An OpenClaw skill that connects to a Meshtastic LoRa device via USB to receive `DETECTION_SENSOR_APP` events from a remote sensor node. When the remote device's GPIO pin triggers (preset target detected), the event is stored locally and an alert is sent to feishu.

- **Receive** `DETECTION_SENSOR_APP` events over LoRa mesh (GPIO trigger)
- **Store** to local JSONL files (no database required)
- **Alert** immediately via feishu through OpenClaw cron
- **Query** through OpenClaw conversation or CLI

## Supported Platforms

| Platform | Serial port pattern | Service manager |
|----------|-------------------|-----------------|
| macOS | `/dev/cu.usbmodem*` | launchd (plist) |
| Linux x86/arm | `/dev/ttyUSB*`, `/dev/ttyACM*` | systemd |
| Raspberry Pi | `/dev/ttyUSB*`, `/dev/ttyACM*` | systemd |
| Docker | `/dev/ttyUSB*`, `/dev/ttyACM*` | entrypoint.sh + `nohup` / container CMD |

`setup.sh` auto-detects your platform (including Docker) and handles all differences.

## Architecture

```
Remote Sensor Device              Host Machine (macOS/Linux/RPi)
[GPIO Detection Sensor]           [Meshtastic Module via USB]
        |                                  |
        | LoRa radio                  usb_receiver.py (daemon)
        |                                  |
        └──────────────────────────────────┘
                                           |
                                    data/sensor_data.jsonl
                                           |
                              ┌────────────┼────────────┐
                              │            │            │
                        sensor_cli.py  event_monitor  OpenClaw cron
                        (query data)   (check new)    (feishu alert)
```

## Quick Start

```bash
# 1. One-click setup (auto-detects platform, Python, serial port)
./setup.sh

# 2. Start receiver (...