Прошивка клавиатуры ZMK для SF32¶

Что такое ZMK для SF32?¶

ZMK Firmware — прошивка клавиатуры с лицензией MIT на базе Zephyr. Основной проект ZMK задаёт модель приложения для многих проводных и беспроводных клавиатур, в том числе состоящих из двух половин: сканирование матрицы, раскладки и слои, поведения клавиш (behaviors), USB- и Bluetooth-HID, постоянное хранение настроек, а также расширяемые описания плат и конфигурации плат расширения Zephyr (shields).

OpenSiFli/zmk — производный репозиторий (fork) ZMK, который сопровождает OpenSiFli. В рассмотренной версии добавлены:

• вариант платы sf32lb52_devkit_lcd/sf32lb525uc6/zmk;
• интеграция SoC SF32LB52 в дерево приложения ZMK;
• конфигурации для одной платы, раздельной клавиатуры, ZMK Studio и платы расширения (shield) urchin_sf32lb52;
• адаптированный для SF32 бэкенд CherryUSB;
• раздел NVS размером 256 KB для настроек и поддержка настроек Bluetooth;
• раскладка раздельной клавиатуры Urchin с тремя слоями, управлением профилями Bluetooth и комбинациями разблокировки ZMK Studio.

Это разрабатываемый порт, а не релиз ZMK для продуктов на SF32, выпущенный под отдельным тегом версии. В корне производного репозитория по-прежнему находится общий README основного проекта ZMK, без краткого руководства для SF32. Используйте плату, конфигурацию платы расширения, манифест, исходный код и коммит как исполняемую эталонную конфигурацию. Прежде чем адаптировать её, самостоятельно подтвердите чистую сборку, загрузку прошивки, работоспособность и возможность восстановления.

Зачем использовать реализацию на SF32?¶

Порт для SF32 демонстрирует, как запустить модель клавиатуры ZMK на SF32LB52, сохранив принятые в Zephyr соглашения для дерева устройств (devicetree), Kconfig, west, раскладок, плат расширения (shields) и клавиатур из двух половин. В конфигурации urchin_sf32lb52 38 клавиш распределены между обеими половинами. Левая конфигурация выполняет роль центральной: в ней включены CherryUSB и ZMK Studio, а хост может получать HID по USB. Правая конфигурация выполняет роль периферийной. ZMK BLE включён на обеих половинах.

Этот производный репозиторий подходит для оценки беспроводной клавиатуры из двух половин, настольного USB/Bluetooth-устройства ввода, программируемой макроклавиатуры или специализированного устройства человеко-машинного интерфейса на SF32. Обратная сторона — зрелость зависимостей: манифест west фиксирует отдельную ветку Zephyr (v4.3+sf32-zmk_fixes), конкретную ревизию SiFli HAL и отдельную ветку CherryUSB zephyr-adapt. Эти зависимости входят в границу совместимости порта; заменять их на самые новые версии основного проекта можно только после полной миграции и регрессионной проверки.

Результат, область применения и условия начала¶

Ожидаемый результат: собрать и загрузить закреплённые по версиям образы левой и правой половин Urchin; проверить всю матрицу клавиш, слои, USB HID, BLE-связь между половинами и подключение к хосту, сохранение настроек, границы применения ZMK Studio и восстановление; затем внести одно контролируемое изменение раскладки или аппаратуры и сохранить воспроизводимые результаты.

Статья не гарантирует полного соответствия функциям основного проекта ZMK, совместимости с любыми платами расширения ZMK (shields), автономности на аккумуляторе, достаточной для серийного изделия, подтверждённых характеристик радиоканала или возможности перейти на другую ревизию Zephyr/ZMK с официальной поддержкой. Здесь также не описана готовая к производству печатная плата клавиатуры: конфигурация Urchin в репозитории сопоставляет эталонную матрицу с выводами SF32LB52-DevKit-LCD. Для собственной аппаратуры это соответствие необходимо осознанно перенести.

Перед началом подготовьте:

• две платы SF32LB52-DevKit-LCD, соответствующие варианту sf32lb525uc6/zmk из производного репозитория;
• испытательный стенд клавиатуры на 38 клавиш, точно подключённый по оверлеям Urchin urchin_sf32lb52_left и urchin_sf32lb52_right, либо небольшая документированная тестовая плата расширения для начальной проверки порта;
• хост с рабочим окружением Zephyr/ZMK west и достаточным объёмом хранилища для зафиксированных в производном репозитории модулей;
• проверенные средства загрузки прошивки, подключения к последовательной консоли и восстановления каждой половины до испытания режима раздельной клавиатуры;
• USB-кабель для передачи данных левой/центральной половины и независимый способ питать и восстанавливать правую/периферийную половину;
• Bluetooth-хост, хост с поддержкой ZMK Studio, если Studio входит в объём испытаний, и средство измерения тока каждой половины;
• журнал с коммитом производного репозитория, ревизиями манифеста, идентификаторами платы и платы расширения, результатами сборки и загрузки, проверки клавиш и Bluetooth-сопряжений, состоянием настроек и измерениями тока.

