Teclado macro multifunción SuperKey¶

¿Qué es SuperKey?¶

SiFliSparks/SuperKey es una implementación de referencia basada en SF32LB52 para un teclado macro multifunción con pantallas. Su firmware de código abierto funciona con RT-Thread y LVGL v9, controla tres LCD GC9107 de 128 × 128, tres LED RGB, cuatro teclas físicas, un codificador rotatorio y un sensor de temperatura y humedad SHT30, y se conecta al ordenador como dispositivo USB compuesto HID/CDC.

SuperKey va más allá de un teclado de accesos directos. La implementación de referencia reúne estas funciones:

• salida USB HID de teclado y controles multimedia;
• recepción de datos de rendimiento del PC, meteorología, configuración y estado de alimentación por USB CDC o UART de 1 Mbps;
• páginas en tres pantallas para supervisar el rendimiento, consultar el tiempo, ver la hora, usar utilidades, acceder a la música y definir asignaciones de teclas;
• aplicación complementaria SuperKeyHub para recopilar datos del host, configurar funciones y actualizar el firmware;
• hardware reproducible mediante el diseño abierto sf32-keyboard.

¿Por qué la implementación con SF32?¶

SuperKey necesita gráficos, varias pantallas, un dispositivo USB compuesto, teclas y codificador, sensores, efectos RGB, un sistema de archivos y audio opcional. SF32LB52 mantiene estas tareas en tiempo real en la MCU, por lo que el dispositivo puede iniciar su interfaz y ofrecer funciones HID básicas aunque la aplicación complementaria no esté ejecutándose. La aplicación del host se ocupa de la telemetría del ordenador y los datos de Internet, que es más adecuado gestionar desde un sistema operativo de escritorio.

Esta división encaja con controladores de escritorio, teclados para flujos de trabajo, paneles de estado e interfaces HMI compactas, pero crea dependencias explícitas. Las pantallas de datos avanzadas requieren la aplicación complementaria, controladores y API externas; las versiones del firmware y del host deben ser compatibles; y la pérdida de USB, la suspensión del host y una configuración dañada requieren pruebas de recuperación independientes.

Resultado, alcance y criterios de entrada¶

Resultado: reproducir una configuración de SuperKey con versiones fijadas y validar HID, CDC, la interfaz de tres pantallas, la entrada, los sensores y la recuperación tras la suspensión; después, modificar una sola categoría de comportamiento y conservar evidencias de compilación, comunicación y regresión para la revisión del producto.

Esta página no demuestra que la PCB abierta esté lista para producción ni que sea compatible con todas las fuentes de telemetría de PC, servicios meteorológicos, puentes serie, hosts USB o versiones de sistemas operativos. Las cotizaciones bursátiles, los datos meteorológicos y los de rendimiento pueden depender de la versión de SuperKeyHub, de API de terceros, de los permisos del sistema y del hardware del host.

Antes de empezar, tenga preparado:

• hardware SuperKey montado según el diseño abierto, con tres LCD GC9107, teclas, codificador y conexión USB de datos;
• un ordenador con Windows 10/11 para la ruta principal documentada; el repositorio de SuperKeyHub indica compatibilidad con Windows y macOS, pero valide la grabación de la placa, CDC y la recuperación en el sistema operativo elegido;
• una versión de SuperKeyHub compatible con el firmware;
• un entorno SiFli-SDK, el submódulo del SDK clonado de forma recursiva y una conexión funcional de grabación/recuperación;
• una API Key, API Host y configuración de ciudad válidos de QWeather, si se va a probar la meteorología;
• un registro de pruebas de enumeración USB, registros serie, respuesta de teclas, estado de pantalla y recuperación tras suspensión.

Especificaciones de hardware y software¶

Especificación de hardware¶

Especificación de software¶

Elegir una configuración de referencia admitida¶

La página de versiones del proyecto incluye el firmware v1.4.2, que sirve como punto de partida fijo. El material citado no establece una versión compatible concreta de SuperKeyHub; elija y fije una versión o un commit de Hub, pruebe con v1.4.2 la telemetría, la configuración y DFU, y registre la combinación probada en lugar de suponer compatibilidad por los números de versión.

La integración continua del proyecto utiliza el siguiente objetivo. Instale y exporte el entorno SiFli-SDK antes de ejecutarlo localmente:

git clone --recursive https://github.com/SiFliSparks/SuperKey.git
cd SuperKey/SiFli-SDK
./install.sh
. ./export.sh
cd ../app/project
scons --board=sf32lb52-superkey --board_search_path="../boards" -j8

En Windows, utilice los scripts correspondientes de instalación y configuración del entorno SiFli-SDK para PowerShell. El paralelismo puede variar, pero el nombre de la placa, la ruta de búsqueda de placas y las revisiones de los submódulos deben quedar registrados en la compilación.

Etapas del proyecto¶

Arquitectura del sistema y dependencias¶

flowchart LR
    U["Usuario\nteclas y codificador rotatorio"] --> F["Firmware SF32LB52\nRT-Thread + LVGL v9"]
    F --> D["Tres LCD GC9107\nLED RGB, SHT30 y audio opcional"]
    F -->|"USB HID\nteclado y eventos multimedia"| P["Equipo anfitrión Windows / macOS"]
    P -->|"USB CDC o UART de 1 Mbps\ntelemetría, clima, configuración y modo de alimentación"| F
    H["SuperKeyHub\nrecopilación, configuración y actualización"] <--> P
    H <--> A["API meteorológica y fuentes de telemetría del equipo anfitrión"]
    H -->|"CDC DFU"| F

