72 lines
3.7 KiB
Markdown
72 lines
3.7 KiB
Markdown
# 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.
|