Initial commit

docs/INSTALL.md

@@ -0,0 +1,56 @@
+---
+description: Установка, udev-правило и решение проблем доступа к устройству.
+---
+
+# Установка
+
+## Зависимости
+
+Нужен Python 3.10+.
+Зависимости: `pyusb` (для `reset`) и `pyyaml` (для `apply`); сам транспорт работает на голых `fcntl`-ioctl'ах к `/dev/hidraw*`:
+
+```
+python3 -m venv .venv
+.venv/bin/pip install pyusb pyyaml
+```
+
+## udev-правило
+
+Без правила доступ к `/dev/hidraw*` есть только у root.
+Файл `70-ganss-katana.rules` даёт доступ группе `plugdev` и через `uaccess` (логин-сессии systemd):
+
+```
+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-узлам (весь обмен RGB), вторая — к USB-устройству (нужна только для команды `reset`, которая делает USB port reset).
+
+**Установка:**
+
+```
+sudo cp 70-ganss-katana.rules /etc/udev/rules.d/ && \
+  sudo udevadm control --reload-rules && \
+  sudo udevadm trigger
+```
+
+Проверка: `katana.py mode ...` должен работать без `sudo`.
+
+## Проверка устройства
+
+Наличие клавиатуры проще всего проверить по USB ID `0c45:8006`:
+
+```
+lsusb | grep -i 0c45
+Bus 001 Device 028: ID 0c45:8006 Microdia Dual Mode Camera (8006 VGA)
+```
+
+Подпись «Dual Mode Camera (8006 VGA)» — это норма, не пугайтесь.
+ID `0c45:8006` принадлежит чипу Sonix SN32, который производитель ставит и в вебкамеры Microdia, и в клавиатуры.
+База имён `usb.ids` знает за этим ID только камеру, поэтому `lsusb` показывает её название для любого устройства с этим ID — включая эту клавиатуру.
+Реальный тип устройства видно по интерфейсам: 2 HID-интерфейса (boot keyboard и mouse/consumer) в `usb-devices` или `lsusb -d 0c45:8006 -v`.
+
+!!! note "Если не помогло"
+
+    Переподключите клавиатуру.
+    Если пользователь не в группе `plugdev` — `sudo usermod -aG plugdev $USER` и перелогин.