adsb-overhead

当飞机在可配置半径内使用本地 ADS-B SBS/基站馈送（读取端口 30003）时发出通知。在设置或排除飞机头顶警报、配置半径/原点坐标/冷却时间或创建 Clawdbot cron 观察程序以发送附近飞机的 WhatsApp 通知时使用。

# 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

从**本地 readsb SBS/BaseStation TCP 馈送**检测头顶上空（在某半径范围内）的飞机，并通过 Clawdbot 消息发送通知。

此技能设计为定期检查器（cron），而非长期运行的守护进程。

## 快速开始（手动测试）

1) 运行检查器几秒钟，看它是否检测到你附近的飞机：

```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
```

- 如果它输出了行，那些就是*新的*警报（不处于冷却期）。
- 如果它没有输出任何内容，说明在采样窗口期间没有新的头顶上空飞机。

## 工作原理

- 连接到 SBS 馈送（TCP），持续 `--listen-seconds`。
- 跟踪每个 ICAO 十六进制码的最新经纬度。
- 计算到 `--home-lat/--home-lon` 的距离（Haversine 公式）。
- 对 `--radius-km` 范围内的飞机发出警报，**仅当**在 `--cooldown-min` 内未发出过警报。
- 将状态持久化到 JSON 文件（默认：`~/.clawdbot/adsb-overhead/state.json`）。

SBS 解析假设记录在：`references/sbs-fields.md`。

## 创建 Clawdbot 观察程序（cron）

使用 Clawdbot cron 任务定期运行。该 cron 任务应：
1) `exec` 该脚本
2) 如果 stdout 非空，通过 WhatsApp `message.send` 发送它

代理的伪代码：

- 运行：
  - `python3 .../sbs_overhead_check.py ...`
- 如果修剪后的 stdout 非空：
  - 发送包含该文本的 WhatsApp 消息

建议的轮询间隔：
- 30–60 秒通常足够（考虑到冷却时间）
- 使用 `--listen-seconds 3..8`，使每次运行都能收集到几个位置帧

## 调节旋钮

- 如果希望减少漏检，增大 `--radius-km`。
- 如果你的馈送繁忙但漏掉了位置更新，增大 `--listen-seconds`。
- 使用 `--cooldown-min` 防止刷屏（推荐 15–60 分钟）。