Протокол GANSS ARDOR Katana¶

Клавиатура GANSS ARDOR_Katana (USB 0C45:8006, чип Sonix SN32) управляется HID feature-репортами: настройки подсветки, раскраска, переназначения и макросы передаются блоками по 64 байта.

Протокол восстановлен по дампам USB-трафика вендорской утилиты и проверен на железе. Ниже — общая картина; детали разобраны на отдельных страницах.

Интерфейсы¶

Интерфейс	Назначение	Канал
iface0	boot keyboard + конфиг-канал	feature-репорты `rid=0`, 64 байта данных
iface1	consumer/mouse	vendor page `0xFF00`, `rid=5`, только input

Работа идёт только с интерфейсом 0. Узел /dev/hidrawN ищется через /sys/class/hidraw/*/device по родителю *:1.0 и modalias hid:b0003g0001v00000C45p00008006. Интерфейс 1 несёт consumer/mouse-репорты и в настройке не участвует.

Транспорт¶

На Linux обмен идёт через hidraw-ioctl (HIDIOCSFEATURE и HIDIOCGFEATURE), буфер — 65 байт, первый байт равен report id 0. Драйвер usbhid при этом не отцепляется, поэтому печать не прерывается. Между запросами выдерживается пауза 0,04 с — вендорский тайминг.

На macOS используется тот же протокол поверх IOKit (IOHIDDeviceSetReport и IOHIDDeviceGetReport) с типом репорта kIOHIDReportTypeFeature. Транспорт выбирается автоматически по sys.platform.

Подробнее — в разделе Транспорт и транзакции.

Транзакция¶

Любая запись настроек состоит из одинаковых шагов.

SET 04 18                          begin            ACK: 04 18 00 01 (или ff = сессия уже открыта)
SET 04 13 00*6 01                  data-begin       ACK: 04 13 00 01
SET <payload 64B>                  данные           (без ACK)
SET 04 02                          commit           ACK: 04 02 00 01 <LE16 sum(payload)>
SET 04 f0                          save (flash)     ACK: 04 f0 00 01

Байт [3] в ACK: 01 — успех, 00 или ff — отказ.
Контрольная сумма — sum(payload) & 0xFFFF в байтах 4–5 ACK коммита, порядок little-endian.
Байт [8] команды data-begin задаёт параметр блока: у таблиц раскраски и переназначений это число пакетов 09, у макросов — фактическое число пакетов.
Сессию всегда закрывайте командой 04 f0, иначе прошивка залипает и перестаёт принимать команды.
Вендорская утилита шлёт полную транзакцию даже для одной настройки; проект повторяет это поведение.

Каналы¶

Канал	Что делает	Страница
`04 18`	открытие обычной сессии	Транспорт
`04 13`	data-begin обычного блока	Транспорт
`04 02`	commit с контрольной суммой	Транспорт
`04 f0`	сохранение области во флеш	Транспорт
`04 23`	запись таблицы раскраски	Раскраска клавиш
`04 f5`	чтение живого кадра	Раскраска клавиш
`04 20`	стриминг кадров per-key анимации	Раскраска клавиш
`04 11`	запись таблицы переназначений	Переназначение
`04 19`	запись содержимого макросов	Макросы
`04 15`	data-begin блока макросов	Макросы

Состояние реверса¶

Что установлено твёрдо:

транспорт и полная транзакция;
формат lighting-payload'а и все 19 режимов;
таблица раскраски и чтение живого кадра;
форматы записей переназначения для мыши, шорткатов, мультимедиа и макросов;
блоб макросов и вендорский XML;
карта из 104 физических клавиш и 39 слепых слотов.

Что осталось открытым:

чтение таблицы переназначений и содержимого макросов;
Fn-слой и прочие типы действий;
полный лимит макросов и семантика задержек;
коллизия кодов 05 и 06 в макросах.

Открытые задачи собраны в конце страницы Реверс-инжиниринг.

Важные грабли¶

pyusb с detach_kernel_driver ломает печать: используйте только hidraw.
Сессия без 04 f0 клинит прошивку; лечение — команда reset.
Перед чтением 04 f5 нельзя делать begin и data-begin: поток возвращает эхо последнего SET.
Ответ ff на begin означает «сессия уже открыта» — это нормально, работу можно продолжать.
Слепые слоты прошивка принимает молча, но они ни к какому светодиоду не подключены.
Пользователь различает цвета приблизительно: для картирования нужны контрастные цвета и мало точек за раз.