docs(k1): record connection mode acceptance
This commit is contained in:
DCCONSTRUCTIONS
parent
57b2208cae
commit
75d2e5da4b
12
README.md
12
README.md
|
|
@ -130,7 +130,8 @@ uv run k1link serve
|
|||
Open `http://127.0.0.1:8000`. The static application, REST/WebSocket control
|
||||
plane and credential endpoint bind to loopback only. The current K1 adapter
|
||||
still provides real CoreBluetooth discovery, one operator-triggered reviewed
|
||||
BLE Wi-Fi provisioning write, read-only MQTT live capture, native `.k1mqtt` and
|
||||
BLE Wi-Fi provisioning write, a one-shot CoreWLAN K1-AP association path,
|
||||
read-only MQTT live capture, native `.k1mqtt` and
|
||||
reviewed-TSV replay, raw-first evidence storage, device-reported scan
|
||||
time/distance/speed and measured preview metrics. Its frontend contribution now
|
||||
also owns an optional spatial-scene control block, including acquisition phase,
|
||||
|
|
@ -138,6 +139,15 @@ telemetry and the stop action. Operator-manual acquisition still finalizes only
|
|||
local reception; plugin-commanded v0.5.0 acquisition uses the separately gated
|
||||
canonical K1 START/STOP dialogue.
|
||||
|
||||
Plugin v0.6.0 makes the local connection direction explicit. Bridge remains the
|
||||
default; Direct Connect sends the same reviewed BLE frame with credentials for
|
||||
an already-running controller hotspot; Quick Connect sends no BLE write and
|
||||
instead associates this Mac with the K1 AP once. Each mode has a distinct
|
||||
topology attestation and no automatic retry. The Bridge path is physically
|
||||
accepted. Direct Connect and the Mission Core Quick Connect host adapter are
|
||||
implemented and offline-verified but still require their own owner-operated
|
||||
physical acceptance cycles; see [ADR 0013](docs/adr/0013-k1-local-connection-matrix.md).
|
||||
|
||||
The exact recovered `ModelingRequest` start/stop encoder, response correlator
|
||||
and device-status state machine are installed in the operator-gated interactive
|
||||
control path.
|
||||
|
|
|
|||
|
|
@ -320,8 +320,10 @@ facts и старые presentation-поля `phase`, `message`, `devices`,
|
|||
активным между сессиями; для его закрытия нужно остановить `k1link serve`.
|
||||
- Пароль Wi-Fi находится только в React memory, передаётся в JSON POST body,
|
||||
очищается после успешного ответа и не сохраняется в URL/local storage.
|
||||
- BLE-подключение выполняет только отдельно рассмотренную provisioning-запись;
|
||||
случайные GATT writes и автоматические повторы запрещены.
|
||||
- Bridge и Direct Connect выполняют только отдельно рассмотренную provisioning-
|
||||
запись; Quick Connect не пишет в GATT и передаёт пароль короткоживущему
|
||||
CoreWLAN helper только через stdin. Случайные GATT writes и автоматические
|
||||
повторы запрещены.
|
||||
- MQTT data live/replay остаётся subscribe-only. Команды изолированы в
|
||||
plugin-owned canonical control session и доступны только через отдельные
|
||||
operator-present UI checkpoints.
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
This plan supersedes the app-dependent experiment order in the reference Bible.
|
||||
Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result.
|
||||
|
||||
## Current checkpoint — 2026-07-18
|
||||
## Current checkpoint — 2026-07-19
|
||||
|
||||
| Stage | Result |
|
||||
| --- | --- |
|
||||
|
|
@ -11,6 +11,7 @@ Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result.
|
|||
| Gate 1 physical operation | GO — autonomous double-click start/stop verified |
|
||||
| Stage 1 BLE discovery | GO — repeatable advertisement and GATT profile |
|
||||
| Stage 2 BLE provisioning | GO — reviewed 99-byte profile, LAN association confirmed |
|
||||
| Stage 2 local connection matrix | GO (implementation) — Bridge remains physically accepted; Direct Connect reuses the reviewed one-shot BLE frame; Quick Connect uses one CoreWLAN host association and no GATT write. Direct Connect and Mission Core Quick Connect still require separate physical acceptance |
|
||||
| Stage 3 application session | GO — MQTT 3.1.1 on confirmed K1 TCP 1883 |
|
||||
| Stage 4 artifacts/flows | GO — bounded capture, hashes and negative control |
|
||||
| Stage 5 point cloud | GO — raw-LZ4 protobuf, 1,140 live frames decoded |
|
||||
|
|
|
|||
|
|
@ -13,6 +13,11 @@ that Mission Core reproduces all ten requests before START, plus START and STOP,
|
|||
byte-for-byte. This describes the current device dialogue but does not authorize
|
||||
writes to any K1.
|
||||
|
||||
The profile identifier above records the accepted v0.5.0 boundary. ADR 0013
|
||||
supersedes the active runtime selection with
|
||||
`xgrids.lixelkity-k1.fw-3.0.2.local-network.v2`; it does not change the command
|
||||
dialogue or retroactively broaden this acceptance evidence.
|
||||
|
||||
The protocol exposes identities with different ownership. Mission Core's
|
||||
inventory UUID and the macOS CoreBluetooth UUID are local transport identities.
|
||||
The vendor device ID and serial identify the live scanner. The OpenAPI value is
|
||||
|
|
|
|||
|
|
@ -0,0 +1,71 @@
|
|||
# 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.
|
||||
|
|
@ -84,8 +84,10 @@ to captured evidence.
|
|||
|
||||
## Current supported choices
|
||||
|
||||
- Connection: direct LAN is active; alternative connection modes remain disabled
|
||||
UI anchors until independently accepted.
|
||||
- Connection at the time of this acceptance: direct LAN only. ADR 0013 later
|
||||
enabled Bridge, Quick Connect and Direct Connect as distinct v0.6.0 paths;
|
||||
that later implementation does not retroactively add physical acceptance to
|
||||
this archived run.
|
||||
- Mount/scan carrier: handheld is active. Ground UGV and aerial UAV choices are
|
||||
visible but disabled anchors.
|
||||
- GNSS: no RTK is the active default. RTK is visible but disabled and optional;
|
||||
|
|
|
|||
|
|
@ -19,7 +19,8 @@ The plugin owns:
|
|||
- the exact firmware/topology compatibility profiles under
|
||||
[`profiles/`](profiles/), with strict evidence flags and a fail-closed loader;
|
||||
- BLE discovery hints and K1 GATT metadata;
|
||||
- the reviewed firmware-3 Wi-Fi provisioning profile;
|
||||
- Bridge and Direct Connect through the reviewed firmware-3 BLE Wi-Fi
|
||||
provisioning frame, plus a one-shot macOS CoreWLAN Quick Connect adapter;
|
||||
- K1 LAN status and private-address validation;
|
||||
- subscribe-only data MQTT transport plus a separately bounded canonical
|
||||
application-control transport;
|
||||
|
|
@ -74,7 +75,8 @@ in-process and its health is lifecycle-only; process isolation, crash/restart
|
|||
containment and signed deployment remain later supervisor gates.
|
||||
|
||||
The compatibility profile is descriptive and cannot itself authorize a vendor
|
||||
write. The UI selects the exact firmware `3.0.2` / direct-LAN profile; the
|
||||
write. The UI selects the exact firmware `3.0.2` local-network profile and an
|
||||
exact topology for Bridge, Quick Connect or Direct Connect; the
|
||||
canonical bootstrap then requires a correlated live `DeviceInfo` match for
|
||||
model `LixelKity K1`, platform type `A4`, activation and firmware before START.
|
||||
Validate the current exact-match profile without device I/O with:
|
||||
|
|
@ -83,7 +85,18 @@ Validate the current exact-match profile without device I/O with:
|
|||
uv run python plugins/xgrids-k1/profile_loader.py
|
||||
```
|
||||
|
||||
Plugin v0.5.0 installs that reviewed transport behind explicit plugin actions.
|
||||
Plugin v0.6.0 retains the physically accepted v0.5.0 control transport and adds
|
||||
the connection matrix behind the existing explicit `network.provision` action.
|
||||
Bridge remains the default. Direct Connect sends the same single reviewed
|
||||
99-byte frame with credentials for an already-running controller hotspot. Quick
|
||||
Connect sends no BLE write: a short-lived Swift/CoreWLAN helper receives the
|
||||
operator-entered K1 AP credentials only over stdin, performs at most one scan
|
||||
and one association, and never receives an automatic retry. Mission Core then
|
||||
uses the observed K1 AP data-plane address. Automatic extraction of AP
|
||||
credentials from undocumented BLE data is deliberately not implemented.
|
||||
|
||||
Plugin v0.5.0 installed the reviewed application-control transport behind
|
||||
explicit plugin actions.
|
||||
The normal UI accepts the project name and one explicit launch confirmation.
|
||||
It then performs operations 1–6, operation 7 and operations 8–10 only after the
|
||||
previous response barrier succeeds, prepares local reception, and emits one
|
||||
|
|
|
|||
|
|
@ -6,15 +6,16 @@ generic application source tree.
|
|||
|
||||
The contribution contains:
|
||||
|
||||
- `K1ProvisioningPipeline` for power confirmation, BLE discovery and the
|
||||
reviewed Wi-Fi provisioning write;
|
||||
- `K1ProvisioningPipeline` for power confirmation, BLE discovery and the three
|
||||
explicit local connection directions: Bridge, Quick Connect and Direct
|
||||
Connect;
|
||||
- `K1AcquisitionPipeline` for explicit canonical connection/workspace/project/
|
||||
START checkpoints, local receiver preparation and compatibility file replay;
|
||||
- `K1SpatialControls` for an explicit no-retry STOP followed by the separate
|
||||
READY plus steady-green completion gate;
|
||||
- plugin-local diagnostics, metrics, API state, lifecycle mapping,
|
||||
observation-source mapping and scoped styles;
|
||||
- typed v0.5.0 interactive application-control state plus legacy shadow
|
||||
- typed v0.6.0 local-network and interactive application-control state plus legacy shadow
|
||||
inspection contracts;
|
||||
- `plugin.ts`, which binds the manifest `device.connection` component key to
|
||||
the runtime provider and connection view.
|
||||
|
|
|
|||
|
|
@ -4,14 +4,17 @@ This directory is the plugin-local, versioned compatibility vocabulary for
|
|||
verified K1 wire behavior. It is deliberately **not** a platform ontology and
|
||||
does not add runtime dependencies on NODE.DC Ontology Core.
|
||||
|
||||
The first profile is
|
||||
[`fw-3.0.2/direct-lan.v1.json`](fw-3.0.2/direct-lan.v1.json). It matches exactly:
|
||||
The active profile is
|
||||
[`fw-3.0.2/local-network.v2.json`](fw-3.0.2/local-network.v2.json). It matches exactly:
|
||||
|
||||
- model: XGRIDS LixelKity K1;
|
||||
- firmware: `3.0.2`;
|
||||
- topology: K1 and connector on the same owner-controlled LAN;
|
||||
- evidence scope: one physical scanner across controlled direct-LAN and
|
||||
owner-operated LixelGO/iPhone laboratory runs.
|
||||
- topology matrix: Bridge (`direct-lan`), Quick Connect (`device-ap`) and
|
||||
Direct Connect (`controller-hotspot`);
|
||||
- evidence scope: one physical scanner across Mission Core Bridge and
|
||||
owner-operated LixelGO/iPhone Quick Connect runs. The Direct Connect adapter
|
||||
reuses the same physically accepted 99-byte BLE Wi-Fi frame, but its complete
|
||||
Mission Core path still awaits a separate physical acceptance run.
|
||||
|
||||
It must not be applied to another firmware or treated as a vendor API claim.
|
||||
Unknown firmware fails closed.
|
||||
|
|
@ -63,14 +66,15 @@ The loader uses only the Python standard library and performs no device I/O:
|
|||
python plugins/xgrids-k1/profile_loader.py
|
||||
```
|
||||
|
||||
It verifies the exact firmware/topology scope, evidence vocabulary, source
|
||||
references, GATT UUIDs, MQTT subscribe-only boundary, channel evidence, camera
|
||||
RTSP/H.264 endpoints, operator-manual acquisition, and disabled vendor request
|
||||
mappings.
|
||||
It verifies the exact firmware/topology matrix, each mode's bounded network
|
||||
actions, evidence vocabulary, source references, GATT UUIDs, local MQTT
|
||||
boundary, channel evidence, camera RTSP/H.264 endpoints, operator-manual
|
||||
acquisition, and disabled descriptive-profile vendor request mappings.
|
||||
|
||||
## Evolution rules
|
||||
|
||||
1. A different firmware or topology gets a new profile file and profile ID.
|
||||
1. A different firmware or connection topology gets a new profile file and
|
||||
profile ID unless it is added through another evidence-backed schema revision.
|
||||
2. New evidence may only promote the flags supported by retained raw evidence,
|
||||
a documented decoder/replay check, or a physical lab report.
|
||||
3. Unknown fields remain explicit; they are never filled from naming or payload
|
||||
|
|
|
|||
Loading…
Reference in New Issue