92 lines
6.1 KiB
Markdown
92 lines
6.1 KiB
Markdown
# Скрипты репозитория
|
|
|
|
Состав репозитория и назначение каждого скрипта.
|
|
Использование `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 (если установлен).
|