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

Репозиторий katana.py содержит утилиту, вспомогательные скрипты, офлайн-тесты и дампы. Документация по командам и протоколу живёт на этом сайте, а в репозитории остаются только сведения о запуске и отладке.

Структура¶

.
├── 70-ganss-katana.rules    udev-правило
├── requirements.txt         pyusb и PyYAML
├── katana.yaml.example      пример YAML-профиля
├── katana.py                основная утилита
├── misc/
│   ├── dataset.py           пути к дампам из manifest.json
│   ├── keymap.py            карта LED-индексов
│   ├── analyze_pcap.py      парсер USBPcap
│   ├── probe.py             чтение feature-репортов
│   ├── iokit_probe.py       диагностика HID на macOS
│   ├── make_ts_fixtures.py  фикстуры для тестов приложения
│   ├── make_layout.py       геометрия клавиатуры для окна
│   └── katana-v1/           правки вендорской утилиты
├── tests/                   офлайн-тесты
│   └── fake_device.py       подменное устройство, общий код тестов
├── raw-data/
│   └── katana-v1/           дампы и manifest.json
└── docs/                    краткие сведения о запуске и отладке

misc/dataset.py¶

Читает raw-data/katana-v1/manifest.json и отдаёт пути к дампам. Скрипты и тесты не содержат имён файлов, поэтому переименование дампа правится в одном месте.

from misc import dataset

dataset.set_dir("keybind")
dataset.ref("xml-macro1")

Состав манифеста и назначение наборов описаны в разделе Дампы.

misc/keymap.py¶

Карта LED-индексов, снятая экспериментально. Утилита использует её для имён клавиш, а отдельный запуск печатает карту, список слепых слотов и таблицу алиасов:

./misc/keymap.py

misc/analyze_pcap.py¶

Парсер захватов USBPcap в человекочитаемый лог control-трансферов.

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

Без второго аргумента результат пишется в /tmp/tx_log.txt.

misc/probe.py¶

Минимальный пример hidraw-транспорта: перебирает report id и читает feature-репорты. Состояние клавиатуры не меняет.

./misc/probe.py [hidrawN]

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

misc/iokit_probe.py¶

Диагностика macOS: открывает HID-сервис через IOKit и печатает точный код IOReturn.

.venv/bin/python misc/iokit_probe.py

misc/make_ts_fixtures.py¶

Готовит фикстуры для тестов приложения из датасета и katana.py.

.venv/bin/python misc/make_ts_fixtures.py            # записать
.venv/bin/python misc/make_ts_fixtures.py --check    # только сверить
.venv/bin/python misc/make_ts_fixtures.py --out DIR  # другой каталог

По умолчанию результат пишется в ../studio/tests/fixtures.

misc/make_layout.py¶

Собирает геометрию клавиатуры для окна приложения из правленой раскладки вендорской утилиты.

.venv/bin/python misc/make_layout.py
.venv/bin/python misc/make_layout.py --out FILE

Результат — список клавиш {idx, label, x, y, w, h}, где idx равен LED-индексу. Подписи клавиш правятся в словаре LABELS этого скрипта.

misc/katana-v1/¶

Патчи для вендорской утилиты, а не код проекта:

• исправленный перевод интерфейса;
• фикс раскладки: Fn больше не применяется к правому Alt, поправлены подписи.

Тесты¶

Тесты офлайновые: железо не нужно.

python3 tests/test_macro.py      # макросы, действия, сверка с дампами
python3 tests/test_apply.py      # YAML-профиль → argv команд
python3 tests/test_parsers.py    # парсеры, payload, ACK, keymap
python3 tests/test_cli.py        # команды на подменном устройстве
python3 tests/test_transport.py  # выбор транспорта, IOKit

tests/fake_device.py — не тест, а общий код: подменное устройство FakeKatana и прогон аргументов. Им пользуются и test_cli.py, и генератор фикстур.

Каждый файл запускается и напрямую, и через pytest:

.venv/bin/python -m pytest

Пути к дампам берутся через misc/dataset.py, а не задаются строками.

Использование как библиотеки¶

Свои скрипты и анимации описаны в разделе Свои скрипты.