chore: initialize K1 connector pre-production scaffold
This commit is contained in:
DCCONSTRUCTIONS
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,134 @@
|
||||
# First lab runbook
|
||||
|
||||
Purpose: gather decisive evidence using only K1, the current MacBook and the
|
||||
existing TP-Link Deco/mesh network. This runbook contains no BLE writes, router
|
||||
changes, broad LAN scans or system package installation.
|
||||
|
||||
## Before powering K1
|
||||
|
||||
- Place K1 on a stable, ventilated surface.
|
||||
- Prepare its normal battery/charger and a known data-capable USB cable.
|
||||
- Ensure enough Mac disk space for one copied project and short captures.
|
||||
- Do not expose the Wi-Fi password in notes, terminal arguments or screenshots.
|
||||
- If the router model becomes visible in the Deco UI, record only the model and
|
||||
operating mode; do not change settings yet.
|
||||
|
||||
Create an ignored session directory outside ordinary Git, for example:
|
||||
|
||||
```text
|
||||
sessions/20260715T120000Z_gate1_baseline/
|
||||
```
|
||||
|
||||
The operator notes should use masked serials and relative timestamps.
|
||||
|
||||
## Experiment A — boot and activation state
|
||||
|
||||
1. Start a phone/Mac video focused on the LED if convenient.
|
||||
2. Power K1 on normally.
|
||||
3. Record LED colors and durations until stable.
|
||||
4. Record whether the final state is normal standby, activation warning or fault.
|
||||
5. Stop immediately on serious fault, unusual heat, smell, battery problem or
|
||||
undocumented state.
|
||||
|
||||
Expected output: `notes.md`, optional local video, and a redacted manifest.
|
||||
|
||||
## Experiment B — autonomous project
|
||||
|
||||
1. From normal standby, start scanning with the documented double-click.
|
||||
2. Keep K1 completely still for at least 20 seconds.
|
||||
3. Move slowly through a simple scene for about one minute.
|
||||
4. Stop scanning with the documented double-click and wait for stable standby.
|
||||
5. Enter USB mode using the physical shortcut only if its state is understood.
|
||||
6. Copy the project tree, `project.json`, `poses.csv`, `map.las` metadata and logs
|
||||
when present. Raw project data remains ignored and local.
|
||||
7. Generate a SHA-256 inventory; commit only a redacted report later.
|
||||
|
||||
Decision:
|
||||
|
||||
- GO if a valid autonomous project exists.
|
||||
- PAUSE USB analysis if recording works but USB is unavailable.
|
||||
- STOP on activation lock or device fault.
|
||||
|
||||
## Experiment C — passive BLE surface
|
||||
|
||||
Prerequisite: Stage 1 BLE commands implemented and reviewed.
|
||||
|
||||
1. Run a 30-second scan in standby.
|
||||
2. Save advertisement and manufacturer/service data.
|
||||
3. Connect for service discovery without writes.
|
||||
4. Read standard device-information/battery characteristics first.
|
||||
5. Repeat advertisement/GATT observation during scanning and USB mode.
|
||||
6. Subscribe to an individually selected notify/indicate characteristic only
|
||||
after its properties are recorded.
|
||||
|
||||
Decision:
|
||||
|
||||
- GO if K1 has a reproducible BLE identity and observable surface.
|
||||
- PAUSE if macOS asks for pairing/authentication that cannot be completed.
|
||||
|
||||
## Experiment D — current network, no router changes
|
||||
|
||||
1. Capture the Mac route/interface and its current neighbor table with K1 off.
|
||||
2. Note the Deco client list if accessible.
|
||||
3. Boot K1 and repeat in standby.
|
||||
4. Repeat during a button scan.
|
||||
5. Power-cycle K1 and confirm whether any candidate disappears/reappears.
|
||||
6. Check visible SSIDs for a K1-associated AP.
|
||||
|
||||
Do not infer identity from one unknown LAN client. Require power-state
|
||||
correlation or an independent device fingerprint.
|
||||
|
||||
Decision:
|
||||
|
||||
- remembered-LAN GO: confirmed K1 address appears;
|
||||
- device-AP GO: a repeatable K1 SSID appears;
|
||||
- provisioning BLOCKED: neither appears and no known GATT provisioning profile
|
||||
exists.
|
||||
|
||||
## About Guest/IoT networks on Deco
|
||||
|
||||
Do not create one during this first run. Depending on Deco model and Router/AP
|
||||
mode, Guest/IoT networks may isolate clients from the main LAN or from each
|
||||
other. A later dedicated SSID is useful only if both K1 and Mac can communicate
|
||||
and its password can be entered through a known provisioning profile.
|
||||
|
||||
## Minimum lab report
|
||||
|
||||
```markdown
|
||||
# K1 Lab Report 001
|
||||
|
||||
## Host
|
||||
macOS:
|
||||
Mac model/architecture:
|
||||
Router model/mode (if known):
|
||||
|
||||
## Device
|
||||
Model:
|
||||
Serial suffix only:
|
||||
Activation/LED state:
|
||||
Firmware evidence:
|
||||
|
||||
## Autonomous scan
|
||||
Start/stop behavior:
|
||||
Project created:
|
||||
USB accessible:
|
||||
Files observed:
|
||||
|
||||
## BLE
|
||||
Advertised name:
|
||||
macOS UUID: [redacted]
|
||||
Service fingerprint:
|
||||
Pairing/auth prompts:
|
||||
|
||||
## Network
|
||||
Remembered LAN candidate:
|
||||
Device AP candidate:
|
||||
Confirmed K1 IP: [redacted]
|
||||
|
||||
## Decision
|
||||
Current gate:
|
||||
GO / PAUSE / BLOCKED:
|
||||
Evidence:
|
||||
Next smallest experiment:
|
||||
```
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# Artifact and secret policy
|
||||
|
||||
The experiment should be reproducible from Git without placing household
|
||||
credentials, spatial maps or device secrets into normal Git history.
|
||||
|
||||
## Sensitive by default
|
||||
|
||||
- Wi-Fi SSID and PSK;
|
||||
- full K1 serial, BLE UUID, MAC/IP addresses and router client lists;
|
||||
- provisioning payloads, tokens, nonces, certificates and session keys;
|
||||
- PCAP/PCAPNG, Bluetooth logs and extracted flows;
|
||||
- K1 logs, `project.json`, `.xbin`, LAS/point clouds and trajectories;
|
||||
- camera frames, previews, panoramas and mapped interiors;
|
||||
- command lines or shell history containing a credential.
|
||||
|
||||
Private Git is still durable replicated storage. Git LFS changes storage and
|
||||
size behavior; it does not provide confidentiality.
|
||||
|
||||
## Commit to normal Git
|
||||
|
||||
- source, tests and lock-file;
|
||||
- immutable reference documents and their hashes;
|
||||
- schemas, runbooks, ADRs and redacted reports;
|
||||
- synthetic or explicitly redacted fixtures;
|
||||
- redacted manifests and SHA-256 inventories;
|
||||
- commands needed to reproduce analysis from a locally supplied artifact.
|
||||
|
||||
## Keep outside normal Git
|
||||
|
||||
- `.venv`, local config and Keychain references;
|
||||
- actual credentials;
|
||||
- real captures and decoded output;
|
||||
- complete K1 project copies;
|
||||
- unredacted device and router metadata.
|
||||
|
||||
## Session integrity
|
||||
|
||||
Every real session should record:
|
||||
|
||||
- schema version and unique session ID;
|
||||
- tool Git commit;
|
||||
- UTC start/end and Mac monotonic start/end;
|
||||
- masked device/host/network identities;
|
||||
- physical state timeline;
|
||||
- exact capture filter and interface;
|
||||
- artifact path, size and SHA-256;
|
||||
- redaction status and storage location classification;
|
||||
- operator notes and final GO/PAUSE/BLOCKED decision.
|
||||
|
||||
Raw artifacts are never silently deleted by code. That does not imply infinite
|
||||
retention: capacity, encryption, backup and deliberate deletion policy are an
|
||||
operator decision outside the capture command.
|
||||
|
||||
## Future provisioning secret input
|
||||
|
||||
The Wi-Fi password must not be accepted as a normal CLI argument. A reviewed
|
||||
provisioner should use a hidden prompt, stdin/file descriptor with strict
|
||||
permissions, or macOS Keychain. Logs and manifests record only that a credential
|
||||
was supplied, never its value or unredacted payload bytes.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# ADR 0001: Treat LixelGO as unavailable
|
||||
|
||||
Status: accepted.
|
||||
|
||||
## Context
|
||||
|
||||
The actual stand consists of one K1, one MacBook and one ordinary TP-Link
|
||||
Deco/mesh router. There is no phone, LixelGO reference session, Linux host,
|
||||
dedicated capture router or public SDK.
|
||||
|
||||
The supplied design documents include several app-dependent experiments and
|
||||
assume that provisioning payloads can be recovered by comparing LixelGO BLE
|
||||
writes. That evidence source does not exist.
|
||||
|
||||
## Decision
|
||||
|
||||
- LixelGO is not a temporary dependency, broker or test oracle.
|
||||
- App-dependent experiments remain only as historical reference.
|
||||
- The active critical path is physical baseline, passive BLE, remembered Wi-Fi
|
||||
or device AP, evidence-led provisioning, application-session discovery, then
|
||||
stream capture and decoding.
|
||||
- A fully opaque provisioning protocol with no evidence source is reported as a
|
||||
hard black-box blocker rather than approached with random writes.
|
||||
- The existing router is used without changes for the first observation gate.
|
||||
|
||||
## Consequences
|
||||
|
||||
The project may reach a legitimate BLOCKED result before receiving live data.
|
||||
This is still a successful pre-production conclusion because it identifies the
|
||||
exact missing interface and prevents premature decoder work or risky device
|
||||
mutation.
|
||||
|
||||
@@ -0,0 +1,220 @@
|
||||
# Codex prompt: k1-mac-link
|
||||
|
||||
Ты работаешь над проектом `k1-mac-link`.
|
||||
|
||||
## Контекст
|
||||
|
||||
Есть официальный XGRIDS / LixelKity K1, MacBook, Wi-Fi router. Linux как отдельного стенда нет. Цель - использовать K1 как black-box realtime computer vision sensor без модификации firmware и без вскрытия на первом этапе.
|
||||
|
||||
Нужны realtime/cached данные:
|
||||
|
||||
- point cloud / preview cloud;
|
||||
- pose / trajectory / odometry-like stream, если есть;
|
||||
- camera / panoramic preview / RGB stream, если есть;
|
||||
- device status;
|
||||
- raw packets для reverse engineering.
|
||||
|
||||
Не нужно в runtime:
|
||||
|
||||
- считать LAS;
|
||||
- считать LCC;
|
||||
- считать Gaussian splats;
|
||||
- менять firmware;
|
||||
- делать brute force;
|
||||
- слать random BLE writes.
|
||||
|
||||
## Главная архитектура
|
||||
|
||||
Официальные мануалы K1 показывают такую модель:
|
||||
|
||||
- BLE используется для discovery/provisioning;
|
||||
- SSID/password - это реквизиты нашей Wi-Fi сети;
|
||||
- после подключения к Wi-Fi есть отдельный `data connection status`;
|
||||
- K1 умеет автономно стартовать scanning double-click кнопкой;
|
||||
- K1 пишет `map.las` как realtime point cloud output, но downsampled;
|
||||
- K1 пишет `poses.csv` как trajectory recorded during scanning;
|
||||
- K1 содержит 2 panoramic cameras и 360 deg LiDAR;
|
||||
- live camera stream наружу не доказан, его надо искать экспериментально.
|
||||
|
||||
## Создай проект
|
||||
|
||||
Python 3.12, macOS-first, Typer CLI.
|
||||
|
||||
Структура:
|
||||
|
||||
```text
|
||||
k1-mac-link/
|
||||
README.md
|
||||
pyproject.toml
|
||||
docs/
|
||||
src/k1link/
|
||||
cli.py
|
||||
config.py
|
||||
logging.py
|
||||
artifacts.py
|
||||
ble/
|
||||
scanner.py
|
||||
gatt_dump.py
|
||||
listener.py
|
||||
provisioner.py
|
||||
net/
|
||||
discover.py
|
||||
ports.py
|
||||
capture.py
|
||||
mdns.py
|
||||
tshark.py
|
||||
analysis/
|
||||
pcap_summary.py
|
||||
flow_classifier.py
|
||||
payload_extract.py
|
||||
payload_fingerprint.py
|
||||
protocol_diff.py
|
||||
pointcloud_probe.py
|
||||
video_probe.py
|
||||
timeline.py
|
||||
decode/
|
||||
pointcloud.py
|
||||
pose.py
|
||||
video.py
|
||||
status.py
|
||||
cache/
|
||||
writer.py
|
||||
manifest.py
|
||||
raw_stream.py
|
||||
export/
|
||||
ply.py
|
||||
pcd.py
|
||||
npz.py
|
||||
frames.py
|
||||
tests/
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
bleak
|
||||
typer
|
||||
rich
|
||||
pydantic
|
||||
pydantic-settings
|
||||
loguru
|
||||
pyshark
|
||||
scapy
|
||||
construct
|
||||
numpy
|
||||
pandas
|
||||
opencv-python
|
||||
open3d
|
||||
pillow
|
||||
zeroconf
|
||||
ifaddr
|
||||
psutil
|
||||
pytest
|
||||
pytest-asyncio
|
||||
ruff
|
||||
mypy
|
||||
```
|
||||
|
||||
## CLI commands
|
||||
|
||||
Implement:
|
||||
|
||||
```bash
|
||||
k1link doctor
|
||||
k1link ble scan --duration 30 --out captures/ble_scan.json
|
||||
k1link ble gatt-dump --device <macos_uuid> --out captures/gatt_dump.json
|
||||
k1link ble listen --device <macos_uuid> --duration 120 --out captures/ble_notifications.jsonl
|
||||
k1link net discover --subnet 192.168.1.0/24 --out captures/net_discover.json
|
||||
k1link net ports --ip <K1_IP> --out captures/ports.json
|
||||
k1link net capture --iface en0 --host <K1_IP> --out captures/session.pcap
|
||||
k1link analyze summarize --pcap captures/session.pcap --out captures/session_summary.json
|
||||
k1link analyze extract-flows --pcap captures/session.pcap --out-dir captures/flows
|
||||
k1link analyze fingerprint --flows captures/flows --out captures/fingerprint.json
|
||||
k1link analyze pointcloud-probe --flows captures/flows --out-dir captures/pointcloud_candidates
|
||||
k1link analyze video-probe --flows captures/flows --out-dir captures/video_candidates
|
||||
```
|
||||
|
||||
## Safety rules
|
||||
|
||||
Allowed by default:
|
||||
|
||||
- BLE scan;
|
||||
- GATT discovery;
|
||||
- read characteristics;
|
||||
- notifications;
|
||||
- network discovery;
|
||||
- port scanning of owned device;
|
||||
- tcpdump capture;
|
||||
- pcap analysis.
|
||||
|
||||
Forbidden by default:
|
||||
|
||||
- BLE write;
|
||||
- random fuzzing;
|
||||
- brute force;
|
||||
- firmware upload;
|
||||
- deleting/modifying K1 files;
|
||||
- SSH/ADB login attempts.
|
||||
|
||||
Any BLE write must require:
|
||||
|
||||
```bash
|
||||
--i-understand-this-writes-to-device
|
||||
```
|
||||
|
||||
Provisioner stays NotImplemented until a known payload profile is manually added.
|
||||
|
||||
## Outputs
|
||||
|
||||
Every session creates:
|
||||
|
||||
```text
|
||||
session_manifest.json
|
||||
notes.md
|
||||
captures/*.pcap
|
||||
captures/*.json
|
||||
flows/*.bin
|
||||
flows/*.jsonl
|
||||
analysis/*.json
|
||||
decoded/pointcloud/*
|
||||
decoded/video/*
|
||||
decoded/pose/*
|
||||
```
|
||||
|
||||
Raw captures are never deleted.
|
||||
|
||||
## Implement pointcloud probe
|
||||
|
||||
Try:
|
||||
|
||||
- float32 little-endian XYZ;
|
||||
- offsets 0..128;
|
||||
- strides 12, 16, 20, 24, 28, 32, 40, 48;
|
||||
- scaled int16/int32 fallback;
|
||||
- score finite ratio, coordinate range, variance, temporal continuity;
|
||||
- export PLY/NPZ for top candidates.
|
||||
|
||||
## Implement video probe
|
||||
|
||||
Detect/extract:
|
||||
|
||||
- JPEG FF D8 FF ... FF D9;
|
||||
- PNG signature;
|
||||
- H264/H265 Annex B;
|
||||
- MP4 ftyp/moof/mdat;
|
||||
- RTSP/RTP;
|
||||
- MJPEG;
|
||||
- WebSocket binary large frames.
|
||||
|
||||
Try ffmpeg/OpenCV extraction where possible.
|
||||
|
||||
## README must include
|
||||
|
||||
- macOS setup;
|
||||
- Wireshark ChmodBPF note;
|
||||
- Bluetooth permission note;
|
||||
- Bleak macOS UUID caveat;
|
||||
- K1 lab network setup;
|
||||
- experiment flow: idle capture, button scan capture, app scan capture, camera perturbation, point cloud perturbation.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Reference inputs
|
||||
|
||||
These files are immutable copies of the user-supplied pre-production material.
|
||||
They are retained as inputs, not treated as verified specifications.
|
||||
|
||||
| File | SHA-256 | Role |
|
||||
|---|---|---|
|
||||
| `CODEX_K1_MAC_LINK_PREPROD_PROMPT.md` | `f24537119bd76f76d1914ca7f34a6736d8c5d3b6d19ead6d0ae8a0e5966c9770` | Requested project shape and CLI scope |
|
||||
| `XGRIDS_Lixel_K1_PreProduction_Bible.md` | `22ea9d0dc6f5a623ba26d6f08108a905170db08112e0531a1d80bddd6101689c` | OSINT dossier, hypotheses, experiments and long-form design |
|
||||
|
||||
Important contextual correction: the actual stand has no LixelGO and no mobile
|
||||
device. All experiments in the source documents that require an app or a
|
||||
reference app session are unavailable. The active plan is therefore defined by
|
||||
`docs/01_IMPLEMENTATION_PLAN.md`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user