Firmware de teclado ZMK en SF32¶

¿Qué es ZMK en SF32?¶

ZMK Firmware es un firmware de teclado con licencia MIT basado en Zephyr. El proyecto principal de ZMK proporciona el modelo de aplicación utilizado por muchos teclados cableados, inalámbricos y divididos en dos mitades: escaneo de matrices, mapas de teclas y capas, comportamientos de tecla, HID por USB y Bluetooth, ajustes persistentes y definiciones ampliables de placas y shields.

OpenSiFli/zmk es un repositorio derivado (fork) de ZMK mantenido por OpenSiFli. La versión revisada añade:

• una variante de placa sf32lb52_devkit_lcd/sf32lb525uc6/zmk;
• integración del SoC SF32LB52 dentro del árbol de la aplicación ZMK;
• configuraciones para placa única, teclado dividido, ZMK Studio y el shield urchin_sf32lb52;
• un backend CherryUSB adaptado a SF32;
• una partición de ajustes NVS de 256 KB y soporte para los ajustes de Bluetooth;
• un mapa de teclas para el teclado dividido Urchin con tres capas, controles de perfiles Bluetooth y combinaciones para desbloquear ZMK Studio.

Se trata de una adaptación en desarrollo, no de una versión de producto de ZMK para SF32 identificada mediante una etiqueta de lanzamiento. El README de nivel superior del repositorio derivado sigue siendo el README genérico del proyecto principal de ZMK y no ofrece una guía de inicio rápido específica para SF32. Utilice la placa, el shield, el manifiesto, el código fuente y el commit como referencia ejecutable, y exija evidencias propias de compilación limpia, grabación, funcionamiento y recuperación antes de adaptar el sistema.

¿Por qué esta implementación en SF32?¶

La adaptación para SF32 muestra cómo ejecutar el modelo de teclado de ZMK en SF32LB52 y conservar las convenciones de Zephyr para el árbol de dispositivos (devicetree), Kconfig, west, mapas de teclas, shields y teclados divididos. La configuración urchin_sf32lb52 reparte 38 teclas entre las dos mitades. La configuración izquierda cumple la función central: activa CherryUSB y ZMK Studio y puede ofrecer HID por USB al equipo anfitrión. La configuración derecha cumple la función periférica. ZMK BLE está activado en ambas mitades.

El repositorio derivado resulta útil para evaluar un teclado inalámbrico dividido en dos mitades, un dispositivo de entrada USB/Bluetooth para escritorio, un teclado macro programable o un producto HMI personalizado basado en SF32. La contrapartida es la madurez de las dependencias: el manifiesto west fija una rama personalizada de Zephyr (v4.3+sf32-zmk_fixes), una revisión concreta de SiFli HAL y la rama personalizada zephyr-adapt de CherryUSB. Estas dependencias forman parte de los límites de compatibilidad de la adaptación; no pueden sustituirse por las revisiones «latest» del proyecto principal sin una migración completa y una ronda de regresión.

Resultado, alcance y criterios de entrada¶

Resultado: compilar y grabar imágenes con versiones fijadas de las mitades izquierda y derecha de Urchin; validar toda la matriz de teclas, las capas, HID USB, el enlace BLE entre mitades y la conexión con el host, la persistencia de los ajustes, los límites de ZMK Studio y la recuperación; y después realizar un cambio controlado en el mapa de teclas o el hardware con evidencias repetibles.

Esta página no afirma que exista paridad completa de funciones con el proyecto principal de ZMK, compatibilidad con cualquier shield de ZMK, autonomía de batería apta para producción, rendimiento de radio verificado ni una migración admitida a otra revisión de Zephyr/ZMK. Tampoco define una PCB de teclado lista para producción: la configuración Urchin del repositorio asigna una matriz de referencia a los pines de SF32LB52-DevKit-LCD; esa asignación debe adaptarse deliberadamente a cada diseño de hardware personalizado.

Antes de empezar, tenga preparado lo siguiente:

• dos placas SF32LB52-DevKit-LCD compatibles con la variante sf32lb525uc6/zmk del repositorio derivado;
• un montaje de prueba para teclado dividido de 38 teclas, cableado exactamente según los overlays urchin_sf32lb52_left y urchin_sf32lb52_right, o un shield de prueba más pequeño y documentado para las primeras comprobaciones de la adaptación;
• un host con un entorno west de Zephyr/ZMK funcional y espacio suficiente para los módulos fijados en el repositorio derivado;
• conexiones de grabación, consola serie y recuperación verificadas para cada mitad antes de probar la comunicación entre ellas;
• un cable USB de datos para la mitad izquierda/central y un método independiente para alimentar y recuperar la mitad derecha/periférica;
• un host Bluetooth, un host compatible con ZMK Studio si se incluye Studio en el alcance y una forma de medir la corriente de cada mitad;
• un registro del commit del repositorio derivado, las revisiones del manifiesto, los identificadores de placa y shield, los registros de compilación y grabación, los resultados de las pruebas de teclas, las vinculaciones (bonds) Bluetooth, el estado de los ajustes y las medidas de corriente.

