feat(perception): integrate calibrated operator pipeline
Add calibrated K1 projection, recorded and near-live perception qualification, unified Rerun operator layers, bounded replay admission, audited viewer controls, worker experiments, and lab evidence.
This commit is contained in:
DCCONSTRUCTIONS
@@ -1,6 +1,6 @@
|
||||
# ADR 0013: explicit K1 local connection matrix
|
||||
|
||||
- Status: accepted for implementation; physical acceptance is mode-specific
|
||||
- Status: amended 2026-07-20; Bridge is the product path, Quick Connect retained as a prepared-host laboratory path
|
||||
- Date: 2026-07-19
|
||||
- Extends: ADR 0004, ADR 0005 and ADR 0012
|
||||
|
||||
@@ -28,7 +28,7 @@ firmware `3.0.2` compatibility profile:
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 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 |
|
||||
| Quick Connect | `device-ap` | one fixed reviewed 100-byte AP-enable write | preinstalled exact-firmware credential provider, bounded exact-SSID discovery and one association | physically accepted on one prepared Mac; not portable bootstrap |
|
||||
|
||||
Bridge remains the default. Every API request carries both `connection_mode`
|
||||
and its exact topology attestation; mismatched pairs are rejected before any
|
||||
@@ -36,36 +36,121 @@ 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.
|
||||
|
||||
Bridge and Direct Connect do not have a fixed product IP. The address reported
|
||||
by BLE characteristic `7f02` is a DHCP lease observation scoped to the current
|
||||
connection, never device identity and never a durable configuration value.
|
||||
Before a new application-control session, an implicit-host acquisition, or a
|
||||
factory-calibration read, Mission Core performs one read-only `7f02` read for
|
||||
the selected CoreBluetooth device and replaces the previous target. An address
|
||||
change creates a new `device_session_id` and invalidates calibration captured
|
||||
for the previous session. An active acquisition is never retargeted in place.
|
||||
The later correlated MQTT `DeviceInfo` response supplies model, firmware,
|
||||
serial and vendor identity; IP equality alone cannot identify a K1.
|
||||
|
||||
Product decision on 2026-07-20: Bridge/direct-LAN is the continuing route.
|
||||
Quick Connect remains visible and executable on an already prepared host, but
|
||||
is not a deployment dependency or portability claim.
|
||||
|
||||
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.
|
||||
Quick Connect does not accept a credential from the browser/API. The first
|
||||
implementation incorrectly jumped from BLE discovery directly to host Wi-Fi
|
||||
association. A physical negative run showed that the selected K1 was still on
|
||||
the existing LAN and the expected AP was not visible. Re-review of the exact
|
||||
LixelGO branch recovered the missing state transition: after BLE connection it
|
||||
writes one 100-byte `7f01` frame, zero except for `0x01` at offset 99, and treats
|
||||
the callback as the AP-launch result before invoking the OS Wi-Fi connector.
|
||||
|
||||
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.
|
||||
Mission Core now performs that bounded AP-enable write at most once. The first
|
||||
physical run reached `WIFI_AP` at the reviewed AP address, and a targeted
|
||||
CoreWLAN scan found the SSID matching the selected BLE advertised name. It also
|
||||
disproved the earlier assumption that LixelGO carried one global Quick Connect
|
||||
profile: retained client analysis exposes `WiFiAP_SSID` and `WiFiAP_Password` as
|
||||
fields of each device record.
|
||||
|
||||
A subsequent run found that `7f02` may retain `WIFI_AP / 192.168.56.1` after the
|
||||
SSID stops beaconing. Static review then recovered the missing discriminator:
|
||||
LixelGO maps response byte 51 to its AP-ready flag and waits up to 15 seconds for
|
||||
that flag. Mission Core therefore mirrors LixelGO: every new operator Quick
|
||||
Connect action emits exactly one reviewed enable frame, including from a
|
||||
`WIFI_AP` baseline, and admits host discovery only after byte 51 becomes
|
||||
non-zero. This is not an automatic retry.
|
||||
|
||||
The same review proved that LixelGO does not close its BLE manager between the
|
||||
AP-ready callback and native Wi-Fi connect. A failed Mission Core run had done
|
||||
exactly that: byte 51 changed from zero to one, the Python BLE context exited,
|
||||
and the following cold Swift/CoreWLAN process missed the beacon. The corrected
|
||||
implementation holds the selected `BleakClient` open through bounded native
|
||||
SSID discovery and the single association call.
|
||||
|
||||
BLE discovery and the selected device action form one host session. A physical
|
||||
run proved that immediately rediscovering the same K1 by its CoreBluetooth UUID
|
||||
can fail even though the preceding scan exposed it. Mission Core retains the
|
||||
non-serializable `BLEDevice` handle process-locally and uses that exact handle
|
||||
for the next selected network action; it never exposes the handle through API
|
||||
state or treats the macOS UUID as durable device identity.
|
||||
|
||||
The corrected host boundary derives a non-secret, device-scoped profile ID from
|
||||
the selected SSID. The reviewed client contains per-device `WiFiAP_SSID` and
|
||||
`WiFiAP_Password` fields, but the 2026-07-20 review of the exact official K1
|
||||
`3.0.2` firmware recovered their upstream source: the scanner's bundled
|
||||
NetworkManager AP script assigns one firmware-constant WPA2 material, while
|
||||
`lixel_nman` constructs `XGR-` plus six device-identity characters with a MAC
|
||||
fallback. It is neither an iPhone credential nor a per-device secret.
|
||||
|
||||
The laboratory implementation can install a firmware-scoped credential source from the
|
||||
authenticated official archive. The offline importer validates the exact
|
||||
SHA-256, streams the bounded application-partition range, requires one valid AP
|
||||
declaration and writes the value to the OS secure store through helper stdin.
|
||||
On macOS, the Keychain helper materializes the selected device profile from
|
||||
that opaque source before any BLE write. A missing provider fails closed. The
|
||||
browser, API, argv, logs, manifests and evidence never receive the secret; the
|
||||
importer's short-lived mutable buffer is zeroized after the Keychain handoff.
|
||||
|
||||
The host-network boundary, rather than the XGRIDS frontend, owns platform
|
||||
association. Browsers expose no Wi-Fi join API, and Apple's iOS
|
||||
`NEHotspotConfiguration` consent flow is unavailable on macOS. The current
|
||||
implementation therefore uses a short-lived Swift/CoreWLAN + macOS Keychain
|
||||
helper; Windows Credential Manager and Linux Secret Service adapters remain
|
||||
separate platform work. The helper performs repeated read-only exact-SSID scans
|
||||
inside one 15-second discovery window and at most one association. It never
|
||||
repeats the BLE command, guesses a password or treats `7f01` as a credential-read
|
||||
command. The credential-bearing 99-byte station-provisioning frame and fixed
|
||||
100-byte AP-enable frame are separate reviewed payloads.
|
||||
|
||||
No reviewed BLE characteristic or response supplies the AP credential. That
|
||||
does not prove a universal negative for every vendor build, but it means the
|
||||
current plugin has no evidence-backed device-side credential acquisition path.
|
||||
The owner also observed no explicit device/account pairing in the normal
|
||||
LixelGo onboarding flow; this is consistent with a firmware-defined AP secret,
|
||||
but does not establish account-wide authorization for arbitrary scanners.
|
||||
|
||||
Connection verification refreshes the session-scoped lease with the same
|
||||
read-only BLE status operation. It does not write a characteristic, re-provision
|
||||
Wi-Fi, scan the subnet, change a host route, or touch VPN configuration. The
|
||||
later canonical MQTT session supplies the real data-plane connection and live
|
||||
`DeviceInfo` identity check. A BLE lease observation is therefore not by itself
|
||||
a claim that MQTT/RTSP is reachable.
|
||||
|
||||
## 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.
|
||||
- Quick Connect can temporarily remove the controlling host from its previous
|
||||
Wi-Fi network. The operating system may require Wi-Fi/location permission.
|
||||
- A new host needs a separate exact-firmware provider installation. The current
|
||||
application does not obtain it from BLE and does not bootstrap it by itself.
|
||||
- Automatic firmware download, iPhone extraction and hard-coded credential
|
||||
delivery are explicitly rejected product routes. Windows/Linux adapters are
|
||||
therefore not scheduled for this Quick Connect path.
|
||||
- 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.
|
||||
- Direct Connect remains explicitly pending one owner-operated physical
|
||||
acceptance cycle. Quick Connect AP activation and host association are
|
||||
physically accepted only on the prepared K1/FW 3.0.2 Mac stand. Bridge is the
|
||||
only accepted portable product path in this matrix.
|
||||
|
||||
Reference in New Issue
Block a user