Skip to content
tarikbcPublic

About

A fast, light firmware for the GKD Pixel 2 that plays your whole retro library: forty systems, PortMaster ports, and your music, audiobooks and videos.

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Repository files navigation

ZyperOS: Zyper, a miniature schnauzer with his head cocked and his tongue out, beside the name

A fast, light firmware for the GKD Pixel 2 and the TrimUI Brick that plays your whole retro library.

On in about 2 seconds. The stock firmware takes 30 to 40.
Turn it off mid-game; turn it on, and 2 seconds later you're back where you were.
Forty-five systems with their box art, PortMaster ports, RetroAchievements, and your music and videos. Free and open source.

Download the latest release of ZyperOS  Install in three steps  Join the ZyperOS Discord  Card image downloads of every ZyperOS release

zyperos.com  ·  Why ZyperOS  ·  Features  ·  Systems  ·  Try it on a Mac  ·  Guide  ·  Discord

The Nintendo 64 shelf: Super Mario 64's box large in the middle, Mario Kart 64 and Ocarina of Time beside it, a play mark on each cover for its video snap

Why ZyperOS

  • Your library looks the part. Every game shows its real box art, found on the handheld itself from libretro, ScreenScraper and SteamGridDB, and a few seconds of video when you rest on it.
  • On in about 2 seconds. The stock firmware takes 30 to 40 (my test, on my Pixel 2). Turn it off mid-game, and the next start puts you back where you were, 2 seconds later. Games start the moment you press A.
  • Plays more, smoothly. Forty-five systems, the PSP among them, and PortMaster's ports. On my Pixel 2, Super Mario 64 keeps its 30 frames a second, and Mario Kart DS holds 60 in light scenes and drops to about 40 in a busy race.
  • No more taking the card out. Add games, music and saves from any browser over Wi-Fi or the USB cable, and update ZyperOS the same way.
  • Made to be picked up. A first start that teaches every button, eight languages, light and dark, and a menu that never makes you wait.
  • Free and open source, under GPL-3.0, with nothing locked behind a payment.

Two handhelds

  • GKD Pixel 2: the handheld ZyperOS began on. It has no Wi-Fi of its own: a USB Wi-Fi adapter gives it Wi-Fi, and the USB cable moves files without one.
  • TrimUI Brick (TG3040), from 1.0.6: drawn for its own 1024x768 screen and its keys, with Wi-Fi built in. It runs from its own microSD card and never writes to the Brick's storage: take the card out, and the Brick starts its own system again. The 3D systems, PortMaster's ports and a few extras are not there yet (the list).

Install in three steps

  1. Download ZyperOS Installer for macOS, Windows or Linux from the latest release.
  2. Write the card. Put the microSD card in the computer, pick the GKD Pixel 2 or the TrimUI Brick, the latest release and the card, and choose Fresh install.
  3. Play. Put the card in the handheld and turn it on. The first start sets the card up in about a minute, then shows you each button.

Then add games over Wi-Fi, the USB cable or the card itself. The guide covers the card image, updates and the Wi-Fi adapter.

Questions, ideas, or want to help build it? Come say hi on the ZyperOS Discord.

Watch the ZyperOS tour: a green GKD Pixel 2 showing a shelf of PlayStation covers, beside the ZyperOS name
The 1.0.5 video tour. See the current screens on zyperos.com.

Screens

The PlayStation shelf: Metal Gear Solid's box large, Crash Bandicoot and Spyro the Dragon beside it, a heart before the focused game's name
Your games, cover by cover
The Spotlight home: PlayStation's console large, the other systems in a row below
Every system, in pixel art
Metal Gear Solid's Cover and Video page: its cover now, the boxes, title screen and screenshots the sources offer, and its video
Pick a cover, and see it first
An achievement's unlock notice: its badge, 'Unlocked · 10 points' over its name, and Zyper at the right
RetroAchievements, and Zyper cheers
The in-game menu over a paused Spyro the Dragon, on its Display tab and Shader row: Sharp-Shimmerless, with the Game and Controls tabs beside it
A shader for each system, in the Display tab
Install PortMaster: its crane icon, PortMaster's version, what it is, and the download's bar at 9.8 of 24 MB
PortMaster with one press
MENU > Storage: the card in one bar by part, two recommendations, then every system by size
What fills the card
The Grid home: eighteen systems' consoles in three rows of six, each with its name, NES underlined, its whole name and 18 games under the grid
Or the Grid home, 18 systems at once
The ZyperOS home on the TrimUI Brick's 1024x768 screen: the PS1 with ZyperOS's own system art, and MENU, the Brick's key, for Settings
The same, on the TrimUI Brick

