3.7 KiB
ADR 0013: explicit K1 local connection matrix
- Status: accepted for implementation; physical acceptance is mode-specific
- Date: 2026-07-19
- Extends: ADR 0004, ADR 0005 and ADR 0012
Context
Mission Core v0.5.0 exposed only the already accepted shared-LAN path even though the product UI named the other XGRIDS connection directions. Retained owner-operated evidence establishes two different network ownership models:
- the K1 joins a network whose credentials are sent in the reviewed 99-byte BLE provisioning frame; and
- the controller joins the K1 access point and then reaches the same local MQTT/RTSP data plane at the observed AP address.
Official workflow notes separately name Bridge, Direct Connect and Quick Connect. The names alone do not authorize another BLE command or an inferred credential decoder.
Decision
Plugin v0.6.0 exposes three explicit, fail-closed choices under one exact
firmware 3.0.2 compatibility profile:
| UI mode | Topology | Device action | Host action | Acceptance |
|---|---|---|---|---|
| Bridge | direct-lan |
one reviewed BLE provisioning write | none | physically accepted in Mission Core |
| Direct Connect | controller-hotspot |
the same reviewed BLE provisioning write | operator prepares the hotspot and route | implementation complete; physical run pending |
| Quick Connect | device-ap |
none | one CoreWLAN scan and association | LixelGO data plane observed; Mission Core host run pending |
Bridge remains the default. Every API request carries both connection_mode
and its exact topology attestation; mismatched pairs are rejected before any
network action. Acquisition and camera admission must match the active mode.
The fixed K1 AP address is admitted only after a successful Quick Connect host
association.
Direct Connect does not introduce a new vendor payload. The operator first starts a hotspot on the controlling device and enters that hotspot's SSID and password. Mission Core performs the same single, physically reviewed BLE write used by Bridge and accepts only the non-AP private IPv4 returned by K1 status.
Quick Connect does not write GATT. A short-lived macOS Swift/CoreWLAN helper receives the operator-entered AP SSID and password as bounded JSON on stdin. The credential never appears in argv, environment, stdout, stderr, manifests or browser persistence. The helper performs at most one scan and one association; Mission Core does not retry. The implementation intentionally does not infer or read the K1 AP password from an undocumented BLE structure. Until that read has its own captured characteristic, bounded decoder and review, the operator must enter the AP credentials shown for the owner-controlled scanner.
No connection-verification button emits a probe. It validates only the admitted private address; the later canonical MQTT session supplies the real data-plane connection attempt. A failed or ambiguous network action remains terminal until the operator checks physical state and explicitly starts a new operation.
Consequences
- The UI now represents all three intended directions instead of disabled placeholders.
- Quick Connect can temporarily remove the Mac from its previous Wi-Fi network. macOS may require Wi-Fi/location permission for the process running Mission Core.
- Direct Connect requires an already-running hotspot and a controller route; Mission Core does not create or manage that hotspot.
- The application-control, START/STOP and raw-first acquisition protocol is unchanged after a target address is admitted.
- Direct Connect and Mission Core Quick Connect remain explicitly pending one owner-operated physical acceptance cycle each. Offline tests cannot promote those claims.