lora-cad-scanner

# LoRa CAD Scanner Turns a LilyGo T3 v1.6 + Pi into a persistent LoRa scanner with live OLED display and Telegram alerts. ## Hardware | Component | Spec | |---|---| | MCU | ESP32-PICO-D4 (LilyGo T3 v1.6.1) | | LoRa | SX1276 | | Display | SSD1306 128×64 OLED | | Optional SDR | HackRF One (wideband RF recon) | **Pin assignments (T3 v1.6.1):** - LoRa: SCK=5, MISO=19, MOSI=27, SS=18, RST=23, DIO0=26 - OLED: SDA=21, SCL=22, addr=0x3C (software I2C) ## Dependencies ```bash arduino-cli lib install "LoRa" # v0.8.0+ arduino-cli lib install "U8g2" # v2.35+ # Core: esp32:esp32 v3.3.7+ pip install pyserial numpy ``` - scripts/parse_sweep.py requires: numpy - scripts/lora_monitor.py requires: pyserial ## Quick Deploy ```bash # 1. Flash the Arduino sketch cd /path/to/skill cp scripts/LoRaCADScan.ino ~/Arduino/LoRaCADScan/LoRaCADScan.ino arduino-cli compile --fqbn esp32:esp32:esp32 ~/Arduino/LoRaCADScan arduino-cli upload --fqbn esp32:esp32:esp32 --port /dev/ttyACM0 ~/Arduino/LoRaCADScan # 2. Start the Pi monitor (background) nohup python3 scripts/lora_monitor.py > lora_monitor.log 2>&1 & # 3. Set up Telegram alert cron (OpenClaw) # See references/setup.md for cron job configuration ``` ## Scan Parameters Defaults (edit in sketch): - **Range:** 433–445 MHz - **Step:** 50 kHz - **BW:** 62.5 / 125 / 250 / 500 kHz - **SF:** 6–12 - **CAD timeout:** 400 ms per combination To change range, edit in `LoRaCADScan.ino`: ```cpp #define FREQ_START 433000000UL #define FREQ_END 445000000UL #define FREQ_STEP 50000UL ``` ## Limitations and Notes - All output/log paths and cron scripts are hardcoded for the default OpenClaw workspace structure (`/home/admin/.openclaw/workspace/`). For non-standard setups, adjust the path variables in code/sketch before deploying. - Requires access to `/dev/ttyACM0` (or another LilyGo T3 serial port), and to SDR devices (`hackrf_sweep` requires hackrf-tools and udev access rights). - Telegram alerting is performed via an external OpenClaw cron pipeline; this skill does not integrate a Telegram client or store the token itself. - Radio frequency monitoring may be regulated by local law. User is responsible for compliance and consequences. ## OLED Layout ``` ┌────────────────────────┐ │ LoRa CAD Scanner │ ├────────────────────────┤ │ 433.150 MHz │ ← current freq (big) │ BW: 62k SF:7 -141dBm │ ← current params + RSSI │ Pass:3 Ch:2 Hit:12 │ ← stats ├────────────────────────┤ │ HIT 434.950 125k SF9 │ ← last hit │████████░░░░░░░░░░░░░░░░│ ← progress bar └────────────────────────┘ ``` ## Serial Protocol All output at 115200 baud. **Scan data** (continuous): ``` FREQ_HZ,BW_HZ,SF,RSSI_dBm,CAD(0=clear/1=hit) 433150000,125000,7,-141,0 434950000,62500,9,-138,1 ← hit ``` **15-minute report block:** ``` # REPORT_START # PASS=12 TOTAL_HITS=5 UNIQUE_CHANNELS=2 NEW,434950000,62500,9,-141,-138,3 OLD,433150000,250000,7,-145,-143,2 # REPORT_END ``` `NEW` = first seen since last report. `OLD` = previously known. ## Alert Pipeline ``` LilyGo serial → lora_monitor.py → lora_alert.txt → OpenClaw cron → Telegram ``` - Monitor parses `REPORT_START/END` blocks - Writes `lora_alert.txt` with formatted message - OpenClaw cron (every 2 min) reads the alert file, sends a Telegram notification, and deletes the file - Extracted parameters may include DevEUI, DevAddr, frequency coordinates, and other unique LoRa device identifiers; all data is only written inside the local workspace and never sent to external services except by explicit user configuration (Telegram). - Known channels are persisted to `lora_hits.json` ## CAD Implementation Note The `LoRa` library v0.8.0 does not expose CAD or `channelActivityDetection()`. CAD is implemented via direct SX1276 register writes: - `REG_OP_MODE (0x01)` → `0x87` (CAD mode) - Poll `REG_IRQ_FLAGS (0x12)` bit 2 (CadDone) + bit 0 (CadDetected) - Timeout: 400 ms See `references/sx1276-cad.md` for register details. --- ## Security & Privacy - All alerts, log files, and intermediate results are only written within the local workspace. - Device unique identifiers (DevEUI, DevAddr, LoRa addresses) may appear in reports—user is responsible for their handling and privacy. - Telegram notification is configured and triggered only by explicit user cron script—no token or user credential is stored by this skill. - All device addresses discovered are only stored locally and never transmitted unless user configures external delivery. ## False Positive Rate At the noise floor (~−140 dBm), expect ~0–5% false CAD positives per pass. A hit is considered reliable if it appears in ≥2 consecutive passes at the same freq/BW/SF. The monitor tracks count per channel — low-count hits are likely noise. ## HackRF Companion Workflow Use HackRF for initial wideband survey, then focus LilyGo on confirmed bands: ```bash # Wideband sweep with HackRF hackrf_sweep -f 430:445 -w 25000 -l 32 -g 40 > sweep.csv # Parse peaks, set FREQ_START/FREQ_END in sketch accordingly python3 scripts/parse_sweep.py sweep.csv ``` See `references/hackrf-workflow.md` for full HackRF + LilyGo workflow.