The shots show real box art to show what the Scraper does. The games and their art belong to their owners: ZyperOS comes with no games and no art.

Features

Each line has its details in the guide.

  • Forty-five systems, from the Atari 2600 and the SG-1000 to the PSP, Dreamcast and Saturn, with Arcade, MAME, Doom, ScummVM, PICO-8 and OpenBOR (the list).
  • Ports: the Ports shelf installs the official PortMaster with one press and runs its games, such as Stardew Valley and Celeste, with ZyperOS's in-game menu over every port (how).
  • Your own PICO-8: add the PICO-8 for Raspberry Pi zip you bought from Lexaloffle with ZyperOS Installer, or copy it to the card, and your PICO-8 plays the carts, with Splore, its online cart browser, first on the PICO-8 shelf, and your hotkeys, Reset and your own buttons over it. ZyperOS never ships or downloads PICO-8; without it, FAKE-08 plays the carts (how).
  • Nintendo DS your way: DSperate with three screen layouts, a d-pad stylus and a language you pick for each game (notes).
  • Nintendo 64 and Dreamcast: ParallelN64 with Glide64 holds Super Mario 64 and Mario Kart 64 at 30 frames a second on my Pixel 2, and flycast2021 runs the Dreamcast (Dreamcast).
  • Zipped games read stored, Deflate or LZMA, and a zip it cannot read says so on the shelf.
  • Two Game Boy cores: mGBA, or Gambatte from the Game Boy and Game Boy Color shelves' Core row.
  • Smooth or exact timing in the Game Boy, Game Boy Advance, DS and Genesis shelves: one game frame for each screen refresh, or the console's own speed for timers and rhythm games.
  • A home in pixel art: every system as its own animated console on a Spotlight, Gallery or Grid home, with Favorites, Recents and a choice of which systems show (the shelf).
  • Recents where you stopped: Recents can show each game's last screen, its cover small in the corner, instead of the cover.
  • Your folders, a grid or a list: folders on the card show as folders, a game on several discs shows once by its .m3u, and a system's games show as a row of covers, a grid shaped like the art, or a list.
  • A Video view: each game's video snap on the whole screen as you move, its cover in a row at the foot.
  • Collections of your own: put any game in a list from its details, mix systems, and find your lists in a group on the home (collections).
  • MENU in six tabs, with Search Games and Random Game for any system (menus).
  • Your look: light and dark, or Auto by Night Mode's hours, ten accents, three backgrounds for each theme, a folder color, rounded or square corners, how the game or system in focus is marked (a bar, a border, a lift, or none), and Zyper on or off (light and dark).
  • Screen Colors and Night Mode on the Pixel 2: temperature, tint, contrast, saturation and gamma, ready-made looks, set from MENU or a game's own menu, and a warm screen for the night (how).
  • Shaders: Sharp-Shimmerless for even pixels, and CRT, CRT Curved, Scanlines and LCD Grid for an old screen, each at a strength you set (how they look).
  • Borders round a handheld game: the three Game Boys' own faces drawn around the game at its scale (the Game Boy Color in its six colors), the game blurred, or a picture of your own (Border).
  • Eight languages, chosen on the first start or in MENU > Language, with every word following it, down to the charging screen (languages).
  • A first start that asks: Zyper teaches each button, then asks for the theme, the home screen, the button sounds and the menu music (the first start).
  • Box art the device finds itself from libretro, ScreenScraper and SteamGridDB, with Cover and Video to pick a cover and see it first (Scraper).
  • Every download in one place: MENU > Downloads gets covers, video snaps, names and every game's achievements at once, side by side, and keeps going behind the menus while you browse (Downloads).
  • Video snaps and a screensaver: rest on a game and its cover turns into a few seconds of the game itself, and after a minute on the shelf the snaps of random games play over the whole screen (how).
  • RetroAchievements, signed in on the device and working offline: an unlock shows at once and goes to your account when Wi-Fi is back, dated when you earned it (how).
  • Coming from Knulli, ROCKNIX, ArkOS or ROGUE OS: copy their roms folders over as they are, with the covers, video snaps, names and favorites their scrapers left (what ZyperOS reads).
  • Rename or delete a game on the handheld: its saves, states, cover and play time follow the new name or go with the game (Delete Game).
  • Storage, as a phone shows it: what fills the card by part, by system and by game, with two recommendations for room to clear (Storage).
  • Wi-Fi and USB File Transfer: move games, music, videos, saves and covers from any browser behind a PIN; with no Wi-Fi around the handheld makes its own network, and an upload that loses Wi-Fi goes on where it stopped (how).
  • USB that only charges until you say so, and an Android phone's USB tethering that gives the Pixel 2 the phone's internet (plugging in).
  • System Update over Wi-Fi or the USB cable: only what changed, signed, with roll back (how).
  • Player 2 on a friend's phone, in NES games on the Pixel 2, with no app and no account (how).
  • Autosave and resume, six save slots, quick save and quick load on SELECT + R1 and L1, Undo Load, and a Disc row for games on more than one disc (in a game).
  • Faster and slower (1.5x, 2x and 3x), turbo buttons and On-Screen Stats over the game (in a game).
  • Hotkeys you choose, SELECT and a button, for a screenshot, the next shader or display, reset and quit, for every game, a system or one game (hotkeys).
  • Your screenshots on the home: every shot in a group of its own, OpenBOR's too, newest first, opened on the whole screen (screenshots).
  • Change what a button does, for one game or a whole system, two buttons on one game button if you like, a button that turns the d-pad into the stick (each press, or while held) among the choices, with the handheld drawn beside the rows, and every control listed in the game with the handheld's own buttons (controls).
  • Cheats from libretro's cheat list or a .cht file of your own, on and off per game in the in-game menu; achievements wait while one is on (cheats).
  • Rumble on the Pixel 2 for Dreamcast, PlayStation, Game Boy Color and Nintendo 64 games, Off, Low, Medium or Full for every game or one (rumble).
  • Sound your way: a USB-C headphone adapter on the Pixel 2, Bluetooth headphones on the Brick (untried so far), and mono audio for anyone who hears with one ear (audio).
  • Louder than the top: hold VOL+ a second at the top, or press it three more times, for up to +12 dB on quiet films and games, with a limiter; the brightness key lifts a dark picture the same way (boost).
  • An equalizer for everything you hear: Bass, Voice, Treble or five bands of your own, one preset for the speaker and one for headphones, heard live as you tune it (equalizer).
  • MP4 and menu music: a player for your music, audiobooks and videos that keeps playing behind the shelf and comes back paused where it was after a power-off, its albums as covers, a grid or a list (START turns them), showing a song as its cover, a cassette whose reels turn, a record in the cover's color, or bars that move to the music, and ten free 8-bit tracks, or your own, behind the menus (MP4).
  • The top bar and side lights: the clock, Wi-Fi and the battery with its time left, and on the Pixel 2 side lights for the battery, volume, transfers and achievements.
  • Battery care: a charging screen while it is off, a charge limit of 80, 85 or 90%, a warning before it gets hot, a Power Button that asks for a hold, and clocks for each system that save battery (battery and power).
  • Play Time, Continue or start from the start, favorites, sorting, a QWERTY keyboard that keeps up with the d-pad, and MENU + START for a way out of anything.

