Донгл ни при чём: реверс-инжиниринг Keychron Launcher и перепрошивка радиомодуля K2 HE через raw HID

Прокомментировать Просмотры: 0

Донгл оказался ни при чём

На моей Keychron K2 HE перестало работать подключение на частоте 2,4 ГГц. Всё указывало на неисправность приёмника: инструкции в интернете подтверждали эту версию, но ни одна не помогла. За два часа мы с ИИ-агентом изучили веб-приложение Keychron Launcher, пообщались с приёмником на его собственном протоколе, добрались до радиомодуля клавиатуры через сквозной канал прошивки и обнаружили обновление, которое Keychron разместила на сервере, но так и не предложила владельцам этой модели. В конце статьи — утилита, позволяющая выполнить всё это одной командой.

Иллюстрация создана нейросетью.

Почему я выбрал K2 HE

К клавиатуре у меня было несколько, казалось бы, несложных требований:

  • магнитные переключатели Hall Effect с регулируемой точкой срабатывания и поддержкой Rapid Trigger;

  • беспроводное соединение без увеличения задержки — на частоте 2,4 ГГц, с Bluetooth в качестве запасного варианта;

  • формат 75%: функциональный ряд и стрелки на месте, цифрового блока нет;

  • комфортная работа как при написании кода, так и в играх.

По отдельности каждому условию легко найти соответствие, но совместить их оказалось почти невозможно. Большинство магнитных клавиатур — проводные. Wooting 60HE и 80HE считаются эталоном для игр и обеспечивают частоту опроса 8 кГц, однако они проводные и стоят дороже. Беспроводные модели обычно оснащены механическими переключателями, а корпуса беспроводных «игровых» клавиатур нередко сделаны из пластика, который гнётся в руках. Добавьте к этому множество HE-переключателей, несовместимых между производителями.

K2 HE соответствует всем перечисленным требованиям:

Параметр

Значение

Подключение

кабель, Bluetooth и 2,4 ГГц; частота опроса на 2,4 ГГц — 1000 Гц, как и при проводном подключении

Задержка по измерениям RTINGS

около 5,6 мс через приёмник и 9,9 мс по Bluetooth

Корпус

966 г, не прогибается; внутри несколько слоёв демпфирующей пены

Аккумулятор

4000 мА·ч, до 110 часов работы с выключенной подсветкой

Рекомендованная цена

$129.99–139.99

iMore оценил клавиатуру на 5/5, Tom’s Guide — на 4,5/5, PC Gamer — на 88/100. Недостатки тоже известны. Первая версия совместима только с магнитными Gateron Double-Rail. С включённой подсветкой заряда хватает примерно на 28 часов по измерениям APH Networks. Фирменное ПО работает в браузере и местами выглядит недоработанным.

И вот у этой клавиатуры перестала работать её главная особенность.

Исходные данные

Симптомы были следующими:

  • переключатель установлен в положение 2.4G, приёмник Keychron Link подключён к USB, но связи нет;

  • по Bluetooth клавиатура работает, хотя периодически отключается;

  • по кабелю всё работает безупречно.

Разобраться с проблемой я поручил Claude Code. Агент работал из WSL, а к устройствам обращался через Windows: использовал PowerShell для перечисления оборудования и отдельное виртуальное окружение Python с hidapi, которое сам установил в %TEMP% и запускал через powershell.exe. Мне в основном оставалась физическая работа: передвинуть переключатель, удержать клавишу или нажать кнопку в браузере. Последнее агент принципиально выполнить не может: окно выбора устройства WebHID требует клика человека, и это правильно.

Акт 1. Следуем инструкциям

Первый час мы потратили на стандартные рекомендации с форумов.

Проверяем, что видит Windows. Среди устройств с VID 3434 (Keychron) обнаружились клавиатура 3434:0E20 и приёмник 3434:D030 с необычной ревизией REV_=300 в дескрипторе. В этот момент клавиатура работала по Bluetooth и была дважды сопряжена с ПК: в системе значились две записи K2 HE. Bluetooth-адаптер — комбинированный MediaTek с Wi-Fi. Выглядит подозрительно, но к подключению на 2,4 ГГц отношения не имеет.

Обновляем прошивку клавиатуры. Через Launcher установили версию 1.3.0 вместо 1.2.1. Для этого пришлось поставить драйвер DFU из QMK Toolbox и перевести плату в режим загрузчика (0483:DF11, это STM32). Агент запустил фоновый скрипт, который каждые три секунды опрашивал USB и сообщал о переходе платы в DFU. Прошивка установилась, но связь на 2,4 ГГц не появилась.

Повторяем сопряжение. Нажимаем Fn+4 — клавиша 4 медленно мигает зелёным. Подключаем приёмник до нажатия и после него, удерживаем сочетание дольше, размещаем приёмник в 20 см от клавиатуры. Результата нет.

