Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
O

one-rom

> 编程语言
Open source

The most flexible ROM replacement for retro systems - using a sub-$2 Raspberry Pi RP2350 or STM32 microcontroller.

330 stars0 likes0 views
WebsiteGitHub

About

The most flexible ROM replacement for retro systems - using a sub-$2 Raspberry Pi RP2350 or STM32 microcontroller.

One ROM

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.

New to One ROM?

Start at onerom.org. That is where the project is explained and supported:

  • What One ROM is and why — the overview, with pictures
  • Getting started — install it, program it, use it
  • Buy one — known vendors, if you'd rather not fab your own
  • Program from your browser — no software to install

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.

Ways in

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

Hardware

One ROM comes in two families:

  • Fire — RP2350, in 24, 28, 32 and 40 pin variants, latest boards include an RGB NeoPixel. All development happens for these boards.
  • Ice — STM32F4, 24 pin only. Legacy: still supported with 0.6.x firmware, but it is not being enhanced. The 0.7.x firmware and the CLI do not support it.

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.

Programming a One ROM

There are three tools, all doing the same job over USB:

  • One ROM Web — browser based, nothing to install, the best choice for most people.
  • One ROM CLI — the full device tool, and what the examples below use (rust/cli).
  • One ROM Studio — native desktop GUI for Windows, macOS and Linux (rust/studio).

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:

bash
onerom scan

Build an image from a config file and flash it:

bash
onerom program --config onerom-config/vic20-pal.json

Program chips straight from the command line, without a config file, adding the USB plugin so the device stays on the bus while it serves:

bash
onerom program --slot file=kernal.901227-03.bin,type=2364,cs1=active-low --plugin usb

Build a firmware binary without touching a device, and look inside one:

bash
onerom firmware build --config onerom-config/vic20-pal.json --board fire-24-e --output /tmp/onerom.bin
onerom firmware inspect --firmware /tmp/onerom.bin

Read and write the ROM image live, while the host is running from it:

bash
onerom peek live --address 0x100 --length 64
onerom poke live --address 0x100 --byte 0xEA

Driving the host — GPIO and reset

The 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:

bash
onerom control reset --pin sel_c

sel_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:

bash
onerom inspect gpio --all
onerom inspect socket --chip-type 2364 --gpio

The 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.

Plugins

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.

RBCP — talking to the host system

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:

  • remote debugging of code running on real hardware
  • ROM-based bootloaders — grub for the C64
  • dynamic patching of games and demos as they run

The 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

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.

bash
cd rust/lab && scripts/flash.sh

Building from source

Dependencies 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:

bash
make

That 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:

bash
onerom program --config onerom-config/vic20-pal.json --base-firmware firmware/build/onerom-rp235x.bin

How the firmware works

Worth 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

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rustcommodoreone-romoneromraspberry-pi

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 18, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言