Repository navigation
v0.1.0-beta.1
Pre-release
Pre-release
·
81 commits
to main
since this release
The first release: kb7screen and Commander as ready-built executables.
Added
- Release builds: a version tag builds
kb7screenfor Windows and Linux and
Commander for Windows, publishes them with their SHA-256 checksums and
submits them to VirusTotal.kb7screen --versionand Commander's log say
which version runs. - Commander, a program for the Windows notification area that keeps
kb7screen rungoing. Its menu reloads the configuration, applies the
buttons, switches Start with Windows and opens the configuration folder and
the log. A balloon shows when a start or reload failed; a failed reload keeps
the old configuration running, and a red dot on the icon means no
configuration is running. It is built frominternal/supervisor,
internal/tray,internal/autostart,internal/appdataand
internal/icon. It has been checked on the Windows 11 desktop (see
docs/design/commander-tray.md, "Desktop check"). kb7screen stop <config>andkb7screen reload <config>ask the running
runfor that folder to end cleanly or read its configuration again.- One program owns the keyboard per user: a second Commander or
runrefuses
to start, andapplyandrestorerefuse while one of them runs. - Lighting layers in
kb7screen: a profile's layout file can have a[light]
block with a stack of effects (static,fixed,breathing,wave,
ripple,state), each declaring its own settings, whichrunstreams to
the LEDs.runreads the brightness at start and after a profile switch,
scales the colours by the brightness notifications, keeps streaming while
the RGB button has the LEDs off, and when the stream stops leaves the active
profile's stored lighting (report0x11, read with the brightness) on the
LEDs, or the last lit profile's layers at rest when that cannot be read.
Buttons can flip a lighting state withstate = "name", with or without an
action. The start-up brightness read has run on the keyboard without an
error; the rest is pending hardware acceptance: whether that level is right,
the brightness handling and the RGB button have not been tried yet. - Reading the KB7's own key presses for the ripple and the states: Raw Input on
Windows (measured with Star Citizen focused),/dev/input/event*on Linux,
with an optional udev rule; the Linux reader has not been run on hardware.
kb7screen keytestprints the keys pressed for a
few seconds and saves nothing. kb7screen light-preview, an animated GIF of a profile's lighting with
simulated key presses.confirm = "hold <duration>"on a button: it acts only after the finger has
stayed on it that long.- A run lock,
.kb7screen-run.lock: a secondrunfor a folder, andapply
andrestorewhilerunholds it, refuse to start. - Image slots 9 to 15 took uploads from Swarm II (
40-swarm-slots-pages-1);
15 as the highest slot is a hypothesis from Swarm II's own limit of 15
application widgets. - Pages 2 and 3 of the touchscreen: byte 2 of report
0x35is the page,
report0x29holds the pages one after the other, twelve entries each, and
report0x25puts a marker before the twelve types of each page
(40-swarm-slots-pages-1). Observed for page 2; page 3's0x29position
comes from the table size only. kb7screen, a Go program inscreen/that puts own buttons (built-in style
or own PNG pictures) on the KB7's touchscreen per profile and carries out
their actions on the PC: key chords, sequences with waits, programs, URLs.
Commands:check,read,preview,apply,restoreandrun, which
also switches profile when a named program starts. Builds for Windows and
Linux.- Application buttons: a screen button whose picture is uploaded by the host.
The upload (a5 41) is 142 x 148 RGB565 followed by a one-byte-per-pixel
alpha mask. A picture uploaded from our own code was drawn with its
transparency, straight on the background and without any firmware tile. Its
0x29label can be set (eleven characters were drawn in full) or left
empty, which draws no text. A tap is reported as0x33plus a newf1
notification once0x0eis written; the keyboard starts nothing itself. - A key position turned into an application button from our own code, with
its own picture: upload to an image slot, the slot in byte 3 of the0x29
entry, and0x35type05/06. Positions can share a slot. Report0x25
decoded as the page's whole type table, the same pairs as0x35. - Image slots 1–9 seen, numbered across profiles, with slot 4 written from our
own code; the top row's buttons can be application buttons too; each profile
has its own button tables; the host switches the active profile with report
0x06. Swarm II and our own code conflict over slots and labels, so only
one of them should manage the buttons. - The CPU temperature widget:
0x35type39, drawn by the firmware, with the
value pushed by the host as a number in ana3frame. The top row's buttons
change type like any other position. - Macro buttons: binding kind
07in0x29and widget type05in0x35,
drawn as a fixed "M" icon with the0x29label; Swarm II cuts the label to
ten characters before sending it. - Three upload pitfalls: the keyboard does not answer on interface 1 for about
2 s after a0x0ewrite; an upload left open stops it working as a keyboard
until it is unplugged; and0x25has to wait 200 ms after0x29. - Second command replayed to the hardware: writing feature report
0x0eas
0e 05 01 00 00switches on the notifications that the keyboard otherwise
only sends with Swarm II running; Fn and dial events were checked.
0e 05 00 00 00switches them off again, and the setting is lost when the
keyboard is unplugged. - Fourth command replayed: report
0x35on its own empties and restores a
screen button; the keyboard redraws just that widget and the restored button
works as before. - Third command replayed: a background image uploaded from our own code, with
framing verified byte for byte against Swarm II's before sending. The device
sets the pace, so a full screen takes 32 seconds whoever sends it. - Report
0x35sets the widget type of one screen position; type00leaves
the position empty, so the background image shows through. - Hardware hints from the names and sizes of files in the Swarm II
installation, marked as hypotheses: a Sonix main controller and a second
microcontroller with its own firmware. The do-not-send list now names both
firmware-update paths.firmware/is ignored so vendor files stay local. - The clean-room rule stated precisely in the README,
CONTRIBUTING.mdand
docs/DEVELOPMENT.md: the protocol is derived solely from observing USB
traffic of hardware we own (EU Directive 2009/24/EC art. 5(3)), and Swarm II
binaries, firmware images and assets are not analysed, decompiled or
included. - Screen pixel order: row by row from the top left. The second, smaller image
upload is the keyboard's thumbnail of the background: the image squashed to
142 x 148, followed by what is most likely a fully opaque alpha mask. - The keyboard without Swarm II: a plain keyboard with media keys. The dial,
the buttons beside it and the screen's default page send ordinary Consumer
reports, the brightness and profile keys work on the device alone, and the
extra notifications (Fn, brightness level, dial, active profile, touch
positions) stay off until Swarm II is running. The full Consumer bitmap is
listed from the report descriptor. - Development notes: injected descriptors can name the wrong device address
after a reboot, which leaves that device's traffic unfiltered. kb7capcapture toolkit (stdlib only): pcap/pcapng reader, USBPcap and
Linux usbmon transfer pairing, device/configuration/string/HID report
descriptor parsing, andsummary,dumpanddiffcommands.- Boot-keyboard reports are hidden by default in
dumpanddiff. - Capture guide for Phase 0, protocol notes skeleton, PNG test images with
known pixel values. - CI: unit tests on Python 3.10 and 3.12; Dependabot for GitHub Actions.
- Project documentation:
CONTRIBUTING.md,SECURITY.md,
CODE_OF_CONDUCT.md(Contributor Covenant 2.1) and
docs/DEVELOPMENT.md. - Issue forms for bug reports, protocol findings, capture contributions and
open questions, plus a pull request template. All of them refuse raw
captures. - First real protocol notes: KB7 device identity (
10f5:5038, bcdDevice
0x0139, integrated hub10f5:503d) and the full interface/endpoint map —
four HID interfaces, three of them with an OUT endpoint. - Capture guide: the
00-descriptorsshortcut for pulling device and
configuration descriptors without a full plug-in capture. - The Swarm II startup exchange: a selector register (report
0x05) that
selects one of nineteen configuration blocks, whose report IDs and lengths
match the report map exactly. Plus thea1state stream anda3frames on
interface 1, and the device's own notification report0x03. - The system-volume frame on interface 1, verified by predicting where the
level would appear and then capturing a slider drag. Live PC values reach
the screen as numbers, not as rendered images. - The RGB lighting format: report
0x11over the control endpoint, a 112-LED
table stored as seven blocks of sixteen reds, greens and blues, and a
trailing 16-bit sum as its checksum. - Touch events: report
0x33reports a screen button being touched and
released, with the button's key in it, and the keyboard sends that key
itself. The dial's volume-down bit, and the boot-complete notification
about 4.9 s after plug-in. Report0x33carries the button's position on
the page, confirmed by prediction on two more buttons, and the mute loop
identifies the mute byte of the volume frame and the mute-state frame. - Who handles which key: the keyboard reports Fn, its own keys and the new LED
brightness through notification0x03; Swarm II applies brightness by scaling
the colours it streams, the keyboard switches its LEDs off by itself, and
Microphone Off is carried out on the host alone. Header byte 6 of report
0x11is the brightness in percent. - Default key and button functions from Turtle Beach's public support
article, cited as such: the action bar's buttons now have names in the LED
map, and the empty LED slots line up with the extra keys of the ISO and
Japanese layouts the KB7 is sold in. - Background image upload:
a5frames on interface 1 carry a 480 x 800 RGB565
image in 4096-byte blocks, every frame acknowledged by the device, at about
23 KiB/s. The screen resolution and pixel format follow from it. - Profile switching: the keyboard steps through its five slots itself when the
profile name on the screen is tapped, announces each switch with notification
03 00 01 <slot>, and Swarm II only follows by resuming its streams. - Screen buttons and profiles: report
0x29is the page's button table —
binding and label per position, with the same checksum as the lighting
block — and configuration blocks carry one of five profile slots in byte
3, with all five profile names in report0x16. A button bound to a
modifier on its own reports through notification0x03, not as a key. - The complete LED map: 94 of the 112 slots identified, including the arrow
keys, the top buttons and the ten-segment wrist rest strip, with the matrix
shown to be wired for an ISO layout. With Swarm II closed, a written report
0x11is what the keyboard displays. - Lighting driven from our own code: streaming
a1frames at 30 Hz rendered
on the keyboard, contending with Swarm II's 20 Hz for a 56% share of the
frames. Whoever streams last owns the LEDs. - What actually drives the lighting: the
a1stream on interface 1 carries the
live 112-LED colour table, in the same layout as report0x11and scaled by
the current brightness. Report0x11is stored configuration, which is why writing it only
makes the keyboard flicker before the stream wins. - The LED addressing scheme, proved by lighting a single key: an LED's red,
green and blue bytes sit sixteen apart inside its 48-byte block, and
Escape is LED index 0. - First command replayed to the hardware: an
a3volume frame written to
interface 1 set the level shown on the keyboard's screen, promoting that
frame fromobservedtoconfirmed. Documented with the Windows HID
details needed to repeat it. - The volume dial's full round trip: the device reports a relative step as a
Consumer bitmap plus a notification, and the host pushes the resulting
absolute level back about 9 ms later. The screen is a slave display for
host-side state.
Fixed
- Transfers were timestamped and ordered by when the request was queued rather
than when it completed. For interrupt IN that is wrong by up to the gap
between two reports, so touch events appeared as duplicates and the order of
reports within a dial click was reversed. Transfers now carry their
completion time, with the queueing time kept inTransfer.submitted. - The keystroke filter could still leak. A report was classified by the usage
page in effect at its first main item only, so one that starts on a vendor
page and switches to the keyboard page passed as vendor data, and usage pages
carried in four-byte usages were ignored. Every page a report uses is now
recorded, and when a HID interface's report descriptor is missing from the
capture or truncated, its reports are hidden rather than shown. - Keyboard reports on a vendor-defined interface were printed in full. Hiding
only looked at boot-keyboard interfaces, but the KB7 also exposes a keyboard
report on interface 2 alongside unrelated reports, so typed text could appear
indumpoutput without--show-keystrokes. Hiding is now decided per report
ID from the HID report descriptor, which keeps the other reports on that
endpoint visible. - USBPcap control transfers lost their payload. USBPcap 1.5.4 attaches the data
of a control transfer to the COMPLETE stage and emits no DATA stage at all, so
every control transfer in a real capture was parsed as empty and no device or
configuration descriptor was ever recognised.tests/synth.pycan now build
both layouts, and the device-inventory test runs against each. PROTOCOL.mdgave the selector write as05 00 <selector> 00. Byte 1 is the
profile: Swarm II writes every selector with00to04at startup
(02-swarm-start-1,02-swarm-start-2), and05 01 b9 00/05 01 b8 00
read profile 1's tables (34-read-profile-1).kb7screen applycould change the wrong profile. It set each position's
type with report0x35, which names no profile and which the keyboard
queues: a profile switch sent right after it made the queued changes land
on the profile switched to (37-kb7screen-apply-sc-1).applyand
restorenow write each profile's whole0x25table and wait for the
keyboard's full redraw before anything else is sent.- A profile switch to the profile that is already active is not confirmed by
the keyboard, soapply,restoreandruntimed out when the keyboard
was already on the profile (38-copy-factory-to-desktop-1). Where the
active profile is not known they now switch to another profile first;run
sends no switch when a program starts or stops and its profile is already
active. PROTOCOL.mdgave0x29plus0x35as the recipe for an application
button. It now records that0x35is queued and names no profile, that a
switch to the active profile is not confirmed, and that a whole0x25table
from our own code is taken over with a full redraw.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
7add515d67bc411a0db23ed5ce02dd813cfabd719b485ae611043bdb9f278883 |
commander-windows-amd64.exe |
4939389f6e59fb9e3fbda72a1e0a50bf4c8c1eb0f009ce1c74d44b4c2e184f8d |
kb7screen-linux-amd64 |
53f564e4525c656604724a2cf7c38567d69f5357f428af36c1889e76c40d96bf |
The executables are not code-signed, so Windows SmartScreen may warn
before the first start. Check a download against its SHA-256:
Get-FileHash <file> -Algorithm SHA256 (PowerShell) or sha256sum <file>.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):