Add the ITPROTECH MK series (8808) as a third pad family

Confirmed on the MK-09 (8808:660a, 9 keys): the vendor's .NET configurator
was decompiled for the wire format and every frame was then written to a
real pad and read back. Keys, media keys and multikey sequences are
supported; lighting from the command line.

The firmware acts on every other output report, so each report is sent
twice (as the vendor software does) and every write is verified by reading
the key back. The app now keeps one state file per pad and starts with a
known layout for a known USB id, and the editor asks the backend whether a
binding fits before offering to write it. The actions listener and the
udev rule cover every supported vendor.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
2026-10-23 19:24:30 +02:00
parent 2b75543c74
commit 80c6a5da1c
17 changed files with 1085 additions and 23 deletions

View File

@@ -58,6 +58,9 @@ Bus 001 Device 011: ID 1189:8840 Acer Communications & Multimedia USB Composite
The important bit is **`1189:8840`**. Don't worry about the "Acer" part: it isn't made by Acer, these pads just borrow that ID.
> [!TIP]
> **`8808:660a` with no name next to it?** That's the ITPROTECH MK-09, the Japanese 9 key pad (ちょい足しキーボード). MacroPad supports it too; see [ITPROTECH MK series](#-itprotech-mk-series-8808).
> [!NOTE]
> **Different number, like `1189:8890` or `1189:8842`?** That's a sibling of this pad with a different layout. MacroPad will spot it and tell you it isn't supported yet, rather than risk sending it the wrong thing. [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) supports several of them today, and [you can help add yours here](#-other-pads-in-this-family).
@@ -95,7 +98,7 @@ Both write straight to the pad's own memory, so you can even use both. Pick whic
| | MacroPad | [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool) |
|---|---|---|
| How you use it | Click on the UI of your pad | Write a YAML file, run a command |
| Supported Pads | `1189:8840` (12 keys, 2 knobs) | `1189:8840`, `8842`, `8890`, several layouts |
| Supported Pads | `1189:8840` (12 keys, 2 knobs), `8808:660a` (ITPROTECH 9 keys) | `1189:8840`, `8842`, `8890`, several layouts |
| Operating Systems | Linux | Linux, macOS, Windows |
| Shortcuts | Yes | Yes |
| Media Keys | Yes | Yes |
@@ -430,6 +433,27 @@ If you'd like your pad in MacroPad too, you'll need the vendor software (`MINI_K
6. **[Open an issue](https://github.com/Probler-Yt/MacroPad/issues)** with that file, your `macropad-probe.py` output, and a photo of your pad. That's genuinely all it takes to get your pad supported.
## 🇯🇵 ITPROTECH MK series (8808)
The **ITPROTECH ちょい足しキーボード** pads sold in Japan (MK-02, MK-04, MK-09 and friends, USB vendor id `8808`) speak a different protocol from the CH57x pads, and the vendor's configurator is Windows only. MacroPad talks to them natively.
**Confirmed on `8808:660a`, the MK-09 (3x3, hot-swap switches, RGB).** Keys are numbered 1 to 9 left to right, top to bottom. Shortcuts, media keys and key sequences all work and are read back from the pad after every write, so the drawing always shows what the pad really holds.
What the hardware can and can't do:
| | MK-09 |
|---|---|
| Shortcuts with modifiers | Yes |
| Media keys | Yes, any consumer usage |
| Key sequences | Yes, up to 10 keys with **one** set of modifiers for the whole sequence, no delays |
| Mouse actions | The pad can, the app doesn't offer them yet |
| Layers | None |
| Lighting | 15 modes and a custom colour, from the command line: `python3 -m macropad_gui.backends.itprotech rgb "press: blue"` |
Other sizes under vendor `8808` are found and offered **Ask the pad what it is**, which reads only. If the pad answers like an MK-09 does, the app adopts it. If you have one, a report from that button is all it takes to add it to the confirmed list.
How it was worked out, and the wire format, is in [docs/protocol-itprotech.md](docs/protocol-itprotech.md).
## 🪟 Windows Support?
Windows already works with apps from vendors shipped as `.exe` files, and [ch57x-keyboard-tool](https://github.com/kriomant/ch57x-keyboard-tool).
@@ -623,6 +647,7 @@ tests/ real captures and the tests that replay them
- [ ] Knob press to toggle brightness between 0% and 100%
- [ ] Save and switch between named profiles (gaming, editing, streaming)
- [ ] **Windows and macOS** via a cross platform USB layer
- [x] A third protocol family: ITPROTECH MK series (`8808:660a`)
- [ ] **More pads**: every capture sent in gets us closer
---