6.1 KiB
Скрипты репозитория
Состав репозитория и назначение каждого скрипта.
Использование katana.py как библиотеки (свои скрипты и анимации) — в 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 (раздел «Карта клавиш»).
analyze_pcap.py
Парсер захватов USBPcap (pcapng) в человекочитаемый лог control-трансферов.
Нужен только при пополнении raw-data/ новыми дампами:
./analyze_pcap.py <вход.pcapng> [выход.txt]
Без второго аргумента пишет /tmp/tx_log.txt.
Формат строк и методика снятия захватов — в 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 (если установлен).