spruceOS: a community firmware and front end for cheap retro handhelds

A community package for handhelds that ship with rough software

spruceOS describes itself as a community software package intended to help you get the most out of your Miyoo, TrimUI and Anbernic RG XX devices. The stated mission is a balanced user experience for both new and seasoned emulation enthusiasts, with sane and well-optimized defaults for people who do not want to tweak settings and deep customization for people who do. The target hardware is the class of inexpensive Linux-based handhelds that ship with a usable but unpolished interface. The project is volunteer work with a fluid team structure, and the README names individual contributors from recent development cycles along with a special thanks list covering themes, custom emulator builds, custom SDL2 versions, shaders and organizational work. It is a community around a device rather than a commercial product, and the tone of the README, including the risk disclaimer about device damage, reflects that.

The UI is Python, which is why it is themeable at all

The feature list leads with a snappy and incredibly themeable custom Python-based UI. That choice explains a lot of what follows. A UI written in Python running on the handheld's Linux userspace can be restyled without recompiling anything, which is what makes the theme system possible at the scale described later. The repository layout backs this up with a spruce directory for the UI itself, an App directory, and separate directories per device family: miyoo, miyoo355 and trimui. The presence of a directory per device tells you the package ships device-specific parts, since button labels, key mappings and screen behaviour differ between these handhelds. There is also a RetroArch directory, an Emu directory, Persistent, Roms, Saves, BIOS, Themes, Licenses and a To-Do.txt, which is the full on-card layout a user ends up with after installation.

Save states, the Game Switcher and autosave on shutdown

The features that change how the device feels day to day are about state management rather than emulation. The Game Switcher lets you switch between save states during gameplay, and the README explains the shortcut as holding the MENU button for three seconds. Autosave on shutdown and autoresume on boot means the game state is saved automatically when you power off in-game and restored when you power on. The global hotkey list also includes quicksave plus shutdown, which is holding POWER for three seconds, and brightness down and up mapped to START plus the shoulder buttons or MENU plus the volume keys, depending on the device. The README also notes a detail that is easy to miss: holding POWER after the vibration occurs forces a shutdown, which is the escape hatch if a game has frozen the device.

Network services over WiFi, and how updates arrive

spruceOS adds connectivity features the stock firmware generally lacks. The list includes RetroAchievements, RTC sync over WiFi, SSH and SFTP, Syncthing, Samba and HTTP file transfer. Syncthing in particular turns the handheld into a device that syncs your game library from a desktop without a cable, and Samba and HTTP file transfer are the simpler alternatives for people who do not want to run a sync client. Updates also arrive over the air on the device, so you are not pulling an image to a PC and copying it back. The README credits XanXic with designing the OTA and EZ Updaters, which are separate pieces of tooling for getting new versions onto the card. The whole feature set here is a strong reason to use a USB or network file transfer rather than repeatedly swapping SD cards.

Installation is format the card and copy files

The install instructions are unusually short, and the reason is that there is no operating system to install. The short version is to format the SD card to FAT32, extract the 7z file using the 7zip app, and copy the files onto the card. There is a longer wiki installation page for anyone who wants more detail, and one manual step remains regardless: you place your own BIOS files in the BIOS folder at the root of the card, which is a licensing matter as much as a technical one, since the project does not ship them. A separate all-in-one installer program is published for people who would rather not do it by hand. You insert the SD card, run the program, select the correct drive, and it formats the card, downloads the latest official release and installs it in one click. The warning about selecting the correct drive is not decorative, given that the operation begins with a format.

The theme system is the community's real contribution

The themes section shows where the project's energy goes. The classic spruce theme is described as minimalistic, and around a dozen default themes ship with the package. Beyond those, you can download community themes from a separate PyUI-Themes repository and place the unextracted .7z archives into the Themes folder on the card, or use the Theme Garden app, which browses the repository and installs over the air directly onto the device. The Theme Garden is listed as carrying currently over 80 community-made themes, and that number is the closest thing to a measure of the community's activity. There is also a Theme Design Guide in the wiki, described as preliminary work, and the project asks theme authors to get in touch so it can feature their artwork. The combination of a documented format, an over-the-air installer and a submission process is a genuine platform rather than a settings screen.

The rest of the feature set is emulation and a scraper

The remaining features are more conventional. CPU performance profiles come pre-configured, tuned for a balance of battery life and performance, which is the single most useful thing to get right on a handheld that runs on a small battery. Native Pico-8 support comes with Splore, so the fantasy console works without an emulator front end. A built-in boxart scraper app uses the libretro API to fetch cover art, and the all-in-one installer section notes that version 1.1 added that scraper. There is also a Game Nursery app for downloading free ports, demakes and homebrew for various systems directly to the device, and that one is a different proposition from the rest because it fetches content over the network rather than formatting it. The project ships per-device key mappings for RetroArch, PPSSPP and DSperate, and the DSperate section has a full breakdown of the differences between zero-stick, one-stick and two-stick devices, since stylus control moves between them.

Editorial conclusion

spruceOS fits an owner of one of the supported handhelds who wants a coherent front end, save state management, network features and a theme they control instead of the device's stock software, and who is comfortable replacing an SD card's contents. It does not fit someone who wants the vendor's supported firmware with its warranty intact, since the project is explicitly unofficial and carries a damage warning, and it does not fit a device outside the listed models. Verify first that your exact handheld and firmware revision are covered, back up anything on the card before the install, and read the BIOS folder requirement, since the games will not run until you supply your own BIOS files.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. spruceUI/spruceOS on GitHub