The most flexible ROM replacement for retro systems - using a sub-$2 Raspberry Pi RP2350 or STM32 microcontroller.
The most flexible ROM replacement for retro systems - using a sub-$2 Raspberry Pi RP2350 or STM32 microcontroller.
One ROM - One ROM To Rule Them All
The most flexible and powerful ROM replacement for your retro computer. A single Raspberry Pi RP2350-base board in the footprint of the original chip emulates 24, 28, 32 and 40 pin mask ROMs, EPROMs, EEPROMs, bipolar PROMs and some SRAM — and then does things the original never could. It serves several ROM sockets at once, switches images at runtime, reprograms over USB without leaving the socket, talks back to the machine it is installed in, and runs your own code as plugins.
Thousands of One ROMs are installed in Commodore 64s, VIC-20s, PETs, Amigas, BBCs, Ataris, TIs, Apple IIs, disk drives, IBM PCs, pinball machines, drum machines, synthesizers and more. It is open source hardware and software, it is cheap to make, and it is actively maintained and developed.
Start at onerom.org. That is where the project is explained and supported:
The rest of this README is for people who want to build One ROM, hack on it, or build things on top of it. If you just want a working ROM replacement, onerom.org will get you there faster.
One ROM is designed to be extended in many different ways.
| I want to… | Start here | Steps |
|---|---|---|
| Drive a device from scripts or my own tooling | Programming a One ROM, CLI manual | Install and run the CLI |
| Fab and assemble existing boards | hardware/pcb | Upload gerbers and BOM/POS files to a fab |
| Build the firmware myself | Building from source | Use make or the build container |
| Use the header pins as GPIOs — reset the host, drive a line | Driving the host | One command, plus a wire for host reset |
| Add support for a chip type One ROM doesn't know | Adding a chip type | A JSON entry plus one line of Rust or a firmware and tooling update if no existing serving algorithm fits |
| Add support for a new board revision | rust/config/json | A new JSON file once the board is designed |
| Write a plugin — from scratch, or from a working one | Plugins, firmware/ora/examples | C, against a stable API |
| Talk to the retro machine from the ROM socket | RBCP | 6502 and 68000 host code provided |
| Build host-side tools of my own | Rust crates | Rust, on published crates |
| Read and test real ROM chips | One ROM Lab | Flash Lab to a spare Fire board |
| Add a serving algorithm, or change how serving works | How the firmware works | Bare metal C, PIO and DMA, plus Rust tooling |
| Design a new board | hardware/pcb | KiCad |
One ROM comes in two families:
All the design files needed to manufacture your own are in hardware/pcb. Start with the recommended revisions and read the fabrication notes in the same file before you order. Boards can be fabbed and assembled at JLCPCB and other manufacturers cheaply.
Three One ROM Fire 24s in a Commodore 64, serving BASIC, KERNAL and the character ROM.
There are three tools, all doing the same job over USB:
The CLI is the complete interface: everything the device can do is reachable from it. Full reference in the CLI manual.
Find what is connected:
onerom scanBuild an image from a config file and flash it:
onerom program --config onerom-config/vic20-pal.jsonProgram chips straight from the command line, without a config file, adding the USB plugin so the device stays on the bus while it serves:
onerom program --slot file=kernal.901227-03.bin,type=2364,cs1=active-low --plugin usbBuild a firmware binary without touching a device, and look inside one:
onerom firmware build --config onerom-config/vic20-pal.json --board fire-24-e --output /tmp/onerom.bin
onerom firmware inspect --firmware /tmp/onerom.binRead and write the ROM image live, while the host is running from it:
onerom peek live --address 0x100 --length 64
onerom poke live --address 0x100 --byte 0xEAThe image select and X pads are not just jumpers. They are GPIOs, and One ROM will drive them for you — which means the ROM socket becomes a way to manipulate the machine it is plugged into.
Run a wire from a pad to the host's reset line and you can reset the machine after flashing a new image:
onerom control reset --pin sel_csel_c is the usual choice — more boards have it than have X pads, and it is 5V
tolerant where it exists. Any pad works, named with --pin.
A One ROM Fire 40 in an Amiga A500, with Sel_C wired to the 68000's reset line.
You can see what every pin is and what it is currently doing:
onerom inspect gpio --all
onerom inspect socket --chip-type 2364 --gpioThe same GPIOs are available to plugins, so a plugin can drive them autonomously — hold the host in reset until something is ready, blink an external LED on ROM activity, or drive whatever you have wired up.
Serving runs entirely on PIO and DMA, so both CPU cores are free. Plugins are separate binaries, written in C against a stable API in firmware/ora, that run on those cores while serving continues. Two run at once. This is how One ROM gains functionality without needing to fork the core firmware.
There are two types, system and user. The difference is resources, not authorship — each is built for a different flash slot with a different RAM and stack allocation, and you can write either. System is intended for official One ROM plugins such as the USB stack, but nothing stops you replacing it with your own.
| Plugin | Type | What it does |
|---|---|---|
| usb | system | The device's own USB stack, so a running One ROM stays on the bus. Exposes the ROM being served for live read and write, and the picobootx extended PICOBOOT interface. |
| host-control | user | A full RBCP implementation. |
| rgb | user | Cycles the NeoPixel on RGB boards. Superseded by the USB plugin's RGB support, reached with onerom control rgb. |
| activity | user | Blinks the status LED when the host is reading the ROM. |
| blink | user | Minimal example. |
The firmware passes each plugin a lookup function at startup. The plugin calls it with the ID of the facility it wants, and gets back a function pointer. Available that way: status LED and GPIO control, device and firmware metadata, logging, memory allocation, the ROM and RAM slots being served, and the address monitor that reports what the host is reading — which is what RBCP is built on. New IDs are only ever added, never changed, and each plugin declares the minimum firmware version it needs, which the firmware enforces before launching it.
Start with plugins/README.md for how plugins are built and configured, firmware/ora/api.h for the API, and firmware/ora/examples for worked examples — including one that patches the C64 kernal live and one that drives an LED from character ROM accesses.
The ROM Bus Control Protocol is bidirectional communication between a retro machine and the ROM emulator installed in it, carried over nothing but the ROM's own address and data buses. No extra wiring. The machine reads and writes ROM addresses, and One ROM interprets them.
That opens up things a ROM socket has no business being able to do:
grub for the C64The device side is the host-control plugin. The specification lives in the RBCP repository, along with reference host implementations for 6502 and 68000 — generic routines plus sample C64 kernal and Amiga Kickstart bootloaders.
One ROM Lab is alternate firmware for a spare Fire board that turns its ROM socket into a bus reader and tester. Flash it, connect over USB, and you get an interactive shell.
Read a real chip in the socket, as a checksum, a hexdump or Intel HEX. Verify that a One ROM under test serves the right bytes and tristates its data lines when deselected. Auto-detect chip select polarity on an unmarked mask ROM by brute-forcing the combinations. Dump the board's pin map, socket pin to signal to GPIO. It is what Fire 40 boards are tested with before they ship.
cd rust/lab && scripts/flash.shDependencies are listed in INSTALL.md, or use the
build container. The ARM and
Emscripten toolchain versions are pinned (ci/arm-toolchain-version,
ci/emscripten-version), as are the documentation tools that render the PDF
editions (ci/pandoc-version, ci/weasyprint-version), so a firmware binary is byte-identical wherever it is
built.
Build the base firmware:
makeThat produces firmware/build/onerom-rp235x.bin — one binary, for every Fire
board. The ROM images, chip configuration and plugins are composed onto it by
the host-side tools. To flash your build rather than a downloaded release,
pass it explicitly:
onerom program --config onerom-config/vic20-pal.json --base-firmware firmware/build/onerom-rp235x.binWorth knowing before you go digging in firmware/:
It is fully bare metal. No SDK, no HAL — not pico-sdk, not a vendor library. C with its own startup code and its own linker scripts to keep it lean.
Serving runs on PIO and DMA. The RP2350's PIO state machines watch the address and chip select lines and DMA the right byte onto the data pins. The CPU is not in the critical path, which is what leaves both cores free for plugins.
The chip type is not compiled in. The firmware knows nothing about a 2364 or a 27C400. It has a small set of parameterised serving algorithms, and the host-side generator works out which algorithm and what arguments a given chip on a given board needs, then writes that into the firmware metadata.
It is one binary for all boards. Board differences are metadata too.
Bad configuration is visible, not silent. An image the firmware cannot make sense of drops it into limp mode, with an special LED blink pattern.
**T
No open issues yet, or sync has not completed.