Especificaciones de hardware y software¶

Especificación de hardware¶

Especificación de software¶

Elegir una configuración de referencia admitida¶

La configuración de referencia revisada de OpenSiFli corresponde al commit fd4d5843065f del 27-05-2026. Incluye la actualización del shield Urchin y de la configuración de la placa disponible en ese commit, pero no es una versión etiquetada de ZMK para SF32. Fije este commit para la reproducción inicial o registre y revise expresamente cualquier commit posterior.

Los siguientes comandos siguen el flujo de trabajo west del repositorio derivado y usan los identificadores exactos de la placa SF32 y los shields Urchin. Mantenga separados los dos directorios de compilación para no confundir las imágenes:

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

Registre el west list final, la configuración Kconfig y el devicetree generados, los hashes de los artefactos, las etiquetas de imagen/mitad y el procedimiento real de grabación. No empiece a probar el teclado dividido hasta que pueda recuperar cada placa de forma independiente.

Etapas del proyecto¶

Arquitectura del sistema y dependencias¶

flowchart LR
    KL["Matriz izquierda\n19 posiciones"] --> L["SF32LB52 izquierdo\nCentral ZMK"]
    KR["Matriz derecha\n19 posiciones"] --> R["SF32LB52 derecho\nPeriférico ZMK"]
    R -->|"Enlace BLE dividido de ZMK"| L
    L -->|"HID USB\nCherryUSB"| H["Ordenador host"]
    L -->|"HID Bluetooth"| H
    H <-->|"ZMK Studio\nsolo en la imagen de firmware del lado izquierdo"| L
    NL["Ajustes NVS\nvinculaciones (bonds) y configuración"] --> L
    NR["Ajustes NVS\nestado persistente"] --> R
    M["Manifiesto west de OpenSiFli\nZephyr + HAL + CherryUSB personalizados"] --> L
    M --> R

Separe los fallos por ámbito: matriz y cableado físico, enlace de derecha a izquierda entre mitades, USB de la mitad izquierda, Bluetooth del host, vinculaciones (bonds) y ajustes almacenados, ZMK Studio, grabación y recuperación de la placa y conjunto de dependencias fijadas. Si una tecla no llega al host, el fallo puede producirse antes del escaneo, durante la comunicación entre mitades, en el mapa de teclas central o en el endpoint HID elegido. Diagnostique la ruta en ese orden.

Etapa 1 — Reproducir la configuración de referencia sin modificarla¶

Objetivo: verificar exactamente la referencia de OpenSiFli antes de cambiar el mapa de teclas, un overlay o alguna dependencia.

1. Registre las revisiones de ambas placas y conecte los dos montajes de prueba exactamente según las configuraciones overlay Urchin izquierda y derecha. Identifique las placas y los cables USB/de grabación según su función.
2. Compile ambas imágenes en el commit fijado y guarde west list. Inspeccione la configuración generada para confirmar la placa, el shield, las funciones central y periférica, BLE, CherryUSB, ZMK Studio y los ajustes NVS esperados.
3. Grabe cada imagen mediante la ruta de recuperación verificada de forma independiente para cada placa. Registre el arranque en frío y la consola antes de emparejar las mitades o el host.
4. Establezca el enlace BLE entre las dos mitades y compruebe las 38 posiciones con las capas default, lower y raise. Pruebe expresamente la selección y eliminación del perfil Bluetooth y las combinaciones de desbloqueo de Studio para evitar que se activen accidentalmente durante las pruebas de escritura.
5. Valide HID USB y ZMK Studio en la mitad izquierda y, a continuación, HID Bluetooth en el host elegido. Repita las pruebas después de un arranque en frío.

Evidencias que se deben conservar: registro de placas y cableado, revisiones del repositorio derivado y del manifiesto, configuraciones generadas, hashes de las imágenes, registros de grabación y arranque, matriz completa de posiciones, resultados por capa, endpoint HID seleccionado y versiones del host/Studio.

Criterio de salida del punto de control 1: dos arranques en frío reproducen las 38 posiciones, las tres capas, el enlace de derecha a izquierda entre mitades y al menos un endpoint HID del host; ambas mitades se pueden recuperar de manera independiente.

Etapa 2 — Validar entrada, transporte, ajustes y recuperación¶

