Development
Crates
crates/
core/ the chip, no_std and I/O-free
armv6m/ Cpu, Bus trait, Ram, exceptions, Ppb (NVIC/SysTick/SCB) deps: none
rp2040-core/ peripherals, ELF/UF2 loading, SystemBus, System deps: armv6m, pcb, usbhost
usbhost/ USB host for the emulated device: enumeration, CDC-ACM, deps: none
HID, USB-MIDI, traffic log
board/ what is around the chip, no_std and I/O-free
pcb/ device framework + Board (no chip knowledge) deps: toml
pcb-devices/ stock device models + `registry()` deps: pcb
sdimage/ SD card images: FAT16/32 formatter and reader deps: none
host/ the host's side: bridges to the OS, log reader
bridge-net/ user-mode network (slirp-style NAT) for the Wi-Fi chip deps: pcb-devices, smoltcp (std)
bridge-hci/ a real Bluetooth adapter through an HCI user channel deps: pcb-devices, libc (Linux)
bridge-usb/ the USB device's serial port as a pty, HID as UHID deps: usbhost, libc (Linux)
rtt/ defmt-over-RTT reader deps: defmt-decoder, object
app/
tartelette-runtime/ Session (firmware + board, stepped), pacing, boards, deps: rp2040-core, pcb-devices,
the host's side of USB/UART/radios, test synth rtt, the bridges, midir
tartelette/ front panel (native + web, eframe), headless runner, deps: tartelette-runtime,
`mkdisk`; end-to-end tests sdimage, eframe, cpal
tools/
cpu-difftest/ differential tests of the CPU against Unicorn dev-deps: armv6m
sitedocs/ renders docs/ as HTML for the demo site deps: pulldown-cmark
web-bench/ the core as a bare wasm module, timed in browsers deps: rp2040-core
armv6m, pcb, pcb-devices, sdimage, usbhost and rp2040-core are no_std +
alloc, deterministic, and do no I/O. The same core runs natively and in the
browser, and two runs with the same inputs are identical. Everything that
touches the outside world (files, sockets, sound, MIDI, the pty) is in
tartelette-runtime, tartelette or one of the bridge crates.
tartelette-runtime has no UI: what the front panel, the headless runner and
tests share (a Session and its clock, board loading, the far ends of the
USB cable and UART lines) lives there, and tartelette adds the command
line, the window and the sound card. A Session hands what the firmware
produced (serial bytes, board events, the defmt log, warnings) to its front
end as an Output after each step: the front panel keeps a capped history
of it for the dock, headless prints it. Anything that must hear board events
as they happen, like the live synth, registers a listener on the session
instead.
pcb talks to the chip only through the Pins trait, which rp2040-core
implements for its GPIO block. Peripherals stay inside rp2040-core: they are
tied to reset gating, IRQ lines, DMA and PIO.
rp2040-core also owns what is on the other end of the USB cable: a
usbhost::Host, which System polls from its own scheduler so that every
transaction lands on the cycle it would on a real bus, as the board's devices
do. Frontends reach it through System::usb_host and System::with_usb_host.
Adding a device
Each device in pcb-devices is one file that exposes a KIND: its name, a
one-line summary, the bus it sits on, and its board-file keys with types,
defaults and help text. Register it in register_builtin in
pcb-devices/src/lib.rs and the board parser, tartelette parts, the JSON
schema and the error messages all pick it up. Regenerate the schema with:
cargo run -p tartelette -- schema > boards/board.schema.json
For it to show on the front panel, give it a widget: a Widget variant,
picked for its kind in crates/app/tartelette/src/panel/layout.rs, and a
file in panel/widgets/ that draws it.
Tests
cargo test --workspace
cpu-difftest is the slow one, at around a minute. The end-to-end tests in
crates/app/tartelette/tests build the firmware in firmware/tests and
firmware/examples and run it headless; firmware/README.md lists what each
one checks. The Wi-Fi and Bluetooth tests need the CYW43439 firmware blobs,
from CYW43_FIRMWARE_DIR or the newest Embassy checkout in Cargo's git cache.
To check that the core still builds for the browser:
cargo build -p armv6m -p pcb -p pcb-devices -p rp2040-core -p tartelette --target wasm32-unknown-unknown
.github/workflows/ci.yml runs both, along with cargo fmt --check and
cargo clippy -D warnings, on each push to main and on pull requests.
In a browser
The web build is checked in a headless Chromium-family browser
(thorium-browser, chromium or google-chrome, or set CHROME), driven
over the DevTools protocol by tools/web-bench/cdp.mjs (Node 22+, no packages):
scripts/web-check.sh [FIRMWARE] [SCREENSHOT] # build with trunk, drop a firmware on the page, fail on exceptions, screenshot
scripts/web-bench.sh [ROUNDS] # time the core in the browser, with and without wasm tail calls
web-check.sh runs firmware/tests/cpu-bench by default. WAIT_MS sets how
long it runs, and CLICK="X,Y" clicks somewhere first (e.g. 283,632, the
USB serial tab). web-bench.sh takes MICROPYTHON_UF2=... to time
MicroPython too.
The web build uses WebAssembly tail calls (set in .cargo/config.toml) so the
CPU interpreter can use threaded dispatch, as it does natively. Without the
flag it still works, about 20% slower.
The demo site
scripts/build-site.sh [OUT] builds the static site GitHub Pages serves
(.github/workflows/pages.yml runs it on each push to main): the
landing page, the web app under emu/, the firmware/showcase demos under
demos/, and the documentation under docs/. MICROPYTHON=fetch adds the
official MicroPython build for the Pico, MICROPYTHON_UF2=FILE a local
one. Look at it with python3 -m http.server -d target/site.
The landing page's text is site/index.md, and the documentation is the
Markdown in docs/. tools/sitedocs (pulldown-cmark) turns both into HTML,
with the layouts in tools/sitedocs/src/landing.html and page.html. The
comment at the top of site/index.md explains how its Markdown maps onto
the page: a ### entry is a demo, its image the screenshot, a list of
Label: value items its details, its last paragraph of links the buttons.
Links are written as they would be on GitHub, relative to the Markdown file.
Links between .md files become links between pages, links into site/
(the screenshots, emu/) stay relative, and anything else in the
repository goes to GitHub. Heading ids follow GitHub's, so
page.md#heading links work in both places. Code blocks in toml and sh
are highlighted (tools/sitedocs/src/highlight.rs).
The page links each demo as emu/?firmware=../demos/NAME.elf&board=....
Its screenshots (site/img/) are checked in: retake them when a demo's
look changes.
To render the pages on their own, into target/site:
cargo run -p sitedocs -- . target/site https://github.com/OWNER/REPO \
--var MICROPYTHON_VERSION=v1.29.0 [--drop micropython]
MicroPython's test suite
scripts/micropython-tests.sh runs MicroPython's own tests/run-tests.py
against a MicroPython firmware in the emulator, over the USB serial port.
It needs the firmware (MICROPYTHON_UF2) and a MicroPython checkout at the
same version with the lib/micropython-lib submodule (MICROPYTHON_DIR):
git clone --depth 1 --branch v1.29.0 https://github.com/micropython/micropython.git
git -C micropython submodule update --init --depth 1 lib/micropython-lib
MICROPYTHON_UF2=RPI_PICO_W-20260824-v1.29.0.uf2 MICROPYTHON_DIR=micropython scripts/micropython-tests.sh
Arguments go to run-tests.py (-d basics, -i REGEX, test files). The
script fails on any failure that isn't listed, with a reason, in
scripts/micropython-known-failures.txt, and tells you when a known failure
starts passing.
scripts/micropython-flash.py copies files onto MicroPython's filesystem in a
--flash image, using MicroPython's pyboard.py.
Release builds with PGO
scripts/pgo-build.sh builds a profile-guided binary at
target/pgo/tartelette, 1.1 to 1.4 times faster than a plain release build.
It builds an instrumented tartelette, runs it on the repository's firmware,
and rebuilds with the profile, which takes a few minutes. It's meant for
release builds in CI.
rustup component add llvm-tools
scripts/pgo-build.sh
It needs llvm-profdata from rustc's LLVM (llvm-tools, or set
LLVM_PROFDATA). CYW43_FIRMWARE_DIR adds the Pico W Wi-Fi example to the
training run, and PGO_FIRMWARE="a.uf2 b.elf" any other firmware.
Releases
Pushing a version tag publishes a release (.github/workflows/release.yml):
git tag v0.1.0 && git push origin v0.1.0
The tag has to match version in the workspace Cargo.toml. The tests run
first, then the release gets the tartelette binary for Linux (x86_64,
aarch64), macOS (Apple silicon) and Windows, the web app as a static
directory, and SHA256SUMS. A tag with a suffix (v0.2.0-rc.1) makes a
pre-release.