Pocket Pi SF32 Handheld Game Console¶

What Is Pocket Pi?¶

SiFliSparks/PocketPi is a handheld game-console and emulator reference for SF32LB52. The current source integrates the Nofrendo NES emulator, an LVGL game browser, a 320 × 240 ST7789 8080 display path, audio, save/load state, an embedded filesystem, and a TF-card ROM directory. Its public build baseline uses the Huangshan Pi / sf32lb52-lchspi-ulp target.

It is useful for testing how local graphics, input, audio, external storage, PSRAM allocation, and emulator load coexist on an SF32LB52 system. The repository does not include commercial game ROMs; users must supply .nes/.NES files they are entitled to use. The public source is also not a complete production-handheld design and does not replace battery-safety, audio, EMC, thermal, licensing, or content-distribution review.

Why the SF32 Implementation?¶

NES emulation compresses several embedded boundaries into one intuitive workload: CPU emulation, PPU graphics, audio sampling, low-latency keys, file reads, frame buffering, and save states must continue to work together. SF32LB52 display, audio, external-storage, PSRAM, and battery-platform capabilities make it a practical starting point for a low-cost local-interaction product.

The value is not a claim that every NES title is fully compatible. ROM mapper support, frame rate, audio, save behavior, peak memory, and input latency can differ by game. Each added ROM or mapper needs its own compatibility and copyright decision.

Outcome, Scope, and Entry Criteria¶

Outcome: build a repeatable image from current PocketPi source, boot at least one legally usable test ROM, validate display, input, audio, pause, save, load, exit, and recovery, then complete one bounded adaptation.

This page does not guarantee every NES mapper, PAL/NTSC timing, game-audio path, save format, or third-party ROM. It grants no right to copy or distribute game content. The repository currently has no top-level license file; before copying code into a product or distributing binaries, an owner must establish the license for PocketPi, Nofrendo, and every incorporated third-party component.

Before starting, have:

• SF32LB52-DevKit-ULP / Huangshan Pi, or hardware that matches the repository’s sf32lb52-lchspi-ulp board definition;
• the 320 × 240 display, AW9523 I²C input expander, keys, audio, and optional TF-card path expected by the current source; the board name alone does not prove that all peripherals are assembled;
• SiFli-SDK, SCons, UART download, and logging tools;
• a self-authored, public-domain, or properly licensed .nes test ROM;
• the ROM under repository disk/ for the built-in filesystem, or under /roms/nes on a TF card;
• a way to observe frame behavior, audio, input, memory, and current.

Choose a Supported Baseline¶

Use the upstream main branch locked to commit 7d9fac2. The README provides this build route:

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

The build script turns ../disk into a filesystem image and adds it to the firmware as fs_root. On Windows, the generated build_sf32lb52-lchspi-ulp_hcpu\uart_download.bat supplies the download path. Other hosts should use the corresponding SiFli-SDK download tool and record equivalent parameters.

Delivery Map¶

System Architecture and Dependencies¶

flowchart LR
    B["Build input\nlegal NES ROMs under disk/"] --> F["fs_root filesystem image"]
    C["TF card\n/sdcard/roms/nes"] --> L["LVGL game browser"]
    F --> L
    L --> N["Nofrendo NES emulator\nCPU, PPU, mappers, state"]
    I["AW9523 I²C keys\nA/B, directions, Start, Select, Menu, L/R"] --> N
    N --> V["320 × 240 ST7789 display"]
    N --> A["32 kHz audio path"]
    N <--> S["Save State / Load State"]
    D["SiFli-SDK and board support\nPSRAM, Flash, TF card, battery"] --> L
    D --> N

The principal failure domains are filesystem/ROM, mapper/emulator, PSRAM/memory, display/frame timing, AW9523 input, audio, save state, and power/reset. A black screen should first be separated into “ROM not discovered,” “artwork decode failed,” “mapper unsupported,” “framebuffer allocation failed,” or “LCD path failed,” rather than being reported generically as an emulator failure.

Stage 1 — Establish the Untouched Game Baseline¶

Goal: use one legal test ROM to prove the complete path from build input to running game.

1. Lock the PocketPi and SiFli-SDK commits plus the board and peripheral revisions.
2. Put a legal .nes ROM under disk/; if supplying artwork, use a same-basename .jpg. Save the ROM hash, provenance, and mapper.
3. Build cleanly and confirm that fs_root is generated and included in the download artifacts.
4. Download and cold-start. Confirm the game appears in the list, cover art or the default image is visible, and the game launches.
5. Record startup time, stable video, key response, audio, and serial logs, then reset and repeat.

Evidence to retain: repository/SDK commits, board and peripherals, ROM hash/license, build log, filesystem image, download log, serial log, and game-list/runtime photos.

Gate 1 exit criterion: two cold starts list and run the same ROM, with repeatable display, basic directions/A/B/Start/Select, and audio behavior.

Stage 2 — Validate Input, State, and Fault Recovery¶

Goal: turn “the game starts” into a reviewable handheld baseline.

Gate 2 exit criterion: input, display, audio, pause, save, load, exit, and reset are recorded for the selected ROM, and each failure maps to a defined domain.

Stage 3 — Build a Reproducible Source and Content Baseline¶

Goal: allow another engineer to rebuild the same firmware and content image.

1. Record PocketPi, SiFli-SDK, and any third-party core revisions.
2. Create a disk/ manifest containing filenames, hashes, provenance, and licenses for each ROM and cover. Do not commit ROMs you cannot redistribute.
3. Build from an empty output directory and save fs_root, firmware, memory/partition output, download script, and hashes.
4. Rebuild on a second computer or in a clean directory and repeat the core Stage 2 tests.

Gate 3 exit criterion: source and content manifests reproduce an image with matching hashes or explained differences, without undocumented local files.

Stage 4 — Adapt One Variable at a Time¶

Goal: measure the emulator, content, and hardware boundary.

Gate 4 exit criterion: the change and content rights are reviewed, the original image is recoverable, and all selected-ROM Stage 2 tests pass.

Stage 5 — Product-Readiness Review¶

Before custom handheld hardware or content distribution, answer:

• Which mappers does the intended game set require, and has each ROM’s frame rate, audio, memory, and save behavior been qualified?
• Are the licenses and distribution rights for PocketPi, Nofrendo, SiFli-SDK, fonts, covers, sounds, and ROMs clear?
• Do the AW9523, LCD, audio, TF card, battery, and charging hardware have complete schematics, BOMs, and production tests?
• What are game, list, pause, sleep, and off-state current, battery life, temperature, and low-battery behavior?
• How are save states protected and migrated after power loss, version updates, full media, or corruption?
• How does the device recover from a damaged filesystem, failed update, black screen, or unbootable ROM?

Gate 5 exit criterion: compatibility matrix, content/software licensing, hardware ownership, power, and recovery risks have named owners and a proceed/defer/stop decision.

Handoff to Product Design¶

Carry forward the SF32/module selection, PSRAM and Flash peaks, display/framebuffer path, AW9523 input matrix, audio amplifier and speaker, TF card and built-in filesystem, save-state format, battery/charging, recovery download port, ROM/mapper compatibility matrix, and complete license manifest. Continue with SF32LB52x, SF32LB52-DevKit-ULP, SiFli-SDK Build, Flash, and Monitor, and Design for Production.

Authoritative Sources¶

• SiFliSparks/PocketPi
• Locked reference commit 7d9fac2
• LCKFB Huangshan Pi SF32LB52-ULP board
• OpenSiFli/SiFli-SDK
• pebri86/esplay-retro-emulation
• LVGL documentation