У меня iMac, на котором macOS установлена через OCLP, и механическая клавиатура Red Square Keyrox TKL. Как клавиатура она меня устраивала, пока компьютер не уходил в сон. После пробуждения она периодически отваливалась, и вернуть её к жизни получалось переподключением USB-кабеля. Каждый раз передёргивать провод быстро надоело.
Заодно хотелось нормально настроить подсветку. Встроенные сочетания Fn есть, но мне нужен был выбор конкретных цветов и управление с Mac. У производителя для этой модели есть Windows-программа, а подходящего приложения под macOS для своей задачи я не нашёл. Так что накопилось сразу два повода разобраться с этой клавиатурой.
Когда появился репозиторий REA, я решил использовать его для анализа Windows-софта производителя. Для исследования исполняемого файла использовал и Ghidra. Дальше к работе подключились Antigravity, а затем Codex — с ними шли анализ, написание кода и исправления. Проверка результата оставалась за мной и физической клавиатурой, и именно здесь начались самые показательные проблемы.
Сборка готова, а на клавиатуре ничего не происходит
Поначалу всё выглядело довольно бодро. Antigravity собрал консольную утилиту, потом приложение с графическим интерфейсом. Появились выбор эффектов, ползунки яркости и скорости, палитра, профили и даже поклавишная настройка. По отчётам функции работали, команды отправлялись, сборка проходила.
Вот только на самой клавиатуре почти ничего из этого не менялось. Можно было выбрать эффект или цвет, увидеть сообщение об успехе и остаться с прежней подсветкой. В какой-то момент максимумом оказались кнопки P1–P4 — через них эффект действительно переключался. Остальной интерфейс создавал гораздо более приятное впечатление, чем результат его работы.
После нескольких таких попыток я подключил Codex. И тут тоже всё не стало рабочим с первой сборки. Сначала тесты подтвердили запись и чтение значений обратно, после чего выяснилось, что подсветка физически осталась прежней. Пришлось менять сам подход к проверке и разбирать каждую функцию до наблюдаемого результата на клавишах.
Что нашлось в HID-интерфейсе
Мой экземпляр определяется с VID 0x1a2c и PID 0x2511. Проверки проводились на этой клавиатуре, на Intel iMac под macOS Sonoma. В строке прошивки устройство возвращает GK8911M-DP-PID2511-104K_V0045_231025112335. В код также добавлена ревизия с PID 0x1511, аппаратная проверка которой ещё предстоит.
Для настройки используется HID-коллекция с UsagePage = 0xff00 и Usage = 0x0002. В macOS обмен идёт через IOHIDDeviceSetReport и IOHIDDeviceGetReport. Управляющий отчёт имеет размер 520 байт, включая восьмибайтный заголовок и буфер данных. В коде он представлен такой структурой.
#pragma pack(push, 1)
typedef struct {
uint32_t offset;
uint16_t len;
uint8_t cmd;
uint8_t subcmd;
uint8_t data[512];
} keyrox_packet_t;
#pragma pack(pop)
В начале разработки использовались результаты анализа Windows-программы. Позже важным источником стал существующий драйвер Keyrox в OpenRGB. Сверка с ним помогла уточнить команду выбора эффекта, аппаратные индексы и формат передачи цветов всей матрицы. Эту часть работы уже проделали до нашего проекта, и она сильно помогла при исправлении первоначальных предположений. Драйвер Keyrox в OpenRGB
Почему P1 и P2 работали, а список эффектов — нет
В первой реализации переключателем эффекта считалась команда 0x08. Команда 0x04 называлась переключением профиля и использовалась кнопками P1–P4. Когда я сообщил, что физически работает именно переключение этих кнопок, появился конкретный повод сравнить две последовательности команд. Оказалось, что список режимов и кнопки обращались к разным командам.
В OpenRGB эффект выбирается через 0x04. Ещё одна ошибка была в нумерации — внутренние номера нашего интерфейса отличались от значений, которые ожидает устройство. Например, Wave в интерфейсе имел номер 1, а в команде выбора должен передаваться 0. Для Const соотношение было обратным, а Custom Matrix соответствовал аппаратному значению 12.
После этого добавили явное преобразование номеров. В текущей таблице описаны 13 аппаратных значений, включая Custom. Кнопки P1–P4 исторически сохранили названия, но сейчас отправляют первые четыре значения этого же селектора эффектов. Считать их полноценной реализацией независимых пользовательских профилей было бы преждевременно. Таблица аппаратных значений OpenRGB
Самая неприятная часть этой ошибки была в проверках. Программа могла записать значение через неверно выбранную команду, прочитать его обратно и объявить операцию успешной. При этом нужный эффект на клавиатуре не появлялся. Только после исправления команды я подтвердил переключение Wave и Const через список, выключение подсветки и заливку всей клавиатуры красным.
Восемьдесят семь клавиш, из которых одну забыли
Следующей неработающей функцией оказалась Custom Matrix. Для неё используется блочная передача цветов с командой 0x07 и длиной данных 0x01b0, то есть 432 байта. Внутри кадра цвета лежат по аппаратным позициям светодиодов. На позицию приходится четыре байта — красный, зелёный, синий и яркость.
Сначала исправили заголовок пакета, в котором 0xb0 ошибочно записывался как команда. Но после этого попытка покрасить Esc всё равно ничего не меняла. Прямая проверка библиотеки могла отправить кадр, а кнопка в приложении не переключала клавиатуру даже в Custom. Значит, искать пришлось и в пути от интерфейса до нативного кода.
Причина оказалась очень простой. JavaScript отправлял 87 цветов, а C-таблица содержала 86 клавиш. Из неё пропустили Fn, и нативная проверка длины отклоняла весь массив ещё до отправки. Клавишу вернули на её позицию, добавили проверку соответствия таблиц и тесты для количества клавиш и LED-позиций.
После этого снова проверили ту же операцию. Я выделил Esc, выбрал зелёный цвет и нажал кнопку применения. В версии 1.0.3 физический Esc действительно загорелся зелёным. Передача карты цветов одним отчётом работает, а предельную частоту обновления этой реализации мы пока не измеряли.
Откуда взялась фоновая служба и почему одной установки было мало
С подсветкой постепенно разобрались, но затем клавиатура снова зависла и пришлось передёрнуть кабель. Это произошло уже после удачных проверок приложения. При разборе выяснилось, что фоновая служба была выгружена, а само приложение закрыто. Автоматического наблюдения за клавиатурой в тот момент не было.
Установленная в «Программы» новая версия приложения сама по себе ещё не означает, что его фоновая часть запущена. Обновлённую службу отдельно зарегистрировали в launchd, включили автозагрузку и проверили её состояние. Затем проверили автоматический перезапуск после тестовой остановки и следующую плановую запись в журнале. Служба продолжила работать.
В старых журналах также нашлись несовпадения ожидаемой команды и полученного ответа. К устройству обращались приложение, CLI и watchdog. Для чтения сначала отправляется SetReport, затем вызывается GetReport, и между этими действиями другой процесс мог отправить собственный запрос. В новой реализации появилась общая файловая блокировка на всю эту пару, после чего прошли 18 параллельных запросов CLI при работающей службе без HID-ошибок.
Сам watchdog теперь проверяет ответ управляющего интерфейса раз в пять секунд. Проверка выполняется отдельным процессом с ограничением времени, чтобы зависший вызов драйвера не остановил наблюдение. После трёх последовательных ошибок служба пытается восстановить устройство, а при неудаче повторяет попытку через 30 секунд. Отдельно проверили обработку имитированного зависшего запроса и запуск восстановления после трёх ошибок.
Для ручного восстановления есть команда keyrox-ctl revive. Она вызывает IOUSBHostDevice resetWithError:, затем ждёт появления отвечающего HID-интерфейса. Apple описывает этот API как сброс с попыткой повторной регистрации USB-устройства. На подключённой клавиатуре такая последовательность прошла успешно. Документация Apple
При этом причину самих зависаний ещё предстоит установить. Я наблюдал отвал клавиатуры при уходе компьютера в сон, но измерений питания на USB у нас нет. На этом iMac используется OCLP, и эту особенность тоже нужно учитывать при сравнении с другими машинами. Объявлять причиной просадку напряжения или считать зависание окончательно устранённым по имеющимся проверкам было бы преждевременно.
Что происходит с яркостью, когда экран засыпает
После обновления защиты я попросил добавить ещё одну вещь. Пока экран спит, клавиатуре незачем светить на полной яркости. Но при пробуждении хочется получить обратно тот уровень, который был выбран до сна. В версии 1.0.5 это поведение добавили в фоновую службу.
Проверка с настоящим сном экрана дала последовательность 4/4 → 1/4 → 4/4. Активным всё время оставался Const. Повторное событие засыпания тоже проверили, чтобы оно не перезаписывало сохранённую исходную яркость уже приглушённым значением. Если подсветка была выключена, пробуждение её не включает.
Для Custom Matrix служба использует сохранённый приложением кадр. При засыпании уменьшаются поклавишные значения яркости, при пробуждении возвращается исходный кадр. В проверке отправляемых данных сохранились RGB-каналы и восстановились исходные значения яркости. Чтобы это работало, схему нужно хотя бы раз применить в новой версии приложения.
Есть и особенность текущей защиты, которую важно учитывать. Служба удерживает PreventUserIdleSystemSleep, поэтому препятствует автоматическому сну системы по бездействию. Экран при этом может засыпать. Проверенный цикл приглушения относится именно ко сну экрана, а дальнейшие наблюдения за полным сном и аппаратными зависаниями ещё нужны.
Что получилось в итоге
Приложение использует Cocoa для окна, меню и жизненного цикла macOS. Сам интерфейс написан на HTML, CSS и JavaScript и работает внутри системного WKWebView. Обмен с клавиатурой вынесен в библиотеку на C. Дополнительно есть консольная утилита и отдельный watchdog.