Аппаратные и программные спецификации¶

Аппаратная спецификация¶

Программная спецификация¶

Выбор поддерживаемой базовой конфигурации¶

Рассмотренная базовая версия OpenSiFli — коммит fd4d5843065f от 27.05.2026. Он включает обновление платы расширения Urchin и конфигурации платы, доступное на тот момент, но не является релизом ZMK для SF32 с отдельным тегом версии. Для первоначального воспроизведения зафиксируйте этот коммит; если выбираете более новый, явно укажите и проверьте его.

Следующие команды сочетают формат рабочего процесса west производного репозитория с точными идентификаторами платы SF32 и расширений Urchin. Сохраняйте два отдельных каталога сборки, чтобы не перепутать образы:

git clone https://github.com/OpenSiFli/zmk.git
cd zmk
git checkout fd4d5843065f

west init -l app
west update --fetch-opt=--filter=tree:0
west zephyr-export

west build -s app -p always -d build-left \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_left

west build -s app -p always -d build-right \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_right

Зафиксируйте итоговый west list, сгенерированные конфигурации Kconfig и devicetree, хеши артефактов, маркировку образов с указанием половины и фактическую процедуру загрузки. Не начинайте тесты раздельной конфигурации, пока не подтвердите независимое восстановление каждой платы.

Этапы проекта¶

Архитектура системы и зависимости¶

flowchart LR
    KL["Левая матрица клавиш\n19 позиций"] --> L["Левый SF32LB52\nцентральная сторона ZMK"]
    KR["Правая матрица клавиш\n19 позиций"] --> R["Правый SF32LB52\nпериферийная сторона ZMK"]
    R -->|"BLE-связь между половинами ZMK"| L
    L -->|"USB HID\nCherryUSB"| H["Компьютер-хост"]
    L -->|"Bluetooth HID"| H
    H <-->|"ZMK Studio\nтолько в прошивке левой половины"| L
    NL["Настройки NVS\nсопряжения и конфигурация"] --> L
    NR["Настройки NVS\nпостоянное состояние"] --> R
    M["Манифест west OpenSiFli\nсобственные Zephyr + HAL + CherryUSB"] --> L
    M --> R

Рассматривайте сбои раздельно: физическая матрица и подключение, связь от правой половины к левой, USB левой стороны, Bluetooth хоста, сохранённые данные сопряжения и настройки, ZMK Studio, загрузка прошивки и восстановление платы, а также зафиксированный набор зависимостей. Если клавиша не доходит до хоста, сбой мог произойти до сканирования, при передаче данных между половинами, в центральной раскладке или на выбранном HID-канале. Проверяйте весь тракт именно в этом порядке.

Этап 1 — Зафиксируйте исходную конфигурацию порта¶

Цель: подтвердить работу точной конфигурации OpenSiFli до изменения раскладки, оверлея платы или зависимости.

1. Запишите ревизии обеих плат и подключите оба испытательных стенда точно по оверлеям Urchin для левой и правой половин. Маркируйте платы и USB-кабели/кабели загрузки по назначению.
2. Соберите оба образа на зафиксированном коммите, сохраните west list и проверьте сгенерированную конфигурацию: целевую плату, конфигурацию платы расширения, роль в разделённой схеме, BLE, CherryUSB, ZMK Studio и настройки NVS.
3. Загрузите каждый образ через независимо проверенный путь восстановления. До сопряжения половин или подключения хоста запишите поведение при холодном запуске и вывод консоли.
4. Установите BLE-связь между половинами и проверьте все 38 позиций на слоях default, lower и raise. Отдельно проверьте выбор/сброс профиля Bluetooth и комбинации разблокировки Studio, чтобы случайно не активировать их при проверке набора текста.
5. Проверьте USB HID и ZMK Studio на левой половине, затем Bluetooth HID на выбранном хосте. Повторите проверки после холодного запуска.

Сохраняемые подтверждения: сведения о платах и подключении, ревизии производного репозитория и манифеста, сгенерированные конфигурации, хеши образов, журналы загрузки и запуска, полная матрица позиций клавиш, результаты по слоям, выбранный канал и версии хоста/Studio.

