Настройка клавиатуры GANSS ARDOR Katana из Linux

Настраивайте RGB-подсветку и клавиши клавиатуры GANSS ARDOR_Katana (продаётся также как ARDOR Gaming Katana) прямо из Linux — без виртуальной машины с Windows и фирменной утилиты.

Что умеет утилита katana.py:

19 режимов подсветки (дыхание, волна, водопад, бегущая строка и другие), выключение подсветки;
яркость (1–15) и скорость анимации (2–15), направление анимации в некоторых режимах;
покраска каждой из 104 клавиш в свой цвет;
переназначение любой клавиши на кнопку мыши, функцию текстового редактора (копировать/вставить/...), горячую клавишу (Ctrl+C, Win+E, ...), мультимедиа-действие (громкость, плеер, ...) или макрос;
макросы: последовательности нажатий хранятся в самой прошивке, есть импорт/экспорт XML фирменной утилиты;
чтение текущего состояния подсветки.

Подсветка и клавиши управляются HID feature-репортами через штатный драйвер usbhid — печатать можно прямо во время настройки, драйвер не отцепляется, root не нужен (после разовой установки udev-правила).

macOS поддерживается экспериментально (транспорт IOKit, см. docs/install.md → «Установка на macOS»).

Характеристика	Значение
Устройство	GANSS ARDOR_Katana
USB ID	`0C45:8006` (Sonix SN32)
Канал	feature-репорты `rid=0`, интерфейс 0, payload 64 байта

Быстрый старт

# 1. установка (подробности — docs/install.md)
python3 -m venv .venv && .venv/bin/pip install pyusb
sudo cp 70-ganss-katana.rules /etc/udev/rules.d/ && sudo udevadm trigger

# 2. подсветка (подробности — docs/color-modes.md)
./katana.py mode breathing --color red        # дыхание красным
./katana.py paint --black --wasd dodgerblue   # чёрная база, WASD голубым
./katana.py keys                              # посмотреть, что сейчас светится

# 3. переназначение клавиш (подробности — docs/cli/remap.md)
./katana.py remap --key caps=copy             # Caps → копировать (Ctrl+C)
./katana.py remap --key menu=meta+e           # Menu → горячая клавиша Win+E

# 4. макросы (подробности — docs/cli/macro.md)
./katana.py macro set 0 -- a@126 s@101 -a@41  # макрос 0: нажать A, S, отпустить A
./katana.py remap --key caps=macro0           # привязать макрос к Caps

# 5. всё сразу из YAML-конфига (подробности — docs/cli/apply.md)
./katana.py apply ~/my-katana.yaml            # макросы + переназначение + подсветка

Если что-то не работает — загляните в docs/install.md (разделы «Проверка устройства» и решение проблем) и в справочник команд docs/cli/README.md.

Документация

Документы разложены по темам в docs/, каждый можно читать независимо.

Документ	Тема
docs/install.md	Установка: зависимости, venv, udev-правило, проверка устройства, решение проблем.
docs/color-modes.md	19 режимов подсветки: таблица, примеры `mode`, аргументы, направление анимации.
docs/cli/README.md	Справочник `katana.py`: именованные цвета, имена клавиш, `paint`/`scan`/`raw`/`remap`/`macro`/`keys`/`reset`, решение проблем.
docs/cli/remap.md	Переназначение клавиш: мышь, редактор, горячие клавиши, мультимедиа, макросы.
docs/cli/macro.md	Макросы: запись, режимы повтора, XML вендора.
docs/cli/apply.md	`apply` — YAML-конфиг: все настройки одним файлом.
docs/extending.md	Свои скрипты и анимации: `katana.py` как библиотека, API `Katana`, ограничения скорости и флеша, готовые приёмы.
docs/protocol.md	Протокол для реверсеров: транспорт, транзакции, форматы payload'ов, карта клавиш, статус реверса, грабли, планы.
docs/scripts.md	Состав репозитория и вспомогательные скрипты: `keymap.py`, `analyze_pcap.py`, `misc/probe.py`.
docs/raw-data.md	Дампы USB-трафика вендорской утилиты: как снимались, как конвертировать, состав `raw-data/katana-v1/`.

Лицензия

Copyright (C) 2026 Антон Аксенов (Anthony Axenov)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

ПО распространяется под лицензией GNU GPL v3.

Производное ПО обязано быть с открытым исходным кодом.

Предостережение

Это исследовательский проект, который я давно хотел воплотить. У меня есть такая клавиатура, но в Linux нет возможности настраивать её.

Я не могу гарантировать и не гарантирую:

работу скриптов на другом ПК с такой же клавиатурой;
достоверность сведений о протоколе обмена данными;
совместимость с другими клавиатурами Ardor.

ВСЕ ОПЕРАЦИИ С ВАШИМ ОБОРУДОВАНИЕМ - НА ВАШ СТРАХ И РИСК.

Использованный стек

AI-модель koda-pro через KodaCode
python 3.10 + pyusb + pyyaml
Linux (hidraw-ioctl) и macOS (IOKit через ctypes, экспериментально)
VirtualBox + Windows 11:
- штатная утилита конфигурации клавиатуры
- WireShark с установленным usbpcap

TODO

переназначение на другие типы действий (Fn-слой) и чтение таблицы переназначений — мышиные действия, шорткаты редактора, горячие клавиши, мультимедиа и макросы реализованы (docs/cli/remap.md, docs/cli/macro.md)
макросы: чтение содержимого из прошивки, коллизия кодов громкости и букв B/C, стрелки Up/Down, остальные медиа-коды (docs/protocol.md → «Макросы»)
пресеты/анимации поверх per-key API — методика описана в docs/extending.md.

Cм. docs/protocol.md → «Следующие шаги»

9.5 KiB Raw Permalink Blame History