Pocket Pi SF32 掌上游戏机¶

Pocket Pi 是什么？¶

SiFliSparks/PocketPi 是一个面向 SF32LB52 的掌上游戏机与模拟器参考工程。在固定提交版本中，项目集成了 Nofrendo NES 模拟器、LVGL 游戏列表、320 × 240 ST7789 8080 显示路径、音频输出、存档/读档、内置文件系统和 TF 卡 ROM 目录，并以黄山派 / sf32lb52-lchspi-ulp 作为公开构建基线。

它适合用来验证本地图形、输入、音频、外部存储、PSRAM 分配和模拟器负载如何在一个 SF32LB52 系统中协同工作。项目仓库不附带商业游戏 ROM；用户必须自行准备有权使用的 .nes/.NES 文件。公开源码也不是完整的量产掌机设计，不能替代电池安全、音频、EMC、散热、许可证和内容分发评审。

为什么选择 SF32 实现？¶

NES 模拟把多个嵌入式系统边界集中到一个直观的工作负载中：CPU 模拟、PPU 图形、音频采样、低延迟（latency）输入、文件读取、帧缓冲和存档都必须协同工作。基于 SF32LB52 的系统具备这一工作负载所需的显示、音频、外部存储和 PSRAM 资源；黄山派还可作为电池供电的评估平台。

这并不意味着所有 NES 游戏都完全兼容。ROM 映射器（mapper）的支持情况、帧率、音频、存档行为、内存峰值和输入延迟都可能因游戏而异；每增加一个 ROM 或 mapper，都需要单独评估兼容性并确认版权。

成果、范围与进入条件¶

**目标成果：**从软件规格表中固定的 PocketPi 提交版本构建可重复镜像，启动至少一个已获使用授权的测试 ROM，验证显示、输入、音频、暂停、存档、读档、退出和恢复，再完成一个受控适配。

本页不保证所有 NES mapper、PAL/NTSC 时序、游戏音频、存档格式或第三方 ROM 可用，也不授予任何游戏内容的复制或分发权。固定版本的仓库没有顶层许可证文件；在复制代码进入产品或发布二进制前，必须由负责人确认 PocketPi、Nofrendo 及每项第三方代码的许可。

开始前应准备：

• SF32LB52-DevKit-ULP / 黄山派，或与仓库 sf32lb52-lchspi-ulp 板级定义一致的硬件；
• 与固定版本源码匹配的 320 × 240 显示、AW9523 I2C 输入扩展器、按键、音频和可选 TF 卡路径；开发板名称本身不证明这些外设已完整装配；
• SiFli-SDK、SCons、串口下载和日志环境；
• 一个自行编写、公共领域或已获得授权的 .nes 测试 ROM；
• 若使用内置文件系统，把 ROM 放入仓库 disk/；若使用 TF 卡，则放入固件配置的 ROM 目录。固定提交版本的运行时扫描路径为 /sdcard/roms/nes，请对照该版本源码确认 TF 卡的挂载路径；
• 可观察帧表现、音频、输入、内存和电流的测试方法。

硬件与软件规格¶

硬件规格¶

软件规格¶

选择受支持的基线¶

使用软件规格中固定的 PocketPi 版本，不要直接构建当前 main 分支指向的提交：

git clone https://github.com/SiFliSparks/PocketPi.git
cd PocketPi
git checkout 7d9fac2cb577d6c9b66a99521aebf3c9de0ae163
cd project
scons --board=sf32lb52-lchspi-ulp -j8

构建脚本会把 ../disk 生成文件系统镜像并作为 fs_root 加入固件产物。Windows 下载路径由生成的 build_sf32lb52-lchspi-ulp_hcpu\uart_download.bat 提供；其他主机应使用 SiFli-SDK 对应的下载工具，并记录等效参数。

项目阶段与决策要点¶

系统架构与依赖¶

flowchart LR
    B["构建输入\ndisk/ 中有权使用的 NES ROM"] --> F["fs_root 文件系统镜像"]
    C["TF 卡\n/sdcard/roms/nes"] --> L["LVGL 游戏列表"]
    F --> L
    L --> N["Nofrendo NES 模拟器\nCPU、PPU、mapper 与存档/读档状态"]
    I["AW9523 I2C 按键\nA/B、方向、Start、Select、Menu、L/R"] --> N
    N --> V["320 × 240 ST7789 显示"]
    N --> A["32 kHz 音频路径"]
    N <--> S["Save State / Load State"]
    D["SiFli-SDK 与板级支持\nPSRAM、Flash、TF 卡、电池"] --> L
    D --> N

