Skip to content

Latest commit

 

History

History
124 lines (91 loc) · 9.46 KB

FEED.md

File metadata and controls

124 lines (91 loc) · 9.46 KB

HTTP feed: remoteid.json

dump3411 can serve its current detections as a JSON document over HTTP so a consumer on the LAN (e.g. ha-airspace, the Home Assistant airspace integration that also ingests ADS-B) can poll them. This is opt-in and additive — it does not change the default detect-and-print-to-journald behavior.

This is not aircraft.json. Drones are not manned aircraft and this feed is not meant for dump1090-family tools. It borrows dump1090's envelope idioms (now, seen, a polled array) only because the intended consumer already understands them. The object schema is purpose-built for ASTM F3411 Remote ID — including operator location, UAS ID type, and native AGL, which dump1090 has no fields for.

The canonical contract lives in the consumer repo (ha-airspace/FEED.md). If this file and that one ever disagree, that one wins. This file restates the contract so the detector repo is self-contained, and adds the producer-side obligations.


Running the feed

sudo python3 dump3411.py --wifi-iface wlan1 --serve 0.0.0.0:8754

Both radios run as threads inside one process and share a single in-memory detection cache; one HTTP server serves the JSON document from that cache. The per-radio scripts (ble_feeder.py, wifi_feeder.py) remain as standalone testing tools and do not serve the feed.

Then from the consumer:

GET http://<dump3411-host>:8754/data/remoteid.json

Use stdlib http.server — no async, no extra deps. dump3411 is designed to run on modest hardware (a Pi Zero W is the reference target), so the HTTP handler must only serialize a pre-built in-memory snapshot — never decode or do work per request.


Document shape

{
  "schema_version": 1,          // bump only on breaking changes
  "now": 1717200000.0,          // epoch seconds at snapshot time (producer clock)
  "messages": 4213,             // total RID messages decoded since start (monotonic)
  "drones": [ /* see below; may be empty */ ]
}

Detection object

Field Type Unit Req Source (decoder)
id string — ✓ Basic ID uas_id — the identity key. For wifi_beacon_fr, the ANSI/CTA-2063 serial when the beacon carries one (id_type serial), otherwise the 30-character French ID (id_type unknown).
id_type string — ✓ serial | caa_reg | utm_uuid | session | unknown (from id_type)
ua_type string — Basic ID ua_type
lat / lon number deg Location msg latitude/longitude
alt_geom_ft number ft Location altitude_geo (m → ft)
agl_ft number ft Location height_agl (m → ft)
gs number kt Location ground_speed (m/s → kt)
track number deg Location heading
geom_rate number ft/min Location vertical_speed (m/s → ft/min)
rssi number dBm transport RSSI of last message
message_count number — running count of decoded RID messages for this id since first seen (per-drone; distinct from the envelope messages)
seen number s ✓ now - last_seen[id]
seen_pos number s now - last_pos_seen[id]
rid_source string — ble | ble5 | wifi_beacon | wifi_beacon_fr | wifi_nan — wifi_beacon_fr = French Direct Remote ID beacon (see below); ble = Bluetooth 4 legacy advertising (one 25-byte ODID message per advertisement); ble5 = Bluetooth 5 long-range / extended advertising (a Message Pack per advertisement), classified from the wire structure — a pack cannot fit legacy advertising's 31-byte PDU cap — because BlueZ does not expose the PHY of received advertisements.
rid_sources array of strings — Every transport this drone has been heard on since it entered the tracker, most-recent-first — e.g. ["wifi_beacon", "ble5", "ble"]. Element 0 always matches the current rid_source. Values mirror rid_source. Resets when the drone TTL-evicts and reappears, same as message_count.
self_id string — Self-ID description — free-text purpose of flight (e.g. "Search and Rescue", "Photography Lesson")
self_id_seen number s now - last_self_id_seen[id]
operator object — from System / Operator-ID msgs (see below)

operator sub-object (present once seen)

