96 lines
3.8 KiB
Markdown
96 lines
3.8 KiB
Markdown
# NDC XGRIDS K1 Connector
|
|
|
|
Pre-production research project for connecting an owner-controlled
|
|
XGRIDS/LixelKity K1 to a Mac without LixelGO, firmware changes, device opening,
|
|
or speculative writes.
|
|
|
|
Current status: repository scaffold and implementation plan. No command in the
|
|
repository currently writes to the K1, changes the router, or installs system
|
|
packages.
|
|
|
|
## Available stand
|
|
|
|
- one XGRIDS/LixelKity K1;
|
|
- one Apple Silicon MacBook running macOS;
|
|
- one ordinary TP-Link Deco/mesh network used by other devices;
|
|
- no LixelGO, phone, Linux host, dedicated AP, OpenWrt, or vendor SDK.
|
|
|
|
The ordinary router is sufficient for the first gates. We first observe the
|
|
existing LAN without changing it. A Guest/IoT SSID is optional and may be
|
|
counterproductive if Deco isolates clients; Mac and K1 must ultimately be able
|
|
to reach each other.
|
|
|
|
## What is actually being proved
|
|
|
|
The project has three independent gates:
|
|
|
|
1. K1 is operational and can record a project autonomously.
|
|
2. Mac can discover and inspect the K1 BLE/GATT surface safely.
|
|
3. Without LixelGO, K1 can be associated with Wi-Fi and a proprietary data
|
|
session can be opened.
|
|
|
|
Only after gate 3 do point-cloud, pose, status, and camera stream decoders become
|
|
meaningful implementation work. Local `map.las` and `poses.csv` prove internal
|
|
capabilities, not an externally accessible network format.
|
|
|
|
## Local environment
|
|
|
|
The project uses Python 3.12 in a repository-local `.venv` managed by `uv`.
|
|
This does not install Python packages globally and does not modify neighboring
|
|
repositories.
|
|
|
|
```bash
|
|
cd /Users/dcconstructions/Downloads/mnt/NODEDC/NDC_xgrids-k1-connector
|
|
uv sync --group dev
|
|
uv run k1link doctor
|
|
uv run pytest
|
|
```
|
|
|
|
`doctor` is intentionally non-invasive. It checks the local Python environment
|
|
and reports external tools; it does not request Bluetooth permission, scan the
|
|
LAN, touch the K1, alter Homebrew, or change capture permissions.
|
|
|
|
The currently implemented laboratory commands are:
|
|
|
|
```bash
|
|
uv run k1link ble scan --duration 30 --out sessions/<id>/captures/ble.json
|
|
uv run k1link ble gatt-dump --device <corebluetooth-uuid> \
|
|
--out sessions/<id>/captures/gatt.json
|
|
uv run k1link net snapshot --out sessions/<id>/captures/network.json
|
|
```
|
|
|
|
On macOS the scan is active CoreBluetooth discovery, but it does not connect to
|
|
or modify devices. `gatt-dump` connects and performs service discovery only; it
|
|
does not read characteristic values, subscribe to notifications or write
|
|
configuration. Session output is sensitive and ignored by Git.
|
|
|
|
## Documentation
|
|
|
|
- [Technical audit](docs/00_TECHNICAL_AUDIT.md)
|
|
- [Implementation gates](docs/01_IMPLEMENTATION_PLAN.md)
|
|
- [First lab runbook](docs/02_FIRST_LAB_RUNBOOK.md)
|
|
- [Artifact and secret policy](docs/03_ARTIFACT_POLICY.md)
|
|
- [Session manifest schema](schemas/session-manifest.schema.json)
|
|
- [Reference input provenance](docs/reference/README.md)
|
|
|
|
The two supplied source documents are retained unchanged under
|
|
`docs/reference/`. Corrections and decisions are recorded separately so their
|
|
provenance remains clear.
|
|
|
|
## Safety boundary
|
|
|
|
Allowed initial work is non-mutating discovery, standard device-information reads,
|
|
controlled notification listening, autonomous button operation, targeted
|
|
capture of traffic to or from the confirmed K1 address, and offline analysis of
|
|
owned artifacts.
|
|
|
|
BLE writes, provisioning, application-session packets, active service probes,
|
|
and router configuration changes require evidence and an explicit reviewed
|
|
step. Random writes, fuzzing, brute force, firmware operations, destructive file
|
|
access, and credential guessing are out of scope.
|
|
|
|
Real captures, projects, router metadata, serials, credentials, maps, images,
|
|
and logs are ignored by normal Git. Redacted manifests and SHA-256 inventories
|
|
are committed; encrypted artifact storage will be selected only when real data
|
|
exists.
|