主要故障域包括文件系统与 ROM、mapper/模拟器、PSRAM 与内存、显示与帧时序、AW9523 输入、音频、存档以及电源/复位。出现黑屏时，应先区分“ROM 没被扫描到”“封面图解码失败”“mapper 不支持”“帧缓冲分配失败”和“LCD 路径错误”，而不是统一归为模拟器故障。

阶段 1 — 建立未经修改的游戏基线¶

**目标：**用一份有权使用的测试 ROM 验证从构建输入到游戏运行的完整路径。

1. 锁定 PocketPi 与 SiFli-SDK 的 commit，以及板卡和外设版本。
2. 将有权使用的 .nes ROM 放入 disk/；如提供封面，使用同名 .jpg。保存 ROM 哈希、来源和 mapper 信息。
3. 执行干净构建，确认 fs_root 被生成并加入下载产物。
4. 下载后冷启动，确认游戏出现在列表中、封面或默认图片可见，并能进入游戏。
5. 记录启动时间、稳定画面、按键响应、音频和串口日志，然后复位并重复一次。

**应保留证据：**仓库/SDK commit、板卡与外设、ROM 哈希/许可、构建日志、文件系统镜像、下载日志、串口日志、游戏列表和运行照片。

**关口 1 退出条件：**两次冷启动均能列出并运行同一 ROM，显示、基本方向/A/B/Start/Select 与音频行为可重复。

阶段 2 — 验证输入、状态和故障恢复¶

**目标：**把“游戏能启动”提升为可评审的掌机基线。

**关口 2 退出条件：**选定 ROM 的输入、显示、音频、暂停、存档、读档、退出和复位都有记录，失败可定位到具体故障域。

阶段 3 — 建立可复现源码与内容基线¶

**目标：**让另一位工程师能够重建同一固件与同一内容镜像。

1. 保存 PocketPi、SiFli-SDK 和任何第三方内核的版本记录。
2. 为 disk/ 建立清单，记录每个 ROM/封面的文件名、哈希、来源和许可；不要把无权分发的 ROM 提交到仓库。
3. 从空输出目录构建，保存 fs_root、固件、分区/内存输出、下载脚本和哈希。
4. 在第二台电脑或干净目录中重建并执行阶段 2 核心测试。

**关口 3 退出条件：**源码与内容清单足以重现哈希一致或差异已有说明的镜像，且没有依赖未记录的本地文件。

阶段 4 — 一次只适配一个变量¶

**目标：**测清模拟器、内容和硬件边界。

**关口 4 退出条件：**改动及其内容许可已经评审，原版镜像可恢复，选定 ROM 的阶段 2 测试全部通过。

阶段 5 — 产品就绪评审¶

进入定制掌机或内容发布前，必须回答：

• 目标游戏集合需要哪些 mapper，每个 ROM 的帧率、音频、内存和存档是否逐一验证？
• PocketPi、Nofrendo、SiFli-SDK、字体、封面、声音和 ROM 的许可证与分发权是否清晰？
• AW9523、LCD、音频、TF 卡、电池和充电硬件是否有完整原理图、BOM 与生产测试？
• 游戏中、列表、暂停、睡眠和关机的电流、续航、温升与低电量行为是多少？
• 存档在断电、版本升级、空间不足和损坏时如何保护和迁移？
• 设备如何从损坏文件系统、失败升级、黑屏或不可启动 ROM 中恢复？

**关口 5 退出条件：**兼容性矩阵、内容/软件许可、硬件责任、功耗和恢复风险均有负责人和继续/延期/停止决定。

产品设计阶段交接¶

交接资料应包含 SF32/模组选择、PSRAM 与 Flash 峰值、显示和帧缓冲、AW9523 输入矩阵、音频放大器与扬声器、TF 卡和内置文件系统、存档格式、电池/充电、恢复下载口、ROM/mapper 兼容矩阵以及完整许可证清单。可从 SF32LB52x、SF32LB52-DevKit-ULP、SiFli-SDK 构建、烧录与监视和面向量产的设计继续。

权威来源¶

• SiFliSparks/PocketPi
• 锁定的参考 commit 7d9fac2
• 立创·黄山派 SF32LB52-ULP 开发板
• OpenSiFli/SiFli-SDK
• 思澈科技（SiFli）Wiki：黄山派开发板指南
• SiFli-SDK 上手指南
• pebri86/esplay-retro-emulation
• LVGL 文档

最后更新: 2026-10-21