Тёмная сторона KD87A

HID-протокол, скрытые режимы, таблицы подсветки и лечение «кирпича» через SWD

Коротко

Dark Project KD87A — механика на 87 клавиш, у которой вся подсветка (132 светодиода, включая боковую зону) висит на одном микроконтроллере Nuvoton M252SD2AE. Вендорское приложение умеет пять эффектов, а сама прошивка знает четырнадцать — и почти все спрятаны: их включает одна HID-команда, а два режима вообще отключены проверкой в коде.

Здесь собрано то, что удалось выяснить реверсом прошивки и живых экспериментов: формат команд, таблицы яркости и скорости, устройство подсветки (у неё нет драйвера — поле сканируется программно, 19 фаз на кадр), протокол вендорского апдейтера и способ поднять клавиатуру, если прошивка «окирпичилась» — через SWD по трём проводам, без паяльной станции и программатора.

⚠️ Предупреждение. Команды 0x0B, 0x18, 0x19 пишут во флеш-память контроллера. Ошибка при работе с ними оставляет клавиатуру в состоянии «кирпич» — восстановление требует физического доступа к выводам чипа. Прежде чем что-то отправлять, прочитай docs/protocol.md целиком.

Что в репозитории

Файл	О чём
docs/protocol.md	HID-протокол: формат пакета, все команды, какие из них опасны
docs/effects.md	14 нативных эффектов, два спящих режима, modeType-варианты
docs/memory.md	Карта RAM и флеш: записи светодиодов, таблицы яркости/скорости/гаммы
docs/hardware.md	Как устроена подсветка: мультиплексирование, 19 фаз, боковая зона
docs/updater.md	Как вендорский апдейтер прошивает клавиатуру и где лежит образ
docs/unbrick-swd.md	Восстановление через SWD: ESP32, три провода, OpenOCD
tools/	Диагностические скрипты (только чтение, ничего не пишут в устройство)

Ключевые находки

Подсветка без драйвера. Светодиодная матрица 132 светодиодов сканируется программно: 19 фаз на кадр (~22 мс), в каждой фазе контроллер наливает ШИМ на 24 канала из таблицы волновых форм (0x20001310, 8 групп × 19 фаз × RGB). Отсюда же — артефакты: если фаза опаздывает, подсвечивается не та строка («куски белой подсветки посреди клавиатуры»), а мерцание прямо пропорционально числу пакетов в секунду, потому что каждый кадр, пришедший с ПК, сбивает сканирование.

Четырнадцать эффектов вместо пяти. Список разрешённых режимов лежит в прошивке по 0x88F0 (14 значений), диспетчер — таблица off_8B6C. Вендорское приложение показывает пять; остальные включаются командой 0x14 или полем ledType в 0x07. Два режима (5 и 13) отключены проверкой (mode & 0xF7) != 5 — их можно вернуть, поправив восемь байт.

Живая заливка одним пакетом. Команда 0x12 заставляет саму плату заливать всё поле и перебирать до трёх цветов с шагом около секунды. Пакетов в потоке нет, поэтому это единственное переливание без мерцания — идеальный «дежурный» режим.

Обновление прошивки. Образ прошивки вклеен целиком внутрь вендорского апдейтера GK8110DPRGB_V10401.exe (без сжатия и без контрольных сумм), поэтому копия апдейтера с правленым образом работает как обычный апдейтер. Поток: преамбула → 0x0B (вход в загрузчик) → плата переподключается с другим PID (0416:3F00) → страницы по 48 байт с инвертированными данными.

Восстановление через SWD. Если прошивка не обслуживает USB-команды, спасает только доступ к чипу: SWCLK, SWDIO, GND (выводы 31/32/33), ESP32 как битбанк-адаптер, мост Serial→TCP и OpenOCD. Инструкция и готовые скрипты — в docs/unbrick-swd.md.

Чего здесь нет

Репозиторий содержит только описания и находки. В нём намеренно нет ни образов прошивки, ни исполняемых файлов вендора, ни кода, который что-либо записывает в устройство — всё это собственность производителя, а правка прошивки делается на свой страх и риск.

Лицензия

MIT — см. LICENSE.