Adaptación de Arduboy2 para SF32LB52¶

¿Qué es Arduboy2-SiFli?¶

OpenSiFli/Arduboy2-SiFli es una adaptación de la biblioteca Arduboy2 realizada por OpenSiFli para el entorno de desarrollo de SiFli. Arduboy2 ofrece un modelo de aplicación para dispositivos de juego pequeños: bucle de fotogramas, búfer de pantalla, botones, sprites, texto y control de sonido opcional. Por ello, esta adaptación sirve como experimento de compatibilidad: permite comprobar cuánto de un juego estilo Arduboy puede conservarse al trasladar a SF32 la placa, la pantalla, la entrada, el audio y el proceso de compilación.

El repositorio es una referencia de software, no una consola terminada ni un diseño de hardware para producción. Utilice el README, el árbol de fuentes, los ejemplos, el historial de incidencias y los archivos de licencia como autoridad sobre la placa objetivo exacta, la API admitida, las instrucciones de compilación y las condiciones de redistribución. Esta página organiza las decisiones de ingeniería en torno a esa referencia, pero no sustituye sus instrucciones ejecutables.

¿Qué aporta esta adaptación a SF32?¶

Una aplicación estilo Arduboy permite poner a prueba de forma compacta varias decisiones de un producto embebido: un bucle de renderizado predecible, recursos monocromos o de baja resolución, entrada por botones, temporización de audio y un presupuesto de memoria muy acotado. Adaptar ese modelo a SF32 puede servir como referencia inicial para juegos portátiles, demostradores de interfaz, dispositivos educativos y otros productos con interacción local y determinista.

El valor no reside en que todos los sketches de Arduboy funcionen sin cambios, sino en los límites que pone de manifiesto la adaptación:

• El juego puede conservar la lógica de alto nivel de actualización, entrada, dibujo y recursos si se mantiene dentro de la API Arduboy2 admitida.
• La adaptación debe resolver las hipótesis implícitas del hardware original sobre la pantalla, los botones, el audio, la temporización y el almacenamiento.
• Cualquier sketch que controle directamente registros AVR, pines específicos de Arduboy, transacciones de pantalla, temporizadores o disposición de EEPROM requiere una adaptación deliberada y evidencias de regresión independientes.

Estas son expectativas de ingeniería, no afirmaciones de compatibilidad medidas. Confírmelas en el repositorio actual de OpenSiFli y registre el resultado exacto para la placa y el commit seleccionados.

Resultado, alcance y criterios de entrada¶

Esta página define una ruta por etapas desde la referencia de OpenSiFli hasta un juego o demostración interactiva reproducible en SF32. No afirma que la adaptación admita todas las funciones de Arduboy2, todos los juegos de Arduboy o todas las placas SF32, ni que ofrezca temporización de pantalla y audio con calidad de producción. Tampoco concede derechos de licencia sobre juegos, fuentes, gráficos u otros recursos copiados de repositorios de terceros.

Resultado: una compilación de Arduboy2-SiFli bajo control de versiones que ejecute un ejemplo del repositorio o un sketch de prueba pequeño, demuestre la ruta elegida de pantalla/entrada/audio y reúna evidencia para decidir si se justifica adaptar un juego o producto mayor.

Público destinatario: ingenieros de firmware, hardware y producto capaces de usar las herramientas de Arduino, revisar código C/C++, grabar una placa SF32, leer la salida serie y realizar mediciones básicas de pantalla, entrada y consumo.

Antes de empezar, tenga a mano lo siguiente:

• Una placa SF32LB52 que use la variante ArduinoCore-Zephyr sf32lb52_devkit_lcd_sf32lb525uc6, además de los periféricos externos descritos abajo. El README indica que las rutas de pantalla, botones, EEPROM externa y audio se han probado en hardware SF32LB52; también documenta una ruta para un LED RGB, pero no indica ningún resultado de prueba. Tampoco fija una revisión física de la placa ni identifica el modelo exacto del módulo OLED.
• Una instalación de Arduino conocida como funcional y el paquete de placas OpenSiFli correspondiente. El nombre de la variante define una base de software y un mapa de pines, pero no demuestra que todas las unidades SF32LB52-DevKit-LCD coincidan con el cableado externo del proyecto; compruebe el esquemático de la placa concreta antes de conectar periféricos.
• El commit exacto de Arduboy2-SiFli, la versión del core o paquete Arduino, el sistema operativo del host y la herramienta de carga.
• Una conexión USB de datos y un medio para capturar el registro serie y observar la pantalla, los botones y la salida de audio.
• Permiso para utilizar y redistribuir todos los juegos, imágenes, fuentes y recursos de audio incluidos en cualquier adaptación posterior.

Especificaciones de hardware y software¶

Especificación de hardware¶

Especificación de software¶

Elegir una configuración de referencia admitida¶

Empiece por la combinación de placa y software indicada en el repositorio OpenSiFli, en lugar de escoger una placa del catálogo por semejanza. El paquete de placas, cableado de pantalla, asignación de entradas, método de carga e hipótesis de la biblioteca forman parte de la referencia.

El repositorio Arduboy2-SiFli no ofrece el mapa de pines de la placa en un archivo independiente: la tabla concreta está publicada en el README, en SiFli I/O mapping. Las definiciones lógicas de pines de la biblioteca están en pins_sifli.h, y el enrutamiento específico de la placa se define en el overlay de Devicetree de ArduinoCore-Zephyr. Estas fuentes describen una base de software, no un montaje físico validado; antes de cablear, compruebe la revisión real de la placa y su esquemático.

El repositorio identifica una variante de placa de software y un mapa de pines de los periféricos, e indica que las rutas de pantalla, botones, EEPROM externa y audio se han probado en hardware SF32LB52. También documenta una ruta para un LED RGB externo, pero no afirma que se haya probado. No identifica la revisión física de la placa, el modelo/controlador exacto del OLED ni un conjunto completo de accesorios. Antes de cablear o declarar reproducible la base de hardware, contraste el mapa de pines de la variante con el esquemático de la placa concreta y registre los componentes y revisiones utilizados. No complete las lagunas restantes con mapas de pines o direcciones copiados de otro proyecto SF32.

Etapas del proyecto¶

Utilice estas etapas como puntos de decisión, no como una lista de funciones.

Arquitectura del sistema y dependencias¶

flowchart LR
    G["Sketch del juego\nactualización, entrada, dibujo, recursos"] --> A["Arduboy2-SiFli\ncapa de compatibilidad"]
    A --> C["Core Arduino\npaquete de placa y entorno de ejecución"]
    C --> S["SiFli-SDK / SF32\nGPIO, pantalla, temporizadores, almacenamiento y audio"]
    S --> H["Placa SF32 seleccionada\npantalla, botones, altavoz y USB"]
    A --> R["Pruebas de referencia\nregistro serie y comprobaciones visuales"]

Este es un modelo para tomar decisiones, no una afirmación de que el repositorio utilice exactamente estos nombres internos de módulos. Confirme los límites reales del código antes de modificar la adaptación. Los aspectos clave del producto son:

• Fotogramas y temporización: el bucle del juego debe actualizar y renderizar con una cadencia repetible, y cualquier comportamiento de audio o entrada sensible a la temporización debe medirse en la placa objetivo.
• Pantalla: la capa de compatibilidad debe adaptar el búfer y la geometría del juego al controlador de pantalla, formato de píxel, orientación y método de actualización seleccionados.
• Entrada: los nombres y la polaridad de los botones, el antirrebote, las pulsaciones simultáneas y el comportamiento de activación/reinicio deben comprobarse frente al cableado de la placa.
• Audio: la generación de tonos, la asignación de temporizadores, la conexión del altavoz, el volumen y el silencio deben tratarse como específicos de la placa hasta verificarlos.
• Recursos y almacenamiento: las fuentes, los sprites, los datos de sonido, la distribución de Flash y el uso de RAM deben medirse tras enlazar el juego seleccionado.
• Recuperación: conserve un método de carga y recuperación conocido antes de experimentar con temporización, memoria o bajo consumo.

Los principales dominios de fallo son la compatibilidad de aplicación/API, configuración de pantalla, cableado de entrada, comportamiento de audio/temporizadores, memoria y ubicación de recursos, y carga/recuperación. Un fallo en uno de estos dominios no debe notificarse simplemente como «la adaptación no funciona».

Etapa 1 — Establecer la referencia sin modificar¶

Objetivo: comprobar que la configuración de referencia documentada en el repositorio funciona antes de cambiar la biblioteca o el juego.

1. Lea las instrucciones del repositorio, registre la rama o versión predeterminada y revise los ejemplos, la configuración de placa, las dependencias y las licencias.
2. Instale la versión exacta del core/paquete Arduino y las herramientas requeridas por el repositorio. Registre el sistema operativo anfitrión y las versiones de las herramientas.
3. Compile y cargue el ejemplo documentado más pequeño o el sketch de prueba.
4. Capture la salida serie y registre lo que aparece en pantalla, qué botones responden y si el ejemplo utiliza audio.

Evidencia que debe conservar: commit del repositorio, versiones de dependencias/paquetes, revisión de placa, referencia de cableado o esquemático, salida de compilación, registro de carga y serie, y una nota funcional breve.

Criterio de salida del punto de control 1: la referencia sin modificar compila y se carga en la placa seleccionada, y su comportamiento documentado se repite tras un reinicio o ciclo de alimentación.

Etapa 2 — Validar periféricos y límites de temporización¶

Objetivo: distinguir una compilación correcta de una referencia funcional para un dispositivo de juego.

1. Pruebe el borrado de pantalla, la actualización de fotograma completo, el renderizado de sprites o mapas de bits, el texto y las hipótesis de geometría/orientación del ejemplo.
2. Pruebe todas las entradas del proyecto: soltar botones, pulsaciones simultáneas y rápidas, y el comportamiento de reinicio o activación cuando corresponda.
3. Si se incluye audio, verifique el inicio y la parada de tonos, la interacción con temporizadores, el silencio y el efecto de la actividad de pantalla y entrada sobre el audio.
4. Interrumpa el flujo normal mediante reinicio, desconexión/reconexión y una secuencia de entrada no válida o incompleta. Registre si la placa vuelve a un estado utilizable para cargar y ejecutar.

Evidencia que debe conservar: resultados visuales o capturas de pantalla, matriz de entradas, observaciones de temporización y audio, registro de reinicio/recuperación y cualquier medición de corriente o latencia que afecte a la decisión de producto.

Criterio de salida del punto de control 2: se conoce suficientemente la ruta de periféricos para distinguir errores de aplicación de problemas de configuración, temporización o alimentación de la placa.

Etapa 3 — Crear una base reproducible del código fuente¶

Objetivo: hacer reproducible la adaptación sin depender de una única máquina de desarrollo ni de un binario proporcionado.

1. Parta de un checkout limpio e inicialice todas las dependencias requeridas por el repositorio.
2. Registre el paquete de placas, la versión de Arduino IDE/CLI, el compilador y las herramientas, los archivos de configuración y los recursos generados.
3. Compile desde un directorio limpio, guarde la imagen generada y, si están disponibles, el mapa de memoria y el informe de tamaño; registre también el comando o la salida de carga.
4. Repita el proceso en otra máquina o después de eliminar el directorio de compilación.

Evidencia que debe conservar: revisión de fuentes y dependencias, manifiesto del host/herramientas, registro de compilación, binario u otro artefacto, informe de tamaño y registros de carga y serie.

Criterio de salida del punto de control 3: un checkout limpio reproduce una imagen que supera las pruebas de periféricos de la Etapa 2 sin archivos locales ni cambios manuales no documentados.

Etapa 4 — Adaptar un juego de forma controlada¶

Objetivo: demostrar los límites de compatibilidad con un cambio de producto controlado.

Empiece por un sketch o juego pequeño cuyos requisitos de pantalla, entrada, audio y recursos estén claros. Conserve la imagen de referencia sin modificar y cambie una sola clase de comportamiento cada vez:

No copie accesos a registros AVR, hipótesis de pines del Arduboy original ni direcciones de almacenamiento en el proyecto SF32 sin una decisión de diseño respaldada por fuentes. Mantenga las licencias de juegos y recursos de terceros junto al código adaptado y retire todo aquello cuyas condiciones de redistribución no estén claras.

Evidencia que debe conservar: diff revisado, procedencia de recursos, imágenes antes/después, registros de compilación/carga, resultados de regresión e imagen de respaldo para volver a la referencia.

Criterio de salida del punto de control 4: el juego adaptado supera las pruebas de periféricos de referencia y quedan documentados los límites de memoria, temporización, recuperación y licencias.

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

No pase de una demostración de la adaptación a hardware personalizado o pruebas de campo hasta que el equipo pueda responder:

• ¿Qué placa SF32, pantalla, botones, altavoz y fuente de alimentación exactos están admitidos y cuáles siguen siendo hipótesis?
• ¿Qué frecuencia de fotogramas, latencia de entrada, comportamiento de audio, tiempo de inicio y perfil de corriente se midieron en la configuración de producto prevista?
• ¿Cuánta Flash y RAM consumen el juego, recursos, fuentes y entorno de ejecución, incluido el contenido del peor caso?
• ¿Qué ocurre tras un reinicio, caída de tensión, pérdida de alimentación durante el guardado, recursos dañados, carga fallida o actualización incompleta?
• ¿Qué partes de la adaptación mantienen el equipo del producto, OpenSiFli, SiFli o la comunidad original de Arduboy2?
• ¿Son compatibles las licencias de todos los juegos, fuentes, imágenes, sonidos y bibliotecas con el modelo de distribución previsto?

Criterio de salida del punto de control 5: los riesgos pendientes tienen responsables y evidencia, y cada uno cuenta con mitigación, aplazamiento explícito o decisión de detenerse.

Traspaso a la fase de diseño del producto¶

Traslade a la sección Hardware el dispositivo SF32 seleccionado, la arquitectura de pantalla/entrada, el plan de audio/temporizadores, la distribución de Flash y recursos, las mediciones de consumo, el método de recuperación y las hipótesis de pruebas de producción. Utilice el Selector de productos SF32 si los requisitos de pantalla, memoria, encapsulado, alimentación o conectividad del juego modifican la lista de dispositivos candidatos. Para establecer la base de software, consulte Primeros pasos con Arduino y luego la Descripción de la plataforma Arduino.

La referencia ha cumplido su función de desarrollo de producto cuando otro ingeniero puede reconstruir la adaptación, reproducir los resultados de periféricos, explicar cada ajuste específico de placa y revisar la evidencia antes de aprobar una placa personalizada o ampliar la biblioteca de juegos.

Fuentes de referencia¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• Primeros pasos con Arduino en SF32
• Descripción de la plataforma Arduino
• Selector de productos SF32

Última actualización: 2026-10-21