**Status:** implementation-ready transport and capability specification; command
payloads still need an authenticated-device capture before any setting is
written. This document intentionally distinguishes observations from the
vendor's browser driver.
## 1. Identified hardware
The attached keyboard presents as:
| Field | Value |
| --- | --- |
| USB identity | `258a:010c` — BY Tech, product `Kreo Swarm` |
| USB revision | `bcdDevice=0x0300`; USB 2.0 full speed (12 Mb/s) |
| Current topology | bus 003, through USB hub port `3-2.3`; do not hard-code this path |
| USB configuration | two HID interfaces, remote wakeup advertised, 500 mA maximum declared |
| Kernel driver | `hid-generic` / `usbhid`; normal typing already works |
| Vendor controller match | Kreo Kontrol's current device table maps this exact VID/PID plus usage `0xff00:0x01` to the **`swarm75` / `bytech`** profile |
The receiver does not expose a serial number or a layout identifier. The
vendor match is strong evidence that this is a Swarm 75, but the application
must call it `Kreo Swarm 75 (signature match)` until it has completed the
device's authenticated handshake. It must not infer a specific colourway,
switch, or physical layout solely from `258a:010c`.
## 2. HID transport — observed on this laptop
The device has two USB HID interfaces and no interrupt OUT endpoint. Normal
key events arrive through interrupt IN; configuration is therefore expected
to use class `SET_REPORT` / `GET_REPORT` control transfers, exposed safely to
an application through **hidraw**.
| Interface | HID collection / report | Direction and size | Meaning |
| --- | --- | --- | --- |
| 0 | Boot keyboard (no report ID) | IN 8 bytes; OUT 1 byte | 6-key boot keyboard plus Num/Caps/Scroll/Compose/Kana host LED bits |
| 1 | ID 1 | IN, 3 bits | Generic Desktop system control: power, sleep, wake |
| 1 | ID 2 | IN, 16 bits | Consumer/media control usage |
| 1 | ID 3 | IN, 3 bytes | Vendor page `0xff00`, usage 1; meaning unknown |
| 1 | ID 4 | IN, 15-byte payload | 120-bit keyboard bitmap (a non-boot simultaneous-key path) |
| 1 | ID 5 | Feature, 5-byte payload | Vendor configuration channel; not yet associated with a command |
| 1 | ID 6 | IN 7-byte payload; Feature, 519-byte payload | Primary vendor configuration/readback channel |
| 1 | ID 7 | IN, 7-byte payload | Five-button mouse, X/Y, wheel, and AC Pan |
The descriptor is internally consistent with Linux's input devices:
`BY Tech Kreo Swarm Keyboard`, `System Control`, `Consumer Control`, and
`Mouse`. The standard keyboard LED output is live — the current NumLock LED
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`.
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
while the kernel owns the interface returned `LIBUSB_ERROR_IO`; that is an
access-path limitation, not evidence that the feature reports are absent.
## 3. Supported customization
The following comes from the current, publicly delivered Kreo Kontrol
`bytech` driver instantiated for `swarm75` without a physical connection. It
is a precise UI/capability target, but each read/write must still be verified
against this keyboard after authentication.
| Area | Supported capability | Constraints to preserve in the Linux UI |
| --- | --- | --- |
| RGB | Per-key RGB; one custom-light frame; colour, mode, speed, brightness, LED enable | Brightness and speed are five levels (0–4 / 0–100%). No direction control. |
| Effects | Off, Fixed on, Respire, Rainbow, Flash away, Raindrops, Rainbow wheel, Ripples shining, Stars twinkle, Shadow disappear, Retro snake, Neon stream, Reaction, Sine wave, Retinue scanning, Rotating windmill, Colorful waterfall, Blossoming, Rotating storm, and a self-defined mode | The driver disagrees whether the self-defined raw ID is `19` or `277`; treat the mode value as protocol-owned, not a UI constant. |
| Colour mode | Monochrome and colourful | The two exported driver schemas use different raw values for `Colourful`; translate through the protocol adapter. |
| Key mapping | Keyboard, modifier, combination/shortcut, media, mouse, disabled, and macro bindings | Four layers: Base, Fn, Fn1, Fn2. The driver exposes 163 assignable key-function choices; map only controls present in the physical layout map. |
| Macros | 32 slots; up to 112 actions per slot; names up to 127 bytes; press/release actions and 0–65,535 ms delays | Execution types: fixed count, until released, until any key pressed, and toggle. Macro parsing and writes must be bounds-checked. |
| Typing controls | Debounce: 0/10/20/30/40 ms; tap-delay setting | No user-selectable NKRO, report-rate, OS-mode, or Win-lock setting in this model profile. Do not expose them. |
| Power | Battery level/charging status and idle sleep | Present the vendor's discrete choices: off, 30 s, 60 s, 120 s, 180 s, 300 s, 600 s, 900 s, 1,200 s, 1,800 s. |
| Maintenance | Per-layer reset and factory reset | Factory reset is explicitly atomic and destructive: always require a confirmation and create an export first. |
The vendor profile also declares support for authentication, layer reset,
multimedia shortcuts, and battery reporting; it declares **no** static
profiles, side LED writes, lighting direction, or advanced Hall-effect
features (rapid trigger, DKS, SOCD, etc.).
## 4. Protocol boundary and known command facts
Only the following facts are safe to rely on before a transaction capture:
1. Use the vendor-defined HID collection (`usagePage=0xff00`, `usage=0x01`)
and feature report ID 6. Its feature payload is exactly 519 bytes; reject
any shorter or longer message.
2. The official driver begins an authenticated session by sending feature
report 6 with a 519-byte frame whose prefix is
`82 01 00 01 00 06 00`, then reading feature report 6. This was captured
from the official driver against an in-memory transport, never sent to the
attached keyboard.
3. Kreo's client contains a named wired command vocabulary:
Before exploring, read root `CONTEXT.md` (or `CONTEXT-MAP.md` when present) and relevant `docs/adr/` decisions. If absent, proceed silently; domain-modeling creates them when a real terminology or decision need arises.
This is a single-context layout:
```
/
├── CONTEXT.md
├── docs/adr/
└── src/
```
Use defined glossary terms consistently, and explicitly flag conflicts with existing ADRs.
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
| `needs-info` | `needs-info` | Waiting on reporter for more information |
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
| `ready-for-human` | `ready-for-human` | Requires human implementation |
| `wontfix` | `wontfix` | Will not be actioned |
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Codex