ardor-katana-linux/docs/cli/apply.md

apply — применение YAML-конфига

Применяет конфиг из YAML-файла: вместо длинных команд — один файл со всеми настройками. Файл можно хранить в любом месте (например ~/.config/katana.yaml), в репозитории лежит пример katana.yaml.example.

./katana.py apply ~/my-katana.yaml        # применить конфиг
./katana.py apply katana.yaml.example     # применить пример из репозитория

Зависимость: PyYAML (pip install pyyaml, см. 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)

Все слоты пишутся одним блобом (пропуски между номерами — пустые слоты). Ключ — номер слота 0..99, значение — tokens (список) или xml (файл).

macros:
  0:
    tokens: ["+lctrl", "a@50", "-lctrl"]   # Ctrl+A
  1:
    xml: raw-data/katana-v1/test.xml

remap — переназначение клавиш (см. remap.md)

remap:
  keys:
    caps: macro0       # КЛЮЧ: ДЕЙСТВИЕ — те же, что у remap --key
    menu: meta+e
  # clear: true        # вместо keys: сбросить ВСЕ переназначения

paint — раскраска клавиш (см. paint.md)

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)

mode — имя или номер 1..19, а также off и default (применяются как команды off/default).

lighting:
  mode: static
  color: red
  brightness: 15       # 1..15
  # speed: 5           # 2..15
  # rainbow: true      # статика: спектр вместо color
  # direction: north-south

raw — сырой payload (см. raw.md)

raw: "80 00 ... aa 55"   # hex-строка или список строк

Валидация

• Неизвестные секции и неизвестные ключи внутри секций отклоняются с указанием опечатки.
• macros: слот должен иметь либо tokens, либо xml (не оба и не ни одного).
• Значения проверяются тем же парсером, что и CLI-команды (parse_color, parse_mode, диапазоны).

Офлайн-тесты — tests/test_apply.py (пример конфига разбирается и превращается в валидные argv).