feat(device-plugins): add profiled K1 lifecycle and canonical data plane
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,70 @@
|
||||
# XGRIDS K1 compatibility profiles
|
||||
|
||||
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:
|
||||
|
||||
- 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.
|
||||
|
||||
It must not be applied to another firmware or treated as a vendor API claim.
|
||||
Unknown firmware fails closed.
|
||||
|
||||
## Evidence flags
|
||||
|
||||
Every transport, data channel, and semantic action uses five independent
|
||||
boolean flags:
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `observed` | Directly seen on the owner-controlled K1 |
|
||||
| `decoded` | A bounded semantic decoder exists for observed bytes |
|
||||
| `replay_verified` | Captured semantic data passed the replay-to-view path |
|
||||
| `physical_verified` | Correlated with a controlled physical state/action |
|
||||
| `write_enabled` | The profile grants emission of a state-changing request |
|
||||
|
||||
`decoded` does not mean that MQTT framing alone was parsed. Status and heartbeat
|
||||
are therefore observed raw channels, not decoded status models. Camera preview
|
||||
transport is observed, but its media decoder/replay flags remain independent.
|
||||
|
||||
The v1 loader rejects every `write_enabled: true`. Owner-operated LixelGO wire
|
||||
capture verifies the `ModelingRequest` topic and action values, but complete
|
||||
device/session/OpenAPI header construction, settings, save completion, timeout
|
||||
and rollback contracts remain unresolved. Acquisition therefore stays
|
||||
`operator-manual` through the verified physical double-click.
|
||||
|
||||
The existing BLE Wi-Fi provisioning workflow has its own reviewed profile and
|
||||
operator confirmation. Merely loading this compatibility profile neither calls
|
||||
nor authorizes that legacy mutation path.
|
||||
|
||||
## Validation
|
||||
|
||||
The loader uses only the Python standard library and performs no device I/O:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
## Evolution rules
|
||||
|
||||
1. A different firmware or topology gets a new profile file and profile ID.
|
||||
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
|
||||
shape alone.
|
||||
4. Breaking profile semantics require a new `schema_version` and validator.
|
||||
5. Sensitive packet captures, device identities, addresses and credentials stay
|
||||
outside Git; redacted reports and hashes are the committed evidence links.
|
||||
6. A profile describes compatibility. Host authorization and transport writes
|
||||
remain separate policy and execution concerns.
|
||||
@@ -0,0 +1,406 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"profile_id": "xgrids.lixelkity-k1.fw-3.0.2.direct-lan.v1",
|
||||
"profile_status": "experimental-evidence-backed",
|
||||
"scope": {
|
||||
"vendor": "XGRIDS",
|
||||
"model": "LixelKity K1",
|
||||
"firmware": {
|
||||
"match": "exact",
|
||||
"version": "3.0.2"
|
||||
},
|
||||
"topology": "direct-lan",
|
||||
"claim_limit": "One owner-controlled K1 on exact firmware 3.0.2 across controlled direct-LAN and owner-operated LixelGO/iPhone laboratory runs. This is not a vendor API or a cross-firmware compatibility claim."
|
||||
},
|
||||
"evidence_vocabulary": {
|
||||
"observed": "The channel, transport, or physical behavior was directly seen on the owner-controlled K1.",
|
||||
"decoded": "A bounded decoder produces the stated semantic payload from observed bytes; transport framing alone is not a semantic decode.",
|
||||
"replay_verified": "A captured payload of this semantic channel has passed the repository replay-to-view path.",
|
||||
"physical_verified": "The result was correlated with a controlled physical K1 state or operator action.",
|
||||
"write_enabled": "This profile authorizes software to emit the state-changing vendor request. False never grants runtime write authority."
|
||||
},
|
||||
"safety": {
|
||||
"default_mode": "read-only",
|
||||
"vendor_writes_enabled": false,
|
||||
"unknown_firmware_policy": "reject-profile",
|
||||
"request_topic_subscription_enabled": false,
|
||||
"notes": [
|
||||
"Loading this descriptive profile does not authorize a BLE or MQTT write.",
|
||||
"The existing reviewed Wi-Fi provisioning procedure remains separately operator-confirmed and is not activated by this profile.",
|
||||
"Observed LixelGO modeling requests describe the wire contract but remain non-replayable and write-disabled.",
|
||||
"Unknown firmware, transport, topics, fields, and action responses fail closed."
|
||||
]
|
||||
},
|
||||
"evidence_sources": [
|
||||
{
|
||||
"id": "wifi-provisioning-profile",
|
||||
"kind": "reviewed-profile",
|
||||
"path": "docs/04_K1_WIFI_PROVISIONING_PROFILE.md",
|
||||
"scope": "Observed firmware, GATT UUIDs, 99-byte provisioning frame, status read and physical LAN association."
|
||||
},
|
||||
{
|
||||
"id": "mqtt-stream-profile",
|
||||
"kind": "reviewed-profile",
|
||||
"path": "docs/05_K1_MQTT_STREAM_PROFILE.md",
|
||||
"scope": "Direct-LAN MQTT transport, report topics, bounded point/pose codecs and static modeling-request mapping."
|
||||
},
|
||||
{
|
||||
"id": "lab-001",
|
||||
"kind": "redacted-physical-lab-report",
|
||||
"path": "docs/lab/001_K1_LIVE_MQTT_20260715.redacted.md",
|
||||
"scope": "Physical BLE-to-Wi-Fi result, MQTT message counts, point/pose decode totals and negative camera observation."
|
||||
},
|
||||
{
|
||||
"id": "live-viewer-profile",
|
||||
"kind": "implemented-path-description",
|
||||
"path": "docs/06_K1_LIVE_VIEWER.md",
|
||||
"scope": "Raw-first live/replay path for point cloud and pose."
|
||||
},
|
||||
{
|
||||
"id": "lab-002",
|
||||
"kind": "redacted-physical-protocol-report",
|
||||
"path": "docs/lab/002_LIXELGO_IPHONE_LOCAL_PROTOCOL_20260716.redacted.md",
|
||||
"scope": "Owner-operated LixelGO start/stop mapping, local-only bounded traffic result and left/right RTSP/H.264 camera-preview discovery."
|
||||
}
|
||||
],
|
||||
"transports": [
|
||||
{
|
||||
"id": "ble.wifi-bootstrap.fw3.v1",
|
||||
"role": "bootstrap-and-status",
|
||||
"protocol": "BLE GATT",
|
||||
"service_uuid": "00007f00-0000-1000-8000-00805f9b34fb",
|
||||
"characteristics": {
|
||||
"wifi_request": "00007f01-0000-1000-8000-00805f9b34fb",
|
||||
"wifi_status": "00007f02-0000-1000-8000-00805f9b34fb"
|
||||
},
|
||||
"reviewed_profile_id": "xgrids-k1-fw3-wifi-v1",
|
||||
"request_frame_bytes": 99,
|
||||
"status_semantics": {
|
||||
"ap_baseline_ipv4": "192.168.56.1",
|
||||
"lan_acceptance": "A non-AP private IPv4 must be observed and independently confirmed on the intended LAN."
|
||||
},
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"wifi-provisioning-profile",
|
||||
"lab-001"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "mqtt.direct-lan.fw3.v1",
|
||||
"role": "report-data-plane",
|
||||
"protocol": "MQTT 3.1.1",
|
||||
"network": {
|
||||
"transport": "TCP",
|
||||
"port": 1883,
|
||||
"tls": false,
|
||||
"authentication": "none-observed",
|
||||
"addressing": "confirmed-device-private-ipv4-only"
|
||||
},
|
||||
"subscription_allowlist": [
|
||||
"lixel/application/report/#",
|
||||
"RealtimePointcloud",
|
||||
"RealtimePath",
|
||||
"DeviceStatus"
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001",
|
||||
"live-viewer-profile",
|
||||
"lab-002"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "rtsp.camera-preview.fw3.v1",
|
||||
"role": "camera-preview-data-plane",
|
||||
"protocol": "RTSP 1.0 with interleaved RTP over TCP",
|
||||
"network": {
|
||||
"transport": "TCP",
|
||||
"port": 8554,
|
||||
"tls": false,
|
||||
"authentication": "none-observed",
|
||||
"addressing": "confirmed-device-private-ipv4-only"
|
||||
},
|
||||
"media": {
|
||||
"codec": "H.264",
|
||||
"rtp_payload_type": 96,
|
||||
"clock_hz": 90000,
|
||||
"framing": "RTP/AVP/TCP interleaved channels 0-1"
|
||||
},
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"lab-002"
|
||||
]
|
||||
}
|
||||
],
|
||||
"channels": [
|
||||
{
|
||||
"id": "spatial.point-cloud.live",
|
||||
"kind": "point-cloud",
|
||||
"direction": "device-report",
|
||||
"topic": "lixel/application/report/lio_pcl",
|
||||
"wire_format": "protobuf MqttCompressMsg containing raw-LZ4 LioPclReport",
|
||||
"semantic_payload": "metric XYZ, complete uint32 rgbi and verified low-byte intensity",
|
||||
"bounds": {
|
||||
"max_mqtt_payload_bytes": 2097152,
|
||||
"max_compressed_bytes": 1048576,
|
||||
"max_decoded_bytes": 8388608,
|
||||
"max_expansion_ratio": 64,
|
||||
"max_points_per_frame": 250000
|
||||
},
|
||||
"unverified_fields": [
|
||||
"upper 24 bits of rgbi as RGB",
|
||||
"sensor timestamp epoch",
|
||||
"sensor-to-vehicle extrinsics"
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": true,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001",
|
||||
"live-viewer-profile"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "spatial.pose.live",
|
||||
"kind": "pose",
|
||||
"direction": "device-report",
|
||||
"topic": "lixel/application/report/lio_pose",
|
||||
"wire_format": "protobuf LioPoseReport",
|
||||
"semantic_payload": "position XYZ, quaternion XYZW, distance and pose accuracy",
|
||||
"unverified_fields": [
|
||||
"sensor timestamp epoch",
|
||||
"coordinate-frame convention",
|
||||
"sensor-to-vehicle extrinsics"
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": true,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001",
|
||||
"live-viewer-profile"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "device.status.live",
|
||||
"kind": "device-status",
|
||||
"direction": "device-report",
|
||||
"topic": "lixel/application/report/device_status",
|
||||
"wire_format": "opaque bytes",
|
||||
"semantic_payload": null,
|
||||
"limitations": [
|
||||
"The report was physically observed, but no bounded semantic device-status decoder is implemented.",
|
||||
"Raw capture is evidence; field names or meanings must not be inferred from payload shape."
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "device.heartbeat.live",
|
||||
"kind": "heartbeat",
|
||||
"direction": "device-report",
|
||||
"topic": "lixel/application/report/heartbeat",
|
||||
"wire_format": "opaque bytes",
|
||||
"semantic_payload": null,
|
||||
"limitations": [
|
||||
"Only channel presence and approximate report cadence are verified.",
|
||||
"Payload semantics are not decoded."
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "camera.preview.live",
|
||||
"kind": "camera-preview",
|
||||
"direction": "device-report",
|
||||
"discovery_status": "observed",
|
||||
"topic": null,
|
||||
"endpoint_templates": [
|
||||
"rtsp://{confirmed-device-private-ipv4}:8554/live/chn_left_main",
|
||||
"rtsp://{confirmed-device-private-ipv4}:8554/live/chn_right_main"
|
||||
],
|
||||
"wire_format": "RTSP 1.0, interleaved RTP/TCP, H.264 PT96 at 90000 Hz",
|
||||
"semantic_payload": "compressed live left/right camera preview selected by endpoint",
|
||||
"limitations": [
|
||||
"No full-resolution raw frame, camera calibration or panorama-stitching contract is verified.",
|
||||
"Left/right optical identity is supported by endpoint labels and operator-selected application views, not an independent image-content fixture.",
|
||||
"A bounded Mission Core camera decoder and replay fixture are not yet implemented."
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"lab-002"
|
||||
]
|
||||
}
|
||||
],
|
||||
"acquisition_control": {
|
||||
"mode": "operator-manual",
|
||||
"write_enabled": false,
|
||||
"verified_device_control": {
|
||||
"gesture": "physical-double-click",
|
||||
"state_dependent_result": "start from steady-green standby; stop during active scanning",
|
||||
"single_click_result": "not a verified scan-start action",
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"lab-001"
|
||||
]
|
||||
},
|
||||
"semantic_actions": [
|
||||
{
|
||||
"id": "acquisition.start",
|
||||
"execution": "operator-manual",
|
||||
"operator_control": "physical-double-click from steady-green standby",
|
||||
"observed_application_control": "owner-operated LixelGO project confirmation",
|
||||
"vendor_request_mapping": {
|
||||
"evidence_kind": "owner-controlled-wire-observation",
|
||||
"transport": "MQTT 3.1.1",
|
||||
"topic": "lixel/application/request/modeling",
|
||||
"qos": 2,
|
||||
"message_type": "ModelingRequest",
|
||||
"action_field_value": 1,
|
||||
"required_unresolved_context": [
|
||||
"complete device/session/OpenAPI header construction",
|
||||
"project/record/scan/mount setting semantics and safe defaults",
|
||||
"timeout, rejection and rollback contract"
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"write_enabled": false
|
||||
},
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001",
|
||||
"lab-002"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "acquisition.stop",
|
||||
"execution": "operator-manual",
|
||||
"operator_control": "physical-double-click during active scanning",
|
||||
"observed_application_control": "owner-operated LixelGO stop confirmation",
|
||||
"vendor_request_mapping": {
|
||||
"evidence_kind": "owner-controlled-wire-observation",
|
||||
"transport": "MQTT 3.1.1",
|
||||
"topic": "lixel/application/request/modeling",
|
||||
"qos": 2,
|
||||
"message_type": "ModelingRequest",
|
||||
"action_field_value": 2,
|
||||
"required_unresolved_context": [
|
||||
"complete device/session/OpenAPI header construction",
|
||||
"save-completion and final-standby state mapping",
|
||||
"timeout and rollback contract"
|
||||
],
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"write_enabled": false
|
||||
},
|
||||
"evidence": {
|
||||
"observed": true,
|
||||
"decoded": true,
|
||||
"replay_verified": false,
|
||||
"physical_verified": true,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"mqtt-stream-profile",
|
||||
"lab-001",
|
||||
"lab-002"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "calibration.device.start",
|
||||
"execution": "unavailable",
|
||||
"operator_control": null,
|
||||
"vendor_request_mapping": null,
|
||||
"observed_behavior": "Static initialization follows acquisition.start; no independent calibration action was observed.",
|
||||
"limitations": [
|
||||
"No standalone calibration command topic, request schema, acknowledgment or state transition is verified."
|
||||
],
|
||||
"evidence": {
|
||||
"observed": false,
|
||||
"decoded": false,
|
||||
"replay_verified": false,
|
||||
"physical_verified": false,
|
||||
"write_enabled": false
|
||||
},
|
||||
"source_ids": [
|
||||
"lab-002"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user