Repository navigation
Releases
v0.1.0-beta.7
Added
- A project site in
site/: one page that says where Commander is going and
what it does today, with a rendered example, and links to the releases for
the downloads. It follows the visitor's light or dark setting and has a
switch. ThePagesworkflow publishes it to GitHub Pages whensite/
changes onmain. - Diagnostics: Commander keeps the keyboard's recent traffic in memory (kinds
of call, report IDs, lengths, durations and errors; never payloads, key
presses or touch positions) and writes it to its log when the keyboard
stops answering, at most once per five minutes, to show what came before a
hang.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
de89957b2e2d938d57c15e977432837843255412ef77b66166cadc46ebaba9c5 |
commander-windows-amd64.exe |
6ff915727a0f026a9c9fa23bbb1ba860ea00e6dee8a4843476191d710e7d3d43 |
kb7screen-linux-amd64 |
5124c8147abd9e986573f576a2dbaa33b437d5bd8b20dcf76eb67d9e381dfbb4 |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.6
Changed
- The repository is now
Bananenbaas/commander(it waskb7-commander).
Commander asks the new name for updates; older versions keep working
through GitHub's redirect. The Go module path follows the new name.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
84a476a267389e9e86e9b864f234510135b2ef211a317b233836672a852748c0 |
commander-windows-amd64.exe |
4f40763872089874943bbd0f37cb0b8170bcc9bfe557eba1cedc39c7f21f7811 |
kb7screen-linux-amd64 |
088f544961b31f5333737d08ee1498896c4af04369cca43d778965a842324986 |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.5
Added
- Volume mixer (Windows): while
runor Commander holds the keyboard, the
keyboard's mixer page shows the system volume and up to four programs with
sound sessions on any output device (ones playing sound come first), by name (the program's own,
else its executable's description), with their levels, and the sliders on
the keyboard set those volumes in Windows. The page follows Windows as programs start and
stop and as volumes change elsewhere. Not yet checked on the keyboard. - Profile names: a
namekey in a layout file (1 to 19 printable ASCII
characters) makesapplyrename that profile on the keyboard, in one write,
only when the name differs. Withoutnamethe name is left alone. Not yet
checked on the keyboard. - Buttons on pages 2 and 3 of the button screen:
pagetakes 1 to 3 (page 3
has positions 0 to 10).apply,restore,clear-launchersandrun
handle every page, a touch acts only for the button on the touched page,
andpreviewwrites apanel-<profile>-<page>.pngfor pages 2 and 3 with
buttons. Not yet checked on the keyboard. - Stored lighting:
applywrites each profile's stored lighting (what the
keyboard shows when nothing streams). A profile with[light]gets a still
picture of its layers (no ripples, states at theirstartvalue); a new
[stored_light]block withcolorandbrightnessoverrides it or sets a
profile without[light]. It is written only when it differs from what the
keyboard holds; profiles with neither are left alone. Not yet checked on
the keyboard.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
736d8c331a5d459955c065d4ce8f79d01f2aad44141e4b22dea5737d771bee0c |
commander-windows-amd64.exe |
054c3b55aaead821568956057f1a01dace26e87e5bac926a1dc658dcaa5bb399 |
kb7screen-linux-amd64 |
ed86d04b18d1a0491f3f8f1b8935a7f3902a9cf7690c733c24744b09efec525d |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.4
Changed
- A reload, or Apply buttons, no longer switches the keyboard back to the
expected profile: the loop keeps the profile the keyboard was on, also one
chosen by hand, unless a running program's profile differs. After a reload
nothing is switched at all, so the screen no longer flashes another
profile. After an unplug, and at the first start, the profile is chosen as
before. Checked on the keyboard for a reload: it stayed on a profile chosen
by hand, in about 2 seconds.
Added
- When the keyboard stops answering (three failed attempts in a row to set it
up or switch its profile, while it is still connected),runlogs that it
should be unplugged and plugged back in, and Commander's tooltip and a
balloon say so; the message ends as soon as the keyboard answers again. Not
yet checked on the keyboard.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
0a82d946b38c1731e78f9feaaac9f8d92fa5c668557347dbf75436c0f2a337a9 |
commander-windows-amd64.exe |
92c621157f1678326db4806dac784deb30d9d88b29e9e78e2f9635b46b1880e4 |
kb7screen-linux-amd64 |
78c53e15b775388428ad77dcfbd5e99fa221908c5d8c28cb46f30bce32439879 |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.3
Added
kb7screen background <image>uploads a screen background (and the
thumbnail the keyboard's background picker shows), framed as Swarm II does.kb7screen clear-launchers <config> --profile Nempties the launcher
buttons Swarm II left on a profile, so their picture slots are free. The
positions the folder manages are left as they are.- Commander's tooltip and the log of
runname the active profile as the
keyboard stores it ("SC", "DESKTOP") instead of only its number. docs/CAPTURES-WANTED.md: the Swarm II captures the next session should
record (renaming a profile, the volume mixer page, saving lighting, ...).
Changed
- Up to 15 pictures instead of 9: slots 10 to 15 are used too. A ledger
that holds a slot above 9 is refused by older versions of kb7screen and
Commander, which report the slot as out of range; do not go back to one
after applying with this version. applyreads the button tables of all five profiles and leaves the picture
slots of launchers it does not manage alone, on every page. When too few
slots are left it refuses before uploading any picture and names those launchers.- A slot freed by a removed button keeps its picture in the ledger, so a
button moved to another position is not uploaded again. New pictures go to
slots of unknown content first.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
0ff05f5d8e07c6cb60d0df55ed8217436a62a567c29905a012c0237faab5980f |
commander-windows-amd64.exe |
aca438f61354f98090122adc6f8d914c19eeb4ce89eeeb9411266232992ba016 |
kb7screen-linux-amd64 |
fdf7f6434c347f8afa948ef957854f146209474b2c97ebb5dd88e3dcf0b98fc7 |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.2
Commander learns to update itself. Updating from 0.1.0-beta.1 is by hand,
once: that version does not have the update feature yet.
Added
- Commander can update itself from the GitHub releases. Check for updates
in the menu (off by default) checks at start and once a day; Check now
checks at once. A newer release is offered in a balloon and as
Update to v...; after a Yes in the confirmation, Commander downloads it,
checks its SHA-256, replaces itself (keeping.old) and restarts on the same
folder. Not yet checked on a real desktop.
Changed
- Release builds keep their symbol tables (no
-s -w), to see whether fewer
virus scanners flag them. - Releases ship
LICENSE.txtand the title font's licence,
OFL-BarlowCondensed.txt, next to the executables. - The READMEs say where to download the executables, how to check them, and
that--versionprints the version.
Downloads
| File | SHA-256 |
|---|---|
kb7screen-windows-amd64.exe |
a9fe32c4600d54be9597d6fa0704a2265f9f3c61fe004c52bdf3a70898ae753d |
commander-windows-amd64.exe |
fcdef45bee88dd3d8ce259a5919c6a461010c339521d9ebbd4e9eaf6760609b3 |
kb7screen-linux-amd64 |
c719c8f3e6317393d2ca79b96932420c75a0eefd697f789826f628cae04a2beb |
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>.
LICENSE.txt is the licence of this software (GPL-2.0-or-later);
OFL-BarlowCondensed.txt is the licence of the title font built into the executables.
VirusTotal
Scans of these exact files (results can take a few minutes to appear):
v0.1.0-beta.1
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 ke...