From f90df8aba1c7c5a41634bdf6e02beb1a1a6653c1 Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 21 Sep 2026 05:06:05 +0000 Subject: [PATCH] Chart VoidKontrol wayfinding and correct current hidraw evidence --- CONTEXT.md | 43 +++++++++++++++++ KREO-SWARM75-LINUX-CONTROL-SPEC.md | 19 ++++++-- README.md | 33 ++++++++++++++ docs/agents/issue-tracker.md | 38 ++++++++++++++- docs/evidence/2026-09-21-swarm75.md | 71 +++++++++++++++++++++++++++++ 5 files changed, 197 insertions(+), 7 deletions(-) create mode 100644 CONTEXT.md create mode 100644 README.md create mode 100644 docs/evidence/2026-09-21-swarm75.md diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..0a8c8b0 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,43 @@ +# VoidKontrol + +VoidKontrol manages the verified customization capabilities of a Kreo Swarm 75 +keyboard while preserving its ordinary typing and media controls. + +## Language + +**Driver-declared capability**: +A customization advertised by the vendor's software for a keyboard model, +whose behavior on the connected keyboard has not necessarily been verified. +_Avoid_: Verified capability, working feature + +**Verified capability**: +A customization whose behavior has been demonstrated on an identified keyboard +and connection mode, including the readback needed to confirm an update. +_Avoid_: Driver-declared capability + +**Device layer**: +One of the keyboard's Base, Fn, Fn1, or Fn2 sets of key assignments. +_Avoid_: Profile + +**Macro**: +A named sequence of key press/release actions and delays assigned to a keyboard +macro slot, with an execution behavior supported by the device. + +**Desired configuration**: +The settings the user intends the keyboard to use; they may differ from the +settings currently confirmed on the keyboard. +_Avoid_: Device readback + +**Device readback**: +Settings obtained from the keyboard and used as evidence of its current state. +_Avoid_: Desired configuration, successful request + +**Configuration backup**: +A saved, complete configuration read from the keyboard before changes, intended +to support restoration to that known state. +_Avoid_: Raw packet recording + +**Restore**: +An explicit operation that reapplies a compatible configuration backup and +verifies the resulting keyboard state. +_Avoid_: Factory reset diff --git a/KREO-SWARM75-LINUX-CONTROL-SPEC.md b/KREO-SWARM75-LINUX-CONTROL-SPEC.md index 25e0daf..0399852 100644 --- a/KREO-SWARM75-LINUX-CONTROL-SPEC.md +++ b/KREO-SWARM75-LINUX-CONTROL-SPEC.md @@ -49,11 +49,20 @@ is `1` — but it is not RGB control. ### Linux access requirement -This laptop's kernel does not provide `hidraw` (`modprobe hidraw` reports that -the module is absent). A native controller therefore requires a kernel with -`CONFIG_HIDRAW=y` or `CONFIG_HIDRAW=m`, plus a narrow udev rule granting the -controller service access to the matching hidraw node. It must select the -node that represents interface 1 / usage `0xff00:0x01`. +**Corrected by a read-only recheck on 2026-09-21:** the running kernel +`7.2.6_1` has `CONFIG_HIDRAW=y`, and both Swarm HID interfaces now have hidraw +nodes. The earlier `modprobe hidraw` failure did not establish missing +support: Linux defines `CONFIG_HIDRAW` as a boolean, not a separately loadable +module option (`CONFIG_HIDRAW=m` is not valid). + +A native controller requires `CONFIG_HIDRAW=y` and a narrow udev policy +granting its device service access to the matching node. At the recheck, +interface 1 was `/dev/hidraw5`, owned by `root:root` with mode `0600`; the +desktop user could neither read nor write it. Node numbers are dynamic and +must not be hard-coded. Select interface 1 / usage `0xff00:0x01` and validate +the complete descriptor before enabling control. See the dated +[device evidence](docs/evidence/2026-09-21-swarm75.md) and +[Linux HID Kconfig](https://github.com/torvalds/linux/blob/master/drivers/hid/Kconfig). Do **not** use libusb by detaching or unbinding `hid-generic`: that can take the keyboard away from the desktop. A read-only libusb `GET_REPORT` attempt diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c43c79 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# VoidKontrol + +VoidKontrol is being planned as a Kreo Swarm 75 keyboard manager for Void Linux, +with IBM Carbon in the desktop app and native niri and Noctalia integration. +There is no application implementation or working device-control release yet. + +The canonical plan is the Gitea decision map: +[Find the way to VoidKontrol v1: complete verified Swarm75 control on Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/1). +Its child issues hold research, unresolved decisions, and hardware prerequisites. + +## Confirmed v1 boundary + +Start with the verified USB presentation. Target device information, global and +per-key lighting, four key layers, macros, supported typing and power settings, +and backup/export/import/restore. Enable each capability only after its behavior +is verified on the device. Firmware flashing and the factory-reset UI are +excluded from v1; other connection modes require separate validation. + +## Read next + +- [Control specification](KREO-SWARM75-LINUX-CONTROL-SPEC.md): transport facts, + vendor capability targets, safety invariants, and bring-up gates. +- [Domain language](CONTEXT.md): distinctions between declared capabilities, + verified capabilities, desired settings, and device readback. +- [Current device evidence](docs/evidence/2026-09-21-swarm75.md): hidraw is + enabled, but device-service access and authenticated protocol captures are + still needed. No device settings were changed during this recheck. +- [Issue tracker workflow](docs/agents/issue-tracker.md): how to query the map's + frontier, claim a ticket, and record its resolution. + +The original specification was corrected to reflect current hidraw evidence; +its protocol-validation requirements remain in force. Research recommendations +are not implementation decisions or passed hardware tests. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 89041df..ba54e14 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -6,8 +6,8 @@ Issues and specs for this repo live as Gitea issues. Use the official [`tea`](ht - **Create an issue**: `tea issues create --title "..." --description "..."`. - **Read an issue**: `tea issues `. -- **List issues**: `tea issues`; use `tea issues --state all` for all states and `tea issues --format json` for machine-readable output. -- **Comment on an issue**: `tea comment issue `. +- **List issues**: `tea issues`; use `tea issues --state all` for all states and `tea issues --output json` for machine-readable output. +- **Comment on an issue**: `tea comments add ""`. - **Apply / remove labels**: `tea issues edit --add-labels "..."` / `--remove-labels "..."`. - **Close**: `tea issues close `. - **Pull requests**: use `tea pulls create`, `tea pulls `, and `tea pulls checkout `. @@ -25,3 +25,37 @@ Create a Gitea issue. ## When a skill says "fetch the relevant ticket" Run `tea issues `. + +## Wayfinding operations + +The current project is `xavierk/voidkontrol`, with configured tea login +`xavierk`. Pass `--login xavierk --repo xavierk/voidkontrol` when repository +context is unavailable. Use `tea api` for API operations not exposed by a +dedicated command; read the server's `/swagger.v1.json` for its current schema. + +- **Map**: the issue labelled `wayfinder:map`. Start by reading its body. +- **Children**: Gitea 1.27.1 exposes issue dependencies but no parent/subissue + endpoint in this server's schema. Give each child `wayfinder:child-of-` plus its `wayfinder:research`, `wayfinder:task`, + `wayfinder:grilling`, or `wayfinder:prototype` label. Its body ends with a + named `Parent map` link. This membership convention does not replace native + blocking. +- **Claim**: assign the driving user before work: + `tea issues edit --add-assignees xavierk `. An open issue with an + assignee is claimed. If work stops incomplete, leave an evidence/progress + comment and release the claim with an API PATCH containing `{"assignees":[]}`. +- **Blocking**: POST `{"owner":"xavierk","repo":"voidkontrol","index":}` + to `repos/xavierk/voidkontrol/issues//dependencies` using `tea api`. + Create all tickets before adding these relationships. Verify by GET on that + endpoint; each returned issue blocks the issue in the URL. +- **Frontier**: list open issues with the map-membership label, paginate through + all results, discard assigned issues, and GET each candidate's dependencies. + A candidate is takeable when every dependency is closed. Order by issue + creation/index ascending. Use names, with links, when presenting this result. +- **Resolution**: publish the answer as a comment, link any committed research + or prototype asset, close the child, then append one named link and a short + gist to the map's `Decisions so far`. Read the latest map before editing so + concurrent additions survive. The full decision stays on the child. + +Canonical starting map: +[Find the way to VoidKontrol v1: complete verified Swarm75 control on Void Linux](https://git.bongbetic.com/xavierk/voidkontrol/issues/1). diff --git a/docs/evidence/2026-09-21-swarm75.md b/docs/evidence/2026-09-21-swarm75.md new file mode 100644 index 0000000..48c000e --- /dev/null +++ b/docs/evidence/2026-09-21-swarm75.md @@ -0,0 +1,71 @@ +# Swarm75: read-only host and descriptor recheck + +Observed on 2026-09-21 during initial VoidKontrol wayfinding. This is discovery +evidence, not an authenticated control session or a hardware acceptance result. + +## Findings + +| Observation | Evidence | +| --- | --- | +| Host | `/etc/os-release`: Void Linux; `uname -r`: `7.2.6_1`; `getconf GNU_LIBC_VERSION`: `glibc 2.41` | +| hidraw support | `/boot/config-7.2.6_1`: `CONFIG_HIDRAW=y`, `CONFIG_HID_GENERIC=m`, `CONFIG_USB_HID=m` | +| Swarm identity | Both relevant sysfs HID devices report `HID_ID=0003:0000258A:0000010C`, `HID_NAME=BY Tech Kreo Swarm` | +| Input ownership | Both sysfs devices report `DRIVER=hid-generic`; nothing was unbound or grabbed | +| Interface 0 | Present as `/dev/hidraw4` at observation time | +| Interface 1 | Present as `/dev/hidraw5` at observation time; sysfs USB interface suffix `:1.1` | +| Access | Interface 1 node is `root:root`, mode `0600`; desktop-user `test -r` and `test -w` both fail | +| Vendor usage | Interface 1 descriptor includes vendor application collections with usage page `0xff00`, usage `0x01` | +| Descriptor | 240 bytes, SHA-256 `04f6ae259d80ba5828ae7f6b81cdcb2d31acf0b20dc93b473561cd8b3c930ab0` | + +The node numbers are observations, not persistent identifiers. Discovery must +reselect and revalidate the matching interface each time. + +Parsing the descriptor's report-size and report-count items gives these payload +sizes (excluding the report ID byte): + +| Report ID | Input payload | Feature payload | +| --- | --- | --- | +| 1 | 1 byte including padding | — | +| 2 | 2 bytes | — | +| 3 | 3 bytes | — | +| 4 | 15 bytes | — | +| 5 | — | 5 bytes | +| 6 | 7 bytes | 519 bytes | +| 7 | 7 bytes | — | + +Report 1 includes three meaningful system-control bits and padding, consistent +with the original specification's description. The descriptor agrees with the +declared report-6 transport size; that agreement does not establish authentication, +command semantics, checksums, firmware identity, or safe persistence behavior. + +## Correction to the initial specification + +The earlier inference from `modprobe hidraw` was incorrect. Linux declares +[`CONFIG_HIDRAW` as `bool`](https://github.com/torvalds/linux/blob/master/drivers/hid/Kconfig), +so `CONFIG_HIDRAW=m` is not an alternative and a missing standalone module is +not proof that the running kernel lacks hidraw. Current kernel configuration +and existing nodes directly establish its presence here. + +## Reproduction and boundaries + +Inspect `/sys/class/hidraw/*/device/uevent` and resolve their symlink targets to +identify the Swarm interfaces. Read the selected device's `report_descriptor` +attribute, sum report-size × report-count bits by report ID and main-item type, +and hash the descriptor with SHA-256. Query node properties with `udevadm info` +and inspect access without opening the device for control. + +Only kernel configuration, sysfs metadata, descriptor bytes, and filesystem +permissions were read. No feature reports were sent, no normal input events +were read, no permission rules were installed, and no device settings changed. +Ordinary typing continuity was not measured by an interactive acceptance test. + +## Evidence still required + +- Confirm the physical connection and keyboard layout, including special controls. +- A deliberately scoped official Kontrol authentication and configuration-read + capture for this device and transport. +- Exact framing/authentication/checksum and complete configuration-read coverage. +- Later, explicit reversible write/readback/persistence/restore verification for + every feature advertised as supported. + +Tracked by [Obtain authenticated Swarm75 evidence without interrupting normal input](https://git.bongbetic.com/xavierk/voidkontrol/issues/5).