playbooks

home / skills / openclaw / skills / moltbot-adsb-overhead

moltbot-adsb-overhead skill

This skill notifies when aircraft are overhead within a configurable radius using a local ADS-B feed, via cron-driven checks and WhatsApp alerts.

npx playbooks add skill openclaw/skills --skill moltbot-adsb-overhead

Review the files below or copy the command above to add this skill to your agents.

Files (8)
SKILL.md
2.2 KB
---
name: adsb-overhead
description: Notify when aircraft are overhead within a configurable radius using a local ADS-B SBS/BaseStation feed (readsb port 30003). Use when setting up or troubleshooting plane-overhead alerts, configuring radius/home coordinates/cooldowns, or creating a Clawdbot cron watcher that sends WhatsApp notifications for nearby aircraft.
---

# 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).

Overview

This skill notifies you when aircraft pass overhead within a configurable radius by reading a local ADS‑B SBS/BaseStation TCP feed (readsb port 30003). It is designed as a periodic checker for cron-style runs rather than a long‑running daemon. Use it to detect nearby traffic, throttle repeat alerts, and integrate with Clawdbot messaging like WhatsApp.

How this skill works

On each run the script connects to the SBS feed for a short listen window and tracks the latest latitude/longitude per ICAO hex. It computes Haversine distances to your configured home coordinates and emits alerts for aircraft inside the radius only if they aren’t in the cooldown window. State (last alerted times) is persisted to a JSON file so cooldowns survive restarts.

When to use it

  • Add a cron/Clawdbot watcher to get WhatsApp notifications when planes fly nearby
  • Manually test or troubleshoot ADS‑B feed connectivity and parsing with short listen windows
  • Tune detection radius and listen duration to adapt to mountaintop or urban reception conditions
  • Avoid running a continuous daemon; run periodic short checks for reliable, low‑resource monitoring

Best practices

  • Run the checker every 30–60 seconds when using short cooldowns, otherwise less frequently
  • Use --listen-seconds 3–8 to capture a few position frames without long connections
  • Set --cooldown-min (15–60 min recommended) to prevent duplicate alerts for the same aircraft
  • Increase radius if you see missed passes; increase listen time if your feed is busy or sparse
  • Store the state JSON on persistent storage so cooldowns persist across runs

Example use cases

  • Cron job that executes the checker and sends stdout via Clawdbot WhatsApp when non‑empty
  • Site setup: verify your readsb/SBS feed is reachable and producing position messages
  • Neighborhood aircraft alerting: notify when any plane passes within 1–5 km of home
  • Troubleshooting: confirm parsing and distance calculations during short local tests

FAQ

What port and feed format does this expect?

It expects a local readsb SBS/BaseStation TCP feed on port 30003 (SBS‑1 format).

How do cooldowns and state persistence work?

The script persists last‑alert timestamps to a JSON file (default ~/.clawdbot/adsb-overhead/state.json) and will not re-alert for the same ICAO within the configured cooldown minutes.