# 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 — такие файлы понимает фирменная утилита.