Восстанавливаем заводские настройки. Fn+J+Z: подсветка весело переливается, мои настройки удалены, а связи по-прежнему нет.

Проверяем версию с приёмником. Согласно журналу Windows, приёмник впервые появился в системе в мае, а клавиатура — в ноябре. Предположение, что донгл принадлежит другой клавиатуре, выглядело разумно. Агент удалил через pnputil все записи 3434:D030, включая майские, после чего Windows обнаружила приёмник заново. Ничего не изменилось.

Обычно на этом этапе обращаются в поддержку. Я же попросил агента исследовать проблему глубже и перепрошить сам приёмник.

Акт 2. Изучаем Launcher

Keychron Launcher — приложение на Angular, которое взаимодействует с устройствами через WebHID. Значит, протокол содержится в JavaScript, который браузер всё равно скачивает. Агент загрузил index.html, основной бандл main.*.js размером 3,4 МБ и лениво загружаемые чанки, после чего принялся их изучать.

Первой находкой стал API прошивок.

GET https://launcher.keychron.com/vapi/v2/product/<vendor_product_id>
GET https://launcher.keychron.com/vapi/v2/firmware/<vendor_product_id>

Здесь vendor_product_id — это VID и PID, объединённые в одно 32-битное число: для приёмника 0x3434D030 = 875876400, для K2 HE ANSI 0x34340E20 = 875826720. В ответе содержатся список версий, прямые ссылки на бинарные файлы и журнал изменений. Авторизация не требуется.

Вторая находка — команды приёмника.

FR_GET_PROTOCOL_VERSION = 177  // 0xB1
FR_GET_STATE            = 178  // 0xB2
FR_GET_FW_VERSION       = 179  // 0xB3
FR_DFU_OVER_VIA         = 186  // 0xBA

Заодно выяснилось значение ревизии REV_=300: это всего лишь прошивка d.3.0 в системе нумерации Keychron. Отправляем приёмнику 0xB2:

b2 01 34 34 20 0e 00 00 ...

За заголовком следуют пятибайтные слоты: VID, PID и флаг подключения. В слоте 0 указан 3434:0E20 — именно моя K2 HE. Флаг подключения равен нулю.

На этом версия о чужом донгле отпала. Приёмник знает мою клавиатуру и ждёт её, но сама клавиатура к нему не подключается.

Тем не менее, раз протокол уже был известен, я перепрошил приёмник. Агент скачал через тот же API версию d.3.1 размером 30 644 байта и сначала сопоставил модель, которую сообщил приёмник (KCNRFDM3), с моделью в файле. Затем команда 0x67 перевела приёмник в загрузчик 3434:D000, прошивка загрузилась, CRC32 совпал, и приёмник вернулся с REV_=301. Клавиатура по-прежнему не подключалась. Зато подозрения с приёмника можно было снять.

Акт 3. Исследуем клавиатуру

С кабельным подключением есть особенность. Когда переключатель находится в положении BT или 2.4G, кабель только заряжает клавиатуру, а HID по нему недоступен. Переводим переключатель в USB — и появляется интерфейс raw HID с usage page 0xFF60: 32-байтные репорты передаются по тому же каналу, который использует VIA.

Протокол описан в исходном коде. У Keychron есть публичный форк QMK (Keychron/qmk_firmware, ветка 2025q3), а в файле keyboards/keychron/common/keychron_raw_hid.h перечислены команды:

KC_GET_PROTOCOL_VERSION = 0xA0,
KC_GET_FIRMWARE_VERSION = 0xA1,
KC_GET_SUPPORT_FEATURE  = 0xA2,
KC_MISC_CMD_GROUP       = 0xA7,
KC_KEYCHRON_RGB         = 0xA8,
KC_ANALOG_MATRIX        = 0xA9,
KC_WIRELESS_DFU         = 0xAA,

Там же обнаружился заводской тест с префиксом 0xAB. Команда 0xAB 0x05 возвращает текущий режим подключения (1 = USB, 2 = Bluetooth, 4 = 2.4G), а 0xAB 0x08 — строку сборки. Плата назвала себя v1.3.3 2026-05-26, хотя Launcher только что установил «1.3.0». Расхождение безвредное, но именно такие детали напоминают, что интерфейсу производителя не всегда стоит верить на слово.

Гипотеза: неисправен переключатель

Если контакт положения 2.4G не работает, клавиатура просто не переходит в этот режим — и симптомы становятся понятны. Проверить предположение можно без мультиметра. Агент написал монитор, который каждые 0,3 секунды запрашивает у клавиатуры текущий режим, а у приёмника — состояние слотов, и выводит строку при любом изменении. Я последовательно перевёл переключатель во все положения:

