Initial commit

docs/PROTOCOL.md

@@ -0,0 +1,553 @@
+# GANSS ARDOR_Katana (0c45:8006) — протокол и состояние реверса
+
+> Файл содержит ВСЁ необходимое для продолжения работы: протокол, карту клавиш, открытые вопросы, методику.
+> Обновлять по мере находок.
+> Пользовательская документация (установка, команды, режимы, свои скрипты) — по ссылкам из [README.md](../README.md).
+
+## Устройство
+
+- Клавиатура GANSS ARDOR_Katana, USB `0C45:8006` (Sonix SN32), 2 HID-интерфейса.
+- iface0 = boot keyboard + **конфиг-канал** (feature-репорты rid=0, 64 байта).
+- iface1 = consumer/mouse + vendor page 0xFF00 rid=5 (только input, не используется).
+- udev-правило `70-ganss-katana.rules` установлено (доступ к hidraw без root).
+- hidraw-узел iface0 ищется через `/sys/class/hidraw/*/device` (hid_dev, родитель `*:1.0`) + modalias `hid:b0003g0001v00000C45p00008006`.
+
+## Транспорт (реализовано в katana.py)
+
+Feature-репорты через hidraw ioctl (`HIDIOCSFEATURE`/`HIDIOCGFEATURE`), буфер 65 байт: первый байт = report id (0).
+**usbhid не отцепляется** — печать никогда не прерывается.
+pyusb-вариант НЕ использовать (отцеплял драйвер).
+
+## Общая транзакция (все команды)
+
+```
+SET 04 18                          begin            ACK: 04 18 00 01 (или ff = сессия уже открыта, ок)
+SET 04 13 00*6 01                  data-begin       ACK: 04 13 00 01
+SET <payload 64B>                  данные           (без ACK)
+SET 04 02                          commit           ACK: 04 02 00 01 <LE16 sum(payload)>
+SET 04 f0                          save (flash)     ACK: 04 f0 00 01
+```
+
+- ACK-байт [3]: `01` = ok, `00`/`ff` = отказ (залипшая сессия / неверное состояние).
+- Контрольная сумма: `sum(payload) & 0xFFFF`, LE, в ACK коммита (байты 4–5).
+  Проверена на десятках команд вендора и наших записях.
+- **Сессию всегда закрывать `f0`**, иначе прошивка клинится: begin отвечает `00`, команды отклоняются.
+  Лечение: `katana.py reset` (USB port reset, ~2–12 c на переподключение; иногда нужен повторный reset после паузы).
+- Вендор всегда шлёт полную транзакцию begin → data → payload → commit → save, даже на каждый чих.
+  Подражать.
+
+## Lighting payload (блок 1)
+
+```
+[0]      режим: 1..19 (0x13) — список вендора; 0x80 — custom per-key таблица
+[1..3]   R G B
+[8]      flag: 0x00 для режимов 1 и 4, 0x01 для остальных
+[9]      яркость 0x01..0x0F (вендор: слайдер 15 позиций)
+[10]     скорость 0x02..0x0F (вендор); для статики (mode 1) всегда 0x0A,
+         слайдер скорости в UI неактивен — подтверждено katana2-speed
+[11]     подрежим: моно/радуга для статики, направление анимации (см. ниже)
+[14..15] aa 55
+```
+
+### Байт [11] — подрежим (снято по color-toggle-*.pcapng)
+
+| Режим             | Значение    | Смысл                              |
+| ----------------- | ----------- | ---------------------------------- |
+| 1 static          | `00` / `01` | моно (`--color`) / радужный спектр |
+| 10 waterfall      | `02` / `03` | север→юг / юг→север                |
+| 16 marquee (0x10) | `01` / `00` | восток→запад / запад→восток        |
+
+Для остальных режимов вендор всегда шлёт `00`.
+Направления режимов 11 flow, 12 rotate, 18 wind кодируются тем же байтом (значения не сняты — в захватах переключали только waterfall и marquee).
+CLI: `--rainbow`, `--direction north-south|south-north|east-west|west-east`.
+
+- Off = payload из нулей + `aa55` (последний пункт списка вPендора).
+- Яркость масштабирует per-key цвета: 15/15 → `ee` (238), 1/15 → `0f`.
+- Режим 0x80 отображает таблицу per-key (см. ниже) — это и есть «кастом».
+
+### Таблица режимов (описания вендорской утилиты, docs/COLOR-MODES.md)
+
+Номер = байт [0] payload.
+«моно/спектр» — режим рисует одиночный цвет или полный спектр независимо от него.
+У режимов 10, 11, 12, 16, 18 есть **направление анимации** (кодировка в payload пока не снята — ждём снимок установки настроек).
+Алиасы реализованы в katana.py (`MODES`).
+
+| №   | Алиас       | Описание                                                     | Параметры                           |
+| --- | ----------- | ------------------------------------------------------------ | ----------------------------------- |
+| 1   | `static`    | Постоянный свет всех клавиш                                  | моно/спектр, яркость                |
+| 2   | `keypress`  | Подсветка нажатых: всё выключено, горят нажатые              | моно/спектр, яркость, скорость      |
+| 3   | `fade`      | Затухание нажатых: всё включено, гаснут нажатые              | моно/спектр, яркость, скорость      |
+| 4   | `star`      | Звёздный: случайные вспышки после полного затухания          | моно/спектр, яркость, скорость      |
+| 5   | `snow`      | Снежный: как звёздный, но больше соседних клавиш             | моно/спектр, яркость, скорость      |
+| 6   | `flower`    | Цветочный: плавные цвета на каждой клавише без затухания     | спектр, яркость, скорость           |
+| 7   | `breathing` | Дыхание: плавное свечение и затухание всех клавиш            | моно/спектр, яркость, скорость      |
+| 8   | `spectrum`  | Полный спектр: плавные цвета на всех клавишах                | спектр, яркость, скорость           |
+| 9   | `ripple`    | Круги: плавные цвета кругами из центра к краям               | моно/спектр, яркость, скорость      |
+| 10  | `waterfall` | Водопад: спектр по рядам клавиш                              | моно/спектр, яркость, скорость, ↑/↓ |
+| 11  | `flow`      | Течение: косые волны в одну сторону без затухания            | моно/спектр, яркость, скорость, ←/→ |
+| 12  | `rotate`    | Вращение: волна по кругу вокруг центра                       | моно/спектр, яркость, скорость, ←/→ |
+| 13  | `h-edge`    | Горизонтальная грань: волна по ряду от нажатой               | моно/спектр, яркость, скорость      |
+| 14  | `v-edge`    | Вертикальная грань: косая волна от нажатой клавиши           | моно/спектр, яркость, скорость      |
+| 15  | `splash`    | Рябь по воде: плавные круги от нажатой клавиши               | моно/спектр, яркость, скорость      |
+| 16  | `marquee`   | Бегущая строка: подсветка каждой клавиши в ряду              | моно/спектр, яркость, скорость, ←/→ |
+| 17  | `mountains` | Горы: плавные углы из середины в стороны                     | моно/спектр, яркость, скорость      |
+| 18  | `wind`      | Ветер: косые волны в одну сторону с затуханием               | моно/спектр, яркость, скорость, ←/→ |
+| 19  | `shuttle`   | Шаттл: бегущие строки по чётным/нечётным рядам в обе стороны | моно/спектр, яркость, скорость      |
+| —   | `off`       | Выключена (пункт 20 списка)                                  | all-zero payload                    |
+
+Переключение «моно/спектр» — байт [11] (для статики `00`=моно, `01`=радуга), направление анимации — тоже байт [11], значения в таблице выше.
+
+## Per-key таблица (кастомная раскраска)
+
+**Запись** (реализовано, работает стабильно):
+```
+begin 
+  → SET 04 23 00*6 09
+  → ACK
+  → 9 пакетов по 64Б: 143 записи [index, R, G, B] (индексы 0x00..0x8e) + 0000 + aa55  (576 Б)
+  → commit (ACK сумма = sum(576Б))
+  → save
+```
+Затем lighting payload mode=0x80 показывает таблицу.
+
+**Чтение (04 f5) — РАБОТАЕТ (вендорская схема):**
+```
+SET 04 f5 +09 
+  → GET ×9: поток [idx,r,g,b]×16, индексы 0x00,0x10..0x80 (0x00..0x8f)
+  → commit (ACK 01, сумма 0000 — payload не писался)
+  → save
+```
+- **НЕ делать begin+data-begin перед f5** — data-begin disarmит поток (ACK status 00, GET-ы возвращают эхо последнего SET).
+- Первый GET после SET может быть ACK `04 f5 00 01` (наблюдалось на первом чтении после save у вендора, там же было только 8 пакетов) — читатель пропускает не-данные и ждёт пакеты с ожидаемыми индексами.
+- Указатель сбрасывается на 0x00 каждым f5 SET (в рабочем состоянии).
+- Ретрай: до 3 попыток, между ними `begin` (переоткрытие контекста).
+- Кадр = ЖИВОЕ изображение: на статике — цвет режима (масштаб яркости, 15/15 → ee), на анимации — текущие цвета эффектов, меняются между чтениями.
+  Слот 0x6d всегда 000000 (null-слот прошивки, даже у вендора).
+  Слепые слоты в кадре на статике показывают цвет режима (буфер расчётный, физически LED нет).
+
+## Переназначение клавиш (канал 04 11)
+
+**Запись — РАБОТАЕТ** (снято по `raw-data/katana-v1/keybind-mouse-buttons.pcapng`: LCtrl → 5 кнопок мыши по очереди + возврат на default; проверено на железе):
+```
+begin
+  → SET 04 11 00*6 09
+  → ACK
+  → 9 пакетов по 64Б: 143 записи по 4 байта (позиция слота = LED-индекс клавиши) + 0000 + aa55  (576 Б)
+  → commit (ACK сумма = sum(576Б))
+  → save
+```
+Формат блоба совпадает с per-key таблицей, но содержимое записи — назначенное действие, а не цвет.
+В отличие от per-key записи, индекс клавиши в записи НЕ дублируется — слот определяется позицией в блобе.
+
+**Содержимое записи** (4 байта):
+- `[00, 00, 00, 00]` — действие по умолчанию (клавиша работает как обычно).
+- `[01, 01, код, 00]` — кнопка мыши, код в байте [2].
+- `[02, маска, код, 00]` — шорткат: маска модификаторов в байте [1],
+  HID usage ID клавиши (Keyboard/Keypad page 0x07) в байте [2]
+  (дампы keybind-editor, keybind-hotkeys).
+- `[03, usage_lo, usage_hi, 00]` — мультимедиа/веб-действие, байты [1..2] — 16-битный LE usage ID из HID Consumer Page (0x0C) (дамп keybind-multimedia).
+- `[06, индекс, режим, счётчик]` — запуск макроса (дампы macros-set, macros-modes).
+  Индекс 0-based: «Макрос 1» вендорской утилиты = 0.
+  Режим: `00` — однократно, `01` — повторить `счётчик` раз (наблюдалось 1, 5, 8), `02` — повторять до повторного нажатия.
+
+**Коды кнопок мыши** (байт [2]; значения — степени двойки, вероятно битовая маска, но комбинированные записи железом не проверялись):
+
+| Код  | Кнопка                          |
+| ---- | ------------------------------- |
+| `01` | ЛКМ (левая)                     |
+| `02` | ПКМ (правая)                    |
+| `04` | СКМ (средняя)                   |
+| `08` | «назад» (боковая)               |
+| `10` | «вперёд» (боковая)              |
+
+Пример из дампа: LCtrl (слот 0x5b) → ЛКМ = запись `[01, 01, 01, 00]` по смещению 91×4 = 364 (пакет 5, смещение 44).
+
+**Шорткаты редактора** (дамп keybind-editor): 9 транзакций, каждая вешает на Caps (слот 0x37) запись `[02, 01, код, 00]`.
+Код в байте [2] — HID usage ID буквы, порядок транзакций совпадает с порядком списка функций в UI вендора.
+Реализация — `EDITOR_ACTIONS` в katana.py, офлайн-тест по дампу — `tests/test_macro.py` (`test_editor_actions_match_dump`).
+Проверено на железе: `caps=copy` и `menu=undo` работают как Ctrl+C/Ctrl+Z.
+
+| Код  | Функция      | Шорткат |
+| ---- | ------------ | ------- |
+| `12` | Открыть      | Ctrl+O  |
+| `11` | Создать      | Ctrl+N  |
+| `1d` | Отмена       | Ctrl+Z  |
+| `16` | Сохранить    | Ctrl+S  |
+| `06` | Копировать   | Ctrl+C  |
+| `1b` | Вырезать     | Ctrl+X  |
+| `19` | Вставить     | Ctrl+V  |
+| `09` | Найти        | Ctrl+F  |
+| `04` | Выбрать всё  | Ctrl+A  |
+
+**Горячие клавиши** (дамп keybind-hotkeys): 10 транзакций, каждая вешает на Caps (слот 0x37) запись — по порядку списка UI вендора:
+A, Shift+B, Ctrl+C, Alt+D, Meta+E, Esc, F1, Num1, Fn, «Мой компьютер».
+Первые девять — записи типа `02`, десятая — мультимедиа `[03, 94 01, 00]` (usage 0x0194 AL My Computer, см. таблицу выше).
+Реализация — `HOTKEY_MODIFIERS`, `HOTKEY_KEYS` и `parse_hotkey()` в katana.py, офлайн-тесты — `tests/test_macro.py` (`test_hotkey_actions_match_dump`, `test_parse_hotkey`).
+Проверено на железе: `caps=ctrl+c` (одиночный модификатор) и `caps=ctrl+shift+c` (маска 0x03 — комбинация) работают как ожидается.
+
+**Байт [1] типа `02` — битовая маска модификаторов:**
+
+| Маска | Модификатор |
+| ----- | ----------- |
+| `00`  | без модификатора |
+| `01`  | Ctrl        |
+| `02`  | Shift       |
+| `04`  | Alt         |
+| `08`  | Meta (Win)  |
+
+У шорткатов редактора наблюдался только `01` (Ctrl); дамп keybind-hotkeys подтверждает остальные значения и показывает, что маска — степень двойки.
+Комбинации модификаторов (сумма масок, например Ctrl+Shift = `03`) подтверждены на железе: `caps=ctrl+c` и `caps=ctrl+shift+c` работают.
+Коды клавиш в байте [2] сверены с HID Usage Tables и дампом: A–E = `04`–`08`, Esc = `29`, F1 = `3A`, Num1 = `59`.
+Fn = `AF` — собственный код прошивки: в HID Usage Tables такого usage нет, но вендор шлёт именно его.
+
+| Код  | Клавиша | Примечание                        |
+| ---- | ------- | --------------------------------- |
+| `04` | A       | (буквы `04`–`1D`)                 |
+| `29` | Esc     |                                   |
+| `3A` | F1      | (F-клавиши `3A`–`45`)             |
+| `59` | Num1    | (нумпад `58`–`62`, Num0 = `62`)   |
+| `AF` | Fn      | собственный код прошивки, не HID  |
+
+**Мультимедиа/веб-действия** (дамп keybind-multimedia): 18 транзакций, каждая вешает на Caps (слот 0x37) запись `[03, usage u16 LE, 00]`.
+Порядок транзакций совпадает с порядком списка функций в UI вендора, все usages сверены с HID Usage Tables (Consumer Page 0x0C).
+Реализация — `MULTIMEDIA_ACTIONS` в katana.py, офлайн-тест по дампу — `tests/test_macro.py` (`test_multimedia_actions_match_dump`).
+
+| Usage  | Функция                                   |
+| ------ | ----------------------------------------- |
+| `0183` | Плеер (AL Consumer Control Configuration) |
+| `00CD` | Воспроизведение/пауза                     |
+| `00B7` | Стоп                                      |
+| `00B6` | Предыдущая песня                          |
+| `00B5` | Следующая песня                           |
+| `00E9` | Громкость +                               |
+| `00EA` | Громкость −                               |
+| `00E2` | Отключить звук                            |
+| `0223` | Домашняя страница (AL Internet Browser)   |
+| `0227` | Веб: обновить (AL Web Refresh)            |
+| `0226` | Веб: остановить (AL Web Stop)             |
+| `0224` | Веб: назад (AL Web Back)                  |
+| `0225` | Веб: вперед (AL Web Forward)              |
+| `022A` | Веб: избранное (AL Favorites)             |
+| `0221` | Веб: поиск (AL Web Search)                |
+| `0194` | Мой компьютер (AL My Computer)            |
+| `0192` | Калькулятор (AL Calculator)               |
+| `018A` | Электронная почта (AL Email Reader)       |
+
+**Известные ограничения:**
+- Команда перезаписывает ВСЮ таблицу (вендорская утилита делает так же) — каждый раз шлются все 143 слота.
+- Команда чтения текущих переназначений неизвестна (в дампах только запись).
+- Установлены пять типов действий: мышь (`[01, 01, ...]`), шорткаты — редактор и горячие клавиши (`[02, маска, ...]`), мультимедиа (`[03, usage, ...]`) и макрос (`[06, ...]`).
+  Остальные типы (Fn-слой) не исследованы.
+
+## Макросы (канал 04 19 + привязка через 04 11)
+
+Снято по дампам `raw-data/katana-v1/macros-*.pcapng` и вендорскому XML (`test.xml`, `macros-create-test.xml`).
+Содержимое макросов хранится в самой прошивке, а не на ПК:
+в эксперименте макрос сыграл при отключённой вендорской утилите и другой раскладке («ФЫВА» — те же клавиши A, S, D, F).
+
+### Запись содержимого — канал 04 19
+
+Транзакция отличается от обычной:
+```
+SET 04 19                          begin            ACK: 04 19 00 01
+SET 04 15 00*6 <число пакетов>     data-begin       ACK: 04 15 00 01 (эхо числа пакетов в байте [8])
+SET <данные, пакетов × 64Б>        данные           (без ACK)
+SET 04 02                          commit           ACK: 04 02 00 01 <LE16 sum>
+```
+- Вендор после коммита **не делает save** (04 f0) — в дампе macros-create его нет.
+- В байте [8] data-begin — число 64-байтовых пакетов (как у 04 23/04 11, где 09 = 576/64).
+- **Модель сохранения (проверена на железе): каждая область (bind-таблица, paint-таблица, режим, макросы) сохраняется во флеш только своим собственным save (04 f0).**
+  Чужой save чужую область ни сохраняет, ни затирает: remap-save не трогает макросы, macro-save не трогает bind.
+  Практическое правило: область переживает переподключение только если после её записи был её собственный save.
+  В apply каждая секция несёт свой save.
+- **Запись макросов (04 19) сбивает bind-таблицу и режим подсветки В RAM** (во флеше они остаются).
+  После записи макросов bind и режим нужно перепослать (apply делает это автоматически).
+- **Несколько макросов живут только при записи одним блобом**: каждый вызов 04 19 с блобом, содержащим один слот, обнуляет прочие слоты.
+  При обращении к ПУСТОМУ слоту прошивка делает fallback на слот 0 (проверено: macro1 при пустом слоте 1 исполнял содержимое macro0).
+- Вендорская утилита после записи макросов других save-транзакций не делает — в одиночной операции этого достаточно.
+
+**Формат блоба** (дамп macros-create, 14 пакетов = 896 байт):
+- Заголовок 400 байт (0x190) — 100 u32-смещений: смещение данных макроса от начала блоба, 0 = слот пуст.
+  В дампе: слот 0 → 0x190 (400), слот 1 → 0x1d8 (472).
+- На каждый макрос: u32 (число событий × 2), u32 0, затем события по 8 байт:
+  `[00 00][код][тип][задержка u16 LE][00][50]`.
+- Хвост: нули до кратности 64 минус 2 байта + `aa55` (как у per-key блоба).
+- Ёмкость по дампу — 896 байт: один макрос вмещает до 60 событий (при пустых остальных слотах).
+
+**Типы событий** (байт [3]): `B0` — клавиша нажата, `30` — отпущена, `90` — кнопка мыши нажата, `10` — отпущена.
+
+**Коды клавиш** (байт [2]):
+- Буквы, цифры, F1–F12, модификаторы — совпадают с HID usage ID (сверено: A=04, S=16, Q=14, LCtrl=E0, LAlt=E2, LWin=E3).
+- Стрелки — собственные коды прошивки, не HID: Left=`5C`, Right=`5E` (сверено); Up=`5D`, Down=`5F` — предположение по соседству, железом не проверены.
+- Медиа — тоже коды прошивки: VolUp=`05`, VolDown=`06` (сверено по XML: VK 175→05, VK 174→06).
+- Коды кнопок мыши — те же, что в таблице переназначений (`01` ЛКМ, `02` ПКМ, `04` СКМ).
+
+**Коллизия `05`/`06`:** это одновременно VolUp/VolDown и HID-коды букв B/C.
+Как прошивка различает их (и различает ли) — не установлено; вендорская утилита шлёт `05`/`06` именно для громкости.
+
+**Задержки:** в двух событиях вендорского XML стоит `delay_time="0"`, а в блобе прошивки — 10.
+Похоже на минимум вендора (2 наблюдения).
+Семантика задержки (пауза до или после события) по дампу не определяется — значения просто переносятся как есть.
+
+### Привязка макроса к клавише
+
+Обычная транзакция канала 04 11 (см. «Переназначение клавиш»), запись `[06, индекс, режим, счётчик]`.
+Вендор после привязки делает save (в отличие от записи содержимого).
+
+### Вендорский XML
+
+Утилита экспортирует макрос в XML (по файлу на макрос, имя — в `macroinfo`): `item type` `2`/`3` — клавиша вниз/вверх (`value` = VK-код Windows), `4`/`5` — кнопка мыши вниз/вверх (`value`: 1 = ЛКМ, 2 = СКМ, 3 = ПКМ), `delay_time` — мс.
+Реализация: `parse_macro_xml()` / `macro_to_xml()` в katana.py, офлайн-тесты — `tests/test_macro.py`
+(блоб, собранный из вендорских XML, побайтово совпадает с дампом с точностью до двух задержек «0 → 10»).
+
+**Открытые вопросы:**
+- Чтение содержимого макросов из прошивки не найдено (в дампах только запись).
+- Смысл u32 «число событий × 2» (возможно, счётчик полусобытий).
+- Реальный лимит макросов: заголовок рассчитан на 100 слотов, но ёмкости данных хватает лишь на пару десятков событий суммарно.
+- Несохранённое (без 04 f0) содержимое стирается следующим save другой транзакции (проверено) — а вот переживает ли оно переподключение USB, не установлено.
+- Коллизия кодов `05`/`06` (громкость против букв B/C).
+- Коды Up/Down стрелок (`5D`/`5F` — предположение) и остальные медиа-клавиши.
+
+### Особенность режима 7 (breathing): цвет из payload игнорируется
+
+Проверено на железе серией экспериментов:
+
+- Payload режима 7 побайтово совпадает с вендорским (`07 ff 00 00 … 01 0f 0a … aa 55`), но LED-кадр показывает зелёно-жёлто-красную гамму (R=0, G:B ≈ 5:1) при любом цвете в байтах [1..3]: красный, зелёный и синий дают одну и ту же картинку.
+- Цвет честно работает в статике (mode 1: кадр `(238,0,0)` для красного) и в fade (mode 3: кадр красноватый).
+- Speed, flag и paint-таблица (0x80) на это не влияют; после `default` поведение то же.
+
+Вывод: у breathing цветовой цикл зашит в прошивку, байты цвета для него не используются (возможно, вендорская утилита показывает то же самое — в её дампе тот же payload). При выборе режима для моноцвета используйте static или fade.
+
+## Карта клавиш (index → физическая клавиша)
+
+Методика: красим 4–8 индексов контрастными цветами, пользователь называет клавиши.
+Полная карта — в `keymap.py` (источник данных), ниже сводка.
+
+| Индекс        | Клавиша                 |
+| ------------- | ----------------------- |
+| `0x00`        | (слепой)                |
+| `0x01`        | Esc                     |
+| `0x02`        | F1                      |
+| `0x03`        | F2                      |
+| `0x04`        | F3                      |
+| `0x05`        | F4                      |
+| `0x06`        | F5                      |
+| `0x07`        | F6                      |
+| `0x08`        | F7                      |
+| `0x09`        | F8                      |
+| `0x0a`        | F9                      |
+| `0x0b`        | F10                     |
+| `0x0c`        | F11                     |
+| `0x0d`        | F12                     |
+| `0x0e`–`0x12` | (слепые)                |
+| `0x13`        | ~ (`` ` ``)             |
+| `0x14`        | 1                       |
+| `0x15`        | 2                       |
+| `0x16`        | 3                       |
+| `0x17`        | 4                       |
+| `0x18`        | 5                       |
+| `0x19`        | 6                       |
+| `0x1a`        | 7                       |
+| `0x1b`        | 8                       |
+| `0x1c`        | 9                       |
+| `0x1d`        | 0                       |
+| `0x1e`        | - (_)                   |
+| `0x1f`        | = (+)                   |
+| `0x20`        | NumLock                 |
+| `0x21`        | Num/                    |
+| `0x22`        | Num*                    |
+| `0x23`–`0x24` | (слепые)                |
+| `0x25`        | Tab                     |
+| `0x26`        | Q                       |
+| `0x27`        | W                       |
+| `0x28`        | E                       |
+| `0x29`        | R                       |
+| `0x2a`        | T                       |
+| `0x2b`        | Y                       |
+| `0x2c`        | U                       |
+| `0x2d`        | I                       |
+| `0x2e`        | O                       |
+| `0x2f`        | P                       |
+| `0x30`        | [ ({)                   |
+| `0x31`        | ] (})                   |
+| `0x32`        | Num7                    |
+| `0x33`        | Num8                    |
+| `0x34`        | Num9                    |
+| `0x35`–`0x36` | (слепые)                |
+| `0x37`        | Caps                    |
+| `0x38`        | A                       |
+| `0x39`        | S                       |
+| `0x3a`        | D                       |
+| `0x3b`        | F                       |
+| `0x3c`        | G                       |
+| `0x3d`        | H                       |
+| `0x3e`        | J                       |
+| `0x3f`        | K                       |
+| `0x40`        | L                       |
+| `0x41`        | ;                       |
+| `0x42`        | '                       |
+| `0x43`        | \                       |
+| `0x44`        | Num4                    |
+| `0x45`        | Num5                    |
+| `0x46`        | Num6                    |
+| `0x47`–`0x48` | (слепые)                |
+| `0x49`        | LShift                  |
+| `0x4a`        | Z                       |
+| `0x4b`        | X                       |
+| `0x4c`        | C                       |
+| `0x4d`        | V                       |
+| `0x4e`        | B                       |
+| `0x4f`        | N                       |
+| `0x50`        | M                       |
+| `0x51`        | ,                       |
+| `0x52`        | .                       |
+| `0x53`        | /                       |
+| `0x54`        | RShift                  |
+| `0x55`        | Enter                   |
+| `0x56`        | Num1                    |
+| `0x57`        | Num2                    |
+| `0x58`        | Num3                    |
+| `0x59`–`0x5a` | (слепые)                |
+| `0x5b`        | LCtrl                   |
+| `0x5c`        | LWin                    |
+| `0x5d`        | LAlt                    |
+| `0x5e`        | Space                   |
+| `0x5f`        | RAlt                    |
+| `0x60`        | Fn                      |
+| `0x61`        | Menu                    |
+| `0x62`        | RCtrl                   |
+| `0x63`        | ArrowLeft               |
+| `0x64`        | ArrowDown               |
+| `0x65`        | ArrowUp                 |
+| `0x66`        | ArrowRight              |
+| `0x67`        | Backspace               |
+| `0x68`        | Num0                    |
+| `0x69`        | Num. (Del)              |
+| `0x6a`        | NumEnter                |
+| `0x6b`–`0x6f` | (слепые)                |
+| `0x70`        | PrtSc                   |
+| `0x71`        | ScrLk                   |
+| `0x72`        | (слепой)                |
+| `0x73`        | Pause                   |
+| `0x74`        | Insert                  |
+| `0x75`        | Home                    |
+| `0x76`        | PgUp                    |
+| `0x77`        | Delete                  |
+| `0x78`        | End                     |
+| `0x79`        | PgDown                  |
+| `0x7a`        | Num-                    |
+| `0x7b`        | Num+                    |
+| `0x7c`–`0x8e` | (слепые)                |
+
+Итого **104 клавиши**, все 143 слота проверены, все физические клавиши светятся при полной заливке (проверено: «горят ВСЕ клавиши»).
+Нумпад полный: NumLock, /, *, -, 7/8/9, 4/5/6, 1/2/3, +, 0, ., Enter.
+
+**Слепые слоты** (39 шт, не соответствуют ни одному LED): 0x00, 0x0e–0x12, 0x23, 0x24, 0x35, 0x36, 0x47, 0x48, 0x59, 0x5a, 0x6b–0x6f, 0x72, 0x7c–0x8e.
+Хвост 0x80+ — резерв прошивки под большие раскладки/модели.
+
+**Аномалия 0x80:** в раннем тесте светился синим сам по себе; в финальном тесте (жёлтый) не горел.
+Считать слепым, но помнить про аномалию при чтении f5 (в потоке чтения 0x80 показывал 0000ff).
+
+**Урок картирования:** тёмные/холодные цвета (синий) на дальних клавишах пользователь может не заметить — Num- (0x7a) был пропущен в синем тесте, но найден жёлтым при перепроверке слепых слотов группами.
+При сомнениях перепроверять слепые слоты яркой заливкой группами.
+
+## Статус утилиты katana.py
+
+### `mode N --color RRGGBB [--brightness 1..15] [--speed 2..15] [--flag]`
+
+Валидация диапазонов.
+Для mode 1 speed форсируется 0x0A с warning.
+
+### `off`
+
+Payload нулей + aa55.
+
+### `default`
+
+Вендорский payload 0x80.
+
+### `raw HEX`
+
+Произвольный payload в транзакции.
+
+### `scan --from --to`
+
+Перебор режимов (1..19), каждый с save.
+
+### `reset`
+
+USB port reset (unwedge).
+
+### `paint --all RRGGBB [--key IDX=RRGGBB ...] [--black] [--keep] ...`
+
+Запись таблицы (143 клавиши) + показ mode 0x80.
+`--wasd` = четыре `--key` для W/A/S/D.
+`--numpad` = 17 `--key` для всего нумпада.
+`--alpha` = 26 `--key` для букв A–Z.
+`--punct` = 9 `--key` для знаков `[];',./\` и пробела.
+`--digits` = 13 `--key` для ряда `` `1234567890-= ``.
+`--arrows` = 4 `--key` для стрелок.
+`--row1..--row6` = `--key` для горизонтальных рядов полной клавиатуры, включая нумпад (104 клавиши; высокие клавиши нумпада отнесены к ряду начала; состав — ROW_KEYS в katana.py).
+`--keep` берёт базой текущий живой кадр (чтение f5), остальные клавиши сохраняют цвета.
+В `--key` индексы задаются только в hex (`0x25`), голые цифры — имена клавиш цифрового ряда.
+Клавиши со спецсимволами принимаются символом (`[`, `~`, `;`, ...), синонимом (`tilde`, `minus`, `lbracket`, `semicolon`, `backslash`, `numenter`, ... — таблица KEY_SYMBOL_ALIASES в keymap.py) и каноническим именем из keymap.py.
+
+### `keys`
+
+Чтение живого кадра (04 f5).
+
+### `remap --key KEY=ACTION [--key ...] [--clear]`
+
+Таблица переназначений (канал 04 11).
+ACTION: мышь (`lmb`/`mouse1`, `rmb`/`mouse2`, `mmb`/`mouse3`, `back`/`mouseback`, `forward`/`mouseforward`), шорткаты редактора (`open`/`new`/`undo`/`save`/`copy`/`cut`/`paste`/`find`/`selectall` — Ctrl+O/N/Z/S/C/X/V/F/A), мультимедиа (`player`, `play`, `stop`, `prev`, `next`, `volup`, `voldown`, `mute`, `home`, `refresh`, `webstop`, `webback`, `webforward`, `favorites`, `websearch`, `mycomputer`, `calculator`, `email`), горячие клавиши (`MOD+КЛАВИША`: `ctrl`/`shift`/`alt`/`meta` + `a`..`z`, `0`..`9`, `f1`..`f12`, `esc`, `tab`, `enter`, `space`, `caps`, `backspace`, `num0`..`num9`, `fn` — например `ctrl+c`, `shift+b`, `meta+e`), `default`/`none`/`off`, макросы (`macro<N>` — однократно, `macro<N>:K` — K повторов, `macro<N>-toggle` — до останова).
+`--clear` — вся таблица в default.
+ВАЖНО: каждый вызов перезаписывает всю таблицу — не указанные `--key` сбрасываются в default; чтение текущих переназначений неизвестно.
+
+### `macro set N [токены] [--xml FILE] [--save]`
+
+Записать содержимое макроса N (канал 04 19, без save — как вендор; `--save` шлёт 04 f0).
+Токены: `[+-]имя[@задержка_мс]` (`+` нажать, `-` отпустить, без знака — нажать и отпустить; имена — MACRO_KEYS/MOUSE_ACTIONS); перед токенами с `-` нужен `--`.
+ВАЖНО: перезаписываются ВСЕ слоты макросов — не указанные стираются.
+После записи привязать: `remap --key KEY=macro<N>`.
+
+### `macro clear [--save]`
+
+Стереть ВСЕ слоты макросов.
+
+### `macro show FILE` / `macro export FILE [токены] [--name]`
+
+Офлайн: показать события из вендорского XML / сгенерировать вендорский XML из токенов (без обращения к железу).
+
+## Инструменты анализа
+
+- `analyze_pcap.py <capture.pcapng> [out.txt]` — USBPcap → лог SET/GET control-трансферов (merged setup+data для OUT; GET по irpid).
+- `raw-data/*.txt` — распарсенные логи всех 5 захватов (katana1 + 4×katana2).
+- Захваты: `katana1.pcapng` (базовый реверс), `katana2-color-static` (цвета), `katana2-bright-static` (яркость), `katana2-speed` (скорость), `katana2-modes` (все режимы + off).
+  В режимах был случайный дубликат клика (mode 8 дважды).
+- Сессии записи таблицы клавиш в katana1: события #11 и #36 (0x23, блок 09).
+
+## Следующие шаги
+
+1. ~~Докартировать карту~~ — ЗАВЕРШЕНО (104 клавиши, keymap.py).
+2. ~~Починить чтение f5~~ — ЗАВЕРШЕНО (вендорская схема: SET f5 → 9 GET → commit → save; без begin/data-begin; ретраи с валидацией индексов).
+3. Именованные пресеты (WASD, дыхание и т.п.) поверх paint — keymap.py готов.
+4. ~~Переназначение клавиш: канал 04 20~~ — УТОЧНЕНО: канал `04 11` (не 04 20), формат и мышиные действия сняты и реализованы (см. «Переназначение клавиш»).
+   Шорткаты редактора (тип `02`) тоже сняты и реализованы (дамп keybind-editor).
+   Горячие клавиши (тип `02`, маска модификаторов в байте [1]) сняты по дампу keybind-hotkeys и реализованы (`HOTKEY_KEYS`/`HOTKEY_MODIFIERS`, `remap --key KEY=MOD+KEY`).
+   Осталось: другие типы действий (Fn-слой) и чтение таблицы.
+5. ~~Демо-скрипты (радуга, волна) поверх per-key API + живое чтение f5~~ — ЗАВЕРШЕНО, методика описана и проверена ([EXTENDING.md](EXTENDING.md)): таблица обновляется живьём в режиме 0x80, ~1 кадр/с.
+6. ~~Макросы: запись содержимого и привязка~~ — ЗАВЕРШЕНО (канал 04 19 + записи `[06, ...]` в 04 11, команда `macro`, см. «Макросы»).
+   Осталось: чтение содержимого, коллизия кодов 05/06, стрелки Up/Down, остальные медиа-коды.
+
+## Важные грабли (не наступать повторно)
+
+- pyusb + detach_kernel_driver = клавиатура перестаёт печатать.
+  Только hidraw.
+- Сессия без f0 = клин прошивки.
+  Всегда save.
+- После клина: reset может не помочь с первого раза — повторить с паузой 5–10 c.
+- f5-чтение без begin+data-begin = мусор (указатель не с начала).
+- begin ACK ff = «сессия уже открыта» — это ок, продолжать.
+- Слепые слоты молча игнорируются прошивкой (ACK ok, но не горят).
+- Пользователь различает цвета приблизительно: «розовый»=маджента, «жёлтый»=жёлтый/олива, «зелёный»=зелёный/тёмнозелёный.
+  Для картирования использовать максимально контрастные цвета и мало точек за раз.