chore: initialize K1 connector pre-production scaffold

2026-07-15 15:05:18 +03:00
commit 4c401bc59b
23 changed files with 4232 additions and 0 deletions
@@ -0,0 +1,158 @@
+# Technical audit
+
+Status: pre-production planning, 2026-07-15.
+
+## Executive finding
+
+The project is feasible as a disciplined black-box investigation, but the
+existence of a complete K1-to-Mac realtime link is not yet established. The
+first hard problem is not decoding points or images. It is bootstrapping the K1
+from BLE availability into Wi-Fi association and then opening the proprietary
+application data session without LixelGO.
+
+The supplied Bible is useful as an OSINT dossier. It is not an executable plan
+for the actual stand because many experiments assume a phone and LixelGO. The
+implementation must proceed through explicit gates and stop before speculative
+writes.
+
+## Evidence classes
+
+### Version-scoped facts to verify on the physical unit
+
+- K1 has LiDAR, panoramic cameras, onboard compute, BLE and Wi-Fi.
+- Official workflows use BLE before Wi-Fi network/data connection.
+- Autonomous scan start/stop by the physical button is documented.
+- A scan project may contain local `map.las`, `poses.csv`, `project.json`, logs,
+  preview/model and raw sensor artifacts depending on firmware and settings.
+- macOS exposes a CoreBluetooth device UUID rather than a portable hardware MAC.
+- A normal switched/mesh LAN does not mirror arbitrary client-to-client unicast
+  to the Mac, but the Mac can capture its own future K1 session completely.
+
+Each of these remains scoped to the actual firmware/hardware state observed in
+the lab. The physical unit is authoritative.
+
+### Strong hypotheses
+
+- BLE is the bootstrap/control plane and Wi-Fi is the likely high-rate data
+  plane.
+- The user-provided SSID and PSK are transported inside a vendor-defined GATT
+  protocol.
+- The application may need a second token, certificate, handshake, or stream
+  subscription after ordinary Wi-Fi association.
+- The externally exposed point cloud is more likely a processed/downsampled
+  preview than raw LiDAR packets.
+
+XGRIDS provides stronger product evidence for an external point-cloud path than
+the local LAS alone: current LixelStudio materials describe K1 remote control
+and realtime point-cloud streaming over USB/Wi-Fi. LixelStudio is Windows-only
+and this does not disclose or guarantee access to the protocol from macOS. It
+does, however, justify keeping realtime point cloud as the primary stream target.
+No comparable official evidence proves an exportable raw panorama/camera stream.
+
+### Unsupported until measured
+
+- K1 remembers an existing Wi-Fi profile.
+- K1 exposes its own access point.
+- Provisioning fields are plain UTF-8, JSON, TLV, CBOR, or protobuf.
+- A writable GATT characteristic can be used without bonding or an app token.
+- Local `map.las` layout resembles the network stream.
+- Live pose or camera frames leave the device.
+- A point stream contains simple float32 XYZ tuples.
+- Network payloads are unencrypted.
+
+## Major corrections to the source plan
+
+1. Experiments requiring LixelGO are removed from the active critical path.
+   There will be no app-session capture, provisioning diff, app-start comparison,
+   or temporary broker mode.
+2. The first go/no-go is device activation and autonomous operation. An
+   unactivated unit may be a hard blocker before BLE provisioning is relevant.
+3. Provisioning is not implemented merely because a characteristic is writable.
+   We need target UUID, framing, field encoding, ordering, integrity/auth fields,
+   connect/commit semantics, status response, and rollback.
+4. Wi-Fi association and application data session are modeled as separate
+   states. Obtaining an IP is not success for the realtime connector.
+5. `tcpdump` does not create a stream. A useful capture requires either K1 to
+   initiate traffic or Mac to become the authenticated/subscribed endpoint.
+6. Full port/version/UDP scans are active operations, not passive safe defaults.
+   Discovery begins with power on/off diffs, router client list, ARP and
+   broadcast/multicast observations, then targets only the confirmed K1 IP.
+7. Heavy packages are deferred. OpenCV, Open3D, pandas, Scapy, PyShark and NumPy
+   are not prerequisites for proving bootstrap connectivity.
+8. Wi-Fi passwords must never be CLI arguments. Future provisioning will use a
+   hidden interactive prompt or macOS Keychain and must redact payloads.
+
+## Router audit
+
+The existing TP-Link Deco/mesh router is adequate for the initial work. No
+router setting needs to change before the first observations.
+
+We need only DHCP, a shared reachable network, and ideally a way to view the
+client list. Band steering and a single combined SSID are acceptable. A separate
+Guest/IoT SSID is optional; on some Deco modes it isolates clients, which would
+prevent Mac-to-K1 traffic. If a separate SSID is later used, peer-to-peer reachability
+must be tested before provisioning K1 onto it.
+
+The main-LAN fallback is acceptable for a narrow, target-filtered experiment.
+It must not include a broad scan or unfiltered capture of household traffic.
+
+## Environment audit
+
+Observed host baseline:
+
+- Apple Silicon (`arm64`);
+- macOS 26.5.1;
+- `uv` and Homebrew present;
+- system Python is 3.13.5, while the project requires 3.12;
+- `tcpdump` and `ffmpeg` present;
+- `tshark` and `nmap` not currently found.
+- the current default route is a VPN tunnel (`utun`), while Wi-Fi is `en0`.
+
+The project therefore pins Python 3.12 via `.python-version`; `uv` creates a
+local `.venv`. Nothing in setup installs global Python packages. Missing external
+network-analysis tools are reported by `k1link doctor` and are not installed
+until their gate requires them and the change is explicitly accepted.
+Future network commands must determine the route for the confirmed K1 IP;
+neither the default route nor `en0` may be hardcoded.
+
+## Primary blockers
+
+| Gate | Blocking condition | Meaning |
+|---|---|---|
+| Device | fault, activation lock, no autonomous project | Stop before networking |
+| BLE | no advertisement or only inaccessible/authenticated surface | Investigate state/permissions before writes |
+| Wi-Fi | no remembered network/AP and opaque custom GATT | Provisioning research is the hard block |
+| Data session | IP exists but service requires unknown token/handshake | Association succeeded; connector has not |
+| Streams | session opens but no useful external stream | Realtime goal may be unsupported |
+| Camera | point cloud works but frames never appear | Camera branch may be unsupported; not an MVP failure |
+
+## Implementation consequence
+
+The correct order is:
+
+```text
+device baseline
+  -> autonomous project + USB metadata
+  -> passive BLE surface
+  -> remembered Wi-Fi / device AP check
+  -> evidence-led provisioning gate
+  -> application-session gate
+  -> targeted capture
+  -> flow classification
+  -> point cloud / pose / status / optional camera decoders
+```
+
+## Verified primary references
+
+- [XGRIDS K1 firmware and release notes](https://www.xgrids.com/intl/support/download?page=K1)
+- [XGRIDS LixelStudio](https://www.xgrids.com/intl/lixelstudio)
+- [XGRIDS LixelStudio releases](https://www.xgrids.com/intl/support/download?page=LixelStudio)
+- [XGRIDS device activation and connection](https://docs.xgrids.com/en-us/02-lingguang-k/01-lingguang-k1/v2.4.0/03-device-activation-and-connection.html)
+- [Apple packet-trace guidance](https://developer.apple.com/documentation/network/recording-a-packet-trace)
+- [Bleak macOS backend](https://bleak.readthedocs.io/en/latest/backends/macos.html)
+- [TP-Link Deco Guest Network behavior](https://www.tp-link.com/ca/support/faq/1460/)
+- [TP-Link Deco IoT Network](https://www.tp-link.com/us/support/faq/4420/)
+- [uv project environments](https://docs.astral.sh/uv/guides/projects/)
+
+Reference-document statements not independently repeated here remain inputs or
+hypotheses, not verified conclusions of this audit.