Installation

The SDK ships inside the UVMC2 Starter Kit: the SDK itself, a minimal example game to copy, a full worked example (an arcade game emulated in C) and the host-side tools. Nothing in the kit looks outside its own directory, so it builds from wherever you unpack it.

• Starter kit: github.com/tullulah/uvmc2-starter-kit (latest release: v1.3)
• SDK (a git submodule of the kit, at sdk/): github.com/tullulah/uvmc2-sdk

Prerequisites

All five are required, Rust included.

You also need a network connection for the first build: cargo fetches the crates' dependencies from crates.io once. After that the build is offline.

Why Rust is not optional

The beam model, the code that turns a line into hardware timings, exists in exactly one implementation, written in Rust and shared with the Debug Cart's firmware. The build stops with a fatal error if cargo is not on the PATH. Add the bare-metal target once:

rustup target add thumbv8m.main-none-eabi     # softfp bare-metal Cortex-M33

Optional tools

Set up the kit

git clone --recursive https://github.com/tullulah/uvmc2-starter-kit.git
cd uvmc2-starter-kit
./setup.sh

setup.sh checks the tools, adds the Rust target, fetches the sdk/ submodule if you cloned without --recursive, and shallow-clones pico-sdk 2.2.0 into third_party/pico-sdk. If you already have a pico-sdk 2.2.0 checkout, point PICO_SDK_PATH at it instead.

Build

cd examples/hello_uvmc2 && make uvm2     # -> build_uvm2/hello_uvmc2.um2   (~47 KB)
cd game/tacscan        && make uvm2      # -> build_uvm2/aae_tacscan.um2   (~143 KB)

The .um2 lands in the example's build_uvm2/ directory, next to the .elf you will need later for debugging.

Run it

The SD card

Format the card FAT32 or exFAT, any size. The multicart's menu and SDK games both read either.

/                      the .um2 images, and any sound bundle a game ships (tacscan.vsm)
roms/<game>.zip        romsets, read by the game itself at start-up
config/uvm2.cfg        this console's beam calibration (written by the calibration screen)
config/<GAME>.CFG      per-game settings, for games that declare any

Copy the .um2 to the root of the card and pick it from the multicart menu. For tacscan, also copy:

• game/tacscan/roms/tacscan.zip to roms/tacscan.zip: the game reads its ROM off the card at start-up;
• game/tacscan/build/tacscan.vsm next to the .um2, for the sampled sound. Keep the name 8.3: this SDK reads long names, but not every cartridge's reader does.

config/ is created the first time a calibration is saved. Do not copy config/uvm2.cfg from another console: it describes that console's analog parts, not yours.

Debug Cart: games are launched from the Debug Cart's BIOS menu instead of the multicart's menu. The SD layout is the same.

Calibrate once

If text leans into diagonals, columns cascade to one side or glyphs fall apart while native cartridges look fine on the same console, the console needs calibrating. The image is not broken. Hold buttons 2 and 3 and launch any game with button 4: the calibration screen opens first. See Calibrating a console.

Troubleshooting

Next: Your first game.