Getting Started

Prerequisites

  • Python 3.11+

  • uv for dependency management

  • A Raspberry Pi Pico running the Piclone firmware

  • USB cable connecting the Pico to your computer

For hardware wiring and firmware flashing, see the Piclone documentation.

Install

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

First build and upload

Romulan ships with demo.txt, a sample annotated hex dump. Build and upload it:

uv run romulan demo.txt --build --upload

This produces bin/rom.bin (32 KB) and uploads it to the Pico via the plain-text loadbin protocol.

Serial port

Romulan auto-detects the Pico when exactly one device is connected. If detection fails or finds multiple ports, specify one explicitly:

uv run romulan demo.txt --build --upload --port /dev/ttyACM0   # Linux
uv run romulan demo.txt --build --upload --port /dev/cu.usbmodem101  # macOS
uv run romulan demo.txt --build --upload --port COM3             # Windows

Input file format

Each line in an annotated hex dump contains a file address, a byte value, and an optional comment after @:

0x0000   0x18   @ CLC
0x0001   0xA9   @ LDA 0x05
0x0002   0x05
...
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. Vectors at 0x7FFC–0x7FFF are required.

Next steps