DMG версии 1.0.5 занимает 1 756 922 байта, примерно 1,76 МБ. Приложение и встроенная служба собраны для Intel и Apple Silicon. Все описанные аппаратные проверки выполнены на моём Intel iMac, проверка на Apple Silicon пока ограничилась сборкой arm64. CLI можно собрать из исходников и использовать в собственных сценариях.
make
./keyrox-ctl status
./keyrox-ctl mode wave
./keyrox-ctl color '#00FF88'
./keyrox-ctl brightness 4
./keyrox-ctl revive
На моей клавиатуре физически проверены переключение Wave и Const, включение и выключение подсветки, общая заливка цветом и поклавишная заливка Esc. Проверены обмен параметрами яркости и скорости, а также восстановление яркости после сна экрана. В репозитории есть 12 тестов протокола и workflow GitHub Actions для сборки и запуска тестов. Проверки остальных эффектов, направлений и переназначений, а также работа над макросами остаются дальнейшими задачами.
Главная проблема этой разработки оказалась в разнице между отчётом о готовности и поведением устройства. Antigravity несколько раз выдавал сборку с сообщениями об успехе, хотя на клавиатуре нужные функции не работали. Первые проверки с Codex тоже пришлось пересматривать, после чего исправления наконец начали подтверждаться на самих клавишах. Теперь у каждой проверенной функции есть конкретный сценарий и результат, который можно увидеть или измерить.
Исходники опубликованы под MIT, готовая сборка доступна в релизе v1.0.5. Для фоновой защиты нужно включить службу в Settings, а после обновления приложения отключить и повторно включить её, чтобы обновилась отдельная установленная копия. Если у вас такая же клавиатура с другой прошивкой или ревизией, пригодятся результаты проверки с указанием VID/PID, версии macOS и сценария сбоя. Репозиторий проекта · Релиз v1.0.5

Комментарии 0