chore: initialize K1 connector pre-production scaffold
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,188 @@
|
||||
# Implementation plan
|
||||
|
||||
This plan supersedes the app-dependent experiment order in the reference Bible.
|
||||
Each gate produces evidence and an explicit GO, PAUSE or BLOCKED result.
|
||||
|
||||
## Stage 0 — repository and host baseline
|
||||
|
||||
Deliverables:
|
||||
|
||||
- local Python 3.12 `.venv` and lock-file;
|
||||
- `k1link doctor` with no side effects;
|
||||
- immutable reference documents and checksums;
|
||||
- safety policy, artifact policy, session manifest schema;
|
||||
- no Homebrew changes and no K1 interaction.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- `uv sync --group dev` succeeds;
|
||||
- `uv run k1link doctor` identifies a local `.venv`;
|
||||
- tests, Ruff and mypy pass;
|
||||
- repository contains no secrets or real captures.
|
||||
|
||||
## Gate 1 — physical and USB baseline
|
||||
|
||||
Code needed: none initially.
|
||||
|
||||
Actions:
|
||||
|
||||
1. Record masked device identity, LED boot sequence, battery and visible state.
|
||||
2. Determine whether the unit is activated; solid-yellow or an activation prompt
|
||||
is treated as a distinct blocker.
|
||||
3. Run one short autonomous button scan: start, keep still for at least 20 seconds,
|
||||
move through a simple scene, stop.
|
||||
4. Enter USB mode using the documented physical shortcut if available.
|
||||
5. Copy a project tree and selected metadata/logs into an ignored session path.
|
||||
6. Hash every copied file and create a redacted manifest.
|
||||
|
||||
GO: the unit boots normally and records a usable autonomous project.
|
||||
|
||||
PAUSE: USB access is unavailable but the scan succeeds; continue BLE while
|
||||
documenting the missing ground truth.
|
||||
|
||||
STOP: serious fault, overheating, activation lock, or destructive/ambiguous
|
||||
device state.
|
||||
|
||||
## Stage 1 — BLE read-only toolkit
|
||||
|
||||
Minimal dependencies: `bleak` plus the existing CLI stack. Add them only in the
|
||||
repository-local environment.
|
||||
|
||||
Commands:
|
||||
|
||||
```text
|
||||
k1link ble scan
|
||||
k1link ble gatt-dump
|
||||
k1link ble listen
|
||||
```
|
||||
|
||||
Requirements:
|
||||
|
||||
- preserve advertisement snapshots, manufacturer/service data and RSSI;
|
||||
- identify by observed name + macOS UUID + advertisement fingerprint;
|
||||
- inspect standby, scanning and USB states separately;
|
||||
- start with standard Device Information/Battery services;
|
||||
- custom characteristic reads are opt-in because proprietary reads may have
|
||||
side effects;
|
||||
- notifications are subscribed one characteristic at a time and logged to
|
||||
timestamped JSONL;
|
||||
- no arbitrary characteristic or provisioning writes in this stage. Enabling a
|
||||
notification normally updates the standard CCCD descriptor; this temporary,
|
||||
reversible protocol write is disclosed and handled separately from device
|
||||
configuration.
|
||||
|
||||
GO: reproducible K1 advertisement and useful GATT map.
|
||||
|
||||
PAUSE: permission or pairing/authentication is required.
|
||||
|
||||
## Gate 2 — existing network behavior
|
||||
|
||||
Do not change Deco settings first.
|
||||
|
||||
Actions:
|
||||
|
||||
1. Save the Mac interface and route table.
|
||||
2. Observe router client list and Mac ARP/neighbor state with K1 off.
|
||||
3. Repeat after K1 boot, during standby, scanning and after one power cycle.
|
||||
4. Check for new Wi-Fi SSIDs exposed by K1 without attempting to join unknown
|
||||
networks automatically.
|
||||
5. Confirm any candidate by disappearance/reappearance with K1 power state.
|
||||
|
||||
GO-A: K1 joins a remembered LAN. Provisioning leaves the immediate critical
|
||||
path and work moves to the application-session gate.
|
||||
|
||||
GO-B: K1 exposes its own AP. Document it as a separate topology and determine
|
||||
whether Mac can join without modifying router configuration.
|
||||
|
||||
BLOCKED: neither association nor AP exists; provisioning becomes Stage 2.
|
||||
|
||||
## Stage 2 — no-app provisioning research
|
||||
|
||||
This stage answers whether SSID/PSK can be sent safely from Mac. A generic BLE
|
||||
transport does not define the vendor payload.
|
||||
|
||||
Evidence sources allowed before a write:
|
||||
|
||||
- GATT UUIDs, properties and descriptors;
|
||||
- standard service identification;
|
||||
- read/notify state transitions correlated with network state;
|
||||
- owned K1 project logs and metadata;
|
||||
- public official firmware/documentation static evidence if separately reviewed;
|
||||
- deterministic structure inferred without sending device mutations.
|
||||
|
||||
Before enabling any write profile, document:
|
||||
|
||||
- exact service/characteristic and required security mode;
|
||||
- packet framing, encoding, ordering and length rules;
|
||||
- SSID/PSK redaction and secure input path;
|
||||
- checksum, nonce, token, certificate or signature fields;
|
||||
- commit/connect command and status response;
|
||||
- timeout, failure state, power-cycle behavior and rollback;
|
||||
- one explicit confirmation flag in addition to a named reviewed profile.
|
||||
|
||||
GO: a deterministic provisioning profile exists with an explained expected
|
||||
state transition and safe rollback.
|
||||
|
||||
HARD BLOCK: K1 knows no network, exposes only opaque vendor GATT, and no evidence
|
||||
source reveals the protocol. Random writes are not an alternative.
|
||||
|
||||
## Stage 3 — application session and targeted capture
|
||||
|
||||
Prerequisite: confirmed K1 IP or direct AP topology.
|
||||
|
||||
Implementation order:
|
||||
|
||||
1. Passive ARP/mDNS/SSDP and K1-filtered `tcpdump` baseline.
|
||||
2. Small targeted TCP connect check against the confirmed IP.
|
||||
3. Service detection only where the prior step supplies evidence.
|
||||
4. Parse K1 logs for daemon names, ports and protocol strings.
|
||||
5. Add protocol-specific connection attempts only for demonstrated endpoints.
|
||||
6. Model `WIFI_ASSOCIATED_BUT_NO_DATA_SESSION` explicitly.
|
||||
|
||||
`k1link net capture` must show the exact interface/filter, request privilege in
|
||||
the foreground, handle Ctrl+C, and never configure persistent `sudo` or ChmodBPF.
|
||||
|
||||
GO: Mac becomes a K1 endpoint or receives a reproducible scan-correlated flow.
|
||||
|
||||
BLOCKED: application session requires an unavailable mutual-auth token,
|
||||
certificate or undocumented handshake.
|
||||
|
||||
## Stage 4 — session artifacts and flow analysis
|
||||
|
||||
Implement only after real traffic exists:
|
||||
|
||||
- versioned session manifest;
|
||||
- UTC and monotonic timeline events;
|
||||
- SHA-256 inventory;
|
||||
- TCP reassembly and UDP flow grouping;
|
||||
- packet/byte rates, length histograms, entropy and first-byte fingerprints;
|
||||
- idle versus scanning correlation;
|
||||
- negative-control flows to reduce false positives.
|
||||
|
||||
GO: repeatable flows can be separated and ranked without losing raw evidence.
|
||||
|
||||
## Stage 5 — decoders by evidence priority
|
||||
|
||||
Priority:
|
||||
|
||||
1. device/scan status;
|
||||
2. point-cloud preview;
|
||||
3. pose/trajectory;
|
||||
4. camera/panorama/video.
|
||||
|
||||
Add dependencies per decoder extra, not to the base environment. Point-cloud
|
||||
and video signature probes operate on reassembled flows, not isolated packet
|
||||
payloads. A candidate becomes a decoder only after a controlled physical test
|
||||
confirms it.
|
||||
|
||||
MVP GO: K1-to-Mac scan-correlated data can be captured reliably and at least one
|
||||
useful stream is decoded or structurally identified.
|
||||
|
||||
## Deferred work
|
||||
|
||||
- ROS2/MCAP bridge;
|
||||
- onboard computer and drone integration;
|
||||
- automated scan-button electronics;
|
||||
- OpenWrt/monitor-mode infrastructure;
|
||||
- firmware or internal-Linux analysis;
|
||||
- camera branch if no external frame stream is evidenced.
|
||||
Reference in New Issue
Block a user