wingbits client and cli helpers for mgw310 and other devices

2026-06-22 22:11:27 -04:00
parent edb6b39543
commit 24fe4258f7
28 changed files with 2980 additions and 2 deletions
@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Project-level instructions for working in this repository. Read this before
+touching the filesystem.
+
+## What this is
+
+Go helper packages for talking to a [Wingbits](https://wingbits.com) ADS-B
+station (e.g. the MGW310) and decoding the readsb / tar1090 JSON files it serves.
+
+Module: `gitea.libretechconsulting.com/rmcguire/wingbits` (Go 1.26).
+
+## Layout
+
+```
+pkg/types/readsb     # decode types for aircraft/receiver/stats/outline + aircraft filters
+pkg/types/wingbits   # decode types for diagnostics/metrics/status (+ Prometheus text parser)
+pkg/client           # HTTP Client: query + stream every endpoint, returns the types above
+cmd/wingbits         # flag-driven CLI for one-off queries (test/utility tool)
+```
+
+Rules of the split:
+
+- `pkg/types/*` is **decode-only**. No HTTP, no I/O beyond `encoding/json` and the
+  Prometheus text parser. These packages must not import `pkg/client`.
+- `pkg/client` owns all transport/request logic and depends on both type packages.
+- Keep the two type packages independent of each other.
+
+## Station topology (important for endpoint routing)
+
+A station exposes two HTTP roots; both are plaintext HTTP on the test unit:
+
+| Root      | Default port | Serves                                                        |
+|-----------|--------------|---------------------------------------------------------------|
+| Wingbits  | `:8088`      | `/network/diagnostics`, `/metrics`, `/tailscale/status`, and readsb files under `/readsb/` |
+| tar1090   | `:8504`      | readsb files under `/data/`, plus `/data/outline.json`        |
+
+`outline.json` is **only** served by the tar1090 root. When a tar1090 endpoint is
+configured it overrides the Wingbits root for all readsb files.
+
+## Testing
+
+```
+go test ./...
+```
+
+Tests decode captured fixtures in each package's `testdata/` directory and drive
+the client against an `httptest` server. `pkg/client` reuses the fixtures from
+`pkg/types/*/testdata` (a single source of truth — do not duplicate them).
+
+The live reference unit is an **MGW310 at `192.168.0.127`** (also
+`miner.mcguire.local`), plaintext HTTP on all ports. Re-capture fixtures from it
+with `curl` when fields change; never hand-edit `testdata/` payloads.
+
+## Coding standards
+
+- Go only. Keep functions within ~25 lines; decompose helpers as needed.
+- Every package has a package comment (Go convention) in one of its files.
+- Comment only the non-obvious. Field docs on the decode structs are intentional
+  — they capture readsb/Wingbits semantics that aren't evident from the name.
+- The known JSON quirks to preserve when editing decode types:
+  - `alt_baro` may be the string `"ground"` instead of a number → `readsb.AltBaro`.
+  - readsb timestamps are fractional-second Unix floats → `readsb.UnixTime`.
+  - `outline.json` points are `[lat, lon, altFeet]` tuples → `readsb.RangePoint`.