Romulan¶

Host client for the Piclone 65C02 system — builds ROM images from annotated hex dumps or 6502 assembly and talks to the Pico over the framed v1 JSON Hardware API (USB serial).

Full documentation: romulan.big-iron.dev

Features¶

Parse annotated hex dumps — address, byte, and optional comment per line
Assemble 6502/65C02 source — mnemonics, labels, .org, .byte/.word; input format auto-detected
Build 32 KB ROM images — auto-fill with NOPs ($EA), validate reset/IRQ vectors
Framed Hardware API (v1) — JSON over ENQ/STX/ACK/EOT for scripted control and ROM upload
Verbose protocol traces — -v / --verbose on --upload and on hardware subcommands (NDJSON SEND/RECV)
Bus capture — stream CPU cycles until STP or a cycle limit
Cross-platform port detection — auto-detect the Pico on Linux, macOS, and Windows
65C02 opcode validation — catch undefined opcodes before they reach hardware

Installation¶

Requires Python 3.11+ and uv:

git clone https://github.com/big-iron-cde/romulan.git
cd romulan
uv sync

Quick Usage¶

Build a ROM from an annotated hex file:

uv run romulan demo.txt --build

Or from 6502 assembly (demo.s is the assembly counterpart of demo.txt; the input format is auto-detected):

uv run romulan demo.s --build

Build and upload in one step (framed Hardware API):

uv run romulan demo.txt --build --upload
uv run romulan demo.s --build --upload
uv run romulan demo.s --build --upload -v   # NDJSON protocol trace during upload

Upload an existing binary (optional -v / --timeout):

uv run romulan --upload
uv run romulan --upload -v --timeout 45

-v / --verbose works on the standard --upload path as well as on romulan hardware … commands.

Hardware API commands¶

The --port flag is optional when exactly one Pico is connected. Add --verbose (-v) for NDJSON protocol traffic on any hardware command (and on --upload above).

uv run romulan hardware upload bin/rom.bin
uv run romulan hardware capture --max-cycles 500

# Use a longer timeout for slow operations (e.g. large uploads or long captures)
uv run romulan hardware capture --max-cycles 500 --timeout 45

# Hold CPU in reset
uv run romulan hardware reset --assert
uv run romulan hardware reset --release
uv run romulan hardware monitor --disable
uv run romulan hardware request-addr

# Read back bytes from the loaded ROM image (CPU $F000 == offset 0x7000)
uv run romulan hardware peek --offset 0x7000 --count 16

# Live-peek a CPU bus/RAM byte (briefly resets the CPU)
uv run romulan hardware peek --addr 0x4000

# Set the 65C02 clock speed
uv run romulan hardware clock --hz 100

# Query firmware state
uv run romulan hardware status

Python client¶

from romulan.hardware_api import HardwareAPI

with HardwareAPI("/dev/ttyACM0") as api:
    print(api.status())
    api.reset(assert_reset=True)
    api.upload_rom(open("bin/rom.bin", "rb").read())
    # Verify the byte at CPU $F000 before releasing reset
    print(api.peek(offset=0x7000, count=16).data.hex())
    api.set_clock(hz=100.0)
    api.reset(assert_reset=False)
    capture = api.read_until_stp(max_cycles=500)
    print(capture.reason, len(capture.cycles))

Input formats¶

--build accepts two source formats, auto-detected from the file contents (the extension doesn’t matter). Either way, the result is a 32 KB ROM image and the vectors are required — the builder rejects images without them.

Annotated hex format¶

Each line is address, byte, and an optional @ comment:

0x0000   0x18   @ CLC
0x0001   0xA9   @ LDA 0x05
0x0002   0x05
0x0003   0x8D   @ STA $4000
0x0004   0x00
0x0005   0x40
...
0x7FFC   0x00   @ Reset vector (low)
0x7FFD   0x80   @ Reset vector (high)
0x7FFE   0x00   @ IRQ/BRK vector (low)
0x7FFF   0x80   @ IRQ/BRK vector (high)

File addresses (0x0000–0x7FFF) map to CPU addresses $8000–$FFFF
Comments are optional — everything after @ is ignored
Vectors at 0x7FFC–0x7FFF are required — the builder will reject images without them

6502 assembly¶

A built-in two-pass assembler covers the official NMOS 6502 mnemonics plus the W65C02 additions used by the course (STP, WAI, BRA, PHX/PHY/PLX/PLY, STZ, TRB/TSB, accumulator INC/DEC, (zp) indirect). Comments start with ;:

        .org $8000          ; CPU address (omit to start at $8000)

reset:  CLC                 ; labels end with ':'
        LDA #$05            ; immediate
        STA $4000           ; absolute ($10 would be zero page)
        BNE reset           ; relative branches
        STP

        .org $FFFC
        .word reset         ; reset vector (little-endian)
        .word reset         ; IRQ/BRK vector

