ardor-katana-linux/README.md

# Настройка клавиатуры 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](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/install.md) (разделы «Проверка устройства» и решение проблем) и в справочник команд [docs/cli/README.md](docs/cli/README.md).

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

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

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

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

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

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

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

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

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

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

## TODO

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

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