Clasifique los fallos en cinco dominios: hardware/pantalla del dispositivo, entrada HID, canal de datos CDC/UART, aplicación complementaria/permisos del sistema y servicios de datos externos. Si el panel meteorológico aparece vacío, no significa automáticamente que haya fallado el firmware; puede deberse a la API Key, API Host, configuración de ciudad o envío de datos.

Etapa 1 — Establecer la base de referencia sin modificar¶

Objetivo: demostrar la ruta de referencia completa antes de cambiar el código.

1. Siga las instrucciones de montaje del proyecto original para comprobar la orientación del cable LCD, los interruptores, el codificador, la carcasa y el conector USB; registre las revisiones de la PCB y del firmware.
2. Instale la versión compatible de SuperKeyHub. Compruebe que el dispositivo se enumera y pruebe HID y CDC por separado.
3. Configure las credenciales meteorológicas, el puerto y la comunicación serie a 1 Mbps. Registre el comportamiento sin la aplicación complementaria; después, conéctela y active el envío de datos.
4. Verifique la navegación en las tres pantallas, la asignación de teclas, el control multimedia, el codificador, los datos del SHT30, los efectos LED y un ciclo completo de actualización de telemetría.
5. Realice un arranque en frío y repita las pruebas. Guarde fotos de la interfaz, registros de la aplicación y del dispositivo, y el resultado de la consulta de versión.

Evidencia que se debe conservar: revisión del hardware, etiqueta/commit del firmware, commit del SDK, versión de la aplicación complementaria, sistema operativo, configuración del puerto y la API, enumeración USB, registros, pantallas y registro de entrada.

Criterio de salida del punto de control 1: dos arranques en frío completan la entrada HID, la actualización de datos CDC y la interacción con las tres pantallas; los registros o estados observables permiten distinguir cada dominio de fallo.

Etapa 2 — Validar los límites de fallo y recuperación¶

Objetivo: demostrar que las interrupciones habituales en un ordenador de escritorio no convierten el dispositivo en una demostración que requiera volver a grabar el firmware.

Criterio de salida del punto de control 2: cada fallo aplicable tiene un resultado repetible de detección y recuperación, sin necesidad de reparar manualmente estados no documentados.

Etapa 3 — Crear una base de código reproducible¶

Objetivo: permitir que otro ingeniero compile, grabe el firmware y repita la Etapa 2 desde un clon limpio.

1. Clone el repositorio de forma recursiva y registre los commits de SuperKey y SiFli-SDK.
2. Compile desde cero con el destino sf32lb52-superkey y la ruta de búsqueda ../boards.
3. Guarde el registro de compilación, la salida de memoria/particiones, el script de grabación, las imágenes generadas y el registro serie.
4. Repita la compilación en un segundo ordenador o después de borrar el directorio de compilación; grabe el firmware en el mismo hardware y vuelva a ejecutar las regresiones principales.

Criterio de salida del punto de control 3: no se necesitan archivos sin seguimiento, resultados antiguos ni sustituciones manuales de binarios para generar una imagen que supere la Etapa 2.

Etapa 4 — Adaptar una variable del producto cada vez¶

Objetivo: validar el alcance del cambio sin comprometer la referencia aprobada.

Criterio de salida del punto de control 4: se ha revisado el cambio, se puede recuperar la imagen original y pasan las pruebas HID, CDC, pantalla, entrada, suspensión y recuperación.

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

Antes de crear hardware propio o un lote piloto, el equipo debe responder:

• ¿El producto seguirá dependiendo de SuperKeyHub, privilegios de administrador y un servicio meteorológico de terceros? ¿Quién es responsable de esas dependencias?
• ¿Cómo se gestionan las versiones de firmware, aplicación complementaria y protocolo, y cómo se bloquean las combinaciones incompatibles?
• ¿Qué combinaciones de PC, hubs USB, cables, políticas de suspensión y software de seguridad se han probado?
• ¿Cuánta memoria, temperatura y corriente se registran al usar a la vez las tres pantallas, los datos USB, los LED, los sensores y el audio opcional?
• ¿Cómo se recuperan la configuración, las asignaciones de teclas y el estado de actualización tras perder alimentación o dañarse el almacenamiento?
• ¿Las licencias de la PCB abierta, la carcasa, las fuentes, los iconos, la música y las API de terceros permiten la distribución prevista?

Criterio de salida del punto de control 5: cada riesgo restante tiene un responsable, evidencia y resolución; el equipo ha decidido continuar, aplazar o detener.

Traspaso a la fase de diseño del producto¶

Traslade la selección de SF32 y memoria, los descriptores USB HID/CDC, las conexiones de las tres pantallas y la retroiluminación, las interfaces de entrada y sensores, la política de alimentación y suspensión, el sistema de archivos y las particiones de actualización, el protocolo de la aplicación complementaria, los puntos de prueba de producción y la ruta de recuperación validada. Continúe con SF32LB52x, la guía de diseño de hardware SF32LB52x, Compilar, grabar y supervisar con SiFli-SDK y Diseño para producción.

Fuentes de referencia¶

• Repositorio de firmware SiFliSparks/SuperKey
• Versión SuperKey v1.4.2
• Repositorio de la aplicación complementaria SiFliSparks/SuperKeyHub
• Documentación del proyecto SuperKey
• Hardware abierto sf32-keyboard
• OpenSiFli/SiFli-SDK

Última actualización: 2026-10-21