Repository navigation
Releases
PyAerial 1.0.0
PyAerial 1.0.0 is the first stable production release. Since 0.22.0, this release introduces strict frame verification, archives flights and alert episodes in real time via periodic database checkpoints (so an abrupt crash loses roughly 15 seconds rather than the whole flight), adds native readsb support, introduces Prometheus metrics, and hardens operational security. Our stability commitments for the 1.x series are documented under Compatibility in the README.
Before upgrading an existing installation, remember to back up your SQLite archive, stop the tracking engine cleanly, and run pyaerial validate against your configuration.
Breaking changes and upgrade notes
Before upgrading an existing deployment, back up your SQLite archive and run pyaerial validate against your configuration file. Stability commitments across the 1.x series are detailed in the Compatibility section of the README.
- Outgoing Beast data on
web.beast_portnow defaults to port 30105 rather than 30005, which avoids conflicting with dump1090's own default Beast port. Reconfigure OpenSky feeders and external consumers to connect to port 30105. Receiver configurations attempting to read PyAerial's own Beast port on the local machine will now be rejected. - Configuration validation has been tightened across all subsystems. The parser rejects unrecognized keys in receiver and alerter
optionsblocks, flags format mismatches such as specifyingbeaston port 30002 oravron port 30005, disallows duplicate rule names within a zone, and rejects degenerate polygons, self-intersecting boundaries, multi-polygon geofences, and polygons containing interior holes. Values whereminexceedsmax(except for wrap-around headings), NaN or infinite numbers, and unsupported webhook methods or formats will now fail validation on startup. - Rule conditions that check
integritywill no longer match aircraft whose integrity verdict isunknown. Previously, unverified aircraft were assigned a placeholder score of 1.0; they now reportscore: nullin live feeds, inintegrity.score, and acrosstelemetry.integrity_score. - Altitudes are now treated strictly as barometric measurements. Geometric height reported in ADS-B messages is stored separately as
gnss_height, and alert rules evaluate geometric height only when an aircraft provides no barometric data. - Initial airborne position tracking now waits for an even and odd CPR message pair, which prevents aircraft tracks from beginning at aliased positions across the globe.
- DF18 messages carrying non-ICAO transponder addresses are no longer ingested into tracking state.
- The research database advances to schema version 4. Existing archives from versions 0.12 through 0.22 are migrated in place automatically during the engine's initial startup. Database migrations roll forward only, so an older PyAerial version cannot read an upgraded database.
- Stop existing
pyaerial runprocesses gracefully before upgrading (usingdocker compose stop, Ctrl-C, or SIGTERM). In previous 0.x releases, an ungraceful crash left active flights stranded in Redis. The 1.0.0 engine treats the SQLite database as the sole source of truth and purges leftover unfinalized flights found in Redis upon startup after logging a count warning. - Active flights and alert episodes are now anchored in the SQLite archive from their first 5-second checkpoint. If the engine terminates abruptly, surviving flights are preserved as
interruptedrecords ending at their last recorded checkpoint. Underarchive.flights: rules, interrupted tracks that failed to trigger a retention rule are discarded cleanly. - In Docker Compose setups, the Redis password is provided as a Docker secret via
PYAERIAL_REDIS_PASSWORD_FILErather than through thePYAERIAL_REDISconnection string. A one-shotredis-configcontainer prepares the configuration file, and the PyAerial container ships only sample configs, requiring host configs to be bind-mounted into/opt/PyAerial/config.yaml. - The
fetchTelemetryWebSocket RPC now defaults to returning up to 5000 points (with an upper limit of 20000) and supplies atruncatedboolean indicator alongside returned data. - Invoking
pyaerialwithout specifying a subcommand now exits with status code 2 instead of 0. - Webhook JSON payloads now format
icaoaddresses in lowercase, retaining legacy fields liketypeandreason.hookfor backward compatibility.
Added
- Added support for reading Redis credentials from a file using
database.redis_password_fileand the correspondingPYAERIAL_REDIS_PASSWORD_FILEenvironment variable. - Added support for reading secret values directly from external files in YAML configurations via
${file:/path}. - Introduced versioned JSON webhook alert payloads under schema identifier
pyaerial.alert/1, adding top-leveleventindicators and ensuring all fields are present consistently. - Added
tracking.max_flight_seconds(defaulting to 14400 seconds) to split exceptionally long flights into linked archive segments while maintaining active alert continuity under the samealert_id. - Added the
enrichment.enabledconfiguration toggle to allow disabling external hexdb.io and Planespotters API queries. - Introduced a dedicated
readsbreceiver driver that consumes Beast or AVR streams while querying tar1090receiver.jsonendpoints for dynamic antenna positions. - Added configurable per-IP connection and rate limits for WebSockets and Beast TCP subscribers via
web.ws_rate_limit_per_ip,web.ws_rate_burst_per_ip, andweb.beast_max_clients_per_ip. - Added
integrity.cross_network.timeout_secondsto constrain external aggregator verification queries. - Added
gnss_heighttracking across database tables and live WebSocket telemetry points. - Enriched alert notifications with
alert_id,flight_id, andaltitude_sourceproperties. Alert deactivations include anended_byreason (cleared,lost,shutdown, orrestart), which also surfaces across WebSocket feeds and in the web portal. - Added archive health indicators (
history,history_error, andhistory_pending) to the engine's live Redis heartbeat payload. - Added database lease fencing via the
engine_leasetable to ensure that multiple engines cannot write to the same database simultaneously. - Introduced periodic database checkpoints every 5 seconds for live flights, minimizing data loss during an unexpected power cut or crash to approximately 15 seconds per flight. Interrupted flights surface an
interrupted: trueflag in API queries and display a warning badge in web history. - Added detailed operational counters to the engine heartbeat to track received frames, dropped frames, processed messages, evicted flights, receiver restarts, and stage errors.
- Added the ability to replay dump1090 Beast binary captures alongside synthetic sample data in
examples/replay.yaml. - Added the
--forceflag topyaerial resetto allow purging SQLite data when Redis is unreachable. - Subscribing to
flights,alerts, orstatsstreams on an existing WebSocket connection now immediately pushes a fresh snapshot of current state. - Added Docker Compose health checks and startup ordering dependencies for Redis, the engine, and the web portal.
- Added a Prometheus metrics endpoint at
GET /metricsreporting real-time engine counters, heartbeat status, and web client statistics. - Added dynamic plugin loading for third-party receivers and alerters via standard Python entry points (
pyaerial.receiversandpyaerial.alerters). - Generated TypeScript API types from server wire models to ensure the frontend build enforces strict contract compatibility in CI.
Changed
- Aircraft integrity verdicts now remain in
unknownstatus until an aircraft has been tracked for at least 30 seconds with three or more checks reporting (or two checks for rebroadcast data). Verification failures publish immediately, while improving verdicts require 30 seconds of consistent evidence. - The angle-of-arrival bias is learned dynamically from aircraft that pass all other integrity checks. When
bearing_offsetis omitted, the AoA check remains silent until sufficient calibration data has been collected. - Rules configured with
retain: truenow require conditions to hold continuously fordwell_seconds, evaluating the specific verdict in effect at each recorded sample. - Flight updates are now pushed to web clients whenever integrity verdicts change.
- SQLite archives from previous releases are upgraded automatically in a single database transaction upon startup.
- The web portal opens the SQLite archive in read-only mode and displays history as unavailable until the engine finishes running migrations.
- Redis now acts strictly as an ephemeral cache of active flight state, republishing state each tick and clearing cached entries upon engine startup.
- The intake queue capacity scales automatically with
tracking.hz. - External HTTP queries for receiver metadata and cross-network position checks now enforce deadlines and handle HTTP 429 backoff according to
Retry-Afterheaders. - The
logging.levelsetting is evaluated case-insensitively and acceptswarnas an alias forwarning. - The AoA sidecar driver now ignores incoming
timefields, stamping frames with local arrival times instead. - The
fetchConfigWebSocket RPC no longer exposes receiver hostnames and ports to connected clients. - The logger previously named
pyaerial.calc.planehas been renamed topyaerial.pipeline. - Docker Compose includes a 20-second stop grace period for the engine, restricts Redis and portal containers to 1 GB of memory, and publishes Beast TCP on
127.0.0.1. - Upgraded the web development toolchain to TypeScript 6, Vite 8, Vitest 5, ESLint 10, and jsdom 30 running on Node 22.
- The web portal uses system fonts rather than loading Google Fonts externally and renders a neutral fallback map backgrou...
PyAerial 0.22.0 - integrity checks and research archive
Originally released 2026-10-27.
Breaking changes
- The SQLite archive now includes schema version tracking via
PRAGMA user_version. Archives generated by version 0.21.0 will be rejected until recreated usingpyaerial reset --yes, as automatic migrations are not provided across this boundary. - General flight retention defaults to archiving all observed flights having at least
archive.min_positionssamples (archive.flights: all), rather than saving only flights matched by an alert rule. To restore the previous selective behavior, setarchive.flights: rules. - dump1090 receivers now default to Beast binary format unless connected to port 30002. If you are serving AVR text over a non-standard port, explicitly specify
format: avr. The sample configuration file has been updated to connect to Beast on port 30005.
Added
- Introduced a built-in integrity monitoring engine configured under
integrity, which continuously scores aircraft from 0 to 1 (ok,suspect, orspoofed) across physical and protocol checks. Checks cover angle of arrival, TDOA multilateration with automatic receiver clock synchronization, signal strength decay curves, line-of-sight radio horizons, Mode S altitude corroboration, transmission intervals, kinematics, packet replays, duplicate ICAO detection, shared-emitter clustering, and FAA registration lookups. - Added optional cross-network verification via
integrity.cross_network(targeting adsb.lol by default), querying an external aggregator to confirm whether reported aircraft positions match wider network observations. - Geofence rules can now evaluate an aircraft's
integrityscore directly withinwhencondition blocks. - Added antenna position modeling for receivers, supporting fixed
positioncoordinates, automatic polling viaposition_url(which queries dump1090'sreceiver.jsonbefore falling back tohome), and antenna elevation settings viaantenna_height. - Introduced the
aoareceiver driver for ingesting angle-of-arrival sidecar streams. - Added comprehensive provenance tracking to the research archive, logging detecting receivers and active integrity verdicts alongside each telemetry sample, recording verdict transitions in an
integritytable, and optionally saving all raw receiver frames whenarchive.raw_framesis enabled. - The web portal displays integrity status badges in flight lists, adds an integrity inspector drawer, styles aircraft tracks according to trust, and displays multilaterated transmitter markers when spoofing is detected.
Changed
- The
/ws/rawWebSocket returns a structured JSON stream containing engine receive timestamps and the full list of detecting receivers for each frame, feeding the portal's Raw viewer. The/ws/beaststream and Beast TCP feed remain binary Beast feeds. - The web map has been migrated entirely to MapLibre GL, removing Leaflet and reducing the client bundle size. Flight list sorting controls have been streamlined.
Full changelog: v0.21.0...v0.22.0
PyAerial 0.19.0 - slimmed-down scanner and portal Raw tab
Originally released 2026-09-18.
Breaking changes
- Removed the Kafka alerter integration and the
kafkainstallation extra, standardizing alert delivery on the built-inprintandwebhookdispatchers. - Removed the experimental
py1090RTL-SDR receiver driver along with thesdrandallinstallation extras. Deployments should connect directly to a runningdump1090instance or use thereplaydriver for testing. - Removed the deprecated
pyaerial viewandpyaerial liveterminal commands.
Added
- Added the
pyaerial resetcommand to allow clearing historical SQLite records, supporting full database wipes or selective removal of individual aircraft by ICAO address. - Added a Raw inspector tab to the portal sidebar to display live incoming Mode S frames streamed over
/ws/raw. - Added pagination controls to historical views in the portal to allow browsing past the initial 200 flights.
Full changelog: v0.17.0...v0.19.0
PyAerial 0.21.0 - security and correctness remediation
Originally released 2026-10-21.
Breaking changes
- The raw JSON socket has been replaced with a reconstituted Beast binary output. Frames received across all stations are deduplicated, corrected, and published as dump1090 Beast binary on
/ws/beastand via a dedicated TCP server (configured withweb.beast_port, defaulting to 30005, andweb.beast_host, defaulting to127.0.0.1). Settingweb.beast_portto null or settingPYAERIAL_BEAST_PORT=offdisables the TCP listener. - Browser origin security has been tightened so that
web.originsdefaults to an empty list, requiring exactscheme://host[:port]matches. Localhost connections require settingweb.allow_localhost_origins: true, and same-origin requests are accepted only when browsing by IP, loopback, or hostnames explicitly declared inweb.allowed_hosts. - Docker Compose now requires an explicit
REDIS_PASSWORDin the environment, binds published container ports strictly to127.0.0.1, and drops root privileges across all services without requesting privileged container mode.
Added
- Added configurable WebSocket connection caps and rate limits via
ws_max_connections,ws_max_connections_per_ip,beast_max_clients,ws_max_inflight,ws_rate_limit,ws_rate_burst, andws_request_workers. - Added support for reverse proxy header forwarding via
trusted_proxiesand made interactive OpenAPI documentation opt-in usingenable_docs. - Standardized error codes across WebSocket RPC responses and injected defensive security headers (including Content Security Policy and frame restrictions) on all web responses.
- Added the
--forceflag topyaerial resetso operators can purge historical data when Redis is offline and engine status cannot be verified.
Fixed
- Hardened webhook delivery by refusing HTTP redirects, retrying only on network drops, HTTP 5xx, or HTTP 429 status codes, restricting HTTP methods to POST and PUT, and redacting endpoint URLs in log output.
- Prevented XML entity expansion attacks by validating external geofence files and enforcing a 20 MB size limit.
- Redacted Redis credentials from console logs and runtime status outputs.
- Bounded outgoing alert delivery queues and ensured notifications for a single alert episode are dispatched in chronological order.
- Improved tracking resilience so that isolated bad position fixes no longer freeze aircraft tracks, multi-receiver merges execute faster, and non-monotonic receiver clocks are handled cleanly.
- Resolved web portal rendering bugs to restore basemap display, surface clear status banners when connections are rejected, and apply jittered backoff during reconnect attempts.
Changed
- Migrated to a multi-stage Docker build pinning dump1090 v11.1, locked runtime Python dependencies using sha256 hashes in
requirements.lock, and bumped underlying libraries to patch known security vulnerabilities.
Full changelog: v0.20.2...v0.21.0
PyAerial 0.20.2
Originally released 2026-09-20.
Breaking changes
- Alert rules must now specify at least one spatial condition in their
whenblock, such aseta,distance(ordist), orproximity. PyAerial does not perform implicit inside-polygon testing, so rules defining only non-spatial constraints like altitude are rejected during validation.
Fixed
- Corrected tracking state initialization so that AVR speed and track heading are no longer seeded at zero, surface position frames do not overwrite airborne altitudes, and east-west tracks no longer collapse on longitude boundaries.
- Hid leftover Redis keys from previous engine crashes, prevented a second engine instance from starting when Redis is down, and updated
pyaerial resetto refuse deleting aircraft that are actively being tracked. - Fixed web portal deep linking, improved path history pruning, and aligned historical count metrics with active live state.
Changed
- Configured Docker Compose so
DUMP1090_HOSTdefaults tohost.docker.internaland updated container health checks to query/ready.
Full changelog: v0.20.1...v0.20.2
PyAerial 0.20.1
Originally released 2026-09-18.
- Updated
pyaerial reset <ICAO>to immediately clear matching live Redis snapshots, preventing purged aircraft from reappearing on web maps before the tracking engine cycles. - Updated the web portal to display a clear error message when Redis is unreachable, rather than showing an empty aircraft list.
- Improved capture replay pacing by deriving playback timing from dump1090's 12 MHz clock when reading timestamped AVR (
@CLOCKHEX;) captures, and adjusted the default playback interval to 0.1 seconds.
Full changelog: v0.20.0...v0.20.1
PyAerial 0.20.0 - token auth removed, WebSocket docs
Originally released 2026-09-18.
Breaking changes
- Removed token-based authentication via
web.tokenandPYAERIAL_WEB_TOKEN. Configurations that still defineweb.tokenwill now fail validation. Because the web portal and WebSocket feeds do not provide built-in user authentication, deployments should secure access using network bind addresses and upstream reverse proxies.
Fixed
- Resolved a livelock in the web portal that occurred when enabling track paths for flights with no recorded points.
- Improved error handling so that an unavailable SQLite database surfaces as an explicit failure rather than wiping the currently displayed flight list during portal refreshes.
- Ensured the live Redis writer backs off gracefully when another engine instance holds an active heartbeat.
Documentation
- Added the
WEBSOCKET.mdprotocol guide and revisedCLI.md,CONFIGURATION.md,UNITS.md, and the main project README.
Full changelog: v0.19.0...v0.20.0
PyAerial 0.17.0 - ETA, engine and portal fixes
Originally released 2026-09-17.
Fixed
- Prevented spurious curved ETA calculations caused by rapid AVR heading message pairs arriving within microseconds of each other, preserved recent speed readings across brief transmission gaps, and limited dead-reckoning alert projections to aircraft with fresh position fixes within five seconds.
- Enforced single-instance engine execution by refusing to start
pyaerial runwhen another engine's heartbeat is actively ticking in Redis. - Prevented Redis reconnect routines from purging active live keys, and allowed crash recovery snapshots to restore truncated SQLite archives.
- Improved portal connection handling to halt automatic reconnect loops after receiving an HTTP 1008 rejection, allowed same-host web origins, resolved track path rendering freezes, and ensured velocity updates update aircraft map markers.
- Aligned terminal status reports, reset commands, help documentation, and receiver drivers with documented specifications.
Changed
- Relocated the default
aircraft.dbcache path to the current working directory (overridable viaPYAERIAL_AIRCRAFT_DBor--aircraft-db), while Docker Compose mounts the cache under/data. - Added an informative error message when attempting to use the
py1090receiver withoutpyrtlsdr, suggesting installation withpip install 'pyaerial[sdr]'. - Updated replay behavior so capture lines lacking timestamps are processed at maximum throughput when
interval: 0is set, and ensured speed multipliers apply only to timestamped captures. - Updated
pyaerial viewsubcommands tolist,dump,reset,status, andlive, and enableddump aircraftto read cached metadata without making external network calls.
Full changelog: v0.16.0...v0.17.0
PyAerial 0.16.0 - live store and tracking fixes
Originally released 2026-09-17.
Fixed
- Prevented portal and viewer connections to Redis from accidentally clearing the engine's live tracking keys.
- Prevented completed flights in SQLite from being overwritten when Redis telemetry windows expire, and ensured startup crash recovery deactivates any open alerts left behind.
- Hardened tracking accuracy by discarding late-arriving ADS-B samples, requiring continuous condition matches for retention rather than qualifying an entire flight from a single sample, correcting CPR and antimeridian coordinate unwrapping, resolving conflicting turn rate sources, and properly handling ground-level barometric altitudes.
- Updated the replay receiver to remain running when
loop: falsefinishes rather than exiting abruptly, and preventedpyaerial view resetfrom deleting live keys while an engine is active. - Corrected WebSocket handshake handling by removing redundant Host checks, preventing infinite reconnect loops on authentication failures, sending an initial
hellohandshake on raw feeds, and preventing telemetry cursors from skipping points when network backpressure drops messages. - Added a visual notification banner in the web portal whenever the tracking engine is idle or stopped.
Full changelog: v0.15.0...v0.16.0
PyAerial 0.15.0 - startup archiving and stricter validation
Originally released 2026-09-17.
Fixed
- Updated engine startup to safely archive active flights found in Redis rather than clearing them.
- Clamped unrealistic speed jumps and improved CPR position decoding to decode relative to the aircraft's previous position fix.
- Resolved security advisories for MapLibre and Vitest within frontend dependencies.
- Improved error reporting in
pyaerial viewandpyaerial livewhen reading invalid configurations, and enriched flight inspection dumps with matching alert rules and timestamps.
Changed
- Increased the default
tracking.remember_planestimeout from 30 seconds to 120 seconds. - Strengthened configuration validation to enforce accepted dump1090 formats (
avr,raw,beast, orbinary), validate latitude and longitude ranges, require at least one receiver definition, verify replay capture file paths exist, and require positive interval numbers inlive --interval.
Full changelog: v0.14.0...v0.15.0