kolor-keyboard — рисуем RGB подсветкой клавиатуры флаг языка раскладки

Этот проект почти полностью сгенерирован с помощью AI Claude Code.
Использование на свой страх и риск. Автор проекта не несёт ответственности за любые последствия, включая возможные проблемы с вашим аппаратным или программным обеспечением.

 Протокол передачи цветов на клавиатуру

  HID Raw — транспортный уровень

  Клавиатуры с прошивкой VIA/Vial используют HID Raw interface для обмена данными:

  Usage Page: 0xFF60 (vendor-defined)
  Usage: 0x61
  Размер пакета: 32 байта

  Это стандартный интерфейс VIA, который позволяет обходить обычный HID keyboard протокол и напрямую общаться с прошивкой.

  Два протокола управления RGB

  1. VIA RGB Matrix (stock прошивка)

  Используется для глобального цвета на всех клавишах:

  Пакет: [0x07, 0x03, cmd, value1, value2, ...]
           │     │     │
           │     │     └── команда (brightness=0x01, effect=0x02, color=0x04)
           │     └── канал RGB Matrix (0x03)
           └── id_lighting_set_value

  Пример установки цвета (protocol.go:111-120):
  packet[0] = 0x07  // CmdVIASetValue
  packet[1] = 0x03  // ChannelRGBMatrix
  packet[2] = 0x04  // RGBMatrixColor
  packet[3] = hue   // H (0-255)
  packet[4] = sat   // S (0-255)

  2. Vial RGB Direct (vial прошивка)

  Позволяет управлять каждым LED отдельно (per-key RGB):

  Включение режима: [0x07, 0x41, 0x01, 0x00, speed, H, S, V]
                           │      └── mode=1 (Direct)
                           └── vialrgb_set_mode

  Установка LED:    [0x07, 0x42, start_lo, start_hi, count, H,S,V, H,S,V, ...]
                           │      └── начальный индекс LED (16-bit)
                           └── vialrgb_direct_fastset

  Один пакет вмещает до 9 LED (32-5)/3 = 9 цветов в формате HSV.

  Цветовая модель

  Используется HSV (0-255) в стиле QMK/Vial, а не стандартный HSV (0-360, 0-100, 0-100).

  Автоопределение прошивки

  При запуске программа отправляет команду vialrgb_get_number_leds (0x08, 0x43). Если ответ содержит количество LED > 0 — это Vial прошивка. Если 0 или ошибка — stock.

  ---
  Зачем нужен hidapitester

  https://github.com/todbot/hidapitester — это CLI утилита для отправки сырых HID пакетов. Он был необходим для reverse engineering и отладки:

  1. Проверка доступа к устройству

  hidapitester --vidpid 3434:0331 --usagePage 0xFF60 --usage 0x61 --open
  Позволяет убедиться, что HID устройство открывается и udev права настроены правильно.

  2. Ручная отправка команд для изучения протокола

  # Запросить количество LED (проверка Vial)
  hidapitester --vidpid 3434:0331 --usagePage 0xFF60 --usage 0x61 --open \
    --send-output 0x08,0x43 --read-input

  Это позволяло экспериментировать с командами VIA/Vial протокола:
  - Понять формат пакетов
  - Найти правильные command ID
  - Проверить ответы клавиатуры

  3. Отладка проблем

  Когда Go код не работал, можно было проверить — проблема в коде или в самой клавиатуре:
  # Установить красный цвет (VIA RGB Matrix)
  hidapitester --vidpid 3434:0331 --usagePage 0xFF60 --usage 0x61 --open \
    --send-output 0x07,0x03,0x04,0x00,0xFF --read-input

  4. Документирование протокола

  Результаты экспериментов с hidapitester помогли создать документацию в docs/FIRMWARE.md:190-193 для проверки работоспособности прошивки.

  ---
  Схема взаимодействия

  ┌─────────────────┐     HID Raw (32 bytes)     ┌──────────────────┐
  │  kolor-keyboard │ ─────────────────────────▶ │  QMK/Vial        │
  │  (Go + go-hid)  │                            │  Firmware        │
  │                 │ ◀───────────────────────── │                  │
  └─────────────────┘        Response            └──────────────────┘
          │                                              │
          │ D-Bus                                        │ PWM
          ▼                                              ▼
  ┌─────────────────┐                            ┌──────────────────┐
  │ KDE Plasma 6    │                            │  RGB LED Matrix  │
  │ (раскладка)     │                            │  (per-key)       │
  └─────────────────┘                            └──────────────────┘

$ kolor-keyboard discover                  
╔══════════════════════════════════════════════════════════════╗
║           kolor-keyboard - Keyboard Discovery                ║
╚══════════════════════════════════════════════════════════════╝

Scanning for VIA/Vial compatible keyboards...

Found 1 device(s):

  [1] Keychron Keychron V3
      VID: 0x3434  PID: 0x0331

Using: Keychron Keychron V3

Checking Vial support...
✓ Vial firmware detected! LED count: 87

Do you want to map LED rows for per-key RGB (draw mode)? [Y/n]: 
╔══════════════════════════════════════════════════════════════╗
║              LED Mapping Tour                                ║
╠══════════════════════════════════════════════════════════════╣
║  Detected 87 LEDs (indices 0-86)                             
║                                                              ║
║  Commands:                                                   ║
║    Enter/n  - next LED (add to current row)                  ║
║    r        - end row here (add LED and start new row)       ║
║    s        - skip this LED (don't add to any row)           ║
║    b        - go back (undo last LED)                        ║
║    q        - quit and save                                  ║
║                                                              ║
║  Colors:                                                     ║
║    RED     - current LED                                     ║
║    GREEN   - current row LEDs                                ║
║    YELLOW  - saved rows (different shades per row)           ║
╚══════════════════════════════════════════════════════════════╝

[Row 0] LED 0/86 (row has 0 LEDs) > 
[Row 0] LED 1/86 (row has 1 LEDs) > 
[Row 0] LED 2/86 (row has 2 LEDs) > 
[Row 0] LED 3/86 (row has 3 LEDs) > 
[Row 0] LED 4/86 (row has 4 LEDs) > 
[Row 0] LED 5/86 (row has 5 LEDs) > 
[Row 0] LED 6/86 (row has 6 LEDs) > 
[Row 0] LED 7/86 (row has 7 LEDs) > 
[Row 0] LED 8/86 (row has 8 LEDs) > 
[Row 0] LED 9/86 (row has 9 LEDs) > 


[Row 0] LED 10/86 (row has 10 LEDs) > 
[Row 0] LED 11/86 (row has 11 LEDs) > 
[Row 0] LED 12/86 (row has 12 LEDs) > 
[Row 0] LED 13/86 (row has 13 LEDs) > 
[Row 0] LED 14/86 (row has 14 LEDs) > 
[Row 0] LED 15/86 (row has 15 LEDs) > к
[Row 0] LED 15/86 (row has 15 LEDs) > r

  → Row 0 saved: [0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15] (16 LEDs)