10:32:27 kb transport=2.4G      | dongle slot0=OFF
10:32:35 kb transport=BLUETOOTH | dongle slot0=OFF
10:32:42 kb transport=USB       | dongle slot0=OFF
10:32:56 kb transport=2.4G      | dongle slot0=OFF

Переключатель оказался исправен. Прошивка распознаёт все три положения и при переходе в 2.4G корректно отключает Bluetooth, но приёмник клавиатуру не видит. Повторная попытка сопряжения через Fn+4 под наблюдением монитора дала тот же результат.

Этот монитор стал самым полезным инструментом за всё время расследования. Раньше каждая проверка сводилась к ощущению «нажал, но вроде ничего не случилось». Теперь её результат фиксировался в логе с отметкой времени.

Акт 4. Радиомодуль

За Bluetooth и 2,4 ГГц в K2 HE отвечает не основной STM32, а отдельный радиомодуль семейства LKBT51, подключённый к нему по SPI. Образуется цепочка, в которой неисправным могло оказаться только последнее звено.

Цепочка: STM32, SPI, радиомодуль KCH_KB1, 2.4 ГГц, приёмник Keychron Link
Цепочка: STM32, SPI, радиомодуль KCH_KB1, 2,4 ГГц и приёмник Keychron Link

Место разрыва цепочки. Схема создана нейросетью.

Обратиться к модулю можно через KC_WIRELESS_DFU (0xAA): прошивка клавиатуры пересылает такие пакеты из USB непосредственно в SPI. Формат совпал с драйвером lkbt51.c из того же форка:

AA <type> <len> <~len> <seq> <cmd> ... <checksum16 LE>
type: 0x55 без подтверждения, 0x56 с подтверждением

0x60  информация о модуле
0x61  версия загрузчика (DFU)
0x62  начать DFU
0x63  подготовка
0x64  блок данных, 16 байт
0x65  проверка CRC32
0x66  переключение на новую прошивку

Длина продублирована в инверсном виде, каждый пакет снабжён контрольной суммой: протокол аккуратно спроектирован с расчётом на шумную шину. На команду 0x60 модуль ответил:

Параметр

Значение

Модель

KCH_KB1

Прошивка

0.2.1

Аппаратная версия

1.0.0

Модуль отвечает, Bluetooth через него работает. Значит, аппаратная часть исправна и проблема, вероятно, в программном обеспечении.

Прошивка, отсутствующая в Launcher

В бандле Launcher обнаружились API-идентификаторы радиомодулей: KCH_KB1 = 4288282521, CKBT51 = 4288282520, KCH_KB2 = 4288282519. Это то же объединение VID и PID, только VID у модулей служебный — 0xFF99. На странице K2 HE в Launcher нет раздела с прошивкой модуля. Зато API без проблем возвращает список:

$ python k2he_radio_update.py list      # GET /vapi/v2/firmware/4288282521
0.2.4    2026-07-10
0.2.3    2025-11-26
0.2.2    2026-07-09  Fix the wireless connection problem.
0.2.1    2025-01-17
0.2.0    2026-07-09

Указанные даты относятся к загрузке на сервер, а не к сборке прошивок.

У меня установлена версия 0.2.1. В описании следующей версии Keychron прямо сообщает: «Fix the wireless connection problem.» Обновление существует и размещено на официальном сервере, но владелец K2 HE не может установить его штатными средствами.

В бинарных файлах сохранились строки сборки: для 0.2.1 — Nov 9 2024, для 0.2.4 — Nov 25 2025. Разница составляет год.

Перепрошиваем модуль

Этот этап был самым рискованным. Если загрузка прервётся, модуль останется без рабочей прошивки и оба беспроводных режима перестанут работать. Подключение по кабелю сохранится, поскольку за USB отвечает STM32; загрузчик модуля тоже должен остаться целым, но проверять это на практике не хотелось. Поэтому агент остановился и запросил разрешение, предварительно выполнив все доступные проверки:

  1. Командой 0xAB 0x05 убедился, что клавиатура работает в режиме USB и модуль не занят радиосвязью.

  2. Запросил версию загрузчика модуля (0x61, ответ: DFU v1).

  3. Проверил, что строка модели KCH_KB1, сообщённая модулем, присутствует внутри файла.

Пакеты по 16 байт идут по кабелю к радиомодулю
Пакеты по 16 байт отправляются к радиомодулю по кабелю

Иллюстрация создана нейросетью. В действительности пакеты сначала поступают на основной STM32, который передаёт их модулю по SPI.

Затем последовали команды 0x62 и 0x63 и передача 98 628 байт блоками по 16 байт — всего 6165 пакетов 0x64. Для каждого ожидается подтверждение; при его отсутствии предусмотрено до пяти повторных попыток. Основной цикл выглядит так:

