Passive, multi-sensor drone detection for a Raspberry Pi.
Named for Class G airspace — the uncontrolled airspace below ~1200 ft AGL where nearly all drone activity happens and where almost nobody is watching.
ClassG is receive-only. It never transmits, never jams, never spoofs, never takes over a drone. See docs/research/06-legal-and-ethics.md — this is a design constraint, not a disclaimer.
The operator console, shown here against the "active sky" mock scenario — see Getting started to run it yourself without any hardware. The mobile layout (right) collapses the same map and track list behind a bottom nav.
- What this actually detects
- Architecture in one picture
- Optional integrations
- Getting started
- Repository layout
- Documentation
- Project status
- Contributing
- Acknowledgments
- License
The single most important fact about this hardware, stated up front:
An RTL-SDR V4 tunes 500 kHz – 1.766 GHz. DJI drones talk on 2.4 GHz and 5.8 GHz. The SDR cannot see your DJI. Not with a better antenna, not with more gain, not ever.
So the two radios do genuinely different jobs:
| Radio | Job | Sees your DJI? |
|---|---|---|
| ALFA AWUS036AXML (MT7921AU) | Wi-Fi Remote ID + DJI DroneID beacons | Yes — this is the DJI sensor |
| RTL-SDR V4 (R828D) | Sub-2 GHz control links, analog FPV video, ADS-B airspace context, GNSS interference | No |
Full band-by-band breakdown: docs/research/02-hardware-capabilities.md
| Class | Signal | Sensor | Status |
|---|---|---|---|
| A | ASTM F3411 Remote ID, Wi-Fi Beacon | Wi-Fi | Milestone 1 |
| B | DJI DroneID, Wi-Fi vendor IE (OUI 26:37:12) |
Wi-Fi | Milestone 1 |
| C | Wi-Fi OUI / SSID fingerprint (DJI, Autel, Parrot, Skydio) | Wi-Fi | Milestone 1 |
| D | ADS-B manned traffic (correlation + false-positive suppression) | SDR / network | Milestone 2 |
| E | 433 / 868 / 915 MHz control links (ELRS, Crossfire, RFD900) | SDR | Milestone 3 |
| F | 1.2 / 1.3 GHz analog FPV video downlink | SDR | Milestone 3 |
| G | ASTM F3411 Remote ID over Bluetooth LE | add-on dongle | Milestone 4 |
| H | GNSS L1 noise floor / interference indicator | SDR | Backlog |
Class G needs hardware you don't have yet — see docs/research/02-hardware-capabilities.md#the-bluetooth-gap. It matters: a meaningful share of Remote ID traffic is Bluetooth-only.
ALFA AXML ──► sensor-wifi (Python) ─┐
RTL-SDR ──► sensor-sdr (Rust) ─┼─► ZeroMQ PUB ─► fusion (Go) ─► api (Go) ─► ui (Vite)
[BLE dongle] ► sensor-ble (Python) ─┘ tcp://…:5556 tracks REST+WS map
Each sensor is an isolated process that emits Detections. Fusion correlates them into Tracks. One sensor crashing, or its USB device vanishing, degrades the system instead of killing it. Rationale: ADR-0003.
Why four languages: ADR-0001. Short version — Python where the protocol churn is, Rust where the samples are, Go where the concurrency is, Node where the map is.
One JSON Schema contract in schemas/ is normative across all four; every service
validates against it, so a wire mismatch fails loudly instead of silently.
Five free data sources plug in around the core pipeline. All off by default, all inbound only, all degrading to exactly the behaviour that exists without them — a missing file or a dropped uplink costs enrichment, never detection.
| Source | Adds | Needs a live uplink? |
|---|---|---|
| adsb.lol | Manned traffic for Class D, with no SDR fitted | Yes |
| OpenTopoData | Real height_agl_m from geodetic altitude minus terrain |
No, if self-hosted |
| OpenSky aircraft database | Registration and type for ADS-B contacts | No |
| IEEE MA-L registry | Every OUI a drone vendor actually holds | No |
| Protomaps / OpenFreeMap | A vector basemap that works with the uplink unplugged | No, with Protomaps |
Details, env vars, and the two rules that shaped all of them: docs/ops/07-external-data.md.
- A Raspberry Pi for a real deployment, or any Linux box for development
- ALFA AWUS036AXML and/or an RTL-SDR V4 — see hardware capabilities for what each one actually buys you
- Go 1.26+, Python 3.11+, Rust (stable, 2021 edition), Node 24+ — only needed for the services you're touching; Docker for the web tier
git clone --recursive https://github.com/lnorton89/classg
cd classg--recursive only matters for tools/pi-dash, the optional terminal dashboard
submodule — if you forgot it, git submodule update --init --recursive later.
Configuration is centralized in .env; bootstrap it from the committed contract before
running anything. See docs/ops/00-configuration.md.
make env
make setup # per-service dependencies: Python venv, Go modules, npm ci, cargo fetchmake setup needs all four toolchains (see prerequisites above). If you only
care about one service, run that service's line from the setup target
by hand — but make test assumes the full setup, and says so when it is missing.
A fresh clone has nothing to replay: the capture corpus is gitignored on purpose, because raw captures can contain neighbours' traffic. So the first runnable thing is a synthetic flight — the same frame recipe the sensor's test suite uses, written to a PCAP:
services/sensor-wifi/.venv/bin/python scripts/make-demo-capture.py
cd services/sensor-wifi
.venv/bin/python -m classg_wifi.cli analyze ../../captures/demo-hover.pcapanalyze proves the capture-to-parser chain with no radio attached. Expect
drone transmitters: 1 on channel 6 out of two transmitters seen, a 240 ms
beacon interval, and both vendor IEs decoded from the same MAC: the Remote ID
one carrying serial 1596F3B24C5D7E8F9A0B, the DJI DroneID one carrying
1581F5FMD234A00A.
Two serials for one aircraft is the capture being deliberate, not a fault. It is what exercises the correlation rule that matters — fusion folds them into one track by MAC, because an aircraft that identifies itself differently in two protocols must not become two contacts on the map. Two lines of the report are also expected and are not warnings about your setup:
mfr code: 1596 (unknown ...)— the synthetic serial deliberately does not claim a real CTA-2063 manufacturer code, so the parser correctly says it does not recognise one. A real DJI reads1581.NOTE: the ~1 Hz design assumption looks wrong (4.17 Hz)— that is the analyzer doing its job. 240 ms is what a Mini 5 Pro was measured at, and the note is whyconfig/channels-primary.yamlweights dwell the way it does.
Then push it through the whole stack — bus, fusion, API, map:
make dev # web tier with hot reload; UI on :5173, API on :8081
cd services/sensor-wifi
.venv/bin/python -m classg_wifi.cli replay ../../captures/demo-hover.pcap \
--endpoint tcp://127.0.0.1:5556 --socket-mode connect
curl -s localhost:8081/api/v1/health/health needs no login and should now report wifi-0 healthy with 500
detections in the last five minutes. Open http://localhost:5173, create the
first admin account (there is no default password), and the map shows one
CONFIRMED track hovering near Zürich and then flying a small square — correct
serial, confidence 0.8, per-class evidence listed. The signed-in API views
(/api/v1/tracks, /api/v1/detections) show the same thing.
If any step of that did not happen, a real drone would not have appeared either — which is the point of running this before buying anything.
The operator UI can also run entirely alone on deterministic mock scenarios — browser-only, no API and no bus underneath, so it validates nothing below the browser:
cd services/ui
npm ci
npm run dev- Read docs/research/02-hardware-capabilities.md so you know what to expect from each radio.
- Set up the Pi — docs/ops/01-pi-setup.md
- Set up the Wi-Fi adapter — docs/ops/02-wifi-adapter.md (there are real MT7921AU landmines here; read before plugging in)
- Verify with your DJI — docs/planning/test-plan.md
The first thing worth doing with real hardware is capturing a PCAP of your DJI powering up. Everything else is built against that ground truth.
Monitor mode first. capture --channel retunes the interface before
recording (passively — iw dev set channel transmits nothing), but only an
interface already in monitor mode can be retuned and captured from, and
monitor mode survives neither a reboot nor a replug. On an interface that is
not ready, capture fails with an error naming the fix rather than silently
recording the wrong channel. Set up monitor mode before every session:
make monitor # wraps scripts/setup-monitor.sh; IFACE=wlan2 to override
cd services/sensor-wifi
.venv/bin/python -m classg_wifi.cli capture \
--iface wlan-alfa --channel 6 --out ../../captures/dji-first-flight.pcapReplaying your own capture works exactly like the synthetic one above. For the
web tier in production-shaped containers rather than the dev stack, see
docker/README.md (make compose-up); for a real unit —
sensors under systemd, web tier in Compose, and how to update it in place —
follow docs/ops/09-deployment.md.
make test # all five suites: wifi, fusion, api, ui, sdr — needs `make setup` first
make lint # mirrors the lint jobs in CI — see CLAUDE.md for what it doesn't coverclassg/
├── docs/
│ ├── research/ Band plans, protocol formats, prior art, legal
│ ├── architecture/ System design, data model, ADRs
│ ├── planning/ Roadmap, milestones, test plan
│ └── ops/ Pi setup, adapter setup, calibration, troubleshooting
├── schemas/ JSON Schema — the cross-language contract
├── services/
│ ├── sensor-wifi/ Python: monitor mode, channel hopping, frame parsing
│ ├── sensor-sdr/ Rust: IQ streaming, FFT, energy detection
│ ├── sensor-ble/ Python: BlueZ / Sniffle BLE Remote ID (Milestone 4, not yet implemented)
│ ├── fusion/ Go: detection→track correlation, scoring
│ ├── api/ Go: REST + GraphQL + WebSocket, accounts and sessions
│ └── ui/ React + MapLibre operator console
├── config/ Seed defaults for Tier 2 settings
├── captures/ PCAP / IQ corpus (gitignored, see captures/README.md)
├── scripts/ Bring-up, data-fetch, and diagnostic helpers
├── deploy/ systemd unit templates + installer for the on-host sensors
├── tools/ pi-dash terminal dashboard (Rust submodule)
└── docker/ Compose for the web tier; see docs/ops for USB caveats
docs/README.md is the full documentation index. If you read three things beyond this README, make them:
- Hardware capabilities — what each radio can and cannot do. Prevents the most expensive mistakes in the project.
- Architecture overview — how it all fits together.
- Roadmap — what's built, what's next, and the exit criteria for each milestone.
Milestones 0–2 are complete: hardware bring-up is done, Wi-Fi detection was verified end to end against a live DJI flight (2026-08-10), and ADS-B airspace context is decoding live aircraft on the unit. The Milestone 5 hardening items — systemd units, persistent storage with retention, metrics, Compose — have landed. Milestones 3 (sub-2 GHz control links) and 4 (Bluetooth Remote ID) are open; both need hardware not yet on hand. See docs/planning/roadmap.md for exit criteria and evidence.
Issues and pull requests are welcome. Before sending a change:
- Run the checks for whatever you touched (
make lint, plus the relevant suite frommake test) and mention what you ran — a green result nobody reproduced isn't evidence. - Match the existing style: this codebase comments the why, not the what, and several comments record measurements taken against real hardware. If you change behaviour a comment describes, re-measure or update it rather than leaving a confident statement that's gone stale.
- Changing
schemas/means updating Python, Rust, Go, and TypeScript together — it's the one contract all four services share. - Keep the receive-only constraint intact. No code path may transmit, jam, spoof, or take over a drone; see docs/research/06-legal-and-ethics.md for why that's non-negotiable.
Built on ASTM F3411 / the OpenDroneID reference decoders, MapLibre GL and Protomaps for offline-capable mapping, ZeroMQ for the sensor bus, and libSQL for local-first storage with optional sync. Prior art and what was borrowed from where: docs/research/05-prior-art.md.
MIT — see LICENSE.

