Initial commit

2026-09-06 01:06:40 +08:00
commit 57c4e80f0d
69 changed files with 20940 additions and 0 deletions
@@ -0,0 +1,69 @@
+# macro — макросы
+
+Записывает содержимое макросов в прошивку (канал 04 19) и работает с вендорским XML.
+Формат протокола — в [PROTOCOL.md](../PROTOCOL.md).
+
+Макрос нужно привязать к клавише через `remap --key КЛЮЧ=macro<N>` (индексация 0-based: «Макрос 1» вендорской утилиты = 0).
+
+```
+./katana.py macro set 0 -- a@126 s@101 -a@41 f    # макрос 0 из токенов
+./katana.py macro set 0 --xml test.xml            # макрос 0 из вендорского XML
+./katana.py remap --key caps=macro0               # привязать к Caps
+./katana.py macro clear                           # стереть все макросы
+./katana.py macro show test.xml                   # показать события из XML (офлайн)
+./katana.py macro export my.xml -- +lctrl a@50 -lctrl   # сгенерировать XML (офлайн)
+```
+
+## Токены событий
+
+Токен: `[+-]имя[@задержка_мс]`.
+`+` — нажать, `-` — отпустить, без знака — нажать и отпустить (задержка ставится на отпускание).
+Задержка — пауза в мс после события.
+Перед токенами, начинающимися с `-`, ставьте разделитель `--`, иначе argparse примет их за опции.
+
+Разбор примера `a@126 s@101 -a@41`:
+
+| Токен   | Что делает                                                    |
+| ------- | ------------------------------------------------------------- |
+| `a@126` | нажать и отпустить `A`, после отпускания пауза 126 мс         |
+| `s@101` | нажать и отпустить `S`, пауза 101 мс                          |
+| `+a`    | только нажать `A` (отпустить позже через `-a`)                |
+| `-a@41` | только отпустить `A` (зажатую раньше через `+a`), пауза 41 мс |
+
+Пример сочетания с модификатором: `+lctrl a@50 -lctrl` — зажать Ctrl, нажать-отпустить A, отпустить Ctrl (Ctrl+A).
+
+Имена клавиш — строчные: буквы `a`–`z`, цифры `1`–`0`, `f1`–`f12`, модификаторы (`lctrl`, `lshift`, `lalt`, `lwin`, `rctrl`, ...), `esc`, `tab`, `enter`, `backspace`, `caps`, `space`, стрелки (`left`, `up`, `right`, `down` — собственные коды прошивки, Up/Down не проверены), громкость (`volup`, `voldown`).
+Кнопки мыши — те же имена, что в `remap`: `lmb`, `rmb`, `mmb`, `back`, `forward`.
+
+## Аргументы `macro set`
+
+### `index`
+
+Слот макроса (0-based), `0`–`99`.
+
+### `tokens`
+
+События макроса (см. «Токены событий» выше).
+Указывается либо `tokens`, либо `--xml`.
+
+### `--xml ФАЙЛ`
+
+Взять события из вендорского XML.
+
+### `--save`
+
+Отправить `04 f0` после коммита.
+По умолчанию выключено: вендор после записи макросов save НЕ делает.
+
+**Важно:** запись перезаписывает ВСЕ слоты макросов — макросы в других слотах стираются.
+Несколько макросов записывайте за один вызов (apply так и делает) — см. [apply.md](apply.md).
+Ёмкость по дампу — 896 байт блоба: до ~60 событий в один слот.
+Чтение содержимого из прошивки не реализовано (канал чтения неизвестен).
+Save (`--save`) по умолчанию выключен (как у вендора), но макросы переживают переподключение **только со своим save** — у каждой области прошивки свой save (см. [apply.md](apply.md) → «Порядок применения и сохранение»).
+После записи макросов bind-таблица и режим подсветки сбиваются в RAM — перепошлите их (remap + mode).
+
+## `macro show` и `macro export`
+
+Обе команды работают офлайн, без обращения к клавиатуре.
+`show файл.xml` печатает события в форме токенов.
+`export файл.xml [токены] [--name ИМЯ]` создаёт вендорский XML — такие файлы понимает фирменная утилита.