Objetivo: demostrar que los fallos de teclado habituales son visibles y recuperables sin reconstruir el firmware a partir de un estado desconocido.

Criterio de salida del punto de control 2: cada fallo aplicable tiene un resultado repetible de detección y recuperación; ninguna prueba deja un estado HID atascado; y los ajustes o las vinculaciones pueden volver a la referencia registrada sin sustituir archivos sin seguimiento.

Etapa 3 — Crear una configuración de referencia reproducible desde el código fuente¶

Objetivo: permitir que otro ingeniero regenere ambas imágenes y repita la Etapa 2 desde fuentes limpias.

1. Empiece con una copia de trabajo limpia del repositorio derivado en el commit registrado y ejecute west init, west update y west zephyr-export sin sustituir módulos localmente.
2. Guarde west list, las versiones del compilador y las herramientas, el .config generado, el devicetree generado, la salida de memoria, los registros de compilación y ambos artefactos con sus hashes.
3. Grabe las imágenes etiquetadas de izquierda y derecha en las mitades correctas y repita todas las pruebas de la Etapa 2.
4. Compare los artefactos y la configuración con el registro original; explique cualquier diferencia no reproducible antes de continuar.

Criterio de salida del punto de control 3: un segundo entorno genera imágenes correctamente identificadas que superan la Etapa 2 sin overlays sin seguimiento, resultados de compilación obsoletos ni revisiones de dependencias sin fijar.

Etapa 4 — Adaptar un límite del teclado cada vez¶

Objetivo: realizar un cambio de producto conservando la adaptación cuya funcionalidad ya se ha comprobado y las rutas de recuperación independientes.

Criterio de salida del punto de control 4: el cambio se ha revisado, se pueden restaurar las imágenes y ajustes originales y se superan todas las pruebas aplicables de matriz, capas, comunicación entre mitades, USB, BLE, Studio, alimentación y recuperación.

Etapa 5 — Revisión de preparación del producto¶

Antes de diseñar una PCB de teclado personalizada o un prototipo con batería, responda a estas preguntas:

• ¿Quién mantiene el repositorio derivado de ZMK de OpenSiFli, la rama personalizada de Zephyr, la revisión de SiFli HAL, la adaptación de CherryUSB y las futuras actualizaciones de seguridad o compatibilidad?
• ¿Qué funciones del proyecto principal de ZMK se han probado realmente en SF32 y cuáles solo están presentes en el árbol heredado?
• ¿Cómo se controlarán durante fabricación y mantenimiento la identidad de las imágenes izquierda/derecha, la revisión de la placa, el mapa de teclas, la configuración, las vinculaciones y el estado de restablecimiento de fábrica?
• ¿Cuáles son las corrientes medidas activa, en reposo con conexión, desconectada y en suspensión de cada mitad, incluidas la frecuencia de escaneo, la reconexión y la protección de la batería?
• ¿Qué hosts, sistemas operativos, controladores USB, pilas Bluetooth, rutas de activación, casos de rollover y condiciones de interferencia se han probado?
• ¿Se puede recuperar el producto sin abrirlo ni desecharlo si falla una actualización de dependencias, un cambio de Studio, una escritura de ajustes o una actualización en campo?
• ¿Son aptos para la distribución prevista las licencias de ZMK/Zephyr, los archivos de PCB y carcasa, el contenido del mapa de teclas, los logotipos, las fuentes y cualquier configuración incluida?

Criterio de salida del punto de control 5: todos los riesgos restantes tienen un responsable, evidencias y una decisión, y el equipo ha decidido expresamente continuar, aplazar o detenerse.

Traspaso a la fase de diseño del producto¶

Traslade el número de pieza SF32 y la memoria exactos, las funciones de ambas mitades y el transporte, el mapa de filas/columnas/entradas directas, la dirección de los diodos, la conexión USB, las hipótesis de antena y carcasa, la política NVS/ajustes, las interfaces de grabación y recuperación, el presupuesto de consumo de cada mitad, los útiles de prueba, la identificación de las imágenes y el manifiesto fijado. Continúe con SF32LB52-DevKit-LCD, los límites de la plataforma Zephyr, Arquitectura Bluetooth, la guía de diseño de hardware de SF32LB52x y Diseño para producción.

Fuentes de referencia¶

• Repositorio derivado SF32 de OpenSiFli/zmk
• Commit revisado de OpenSiFli/zmk
• Variante de placa ZMK para SF32LB52 en el commit revisado
• Shield dividido Urchin SF32LB52 en el commit revisado
• Manifiesto west de OpenSiFli ZMK en el commit revisado
• Proyecto principal zmkfirmware/zmk
• Documentación de ZMK
• Documentación del proyecto Zephyr

Última actualización: 2026-10-21