Утилита katana.py¶
katana.py настраивает подсветку, раскраску, переназначения и макросы клавиатуры GANSS ARDOR_Katana прямо из Linux или macOS.
Виртуальная машина с Windows и фирменная утилита не нужны.
Обмен идёт HID feature-репортами через штатный драйвер usbhid.
Драйвер не отцепляется, поэтому печатать можно прямо во время настройки, а root нужен только для разовой установки udev-правила.
Репозиторий утилиты содержит код, тесты, дампы и краткие сведения о запуске и отладке. Полная документация по командам, режимам, протоколу и расширению живёт на этом сайте.
Возможности¶
- 19 режимов подсветки, выключение и вендорский сброс;
- яркость от 1 до 15 и скорость анимации от 2 до 15;
- направление анимации для пяти режимов;
- покраска каждой из 104 клавиш своим цветом;
- переназначение клавиш на мышь, функции редактора, горячие клавиши, мультимедиа и макросы;
- макросы в прошивке, импорт и экспорт XML вендорской утилиты;
- чтение текущего состояния подсветки;
- применение всех настроек одним YAML-файлом.
Требования¶
| Компонент | Версия или примечание |
|---|---|
| Python | 3.10 и новее |
pyusb |
только для команды reset |
PyYAML |
только для команды apply |
| Linux | hidraw и udev-правило 70-ganss-katana.rules |
| macOS | IOKit и разрешение «Input Monitoring», экспериментально |
Быстрый старт¶
Все команды выполняются из корня репозитория katana.py.
# 1. установка
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
sudo cp 70-ganss-katana.rules /etc/udev/rules.d/ && sudo udevadm trigger
# 2. подсветка
./katana.py mode breathing --color red --no-spectrum
./katana.py paint --black --wasd dodgerblue
./katana.py keys
# 3. переназначение
./katana.py remap --key caps=copy
./katana.py remap --key menu=meta+e
# 4. макросы
./katana.py macro set 0 -- a@126 s@101 -a@41
./katana.py remap --key caps=macro0
# 5. всё сразу из YAML
./katana.py apply ~/my-katana.yaml
Карта документации¶
| Документ | Тема |
|---|---|
| Установка | Зависимости, venv, udev-правило, проверка устройства, macOS. |
| Команды | Справочник команд и аргументов. |
| Режимы подсветки | Таблица 19 режимов и наблюдения по живым кадрам. |
| Именованные цвета | 147 имён CSS вместо RRGGBB. |
| Имена клавиш | Канонические имена, символы, синонимы и hex-индексы. |
| Свои скрипты | katana.py как библиотека, ограничения и готовые приёмы. |
| Скрипты репозитория | Вспомогательные скрипты, тесты и структура каталогов. |
| Дампы | Сырые захваты USB-трафика и работа с ними. |
| Протокол | Низкоуровневое описание обмена с прошивкой. |
| Запуск и отладка | Общие команды запуска, проверки и отладки в VS Code. |
Графическое приложение¶
Katana Studio повторяет возможности CLI в окне на Electron.
Профиль у приложения тот же, но две секции названы по-старому: lighting и macros вместо mode и macro, поэтому apply такой файл отклонит.
Описание приложения — в разделе Katana Studio.
Использованный стек¶
- Python 3.10,
pyusbиPyYAML; - Linux: hidraw-ioctl;
- macOS: IOKit через
ctypes; - VirtualBox с Windows 11, вендорская утилита и Wireshark с USBPcap для снятия дампов.
Предостережение¶
Утилита проверена на одном экземпляре клавиатуры. Автор не гарантирует работу на другом устройстве, достоверность сведений о протоколе и совместимость с другими моделями Ardor.
Все операции с оборудованием выполняются на ваш страх и риск.