# The ITPROTECH MK series protocol

The ITPROTECH ちょい足しキーボード pads (USB vendor id `8808`) are a different
family from the CH57x pads: different chip, different configurator, different
wire format. This is what an MK-09 (`8808:660a`, 9 keys) speaks. The code is in
`macropad_gui/backends/itprotech_proto.py` and `itprotech.py`.

## How it was worked out

The vendor's configurator (`mk_series_software.zip` from itprotech.jp,
`Run-me.exe`) is a .NET program, so it decompiles cleanly. Its device code
lists product ids `6600` to `6618` and one form per model; the 9 key form
builds exactly the reports below. Everything was then checked against a real
MK-09 by reading it, writing each kind of binding to key 9, and reading it
back. The responses in `tests/test_itprotech.py` are those real bytes.

## Interfaces

The pad has four HID interfaces. The first two are a boot keyboard and a boot
mouse; the third carries an NKRO keyboard, consumer control and a second
vendor page (`0xFFA0`) the configurator never uses. The fourth is the config
channel: usage page `0xFF00`, 64 byte input and output reports, **no report
id**, so a write to `/dev/hidraw` is `00` followed by 64 bytes.

## Reports

Every report, both directions, is `len payload...` zero padded to 64 bytes.

| Host sends | Meaning |
|---|---|
| `01 55` | Read. The pad answers one report per key, then `02 63 <mode>`, then `04 64 <g> <r> <b>`. |
| `0d <key> <type> ...` | Bind one key. `0d` (13) is the record length on the 9 key model; the 12 key model uses `0a`, the 8 key `0f`, and so on. The record is read off the pad before writing. |
| `02 57 <mode>` | Lighting mode 0 to 14. |
| `04 70 <g> <r> <b>` | Custom colour for mode 14. Green first. |
| `01 56` | **Firmware bootloader. Never sent by this app; `frame()` refuses it.** |

Key types:

| Type | Record | |
|---|---|---|
| `01` | `<mods> <keycode>` | keyboard; mods is the HID modifier byte |
| `02` | `<buttons> <x> <y> <wheel>` | mouse, not offered by the app |
| `03` | `04 <lo> <hi> 00` | consumer page usage, little endian |
| `04` | `<mods> <k1> ... <k10>` | several keys in a row, one modifier byte for all |
| `ff` | | a slot the vendor software never wrote |

Examples that were written to the pad and read back identically:

```
0d 09 01 00 10                   key 9 -> m
0d 09 03 04 e9 00 00             key 9 -> volume up
0d 09 04 00 0b 08 0f 0f 12       key 9 -> h e l l o
```

## The every-other-report rule

The firmware acts on every **second** output report it receives, whatever the
command. Send a read once and you may get silence; send it again and the dump
arrives. The vendor software sends every command twice, 20 ms apart, which
is why it works, and so does this backend (`REPEAT = 2`). A write is then
confirmed by reading the key back; a pad that holds something else makes the
write fail loudly rather than being believed.

Reading never changes anything. There are no layers, no commit command, and
the bindings are in the pad's flash as soon as the write is accepted.

## Lighting modes

0 off, 1 flow 1, 2 to 8 light on press in red, green, blue, yellow, cyan,
purple, white, 9 flow 2, 10 flow 3, 11 irradiation, 12 colourful gradient,
13 table lamp, 14 custom colour.