Skip to content

Releases

PyAerial 1.0.0

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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_port now 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 options blocks, flags format mismatches such as specifying beast on port 30002 or avr on 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 where min exceeds max (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 integrity will no longer match aircraft whose integrity verdict is unknown. Previously, unverified aircraft were assigned a placeholder score of 1.0; they now report score: null in live feeds, in integrity.score, and across telemetry.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 run processes gracefully before upgrading (using docker 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 interrupted records ending at their last recorded checkpoint. Under archive.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_FILE rather than through the PYAERIAL_REDIS connection string. A one-shot redis-config container 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 fetchTelemetry WebSocket RPC now defaults to returning up to 5000 points (with an upper limit of 20000) and supplies a truncated boolean indicator alongside returned data.
  • Invoking pyaerial without specifying a subcommand now exits with status code 2 instead of 0.
  • Webhook JSON payloads now format icao addresses in lowercase, retaining legacy fields like type and reason.hook for backward compatibility.

Added

  • Added support for reading Redis credentials from a file using database.redis_password_file and the corresponding PYAERIAL_REDIS_PASSWORD_FILE environment 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-level event indicators 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 same alert_id.
  • Added the enrichment.enabled configuration toggle to allow disabling external hexdb.io and Planespotters API queries.
  • Introduced a dedicated readsb receiver driver that consumes Beast or AVR streams while querying tar1090 receiver.json endpoints 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, and web.beast_max_clients_per_ip.
  • Added integrity.cross_network.timeout_seconds to constrain external aggregator verification queries.
  • Added gnss_height tracking across database tables and live WebSocket telemetry points.
  • Enriched alert notifications with alert_id, flight_id, and altitude_source properties. Alert deactivations include an ended_by reason (cleared, lost, shutdown, or restart), which also surfaces across WebSocket feeds and in the web portal.
  • Added archive health indicators (history, history_error, and history_pending) to the engine's live Redis heartbeat payload.
  • Added database lease fencing via the engine_lease table 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: true flag 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 --force flag to pyaerial reset to allow purging SQLite data when Redis is unreachable.
  • Subscribing to flights, alerts, or stats streams 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 /metrics reporting 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.receivers and pyaerial.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 unknown status 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_offset is omitted, the AoA check remains silent until sufficient calibration data has been collected.
  • Rules configured with retain: true now require conditions to hold continuously for dwell_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-After headers.
  • The logging.level setting is evaluated case-insensitively and accepts warn as an alias for warning.
  • The AoA sidecar driver now ignores incoming time fields, stamping frames with local arrival times instead.
  • The fetchConfig WebSocket RPC no longer exposes receiver hostnames and ports to connected clients.
  • The logger previously named pyaerial.calc.plane has been renamed to pyaerial.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...
Read more

PyAerial 0.22.0 - integrity checks and research archive

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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 using pyaerial 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_positions samples (archive.flights: all), rather than saving only flights matched by an alert rule. To restore the previous selective behavior, set archive.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, or spoofed) 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 integrity score directly within when condition blocks.
  • Added antenna position modeling for receivers, supporting fixed position coordinates, automatic polling via position_url (which queries dump1090's receiver.json before falling back to home), and antenna elevation settings via antenna_height.
  • Introduced the aoa receiver 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 integrity table, and optionally saving all raw receiver frames when archive.raw_frames is 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/raw WebSocket 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/beast stream 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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

Originally released 2026-09-18.

Breaking changes

  • Removed the Kafka alerter integration and the kafka installation extra, standardizing alert delivery on the built-in print and webhook dispatchers.
  • Removed the experimental py1090 RTL-SDR receiver driver along with the sdr and all installation extras. Deployments should connect directly to a running dump1090 instance or use the replay driver for testing.
  • Removed the deprecated pyaerial view and pyaerial live terminal commands.

Added

  • Added the pyaerial reset command 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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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/beast and via a dedicated TCP server (configured with web.beast_port, defaulting to 30005, and web.beast_host, defaulting to 127.0.0.1). Setting web.beast_port to null or setting PYAERIAL_BEAST_PORT=off disables the TCP listener.
  • Browser origin security has been tightened so that web.origins defaults to an empty list, requiring exact scheme://host[:port] matches. Localhost connections require setting web.allow_localhost_origins: true, and same-origin requests are accepted only when browsing by IP, loopback, or hostnames explicitly declared in web.allowed_hosts.
  • Docker Compose now requires an explicit REDIS_PASSWORD in the environment, binds published container ports strictly to 127.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, and ws_request_workers.
  • Added support for reverse proxy header forwarding via trusted_proxies and made interactive OpenAPI documentation opt-in using enable_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 --force flag to pyaerial reset so 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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

Originally released 2026-09-20.

Breaking changes

  • Alert rules must now specify at least one spatial condition in their when block, such as eta, distance (or dist), or proximity. 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 reset to 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_HOST defaults to host.docker.internal and updated container health checks to query /ready.

Full changelog: v0.20.1...v0.20.2

PyAerial 0.20.1

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

Originally released 2026-09-18.

Breaking changes

  • Removed token-based authentication via web.token and PYAERIAL_WEB_TOKEN. Configurations that still define web.token will 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.md protocol guide and revised CLI.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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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 run when 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.db cache path to the current working directory (overridable via PYAERIAL_AIRCRAFT_DB or --aircraft-db), while Docker Compose mounts the cache under /data.
  • Added an informative error message when attempting to use the py1090 receiver without pyrtlsdr, suggesting installation with pip install 'pyaerial[sdr]'.
  • Updated replay behavior so capture lines lacking timestamps are processed at maximum throughput when interval: 0 is set, and ensured speed multipliers apply only to timestamped captures.
  • Updated pyaerial view subcommands to list, dump, reset, status, and live, and enabled dump aircraft to 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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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: false finishes rather than exiting abruptly, and prevented pyaerial view reset from 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 hello handshake 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

Choose a tag to compare

@quantumbagel quantumbagel released this 04 Nov 04:34

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 view and pyaerial live when reading invalid configurations, and enriched flight inspection dumps with matching alert rules and timestamps.

Changed

  • Increased the default tracking.remember_planes timeout from 30 seconds to 120 seconds.
  • Strengthened configuration validation to enforce accepted dump1090 formats (avr, raw, beast, or binary), validate latitude and longitude ranges, require at least one receiver definition, verify replay capture file paths exist, and require positive interval numbers in live --interval.

Full changelog: v0.14.0...v0.15.0