for off in range(0, len(data), 16):
    w = list(data[off:off + 16])
    n = len(w) + 5
    pkt = [0xAA, 0x56, n, (~n) & 0xFF, seq, 0x64, 0, seq] + w
    s = 0x64 + seq + sum(w)
    pkt += [s & 0xFF, (s >> 8) & 0xFF]
    seq = 0 if seq >= 255 else seq + 1

На последнем этапе команда 0x65 передаёт CRC32 образа. Здесь есть тонкость, на которой легко ошибиться: модуль ожидает CRC32 без финального XOR, то есть zlib.crc32(data) ^ 0xFFFFFFFF. При этом обычный zlib.crc32 всего файла 0.2.4 равен 0xFFFFFFFF. Похоже, контрольная сумма записана в конце образа, поэтому для корректного файла модулю передаётся ноль. Если вы знаете, как это на самом деле устроено в LKBT51, расскажите в комментариях.

Загрузка заняла около 40 секунд. После команды 0x66 модуль перезапустился и ответил на 0x60: 0.2.4.

Результат

Переводим переключатель в 2.4G, нажимаем Fn+4, переподключаем приёмник и смотрим на монитор:

10:49:35 kb transport=2.4G | dongle slot0: vid=3434 pid=0e20 status=ON

Пять опросов подряд показывают ON, клавиатура печатает через соединение на 2,4 ГГц.

Компонент

Было

Стало

Основная прошивка (STM32)

1.2.1

1.3.0 (сама плата сообщает о версии 1.3.3)

Радиомодуль KCH_KB1

0.2.1

0.2.4 — именно это решило проблему

Приёмник Keychron Link

d.3.0

d.3.1

Из трёх прошивок проблему устраняло обновление только одной — именно той, которую Launcher не показывает для K2 HE.

Утилита

Всё, что агент написал в процессе работы, я собрал в репозитории k2he-radio-update:

pip install hidapi
python k2he_radio_update.py info               # прошивки и текущий режим
python k2he_radio_update.py list               # что лежит на сервере Keychron
python k2he_radio_update.py update --dry-run   # все проверки без прошивки
python k2he_radio_update.py update             # скачать и прошить модуль
python monitor.py                              # режим клавиатуры и слоты приёмника вживую

Перед обновлением утилита проверяет положение переключателя USB, соответствие модели модуля модели в файле и то, что новая версия действительно новее установленной. Получение каждого пакета подтверждается, а CRC32 модуль проверяет самостоятельно перед переходом на новую прошивку. Описание протоколов находится в docs/protocol.md. Утилита проверена только на K2 HE ANSI с модулем KCH_KB1. Если у вас другая HE-модель Keychron с похожими симптомами, сначала запустите info и проверьте версию модуля.

Какие выводы я сделал

Разбивайте цепочку на звенья и проверяйте каждое отдельно. «Не работает 2,4 ГГц» звучит как одна неисправность, но за ней стоят пять компонентов: переключатель, STM32, SPI, радиомодуль и приёмник. Для каждого звена можно задать отдельный вопрос с ответом «да» или «нет» — и за пару часов найти источник проблемы.

Сначала наблюдаемость, затем гипотезы. Пока у нас не было монитора, мы лишь строили догадки. С его появлением каждая проверка превратилась в строку лога. Несколько десятков строк на Python окупились уже при первом запуске.

Интерфейсу производителя можно верить, но лучше проверять. Launcher показывал другую версию прошивки платы и скрывал существующее обновление модуля. При этом его собственные API и бандл рассказали больше, чем интерфейс.

ИИ-агент особенно полезен там, где требуется много читать. Минифицированный бандл на 3,4 МБ, форк QMK, логи монитора — агент изучал всё это быстрее меня и собирал протокол по частям. Правда, половину времени он потратил на стандартные советы, которые можно найти на любом форуме. Продвинуться удалось лишь тогда, когда он приступил к чтению кода. Перед каждой прошивкой агент сверял модель устройства с моделью в файле, а перед рискованной операцией запрашивал разрешение. С такими правилами доверить ему работу с оборудованием оказалось не страшно.

О Keychron. Аппаратная часть отличная: качественная сборка, приятный звук и задержка на 2,4 ГГц на уровне проводного подключения. Но исправление беспроводной связи лежит на сервере компании и не доходит до владельцев этой модели. Я бы оценил K2 HE на 8 из 10: девять баллов за железо, минус один за софт.

Если решите повторить

Прошивка от другой модели может превратить клавиатуру в кирпич. Если загрузка прервётся, модуль останется без радиосвязи. Не отключайте кабель во время обновления, обязательно сверяйте модель и начните с --dry-run. Если сомневаетесь, обратитесь в поддержку Keychron и приложите версии всех трёх прошивок: основной, радиомодуля и приёмника. Утилита их покажет.

 

Источник

Похожие статьи

Поиск по играм, новостям и статьям…

Введите не менее двух символов

Введите не менее двух символов