Skip to content
lnorton89Public

About

Passive, receive-only multi-sensor drone detection for Raspberry Pi (RTL-SDR V4 + ALFA AWUS036AXML)

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ClassG

CI License: MIT Go Python Rust Node

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.

ClassG operator console — live map with active drone tracks, manned traffic, and a per-track confidence/evidence list

ClassG operator console on a phone — the same live map and track list collapsed into a single-column, bottom-nav layout

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.


Contents


What this actually detects

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

Detection classes

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.


Architecture in one picture

 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.


Optional integrations

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.


Getting started

Prerequisites

  • 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

Get the code

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.

Configure and install dependencies

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 fetch

make 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.

Prove the pipeline without hardware

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.pcap

analyze 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 reads 1581.
  • 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 why config/channels-primary.yaml weights 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 before you plug anything in

  1. Read docs/research/02-hardware-capabilities.md so you know what to expect from each radio.
  2. Set up the Pi — docs/ops/01-pi-setup.md
  3. Set up the Wi-Fi adapter — docs/ops/02-wifi-adapter.md (there are real MT7921AU landmines here; read before plugging in)
  4. Verify with your DJI — docs/planning/test-plan.md

Run it with your own aircraft

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.pcap

Replaying 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.

Run the tests

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 cover

Repository layout

classg/
├── 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

Documentation

docs/README.md is the full documentation index. If you read three things beyond this README, make them:

  1. Hardware capabilities — what each radio can and cannot do. Prevents the most expensive mistakes in the project.
  2. Architecture overview — how it all fits together.
  3. Roadmap — what's built, what's next, and the exit criteria for each milestone.

Project status

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.


Contributing

Issues and pull requests are welcome. Before sending a change:

  • Run the checks for whatever you touched (make lint, plus the relevant suite from make 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.

Acknowledgments

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.


License

MIT — see LICENSE.

About

Passive, receive-only multi-sensor drone detection for Raspberry Pi (RTL-SDR V4 + ALFA AWUS036AXML)

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages