Arduboy2 的 SF32LB52 移植版¶

什么是 Arduboy2-SiFli？¶

OpenSiFli/Arduboy2-SiFli 是 OpenSiFli 面向思澈科技（SiFli）开发环境移植的 Arduboy2 库。Arduboy2 为小型游戏设备提供面向应用的模型：帧循环、显示缓冲区、按键、精灵、文本和可选的声音控制。因此，思澈科技（SiFli）移植适合作为兼容性实验：它检验在底层开发板、显示、输入、音频和构建路径迁移到 SF32 后，一个 Arduboy 风格的游戏能保留多少内容。

该仓库是软件参考实现，不是完整的游戏机，也不是量产硬件设计。确切的开发板目标、受支持 API 范围、构建流程和再分发条件，应以上游仓库的 README、源代码、示例、问题记录和许可证文件为准。本文负责围绕该参考实现组织工程决策，不替代仓库中的可执行说明。

这一 SF32 移植版有何价值？¶

Arduboy 风格的应用可以一次性验证多项嵌入式产品决策：可预测的渲染循环、小型单色或低分辨率资源、按键输入、音频时序以及严格的内存预算。将这一模型移植到 SF32，可以为掌上游戏、UI 演示、教育设备，以及其他本地交互且具有确定性的产品提供早期参考。

价值不在于每个 Arduboy Sketch 都能原样运行，而在于这次移植暴露出的边界：

• 如果游戏停留在受支持的 Arduboy2 API 范围内，可以保留较高层的更新、输入、绘图和资源逻辑。
• 移植必须转换原始硬件中隐含的显示、按键、音频、时序和存储假设。
• 直接控制 AVR 寄存器、Arduboy 专用引脚、显示事务、定时器或 EEPROM 布局的 Sketch，都需要有意改造并单独提供回归证据。

以上是工程预期，而不是经过测量的兼容性声明。应根据当前 OpenSiFli 仓库，针对所选开发板和提交版本确认实际结果，并记录证据。

成果、范围与进入条件¶

本文定义一条从 OpenSiFli 参考实现出发，得到一个可复现的 SF32 游戏或交互式演示的分阶段路径。本文不声称移植支持所有 Arduboy2 功能、所有 Arduboy 游戏、所有 SF32 开发板，也不声称显示和音频时序已经达到量产品质。本文也不意味着你对从第三方仓库复制的游戏、字体、图像或其他资源拥有使用许可。

**成果：**得到一个受源代码管理的 Arduboy2-SiFli 构建：能在开发板上运行仓库示例或小型测试 Sketch，展示选定的显示 / 输入 / 音频路径，并保留判断是否值得投入更大游戏或产品适配所需的证据。

**目标读者：**能够使用 Arduino 工具、阅读 C/C++ 代码、向 SF32 开发板烧录固件、读取串口输出，并完成基本显示、输入和功耗测量的固件、硬件和产品工程师。

开始前准备好以下内容：

• 使用 ArduinoCore-Zephyr 变体 sf32lb52_devkit_lcd_sf32lb525uc6 的 SF32LB52 开发板，以及下文所列的外接外设。README 说明显示、按键、外接 EEPROM 和音频路径已在 SF32LB52 硬件上运行过；README 也记录了 RGB LED 路径，但未说明该路径经过了测试。README 没有固定实体开发板的硬件版本，也未注明 OLED 模组的具体型号。
• 已验证可用的 Arduino 环境和匹配的 OpenSiFli 开发板软件包。上述变体名称只确定软件目标和引脚映射，并不能证明所有 SF32LB52-DevKit-LCD 实物版本都符合项目的外接接线要求；连接外设前应核对实际开发板原理图。
• Arduboy2-SiFli 的准确提交版本、Arduino 核心 / 软件包版本、主机操作系统和烧录工具。
• USB 数据连接，以及记录串口日志、观察显示、按键和音频输出的方法。
• 对下游适配中包含的每个游戏、图像、字体和声音资源，拥有使用和再分发的许可。

硬件与软件规格¶

硬件规格¶

软件规格¶

选择受支持的基线¶

从 OpenSiFli 仓库明确列出的开发板和软件组合开始，不要因为某块开发板看起来相似，就从产品目录中自行选择。开发板软件包、显示接线、按键映射、烧录方法和库的假设共同构成基线。

Arduboy2-SiFli 仓库没有单独的开发板引脚映射文件；具体映射表发布在 README 的 SiFli I/O mapping 表 中。库内部的逻辑引脚定义见 pins_sifli.h，开发板侧的引脚路由则由 ArduinoCore-Zephyr 中对应的设备树叠加文件（devicetree overlay）定义。这些资料描述的是软件基线，并不代表某个实体装配已通过验证；接线前仍须核对实际开发板版本及其原理图。

仓库给出了软件开发板变体和外设引脚映射，并说明显示、按键、外接 EEPROM 和音频路径已在 SF32LB52 硬件上运行过。仓库还记录了外接 RGB LED 的支持路径，但未说明经过了测试。仓库没有注明实体开发板版本、OLED 模组 / 控制器的具体型号，也没有给出完整的配件装配方案。接线或声明硬件基线可复现之前，应将该变体的引脚映射与实际开发板原理图逐项核对，并记录所用器件及版本。不得用其他 SF32 项目的引脚映射或地址填补剩余信息空缺。

项目阶段与决策要点¶

将以下阶段视为决策门槛，而不是功能清单。

系统架构与依赖¶

flowchart LR
    G["游戏 Sketch\n更新、输入、绘图、资源"] --> A["Arduboy2-SiFli\n兼容层"]
    A --> C["Arduino 核心\n开发板软件包和运行时"]
    C --> S["SiFli-SDK / SF32\nGPIO、显示、定时器、存储、音频"]
    S --> H["所选 SF32 开发板\n显示、按键、扬声器、USB"]
    A --> R["参考测试\n串口日志和视觉检查"]

这是用于决策的模型，不代表仓库内部一定使用这些模块名称。修改移植前，应确认实际源代码边界。对产品最重要的路径包括：

• **帧和时序：**游戏循环必须以可重复的节奏更新和渲染；任何对时序敏感的音频或输入行为，都必须在目标开发板上测量。
• **显示：**兼容层必须将游戏缓冲区和几何参数映射到所选显示控制器、像素格式、方向和刷新路径。
• **输入：**必须针对开发板接线检查按键名称、电平、消抖、同时按键以及唤醒 / 复位行为。
• **音频：**在验证之前，应将音调生成、定时器占用、扬声器连接、音量和静音行为视为开发板专用问题。
• **资源和存储：**必须在链接所选游戏后测量字体、精灵、声音数据、Flash 布局和 RAM 使用量。
• **恢复：**在尝试时序、内存或低功耗改动前，保留已知可用的烧录和恢复路径。

主要故障域包括应用 / API 兼容性、显示配置、输入接线、音频 / 定时器行为、内存与资源布局，以及烧录 / 恢复。某一故障域出错时，不应笼统地报告为“移植不可用”。

阶段 1——建立未修改的参考基线¶

**目标：**在修改库或游戏前，证明仓库文档中的基线确实可用。

1. 阅读仓库说明，记录默认分支或发布版本，并检查示例、开发板配置、依赖和许可证文件。
2. 安装仓库要求的准确 Arduino 核心 / 软件包和工具。记录主机操作系统和工具版本。
3. 构建并烧录文档中最小的示例或测试 Sketch。
4. 捕获串口输出，并记录显示内容、哪些按键有响应，以及示例是否使用音频。

**应保留的证据：**仓库提交版本、依赖 / 软件包版本、开发板版本、接线或原理图依据、构建输出、烧录日志、串口日志和简短功能记录。

**关口 1 退出条件：**未修改的参考实现能在所选开发板上构建和烧录，且复位或断电重启后仍能重复观察到文档描述的行为。

阶段 2——验证外设与时序边界¶

**目标：**将“成功编译”与“可用的游戏设备基线”区分开来。

1. 验证示例使用的显示清屏、整帧更新、精灵或位图绘制、文本路径以及几何 / 方向假设。
2. 验证项目使用的全部输入，包括释放、同时按键、快速按键，以及适用时的复位或唤醒行为。
3. 如果包含音频，验证音调启动 / 停止、定时器交互、静音行为，以及显示和输入活动对音频路径的影响。
4. 通过复位、拔插电源以及无效或不完整的输入序列中断正常流程，记录开发板是否能恢复到可烧录、可运行状态。

**应保留的证据：**视觉或捕获的显示结果、输入矩阵、时序观察、音频观察、复位 / 恢复日志，以及会影响产品决策的电流或延迟（latency）测量。

**关口 2 退出条件：**已经充分理解所选外设路径，能够区分应用错误、开发板配置问题、时序问题和供电问题。

阶段 3——建立可复现的源码基线¶

**目标：**让移植可以复现，而不是依赖某一台开发机或现成二进制文件。

1. 从干净检出开始，并初始化仓库要求的全部依赖。
2. 记录开发板软件包、Arduino IDE / CLI 版本、编译器 / 工具版本、配置文件和生成的资源。
3. 在干净目录中构建，保存生成的镜像以及可用的 map / 大小信息，并记录烧录命令或工具输出。
4. 在第二台机器上，或删除构建目录后重复构建。

**应保留的证据：**源代码版本、依赖版本、主机 / 工具清单、构建日志、二进制或其他产物、大小报告、烧录日志和串口日志。

**关口 3 退出条件：**干净检出能构建出通过阶段 2 外设检查的镜像，且不依赖未记录的本地文件或手工改动。

阶段 4——有意地适配一个游戏¶

**目标：**通过一项受控的产品改动证明兼容边界。

从一个显示、输入、音频和资源需求都清晰的小型 Sketch 或游戏开始。保留未修改的参考镜像，每次只改动一类行为：

没有来源支持时，不要将 AVR 寄存器访问、原始 Arduboy 引脚假设或存储地址直接复制到 SF32 项目中。将第三方游戏和资源许可证随适配后的源码一同保存；再分发条件不清楚的内容应当移除。

**应保留的证据：**经过评审的差异、资源来源、前后镜像、构建和烧录日志、回归结果以及回滚镜像。

**关口 4 退出条件：**适配后的游戏通过参考外设检查，并且已经记录其内存、时序、恢复和许可证边界。

阶段 5——产品就绪评审¶

在从移植演示进入定制硬件或现场试用前，团队必须回答：

• 哪一块 SF32 开发板、显示、按键、扬声器和供电是受支持的，哪些仍只是工程假设？
• 在目标产品基线上测得的帧率、输入延迟、音频行为、启动时间和电流特征是什么？
• 游戏、资源、字体和运行时合计消耗多少Flash 和 RAM，最坏内容规模下又是多少？
• 复位、欠压、保存过程中断电、资源损坏、烧录失败或升级中断后会发生什么？
• 移植中哪些部分由产品团队、OpenSiFli、思澈科技（SiFli）或原始 Arduboy2 社区维护？
• 每个游戏、字体、图像、声音和库的许可证是否与预期的分发方式兼容？

**关口 5 退出条件：**剩余风险已经指定责任人并有证据支持；每一项都有缓解措施、明确的延期决定或停止决定。

产品设计阶段交接¶

将选定的 SF32 器件、显示和输入架构、音频 / 定时器方案、Flash 和资源布局、功耗测量、恢复方法以及量产测试假设带入硬件栏目。如果游戏的显示、内存、封装、功耗或连接能力要求改变了器件候选范围，请使用 SF32 产品选型工具。软件基线应从Arduino 入门指南开始，再阅读 Arduino 平台概览。

当另一名工程师能够重建移植、重复外设结果、解释每一项开发板专用适配，并在批准定制开发板或扩展游戏库前审查相关证据时，该参考实现才完成了产品开发层面的使命。

权威来源¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• SF32 Arduino 入门指南
• Arduino 平台概览
• SF32 产品选型工具

最后更新: 2026-10-21