Numbers: $FF, 0xFF, or decimal
Directives: .org, .byte v1, v2, …, .word v1, v2, …
Addressing modes: implied, accumulator, immediate, zero page, absolute, ,X/,Y indexed, JMP ($1234), ($10,X), ($10),Y, ($10), relative
A numeric operand under $100 uses the zero-page form when the mnemonic has one (so JMP $0000 still encodes as 4C 00 00); label operands are always absolute
All emitted bytes must land in the ROM region $8000–$FFFF; operand values are unrestricted

CLI Reference¶

Standard CLI¶

Flag	Description	Default
`input`	Path to the input file: annotated hex dump or 6502 assembly (required with `--build`)	—
`--build`	Build a `.bin` ROM image from the input file	—
`--upload`	Upload the ROM image to the Pico (framed Hardware API)	—
`-o, --output`	Output ROM binary path	`bin/rom.bin`
`--port`	Serial port for the Pico (auto-detected if omitted)	Auto-detect
`--timeout`	Idle timeout (seconds) with no framing progress on upload	`30.0`
`--verbose`, `-v`	Hardware API NDJSON traces during `--upload`	—

At least one of --build or --upload is required, but --upload can only be used after a successful --build or if a valid ROM binary already exists at the output path.

Hardware API¶

Romulan speaks the Piclone firmware’s v1 JSON protocol over USB-CDC at 115200 baud. Each transaction uses byte-level framing (ENQ → STX → ACK → payload → EOT → ACK/NACK); all payloads include "v": 1.

Subcommand	Arguments	Description
`hardware upload`	`<bin_path> [--port] [-v]`	Upload a ROM binary via the framed protocol
`hardware capture`	`--max-cycles <N> [--port] [-v]`	Capture CPU bus cycles until STP or max cycles reached
`hardware monitor`	`--enable \| --disable [--port] [-v]`	Toggle JSON monitor output
`hardware reset`	`--assert \| --release [--port] [-v]`	Hold or release the CPU reset line
`hardware request-addr`	`[--port] [-v]`	Request the current CPU address
`hardware peek`	`--offset <hex> [--count N]` or `--addr <hex> [--port] [-v]`	Read ROM-image bytes (`--offset`) or live-peek one CPU bus/RAM byte (`--addr`)

Flag	Description	Default
`--verbose`, `-v`	Print every JSON message sent and received over the serial protocol	—
`--timeout`	Idle timeout in seconds with no framing/capture progress	`30.0`

Full firmware-side protocol reference: Piclone Hardware API docs.

Captured cycles include rw: 0 = read, 1 = write. Piclone firmware on Pico 2 infers this from A15 (ROM region = read, RAM region = write), not from a wired RWB sense pin—so STA/store cycles report rw=1 and opcode fetches report rw=0.

hardware peek --addr is a live bus/RAM read (the firmware runs a short LDA/STP stub and samples the matching cycle). It is not a ROM-image offset read — use --offset for that. The CPU is held in reset around the peek. Requires piclone wiring RAM OE# = NOT(RWB) and a current piclone flash (older ROM-image-only firmware answers live requests with a ROM-mode response, which romulan rejects with a clear error).

Verbose example¶

$ uv run romulan hardware request-addr --verbose
{"v":1,"type":"event","event":"port_detected","data":{"port":"/dev/ttyACM0","auto_detected":true}}
{"v":1,"type":"event","event":"call","data":{"method":"request_addr"}}
{"v":1,"type":"event","event":"send","data":{"payload":{"v":1,"cmd":"request_addr","id":"abc123"}}}
{"v":1,"type":"event","event":"ack"}
{"v":1,"type":"event","event":"ack"}
{"v":1,"type":"event","event":"recv","data":{"payload":{"v":1,"ok":true,"addr":"8000"}}}
{"v":1,"type":"event","event":"ret","data":{"method":"request_addr","result":32768}}
{"v":1,"type":"result","cmd":"request_addr","data":{"addr":"8000"}}

Architecture¶

Memory Map¶

The 32 KB ROM image maps directly to the 65C02 address space:

File Offset	CPU Address	Purpose
`0x0000`	`$8000`	Start of ROM
`0x7FFC`	`$FFFC`	Reset vector (low byte)
`0x7FFD`	`$FFFD`	Reset vector (high byte)
`0x7FFE`	`$FFFE`	IRQ/BRK vector (low byte)
`0x7FFF`	`$FFFF`	IRQ/BRK vector (high byte)

Documentation¶

The complete documentation — getting started, CLI reference, Hardware API client guide, and Python API reference — is published at https://big-iron-cde.github.io/romulan/.

Build and view locally:

make docs-serve    # build + serve at http://127.0.0.1:8000
make docs          # build only → docs/_build/html

Or manually:

uv sync --group docs
uv run sphinx-build -W docs docs/_build/html
uv run python -m http.server 8000 --directory docs/_build/html

Testing¶

uv run pytest

License¶

Released under the MIT License.