adsb-overhead

# adsb-overhead

Detect aircraft overhead (within a radius) from a **local readsb SBS/BaseStation TCP feed** and notify via Clawdbot messaging.

This skill is designed for a periodic checker (cron) rather than a long-running daemon.

## Quick start (manual test)

1) Run the checker for a few seconds to see if it detects aircraft near you:

```bash
python3 skills/public/adsb-overhead/scripts/sbs_overhead_check.py \
  --host <SBS_HOST> --port 30003 \
  --home-lat <LAT> --home-lon <LON> \
  --radius-km 2 \
  --listen-seconds 5 \
  --cooldown-min 15
```

- If it prints lines, those are *new* alerts (not in cooldown).
- If it prints nothing, there were no new overhead aircraft during the sample window.

## How it works

- Connect to the SBS feed (TCP) for `--listen-seconds`.
- Track latest lat/lon per ICAO hex.
- Compute distance to `--home-lat/--home-lon` (Haversine).
- Emit alerts for aircraft within `--radius-km` **only if** not alerted within `--cooldown-min`.
- Persist state to a JSON file (default: `~/.clawdbot/adsb-overhead/state.json`).

SBS parsing assumptions are documented in: `references/sbs-fields.md`.

## Create a Clawdbot watcher (cron)

Use a Clawdbot cron job to run periodically. The cron job should:
1) `exec` the script
2) If stdout is non-empty, `message.send` it via WhatsApp

Pseudocode for the agent:

- Run:
  - `python3 .../sbs_overhead_check.py ...`
- If stdout trimmed is not empty:
  - send a WhatsApp message with that text

Suggested polling intervals:
- 30–60 seconds is usually enough (given cooldowns)
- Use `--listen-seconds 3..8` so each run can gather a few position frames

## Tuning knobs

- Increase `--radius-km` if you want fewer misses.
- Increase `--listen-seconds` if your feed is busy but you’re missing position updates.
- Use `--cooldown-min` to prevent spam (15–60 minutes recommended).

# adsb-overhead (Moltbot/Clawdbot skill)

Get WhatsApp alerts when aircraft are within a configurable radius of your home using a **local ADS-B SBS/BaseStation feed** (e.g. `readsb` on port **30003**) and optional enrichment from **tar1090**.

This project is designed to be **production-friendly**:
- **Zero-AI runtime** (no model calls for the watcher)
- Rate-limited per aircraft (cooldowns) with persistent state
- Optional photo attachment via Planespotters (public API)

## Example alert

![Example WhatsApp alert](assets/example-alert.jpg)

## What you need

- An ADS-B receiver feeding **SBS/BaseStation** on TCP (commonly `:30003`)
- (Optional) `tar1090`/`readsb` HTTP endpoint for enrichment, e.g.:
  - `http://TAR1090_HOST/tar1090/data/aircraft.json`
- Clawdbot (aka Moltbot) running with WhatsApp configured

## Data flow (how it works)

1) **SBS/BaseStation feed (TCP 30003)**
- Source of truth for live aircraft positions.
- `sbs_overhead_check.py` connects for a short window, tracks latest position per ICAO hex, computes distance to your home coordinates, and applies per-aircraft cooldowns.

2) **tar1090 aircraft.json (optional enrichment)**
- Used only to enrich aircraft metadata by ICAO hex (e.g. callsign/flight, emitter category, sometimes registration/type depending on your tar1090/readsb DB).
- Does *not* drive the distance check.

3) **Planespotters photo API (optional)**
- If enabled, looks up a thumbnail by ICAO hex and can download it locally for attaching to WhatsApp.

4) **Zero-AI notifier**
- `adsb_overhead_notify.py` runs the checker in JSONL mode and sends one WhatsApp message per aircraft using `clawdbot message send`.

## Files

- `scripts/sbs_overhead_check.py`
  - Connects to the SBS feed for a short window and detects aircraft within radius.
  - Can output `text` or `jsonl`.
  - Can look up aircraft photos from Planespotters (hex endpoint) and optionally download thumbnails.

- `scripts/adsb_overhead_notify.py`
  - **Zero-AI notifier**.
  - Reads...