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

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

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

```
.
├── 70-ganss-katana.rules    udev-правило: доступ к устройству без root
├── katana.yaml.example      Пример YAML-конфига для команды apply
├── katana.py                Основная CLI-утилита управления подсветкой
├── misc/
│   ├── keymap.py            Карта «LED-индекс → физическая клавиша» (104 клавиши)
│   ├── analyze_pcap.py      Парсер USBPcap-захватов → лог control-трансферов
│   ├── probe.py             Исследовательский зонд: чтение feature-репортов
│   └── iokit_probe.py       Диагностика открытия HID на macOS (код IOReturn)
├── 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).

## misc/probe.py

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

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

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

## misc/iokit_probe.py

Диагностика macOS-only: открывает HID-сервис клавиатуры через IOKit напрямую
(ctypes, сторонних библиотек не нужно) и печатает точный код `IOReturn` от
`IOHIDDeviceOpen`. Полезен, когда katana.py сообщает только «open failed»:

```
.venv/bin/python misc/iokit_probe.py
```

Интерпретация результата: `0x00000000` — права есть (проблема в софте),
`0xE00002C1` — нет разрешения «Input Monitoring»,
`0xE00002C5` (`kIOReturnExclusiveAccess`) — устройство захвачено монопольно
(типичный случай — Karabiner-Elements).

## 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 на подменном устройстве
python3 tests/test_transport.py  # выбор транспорта Linux/macOS, IOKit-обмен
```

`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 (если установлен).