Как заставить китайскую механическую клавиатуру работать в Linux

Предыстория

Мне подарили компактную механическую клавиатуру CYBERLYNX ZA63 ^[1] с подсветкой — выглядит стильно, клавиши приятно щёлкают. До этого дел с механникой не имел. Подключил к домашнему ПК. На Windows всё работало идеально: настроил подсветку под себя, привык к расположению клавиш. Данная модель работает только по проводу (USB Type-C). Есть еще Pro версия с беспроводным подключением. Но это подарок, провод так провод.

В один момент мне понадобилось подключить её к рабочему ноутбуку с Ubuntu. "Что может быть проще?" Подключил монитор, подключил клавиатуру и продолжил работать. Подключил кабель... подсветка загорелась, а вот клавиши — молчали. Вообще. Ни одна не работала.

Поиски причины

Сначала грешил на переключение с Win-режима на Mac - не помогло. На драйверы, но в Linux-то HID-устройства обычно работают из коробки. Открыл инструкцию (если можно так назвать листок-вкладыш). Заявлена поддержка Win, MacOS, Android.

Нашел несколько топиков, в том числе на qna.habr ^[2]. И ответы вроде, любая клава должна работать в Linux, явно не бились с моей ситуацией.

Ну что ж, вначале диагностика ситуации.

1.lsusb показывала все устройства, кроме моей клавиатуры. Как будто её и не было.

Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 002: ID 0cf3:e300 Qualcomm Atheros Communications QCA61x4 Bluetooth 4.0
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 003: ID 5986:2137 Acer, Inc Integrated Camera
Bus 001 Device 002: ID 2717:5013 Xiaomi Inc. Mi Wireless Mouse
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

2.  В логах ядра (dmesg) ошибки:

usb 1-4: unable to read config index 0 descriptor/start: -71
usb 1-4: can't read configurations, error -71

Система видела, что что-то подключено (питание-то шло — подсветка работала), но не могла прочитать "паспорт" устройства.

Открытие: я не один такой

Погуглив (именно, нейросеть помочь тут не смогла), я обнаружил таких же "счастливчиков". Оказалось, многие китайские механические клавиатуры (Zifriend, SAMA, Gamestop, Cyberlinx — это всё переименованные версии одной и той же железки) имеют эту проблему.

Производители честно пишут в мануалах: "только Windows и MacOS".

Особенно обидно было читать, что в беспроводном режиме клавиатуры работают, а в проводном — нет. У меня как раз был проводной вариант.

Решение

Ключ к решению нашёлся в параметрах ядра usbcore.quirks ^[3]. Грубо говоря, это способ сказать системе: "это устройство ведёт себя странно, обращайся с ним по-особому".

Шаг 1: Находим VendorID и ProductID клавиатуры

Поскольку в Linux клавиатура не определялась, пришлось на время вернуться к Windows. В диспетчере устройств нашёл свою клавиатуру и посмотрел её ID: VID 5566 и PID 0008.

Совет: если в диспетчере устройств не видно названия, можно использовать PowerShell:

Get-PnpDevice -PresentOnly | Where-Object { $_.InstanceId -match '^USB' }

Искать нужно устройство с VID, отличным от 3151 — это стандартные Windows-устройства.

Шаг 2: Меняем параметры ядра ^[4]

Редактируем конфигурацию GRUB:

sudo nano /etc/default/grub

Добавляем наш параметр (подставьте свои VID и PID):

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.quirks=5566:0008:gki"

Флаг gki — это как раз то, что заставляет систему работать с "нестандартными" устройствами.

Обновляем конфигурацию:

sudo grub-mkconfig -o /boot/grub/grub.cfg

Перезагружаемся... и о чудо! Клавиатура заработала!

Почему это сработало?

Оказалось, эти клавиатуры используют чипы, которые не совсем корректно следуют стандартам USB.

По сути, мы говорим системе: «работай с этим устройством в простом, базовом режиме». Теперь клавиатура прекрасно работает и в Linux.

Вероятно, решить проблему можно было и иначе, но рабочий способ найден, я доволен :-)

P.S. Первая статья, не закидайте сразу :-)