Supported systems

Nintendo NES, SNES, Nintendo 64, Game Boy, Game Boy Color, Game Boy Advance, Nintendo DS, Virtual Boy, Pokémon Mini, Game & Watch
Sega SG-1000, Master System, Genesis, Game Gear, Sega CD, 32X, Saturn, Dreamcast
Sony PlayStation, PSP
Atari Atari 2600, Atari 5200, Atari 7800, Atari Lynx
Others TurboGrafx-16 and CD, Neo Geo, Neo Geo CD, Neo Geo Pocket and Color, WonderSwan and Color, ColecoVision, Vectrex, MSX2, 3DO
Arcade and more Arcade, MAME, NAOMI, Atomiswave, Doom, ScummVM, PICO-8, TIC-80, OpenBOR, J2ME, and PortMaster's ports

Each system's games go in its folder under Roms/, and EmulationStation's folder names (nds, gba, psx, megadrive and the rest) work as they are. BIOS files go loose in Bios/; a Famicom Disk System game (.fds) needs disksys.rom there. A picture of your own in Borders/<system>/ fills the space around a handheld game (NextUI's Overlays/ work too). The guide has every folder, file type and core, and each BIOS file.

Try it on your Mac

No handheld yet? ZyperOS runs on a Mac in a window drawn as the handheld itself, in two ways. The full walk-through is on the blog.

Desk mode: the ZyperOS home in a window drawn as a green GKD Pixel 2, each button labelled with its keyboard key: X on A, Z on B, Esc on MENU, Return on START
Desk mode, each key's letter on show
Desk mode: the in-game menu's Game tab, Continue, Save and Load, over a NES game on the drawn Pixel 2
A game and its in-game menu
Desk mode as the TrimUI Brick: the ZyperOS home on its 1024x768 screen, with the Brick's F1, F2, MENU, SELECT and START keys drawn below
The same, as the TrimUI Brick
The ZyperOS Simulator: a drawn GKD Pixel 2 at the first start, Zyper saying Hello! beside the language list, its four side lights lit green on the cable The ZyperOS Simulator: the home on the drawn Pixel 2 while it charges, the charging mark in the top bar and the side lights filling from the bottom
The ZyperOS Simulator: the first start, and the side lights while it charges

Desk mode is the launcher itself, built for your Mac: the menus, the settings, the themes and a game, at 60 frames a second. With Xcode's command-line tools and Homebrew:

brew install sdl2 sdl2_image sdl2_ttf xz
git clone https://github.com/tarikbc/ZyperOS && cd ZyperOS
make desk          # the GKD Pixel 2; make desk-brick for the TrimUI Brick

The first run takes a few minutes: it builds the launcher, Diatom and a NES core, and makes a sample card with a game on each system. The keyboard is the buttons: the arrows for the d-pad, X Z S A for A B X Y, Q W E R for L1 R1 L2 R2, Return for START, Right Shift for SELECT and Esc for MENU. The mouse presses the drawn keys, Option shows each key's letter, and F1 lists the rest. Linux works too (Building).

The ZyperOS Simulator is the whole system in QEMU on a Mac with Apple silicon: the boot, the first-start setup, the battery, the charger and the side lights, with a panel for what a player can't press. Every release from 1.1.0 on has its QEMU image, and tools/qemu-run.sh fetch downloads it and checks it against the release's SHA256SUMS. Until 1.1.0 is out, you build the image with plastron, in Docker (make -C plastron qemu, how): a few hours the first time, then minutes. Either way there is no SSH key to set up: tools/qemu-run.sh hands the VM yours, or makes one for it.

brew install qemu
tools/qemu-run.sh fetch          # from 1.1.0 on; until then, make -C plastron qemu
simulator/scripts/build-app.sh
open "simulator/build/ZyperOS Simulator.app"

More

  • The guide: installing, every system's folder and BIOS, every control, menu and setting, File Transfer, System Update, PortMaster and the questions people ask.
  • zyperos.com: the screens, the video tour and the blog. The Discord is for questions, ideas and help building it.
  • The releases have the card images and ZyperOS Installer. Issues are for bugs.

The name

Zyper, a grey miniature schnauzer, sitting on the grass with his tongue out

ZyperOS is named after Zyper, my dog, who passed away. He was quick, light on his feet and full of energy, and that is what this system tries to be.

The name is also two words in one: zippy and hyper. Games start the moment you press A, the menus never make you wait, and the whole system is small enough to come up in about two seconds.

For developers

ZyperOS is C and SDL2, in two repositories that build together. ZyperOS (this one) holds the launcher, the card's scripts and the tools, diatom/, the libretro frontend that starts once at boot (its own Makefile, under the Mozilla Public License 2.0), and installer/, ZyperOS Installer (Rust and Tauri). plastron/ is the Linux under it, built with Buildroot in Docker, under the GNU GPL version 3. Building covers the toolchain, the card, QEMU, the simulator, releasing, developer mode and the checks.

To run it on your computer first, see Try it on your Mac.

Credits

ZyperOS stands on other people's work:

  • Eric Reinsmidt, for TortOS, TortOS Installer, plastron and Diatom, where ZyperOS's launcher, installer, Linux and emulator started. His code in ZyperOS keeps his copyright and notices.
  • ROCKNIX, for the RK3326 kernel patches, the Pixel 2 device tree, the U-Boot setup and the DDR clock driver.
  • PortMaster, for the ports and the runtimes they run on.
  • plorpOS by Thwonp, for the DSperate libretro wrapper and the FAKE-08 patches.
  • congusbongus (Napping on a Cloud), Zane Little Music (Apple Cider, Hush Hamlet), HydroGene (Truth), Spring Spring (Scheatt), TAD (Ice Cave), John Oestmann (Starfall Island), nene (Leap), LordZintick (The Arplands) and Joth (Bossa Nova), whose free 8-bit tracks are the menu music a fresh card plays, all given away under CC0 on OpenGameArt (THIRD-PARTY-LICENSES.md).
  • The libretro core authors, ScummVM's, YabaSanshiro's and FreeJ2ME-Plus's among them, whose emulators do the real work, each under its own license (THIRD-PARTY-LICENSES.md).
  • OpenBOR, by Senile Team and the OpenBOR Team, which runs the OpenBOR shelf.
  • Eclipse Temurin (OpenJDK) and DejaVu Sans, the Java runtime and the font J2ME games run with.
  • minimp3 by lieff and stb_vorbis by Sean Barrett, which decode the menu music.
  • zadpos, for Sharp-Shimmerless and its scanlines and grid (CC0), and Timothy Lottes, for his CRT shader, CRTS (public domain), which the Shader row draws with.
  • Rockchip, for the firmware that starts the Pixel 2 and runs its memory at full speed.

License

ZyperOS is open source, under the GNU General Public License, version 3 (GPL-3.0-only), so anyone can build on it. The NOTICE adds two terms that section 7 of the GPL allows. The first keeps the name ZyperOS, ZyperOS Installer, Zyper (the miniature schnauzer the system is named after) and his art, the logo and the website as trademarks, so a fork needs its own name and mascot; naming ZyperOS to say where your work came from is always fine. The second asks you to keep the copyright notice, the NOTICE and the attribution in the About screen when you share it. TRADEMARK.md says in plain words what is and is not fine. Versions published before 2026-11-06 were under the GNU General Public License, version 3 or later, and for a short time after that ZyperOS was under the PolyForm Shield License 1.0.0; this is GPL-3.0-only. Eric Reinsmidt's TortOS code in ZyperOS is from TortOS's MIT-licensed versions and keeps his MIT notice (LICENSES/). plastron stays under the GNU GPL version 3 and Diatom under the Mozilla Public License 2.0. The cores keep their own licenses, some of them non-commercial. OpenBOR, a program of its own on the card, is under the BSD 3-Clause License. Flycast 2.7 is a separate program, not part of ZyperOS. Full notices are in THIRD-PARTY-LICENSES.md.

About

A fast, light firmware for the GKD Pixel 2 that plays your whole retro library: forty systems, PortMaster ports, and your music, audiobooks and videos.

Topics

Resources

Stars

19 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages