FRANK DOOM

Official page: frank.rh1.tech — hub for all FRANK boards and firmware.

DOOM for Raspberry Pi Pico 2 (RP2350) with HDMI output, SD card, PS/2 and USB keyboard/mouse, and OPL music.

Supported Boards

This firmware is designed for the following RP2350-based boards with integrated HDMI, SD card, PS/2, and PSRAM:

• FRANK — A versatile development board based on RP Pico 2, HDMI output, and extensive I/O options.
• Murmulator — A compact retro-computing platform based on RP Pico 2, designed for emulators and classic games.

Both boards provide all necessary peripherals out of the box—no additional wiring required.

Features

• Native 320×240 HDMI video output via PIO
• Full OPL2 music emulation (EMU8950 with ARM assembly optimizations)
• 8MB QSPI PSRAM support for game data
• SD card support for WAD files and savegames
• PS/2 keyboard and mouse input
• USB keyboard and mouse input (via native USB Host)
• USB hub support for multiple devices
• Sound effects and music at 49716 Hz

Hardware Requirements

• Raspberry Pi Pico 2 (RP2350) or compatible board
• 8MB QSPI PSRAM (mandatory!)
• HDMI connector (directly connected via resistors, no HDMI encoder needed)
• SD card module (SPI mode)
• PS/2 keyboard and mouse (directly connected) — OR —
• USB keyboard and mouse (via native USB port, hub supported)
• I2S DAC module (e.g., TDA1387) for audio output

Note: When USB HID is enabled, the native USB port is used for keyboard/mouse input. USB serial console (CDC) is disabled in this mode; use UART for debug output.

PSRAM Options

Frank-Doom requires 8MB PSRAM to run. You can obtain PSRAM-equipped hardware in several ways:

1. Solder a PSRAM chip on top of the Flash chip on a Pico 2 clone (SOP-8 flash chips are only available on clones, not the original Pico 2)
2. Build a Nyx 2 — a DIY RP2350 board with integrated PSRAM
3. Purchase a Pimoroni Pico Plus 2 — a ready-made Pico 2 with 8MB PSRAM

Board Configurations

Two GPIO layouts are supported: M1 and M2. The PSRAM pin is auto-detected based on chip package:

• RP2350B: GPIO47 (both M1 and M2)
• RP2350A: GPIO19 (M1) or GPIO8 (M2)

HDMI (via 270Ω resistors)

Signal	M1 GPIO	M2 GPIO
CLK-	6	12
CLK+	7	13
D0-	8	14
D0+	9	15
D1-	10	16
D1+	11	17
D2-	12	18
D2+	13	19

SD Card (SPI mode)

Signal	M1 GPIO	M2 GPIO
CLK	2	6
CMD	3	7
DAT0	4	4
DAT3/CS	5	5

PS/2 Keyboard

Signal	M1 GPIO	M2 GPIO
CLK	0	2
DATA	1	3

PS/2 Mouse

Signal	M1 GPIO	M2 GPIO
CLK	14	0
DATA	15	1

Note: PS/2 mouse is only supported in overclocked firmware (378/133 MHz or higher). At stock clock speeds (252/100 MHz), PS/2 keyboard works but mouse input may be unreliable due to timing constraints.

I2S Audio

Signal	M1 GPIO	M2 GPIO
DATA	26	9
BCLK	27	10
LRCLK	28	11

Building

Prerequisites

1. Install the Raspberry Pi Pico SDK (version 2.0+)
2. Set environment variable: export PICO_SDK_PATH=/path/to/pico-sdk
3. Install ARM GCC toolchain

Build Steps

# Clone the repository with submodules
git clone --recursive https://github.com/rh1tech/frank-doom.git
cd frank-doom

# Or if already cloned, initialize submodules
git submodule update --init --recursive

# Build for M1 layout with PS/2 input (default)
mkdir build && cd build
cmake -DBOARD_VARIANT=M1 ..
make -j$(nproc)

# Build for M2 layout with PS/2 input
cmake -DBOARD_VARIANT=M2 ..
make -j$(nproc)

# Build with USB keyboard/mouse support (instead of PS/2)
cmake -DBOARD_VARIANT=M1 -DUSB_HID_ENABLED=1 ..
make -j$(nproc)

Build Options

Option	Description
-DBOARD_VARIANT=M1	Use M1 GPIO layout (default)
-DBOARD_VARIANT=M2	Use M2 GPIO layout
-DUSB_HID_ENABLED=1	Enable USB keyboard/mouse (disables USB serial)
-DCPU_SPEED=504	CPU overclock in MHz (252, 378, 504)
-DPSRAM_SPEED=166	PSRAM speed in MHz

Or use the build script (builds M1 by default):

./build.sh

Release Builds

To build both M1 and M2 variants with version numbering:

./release.sh

This creates versioned UF2 files in the release/ directory:

• frank-doom_m1_X_XX.uf2
• frank-doom_m2_X_XX.uf2

Flashing

# With device in BOOTSEL mode:
picotool load build/frank-doom.uf2

# Or with device running:
picotool load -f build/frank-doom.uf2

SD Card Setup

1. Format an SD card as FAT32
2. Create a doom folder in the root of the SD card
3. Copy any DOOM-engine WAD file to the doom folder (e.g., doom1.wad, doom.wad, doom2.wad, plutonia.wad, tnt.wad, or custom WADs)
4. A .savegame/ directory will be created automatically for save files

Example SD card structure:

SD Card/
└── doom/
    ├── doom.wad
    ├── doom2.wad
    └── ...

Shareware WAD Downloads

If you don't have a DOOM WAD file, you can download the shareware versions:

• DOOM Shareware (doom1.wad): Download from Doomworld or id Software FTP
• Freedoom (free open-source alternative): freedoom.github.io

For the full game, purchase DOOM or DOOM II from Steam or GOG.

Controls

Keyboard

• Arrow keys: Move/Turn
• Ctrl: Fire
• Space: Open doors/Use
• Shift: Run
• 1-7: Select weapon
• Escape: Menu

Mouse

• Move left/right: Turn
• Move forward/back: Move forward/back
• Left button: Fire
• Right button: Strafe
• Middle button: Move forward

License

GNU General Public License v2. See LICENSE for details.

This project is based on:

• Chocolate Doom by Simon Howard
• doomgeneric by ozkl
• rp2040-doom by Graham Sanderson (OPL and Pico optimizations)
• EMU8950 by Mitsutaka Okazaki (OPL2 emulator)

Author

Mikhail Matveev xtreme@outlook.com

Acknowledgments

• id Software for the original DOOM
• The Chocolate Doom team for the clean portable source port
• Graham Sanderson for the incredible RP2040 optimizations and EMU8950 ARM assembly
• The Raspberry Pi foundation for the RP2350 and Pico SDK