# Скрипты репозитория

Состав репозитория и назначение каждого скрипта.
Использование `katana.py` как библиотеки (свои скрипты и анимации) — в [EXTENDING.md](EXTENDING.md).

## Структура репозитория

```
.
├── katana.py                Основная CLI-утилита управления подсветкой
├── keymap.py                Карта «LED-индекс → физическая клавиша» (104 клавиши)
├── katana.yaml.example      Пример YAML-конфига для команды apply
├── analyze_pcap.py          Парсер USBPcap-захватов → лог control-трансферов
├── probe.py                 Исследовательский зонд: чтение feature-репортов
├── 70-ganss-katana.rules    udev-правило: доступ к устройству без root
├── tests/                   Офлайн-тесты (без железа)
├── docs/                    Документация (см. README.md)
└── raw-data/
    └── katana-v1/           Сырые дампы (pcapng + распарсенные логи)
```

## keymap.py

Карта LED-индексов, снятая экспериментально (покраска групп индексов контрастными цветами + фиксация, какие клавиши загорелись).
Используется `katana.py` для имён клавиш; отдельно запускается для просмотра:

```
./keymap.py
```

Печатает подтверждённую карту, список слепых слотов (39 шт — резерв прошивки, ни к какому LED не подключены), непроидентифицированные индексы и таблицу алиасов клавиш (`KEY_SYMBOL_ALIASES`).
Методика картирования и открытые вопросы — в [PROTOCOL.md](PROTOCOL.md) (раздел «Карта клавиш»).

## analyze_pcap.py

Парсер захватов USBPcap (pcapng) в человекочитаемый лог control-трансферов.
Нужен только при пополнении `raw-data/` новыми дампами:

```
./analyze_pcap.py <вход.pcapng> [выход.txt]
```

Без второго аргумента пишет `/tmp/tx_log.txt`.
Формат строк и методика снятия захватов — в [RAW-DATA.md](RAW-DATA.md).

## probe.py

Исследовательский зонд времён начала реверса: перебирает report id и читает feature-репорты (только GET, состояние клавиатуры не меняет).
Полезен как минимальный пример hidraw-транспорта:

```
./probe.py [hidrawN]
```

Без аргумента находит все hidraw-узлы клавиатуры сам.

## tests/

Офлайн-тесты (железо не нужно):

```
python3 tests/test_macro.py      # макросы, remap-действия, сверка с дампами
python3 tests/test_apply.py      # apply: YAML-конфиг → argv команд
python3 tests/test_parsers.py    # парсеры, payload, ACK, keymap
python3 tests/test_cli.py        # команды CLI на подменном устройстве
```

`test_macro.py` — блоб, собранный из вендорских XML, сверяется побайтово с дампом macros-create, плюс разбор токенов, round-trip XML, hotkey/remap-действия и сверка с дампами keybind-editor/keybind-hotkeys/keybind-multimedia.
`test_apply.py` — пример katana.yaml.example разбирается и превращается в валидные argv существующих команд, проверка отклонения опечаток и неизвестных секций.
`test_parsers.py` — parse_color/parse_mode/check_range, resolve_key (имена, символы, алиасы, hex-индексы), раскладка lighting payload, номера hidraw ioctl, статические проверки ACK Katana и целостность keymap.py (карта, слепые слоты, алиасы, группы клавиш paint).
`test_cli.py` — команды mode/off/default/raw/scan/reset/paint/keys/remap/macro/apply прогоняются через build_parser() и dispatch() с подменным устройством (FakeKatana пишет вызовы в журнал): формирование payload'ов, вендорские дефолты статики, направления анимаций, раскрытие shorthand-групп paint, записи всех типов действий remap, порядок секций и расстановка save'ов в apply, сообщения об ошибках.

Каждый файл запускается и напрямую (`python3 tests/...`), и через pytest (если установлен).