Критерий выхода из контрольной точки 1: после двух холодных запусков воспроизводятся все 38 позиций, все три слоя, связь от правой половины к левой и как минимум один выбранный канал хоста; обе половины можно восстанавливать независимо.

Этап 2 — Проверьте ввод, транспорт, настройки и восстановление¶

Цель: подтвердить, что типичные отказы клавиатуры обнаруживаются и устраняются без пересборки из неизвестного состояния.

Критерий выхода из контрольной точки 2: для каждого применимого отказа получен воспроизводимый результат обнаружения и восстановления; ни один тест не оставляет HID в зажатом состоянии; настройки или сопряжения можно вернуть к зафиксированной конфигурации без замены файлов вне системы контроля версий.

Этап 3 — Создайте воспроизводимую исходную конфигурацию¶

Цель: дать второму инженеру возможность собрать оба образа из чистых исходников и повторить этап 2.

1. Начните с чистой рабочей копии производного репозитория на записанном коммите и выполните west init, west update и west zephyr-export, не подменяя модули локально.
2. Сохраните west list, версии компилятора и инструментов, сгенерированные .config и devicetree, данные по памяти, журналы сборки и оба артефакта с хешами.
3. Загрузите помеченные образы левой и правой сторон в соответствующие половины и повторите все проверки этапа 2.
4. Сравните артефакты и конфигурацию с исходной записью; объясните любое невоспроизводимое отличие до продолжения.

Критерий выхода из контрольной точки 3: вторая среда создаёт правильно помеченные образы, проходящие этап 2, без неотслеживаемых оверлеев, устаревших результатов сборки или незакреплённых версий зависимостей.

Этап 4 — Адаптируйте по одной границе клавиатуры за раз¶

Цель: внести одно изменение продукта, сохранив проверенный рабочий порт и независимые способы восстановления.

Критерий выхода из контрольной точки 4: изменение проверено, исходные образы и настройки можно восстановить, а все применимые тесты матрицы, слоёв, связи половин, USB, BLE, Studio, питания и восстановления пройдены.

Этап 5 — Оцените готовность продукта¶

Перед разработкой собственной печатной платы клавиатуры или аккумуляторного прототипа ответьте на вопросы:

• Кто отвечает за производный репозиторий ZMK OpenSiFli, собственную ветку Zephyr, ревизию SiFli HAL, адаптацию CherryUSB и будущие обновления безопасности и совместимости?
• Какие функции основного проекта ZMK действительно проверены на SF32, а какие лишь присутствуют в унаследованном дереве исходников?
• Как при производстве и обслуживании будут контролироваться идентификаторы левого/правого образов, ревизия платы, раскладка, конфигурация, сопряжения и состояние сброса к заводским настройкам?
• Каков измеренный ток каждой половины в активном режиме, подключённом ожидании, отключённом состоянии и сне с учётом частоты сканирования, повторных подключений и защиты аккумулятора?
• Какие хосты, ОС, USB-контроллеры, стеки Bluetooth, сценарии пробуждения, сочетания одновременных нажатий и условия помех были проверены?
• Можно ли восстановить продукт без вскрытия или утилизации после сбоя обновления зависимости, изменения Studio, записи настройки или полевого обновления?
• Подходят ли лицензии ZMK/Zephyr, файлы печатной платы и корпуса, содержимое раскладки, логотипы, шрифты и включённые конфигурации для предполагаемого распространения?

Критерий выхода из контрольной точки 5: для каждого оставшегося риска назначены ответственный, подтверждающие данные и способ обработки; команда явно решила продолжить, отложить или остановить работу.

Передача материалов для проектирования изделия¶

Передайте точную модель SF32 и сведения о памяти, роли половин и транспорт, карту строк/столбцов/прямых входов, ориентацию диодов, подключение USB, допущения об антенне и корпусе, политику NVS/настроек, интерфейсы загрузки и восстановления, бюджет питания каждой половины, испытательные стенды, идентификацию образов и зафиксированный манифест. Продолжите с материалов о SF32LB52-DevKit-LCD, границах платформы Zephyr, архитектуре Bluetooth, руководстве по проектированию аппаратуры SF32LB52x и подготовке к серийному производству.

Основные источники¶

• Порт SF32 OpenSiFli/zmk
• Рассмотренный коммит OpenSiFli/zmk
• Вариант платы ZMK для SF32LB52 в проверенном коммите
• Конфигурация платы расширения Urchin из двух половин для SF32LB52 в проверенном коммите
• Манифест west для ZMK OpenSiFli в проверенном коммите
• Основной проект zmkfirmware/zmk
• Документация ZMK
• Документация проекта Zephyr

Последнее обновление: 2026-10-21