Phosphor OS Guide
Phosphor OS turns a Raspberry Pi into a retro console that boots straight into its own menu. It works on CRT TVs and monitors (with the RGBerry boards, over SCART or VGA) and on flat screens over HDMI, including vertical screens for arcade cabinets.
It's free. The RGBerry boards are sold separately, but you don't need one to use Phosphor OS over HDMI.
1. What you need
| Raspberry Pi | Pi 4 / Pi 400 (recommended), Pi 5 / Pi 500, Pi 3 or Zero 2 W |
| microSD | 8 GB or more (32 GB or more is better if you'll have lots of games). A1 / Class 10 |
| Power supply | The official one for each model: Pi 4/400 → USB-C 5 V 3 A · Pi 5/500 → USB-C 27 W · Pi 3/Zero 2 W → micro-USB 2.5 A |
| Display | Over HDMI (TV or monitor) or over SCART/VGA with an RGBerry board |
| Controller | Any USB or Bluetooth controller. A USB keyboard works too |
Rough performance guide:
| System | Zero 2 W / Pi 3 | Pi 4 / 400 | Pi 5 / 500 |
|---|---|---|---|
| NES, Master System, Game Boy, PC Engine | ✓ | ✓ | ✓ |
| SNES, Mega Drive, Game Gear | ✓ (almost everything) | ✓ | ✓ |
| PlayStation | borderline | ✓ | ✓ |
| Arcade (MAME 2003-Plus) | depends on the game | ✓ almost everything | ✓ |
| CRT filter on HDMI | — | light / CRT-Pi | all |
2. Flash the card
- Download
phosphor-os-rpi.img.xz. You don't need to unzip it. - Open Raspberry Pi Imager (or balenaEtcher).
- Go to Choose OS → Use custom and select the
.img.xzfile. - Choose the microSD and write it. Everything on the card will be erased.
In Raspberry Pi Imager, don't use "OS customisation" (user, Wi-Fi...). Phosphor OS ignores it. Set up Wi-Fi as explained in section 5.
3. First boot
Insert the card, connect the display and controller, and power on. You'll see the Phosphor OS animation. The first time, the system creates a partition called SHARE in the free space on the card (this takes a few seconds). Then the menu appears with the message "No games yet".
Video output
- Without an RGBerry board: video goes out over HDMI at the screen's resolution.
- With an RGBerry board: the board is detected automatically and uses SCART or VGA depending on its switches. HDMI is turned off.
| Switch 1 | Switch 2 | Output |
|---|---|---|
| OFF | — | SCART (15 kHz TV, each game's original resolution) |
| ON | OFF | VGA 31 kHz (PC monitor, 640×480) |
| ON | ON | VGA 15 kHz (arcade or multisync monitor) |
If the picture doesn't look right, see section 9.
4. Add games
Phosphor OS doesn't include any games. Only use copies of games you own.
From your computer (the easiest way)
- Turn off the console (Settings → Shut down) and remove the microSD.
- Put it in your PC. Two drives will appear: PHOSPHOR (boot drive, leave it alone
except for
wifi.txt) and SHARE. - Copy each game into
SHARE/roms/<system>:
| Folder | System | Formats |
|---|---|---|
nes |
NES / Famicom | .nes .fds .unf .zip .7z |
snes |
Super Nintendo | .sfc .smc .fig .swc .bs .st .zip .7z |
megadrive |
Mega Drive / Genesis | .md .gen .smd .bin .zip .7z |
mastersystem |
Master System | .sms .zip .7z |
gamegear |
Game Gear | .gg .zip .7z |
segacd |
Mega-CD | .cue .chd .iso .m3u |
pcengine |
PC Engine / TurboGrafx | .pce .cue .chd .sgx .zip .7z |
psx |
PlayStation | .cue .chd .pbp .m3u .exe |
gb |
Game Boy | .gb .zip .7z |
gbc |
Game Boy Color | .gbc .zip .7z |
arcade |
Arcade (MAME 2003-Plus) | .zip .7z |
- Put the card back in and power on. The menu only shows systems that have games.
Arcade: the zip files must come from the MAME 2003-Plus set. Files from other
MAME versions often don't work. Arcade BIOS files (neogeo.zip, etc.) go in the same
arcade folder. They don't show up in the list, because they aren't games.
PlayStation and CD: use .chd (one file per disc, takes up less space) or .cue +
.bin. For multi-disc games, create an .m3u file with one disc per line.
Over the network
With Wi-Fi or a network cable connected, the console accepts SCP on port 22 (user
root, password phosphor). In WinSCP, choose the SCP protocol and copy to
/userdata/roms/<system>. From a terminal:
scp -O "Super Metroid.sfc" root@<IP>:/userdata/roms/snes/
You'll find the IP in Settings → Information. After copying over the network, go back to the home menu and open the system again, or restart, to see the new games.
BIOS
Some systems need the original BIOS, which is not included. It goes in SHARE/bios:
| System | File | Required? |
|---|---|---|
| PlayStation | scph5501.bin (USA) · scph5502.bin (EUR) · scph5500.bin (JAP) |
Recommended (without it, a free but less compatible BIOS is used) |
| Mega-CD | bios_CD_E.bin · bios_CD_U.bin · bios_CD_J.bin |
Yes |
| PC Engine CD | syscard3.pce |
Yes, for CD games |
| Famicom Disk System | disksys.rom |
Yes, for .fds |
| Game Boy / Color | gb_bios.bin · gbc_bios.bin |
No (only for the boot animation) |
Screenshots in the list
If you put a PNG image with the same name as the game in roms/<system>/media/, it shows
up in the game list panel (on HDMI). For example:
roms/snes/media/Super Metroid.png.
5. Wi-Fi and Bluetooth
Wi-Fi
- From the menu: Settings → Wi-Fi. Search for networks, pick yours and type the password with the on-screen keyboard. If you have a USB keyboard connected, you can type with it directly.
- From your PC, before booting: on the PHOSPHOR drive, edit
wifi.txt, remove the#characters and enter your network details. Use your own country code inCOUNTRY:
SSID="MyNetwork"
PASSWORD="MyPassword"
COUNTRY=ES
Networks are saved on SHARE, so you won't lose them when you update Phosphor OS.
Bluetooth controllers
Settings → Bluetooth → Search for controllers. Put the controller in pairing mode before you search:
| Controller | Pairing mode |
|---|---|
| 8BitDo | Hold Start + the mode button (X, B...), then the pairing button |
| DualShock 4 | Hold Share + PS until the light blinks fast |
| DualSense | Hold Create + PS |
| Switch Pro | Small button on top, next to the USB-C port |
Pick the controller in the list and it pairs automatically. Next time, just turn it on. To forget a controller, press A twice on it.
6. Using the menu
| Button | In the menu |
|---|---|
| D-pad | Move |
| A | Enter / play |
| B | Back |
| Y | Mark as favorite |
| L / R | Filter: all, favorites, recent |
| START | Settings |
On a keyboard: arrow keys, Enter (A), Esc or Backspace (B), Y (favorite), Q/W (L/R) and Tab (Settings). If you have no controller or keyboard, the mouse works in a pinch: the wheel moves, left click enters, right click goes back, and clicking the wheel opens Settings.
While playing
- SELECT + START: RetroArch quick menu (save and load states, options...). From there, Close Content takes you back to the Phosphor menu.
- On a keyboard, Esc exits the game.
7. Settings
| Setting | What it does |
|---|---|
| Output | Auto uses the board's switches. Forcing a different output requires a restart |
| Monitor | CRT only: 15 kHz TV, 15 kHz arcade monitor or 31 kHz VGA |
| H / V position | CRT only: moves the picture if it goes off one side |
| CRT filter | HDMI only: scanlines or tube simulation (CRT-Pi is the most accurate) |
| Test pattern | Grid and bars to center and adjust your monitor. On CRT, the D-pad centers the picture live |
| Rotation | 0°, 90° or 270°, for vertical monitors |
| Theme | Changes how the menu looks (see below) |
| Boot animation | Turns the animated logo at power-on on or off |
| Menu sounds | The "blips" when you move around |
| Controllers | See connected controllers and set up one that doesn't respond properly |
| Wi-Fi / Bluetooth | See section 5 |
| Information | Model, board, output, IP and free space |
Setting up a controller that doesn't work properly
If a cheap USB controller has its buttons mixed up, go to Settings → Controllers, select it and press A. The wizard asks you for each button by its position. If your controller is missing a button (X/Y, L/R, SELECT), wait 6 seconds and it's skipped automatically. The setup applies to both the menu and the games.
Themes
Themes go in SHARE/themes/<name> and you choose them in Settings → Theme. A theme
can change just the colors or the whole layout. See docs/TEMAS.md in the project.
8. Advanced settings (SHARE/phosphor.conf)
The same file the menu changes can be edited from your PC:
PHOS_FORCE_OUTPUT=hdmi # scart | vga | hdmi (empty = automatic)
PHOS_FORCE_MONITOR= # generic_15 | arcade_15 | vga
PHOS_CENTER_H=0
PHOS_CENTER_V=0
PHOS_ROTATION=0 # 0 | 90 | 270
PHOS_CRT_FILTER=none # none | scanlines | light | crtpi | lottes
PHOS_THEME=phosphor
PHOS_SPLASH=1
PHOS_UI_SOUNDS=1
PHOS_FRONTEND=phosphor # retroarch = use the RetroArch menu instead
PHOS_DEBUG=0 # 1 = verbose RetroArch log
The RetroArch configuration is in SHARE/system/configs/retroarch/retroarch.cfg, and
your saves are in SHARE/saves and SHARE/states.
9. Troubleshooting
Nothing shows on HDMI with the RGBerry board attached. That's normal: with a board,
HDMI is turned off. Remove the board or set PHOS_FORCE_OUTPUT=hdmi in phosphor.conf.
The CRT picture is shifted or cut off. Go to Settings → Test pattern and center it with the D-pad. If your monitor has geometry controls, adjust them using the pattern.
A system doesn't appear in the menu. Check that the games are in the right folder (section 4) and have one of the listed extensions.
An arcade game won't start. It's almost always a zip from another MAME version. Use
the MAME 2003-Plus set and, if the game needs a BIOS (Neo Geo, for example), also put
the BIOS zip in roms/arcade.
The controller works in the menu but not in games. Set it up in Settings → Controllers.
The screen stays black after the animation. Wait a few seconds. If the menu fails
three times in a row, the RetroArch menu starts instead as a fallback. If you want to
see what happened, connect over SSH (ssh root@<IP>, password phosphor) and check
/userdata/system/logs/phosphor-ui.log and retroarch.log.
10. Licenses
Phosphor OS is free and open-source software. Some of the included emulators (Snes9x, Genesis Plus GX and MAME 2003-Plus) have licenses that don't allow commercial use. Don't sell SD cards with Phosphor OS preinstalled, and don't include it in a paid product.