Установка¶

Зависимости¶

Нужен Python 3.10 или новее. Зависимости: pyusb для команды reset и PyYAML для команды apply. Сам транспорт работает на fcntl-ioctl к /dev/hidraw* на Linux или через IOKit на macOS.

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

udev-правило¶

Без правила доступ к /dev/hidraw* есть только у root. Файл 70-ganss-katana.rules даёт доступ группе plugdev и через uaccess:

SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0c45", ATTRS{idProduct}=="8006", MODE="0660", GROUP="plugdev", TAG+="uaccess"
SUBSYSTEM=="usb",    ATTRS{idVendor}=="0c45", ATTRS{idProduct}=="8006", MODE="0660", GROUP="plugdev", TAG+="uaccess"

Первая строка открывает hidraw-узлы, вторая нужна только для команды reset.

sudo cp 70-ganss-katana.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

После установки переподключите клавиатуру. Если пользователь не входит в группу plugdev, выполните sudo usermod -aG plugdev $USER и перелогиньтесь. Проверка: команда ./katana.py mode ... должна работать без sudo.

Проверка устройства¶

Проще всего проверить наличие клавиатуры по USB ID:

lsusb | grep -i 0c45

Ожидаемый вывод:

Bus 001 Device 028: ID 0c45:8006 Microdia Dual Mode Camera (8006 VGA)

Подпись про камеру — норма. ID 0c45:8006 принадлежит чипу Sonix SN32, который ставится и в вебкамеры, и в клавиатуры. Реальный тип устройства виден по интерфейсам:

lsusb -d 0c45:8006 -v
usb-devices | grep -B 2 -A 8 'Vendor=0c45'

У клавиатуры должно быть два HID-интерфейса: boot keyboard и mouse/consumer.

macOS¶

Поддержка экспериментальная. Транспорт работает через IOKit напрямую, сторонние HID-библиотеки не обязательны, udev-правило не нужно.

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Опционально можно установить hidapi (pip install hid): тогда интерфейс 0 ищется точнее, по registry entry ID.

macOS выдаёт доступ к HID-клавиатурам вручную:

1. откройте «Системные настройки» → «Конфиденциальность и безопасность» → «Input Monitoring»;
2. добавьте приложение, из которого запускается katana.py (Terminal, iTerm2, VS Code);
3. включите разрешение и перезапустите приложение.

Без разрешения утилита выведет подсказку.

Утилиты, перехватывающие клавиатуры, открывают их монопольно. Пока Karabiner-Elements работает, открыть устройство нельзя: возвращается kIOReturnExclusiveAccess. Выйдите из Karabiner на время настройки или исключите клавиатуру в его настройках.

Проверить, кто мешает, можно диагностикой:

.venv/bin/python misc/iokit_probe.py

Транспорт выбирается автоматически: на macOS — IOKit, на остальных системах — hidraw. При выключенном Karabiner команды mode, paint, keys, remap, macro и reset проверены на железе. Katana Studio на macOS записывать не может: node-hid получает от системы not permitted.

Решение проблем¶

• Сначала проверьте версию: ./katana.py version. Клавиатура для этой команды не нужна.
• Если команда отклоняется со статусом 00 или ff, сессия залипла. Повторите команду, затем выполните ./katana.py reset.
• Если reset не помог, выключите и включите клавиатуру физически.
• Полный список известных проблем — в разделе Транспорт и транзакции.

Для приложения нужно то же udev-правило. Как его ставит deb-пакет и что делать с AppImage, описано в разделе Katana Studio.