102 lines
5.5 KiB
Markdown
102 lines
5.5 KiB
Markdown
# apply — применение YAML-конфига
|
|
|
|
Применяет конфиг из YAML-файла: вместо длинных команд — один файл со всеми настройками.
|
|
Файл можно хранить в любом месте (например `~/.config/katana.yaml`), в репозитории лежит пример [katana.yaml.example](../../katana.yaml.example).
|
|
|
|
```
|
|
./katana.py apply ~/my-katana.yaml # применить конфиг
|
|
./katana.py apply katana.yaml.example # применить пример из репозитория
|
|
```
|
|
|
|
Зависимость: PyYAML (`pip install pyyaml`, см. [install.md](../install.md)).
|
|
|
|
## Порядок применения и сохранение
|
|
|
|
Секции применяются всегда в одном порядке, независимо от их порядка в файле:
|
|
|
|
1. `remap` — таблица переназначений (04 11), save;
|
|
2. `paint` — per-key раскраска, включает режим 0x80, save;
|
|
3. `lighting` — финальный режим подсветки (mode/off/default), перекрывает 0x80 от paint, save;
|
|
4. `raw` — произвольный payload (для экспериментов);
|
|
5. `macros` — ВСЕ слоты одним блобом (04 19), save;
|
|
6. `remap` и `lighting` — **повторно** (если секции были в конфиге), со save.
|
|
|
|
**Модель сохранения** (проверена на железе): каждая область прошивки (bind-таблица, paint-таблица, режим, макросы) сохраняется во флеш **только своим собственным save** (04 f0) — чужой save чужую область ни сохраняет, ни затирает. Поэтому в apply каждая секция несёт свой save.
|
|
|
|
**Почему remap и lighting повторяются после макросов:** запись макросов (04 19) сбивает bind-таблицу и режим подсветки **в RAM** (во флеше они остаются). Повторная отправка восстанавливает их в RAM и заодно фиксирует save'ом.
|
|
|
|
**Почему все макросы одним блобом:** каждый вызов `macro set` обнуляет прочие слоты — несколько макросов нужно писать за одну транзакцию (apply так и делает).
|
|
|
|
Ключ `save` в секциях конфига **не поддерживается** — apply управляет save'ами сам (написанный по ошибке `save: false` отклоняется как неизвестный ключ).
|
|
|
|
Каждая секция прогоняется через соответствующую команду CLI — валидация значений та же самая.
|
|
Перед каждым шагом печатается `apply [...] ...`, после — итоговый список применённого.
|
|
|
|
Команды `keys`, `scan`, `reset` в конфиге не нужны: это диагностика, а не состояние.
|
|
|
|
## Секции
|
|
|
|
### `macros` — содержимое макросов (см. [macro.md](macro.md))
|
|
|
|
Все слоты пишутся **одним блобом** (пропуски между номерами — пустые слоты).
|
|
Ключ — номер слота 0..99, значение — `tokens` (список) или `xml` (файл).
|
|
|
|
```yaml
|
|
macros:
|
|
0:
|
|
tokens: ["+lctrl", "a@50", "-lctrl"] # Ctrl+A
|
|
1:
|
|
xml: raw-data/katana-v1/test.xml
|
|
```
|
|
|
|
### `remap` — переназначение клавиш (см. [remap.md](remap.md))
|
|
|
|
```yaml
|
|
remap:
|
|
keys:
|
|
caps: macro0 # КЛЮЧ: ДЕЙСТВИЕ — те же, что у remap --key
|
|
menu: meta+e
|
|
# clear: true # вместо keys: сбросить ВСЕ переназначения
|
|
```
|
|
|
|
### `paint` — раскраска клавиш (см. [paint.md](paint.md))
|
|
|
|
```yaml
|
|
paint:
|
|
all: black # база (или black: true / keep: true)
|
|
keys:
|
|
esc: "ff0000" # КЛЮЧ: ЦВЕТ
|
|
wasd: dodgerblue # shorthand-алиасы CLI: wasd, numpad, alpha, punct, digits, arrows
|
|
rows:
|
|
1: "202020" # ряды 1..6
|
|
brightness: 15
|
|
```
|
|
|
|
### `lighting` — режим подсветки (см. [color-modes.md](../color-modes.md))
|
|
|
|
`mode` — имя или номер 1..19, а также `off` и `default` (применяются как команды `off`/`default`).
|
|
|
|
```yaml
|
|
lighting:
|
|
mode: static
|
|
color: red
|
|
brightness: 15 # 1..15
|
|
# speed: 5 # 2..15
|
|
# rainbow: true # статика: спектр вместо color
|
|
# direction: north-south
|
|
```
|
|
|
|
### `raw` — сырой payload (см. [raw.md](raw.md))
|
|
|
|
```yaml
|
|
raw: "80 00 ... aa 55" # hex-строка или список строк
|
|
```
|
|
|
|
## Валидация
|
|
|
|
- Неизвестные секции и неизвестные ключи внутри секций отклоняются с указанием опечатки.
|
|
- `macros`: слот должен иметь либо `tokens`, либо `xml` (не оба и не ни одного).
|
|
- Значения проверяются тем же парсером, что и CLI-команды (`parse_color`, `parse_mode`, диапазоны).
|
|
|
|
Офлайн-тесты — `tests/test_apply.py` (пример конфига разбирается и превращается в валидные argv).
|