Field Type Unit Source
lat / lon number deg System msg operator_lat/operator_lon
location_type string — takeoff | live_gnss | fixed (from System msg byte 1, bits 0-1). takeoff is the drone's launch point, not a live operator position — some transmitters toggle this across messages, so a consumer that treats every operator.lat/lon as "where the operator is standing right now" will see it jump between the drone's own start point and the operator's actual position.
id string — Operator-ID msg operator_id
alt_takeoff_ft number ft System alt_takeoff_geo (m → ft)
seen number s now - last_operator_seen[id] — staleness of this whole block

A detection with no lat/lon is valid (Basic ID heard before GPS lock). Keep it — the identity is known; position is just unavailable.

French Direct Remote ID (wifi_beacon_fr)

France's national scheme (arrêté of 27 December 2019) is not OpenDroneID: it's a Wi-Fi beacon vendor element under OUI 6A:5C:35 with a TLV payload. Each beacon carries identity, position and takeoff point together, and fills the same fields as the ODID transports:

  • id / id_type as described above; ua_type is never set, because the format has no UA type.
  • lat, lon, alt_geom_ft (MSL), agl_ft (height above takeoff), gs and track. Positions have 1e-5° resolution (about 1 m), and altitude, height and speed are whole metres or m/s. There's no vertical rate, so geom_rate stays absent.
  • The takeoff point fills operator.lat/lon with operator.location_type = takeoff. The format has no live operator position.

Producer obligations (the part that's on this repo)

  1. Single in-memory cache, keyed by uas_id. One process, one dict, one threading.Lock. Each entry holds the latest decoded fields plus three monotonic timestamps: last_seen, last_pos_seen, last_operator_seen. Both radios run as threads inside this process and write into the same cache.
  2. Convert to consumer units at write time. RID broadcasts SI (m, m/s); the feed emits ft, kt, ft/min. The producer owns the conversion so the consumer has a single unit path. The decoders in ble_feeder.py / wifi_feeder.py currently emit SI — do the conversion in the cache layer, not in the decoder, so the journald output stays untouched.
  3. Multi-transport precedence: most-recent message wins. If the same uas_id is heard on more than one transport, the latest message updates rid_source, rssi, and any time-varying field (position, velocity, heading, altitude, operator block). Identity fields (id_type, ua_type) are write-once from the first Basic ID and not overwritten. message_count increments on every decoded message regardless of transport. The set of all transports heard is preserved in the additive rid_sources array (most-recent-first), so a consumer can tell "currently on Wi-Fi Beacon, previously heard on BLE" from the row alone.
  4. seen, seen_pos, operator.seen computed at serialize time from the cached monotonic timestamps relative to now.
  5. Drop stale ids from the cache after a producer-side timeout (default: 60 s with no messages on any transport) so the feed reflects current airspace.
  6. Snapshot-only HTTP handler. Under the cache lock, copy the live state into a plain dict; release the lock; then serialize and return. Never decode, convert, or compute under request.
  7. Additive. Adding the feed must not change the existing detector behavior — journald detection logging stays exactly as-is.

Versioning

schema_version is one integer. Adding optional fields is backward-compatible and does not bump it (consumers ignore unknown fields). Removing/repurposing a field or changing units/semantics bumps the major and is coordinated with ha-airspace. Keep this table and the canonical one in sync.

Version Change
1 Initial contract (draft).

/status

Operational health for the dashboard and Home Assistant-style monitors. Additive fields do not bump schema_version.

Field Type Req Notes
schema_version number ✓ Same integer as the JSON feed
version string ✓ Running build: git describe when served from a checkout, archive describe when served from a GitHub source tarball, else pyproject.toml version, else unknown. Computed once at process start.
uptime_s number ✓ Seconds since process start
messages_total number ✓ Decoded RID messages since start
drones_active number ✓ Entries currently in the tracker
last_seen_s number | null ✓ Seconds since any radio last decoded a message
by_source object ✓ Per-transport {messages, last_seen_s}
cpu_temp_c number | null ✓ Host CPU temperature (°C), null when unreadable
history_enabled boolean ✓ true when --history-db is configured
history object {rows, drones, size_bytes, earliest_ts, latest_ts}; present only when history is enabled