Build options

Every knob is compile-time. Set environment variables and cargo features at cargo build and they bake into the image. Nothing here changes at runtime (except where noted for the phy record).

# the general shape
nix develop -c env KNOB=value cargo build --release -p firmware [--features ...]
picotool uf2 convert target/thumbv8m.main-none-eabihf/release/firmware -t elf firmware.uf2

flowchart TD
    knobs["env knobs + cargo features"] --> build["cargo build (or nix build)"]
    build --> elf["firmware.elf"]
    elf --> conv["picotool uf2 convert"]
    conv --> uf2["firmware.uf2"]
    uf2 --> flash["BOOTSEL flash"]
    uf2 -. "secure boot only" .-> seal["picotool seal --sign<br/>signing key (host-only)"]
    seal -.-> signed["firmware-signed.uf2"]
    signed -.-> flash

Cargo features

Environment variables

The LED_PIN / LED_KIND / LED_ORDER / MAX_LEDS values are boot defaults only. A non-none build compiles all three backends, so the LED pin, driver, and wire order are runtime-configurable (no reflash) with rsk hw (or PicoForge), which write them to the device’s phy record. The build knobs decide the out-of-the-box behaviour and let you drop to a lean none build. Everything else is a rsk hw call away (guides/led.md).

Verify what got baked without flashing:

rg PK_USB_VID  target/thumbv8m.main-none-eabihf/release/build/firmware-*/output   # decimal: 4617 = 0x1209
rg PK_FW_VERSION target/thumbv8m.main-none-eabihf/release/build/rsk-sdk-*/output
rg PK_XOSC_DELAY_MULT target/thumbv8m.main-none-eabihf/release/build/firmware-*/output

The firmware-* glob matches one build dir per feature combination you have built, so a stale entry can show an old value. Read the freshest one (or cargo clean -p firmware first) if the output looks doubled.

Flash size and the memory map

FLASH_SIZE regenerates memory.x: the KV store stays pinned to the top of flash and only the code region grows. A 16 MB board just gets more (unused) code headroom. The credential capacity is unchanged (why the flash is mostly empty by design: architecture.md).

The KV store is 1.5 MB by default (KVMAIN 1408K + KVCNT 128K). On a 2 MB board that leaves too little for the ~900K image, so the firmware can’t link. KVMAIN shrinks the main partition to make room: build a 2 MB Seeed XIAO RP2350 or Waveshare RP2350-Zero-CM with FLASH_SIZE=2M KVMAIN=896K (896K creds + 128K counters + 1024K code). build.rs bakes the size into both memory.x and flash_storage.rs, so the two partitions never disagree, and it rejects a split that leaves under 1 MB for code with a message that names the fix. A fully provisioned key needs only a few hundred KB, so 896K is ample.

At the 4M default the code region is 2560K; the shipping image uses roughly a third of it. check.sh enforces a ratchet well under that: a ceiling that hugs the current image, so a runaway dependency (a whole extra EC curve is ~150 KiB) or any surprise growth trips it long before the linker’s hard limit. Lower FIRMWARE_FLASH_BUDGET_KIB when the image shrinks; raise it in the same commit when a real feature legitimately grows it.

Examples

# default: touch build, RS-Key identity (0x1209:0x0001), fw 5.7.4
cargo build --release -p firmware

# opt-in Yubico interop flavor (so ykman / Yubico Authenticator see the device)
env VIDPID=Yubikey5 cargo build --release -p firmware

# no-touch test build (for the automated suites)
cargo build --release -p firmware --features no-touch

# Nitrokey FIDO2 identity with its own version number
env VIDPID=NitroFIDO2 FW_VERSION=1.4.0 cargo build --release -p firmware

# advertise PQC in getInfo (breaks released Firefox — see above)
cargo build --release -p firmware --features advertise-pqc

# ship with CTAP 2.1 alwaysUv enabled by default (set a PIN after flashing)
cargo build --release -p firmware --features always-uv

# strict admin-write posture (the historical default; config writes stay gated)
cargo build --release -p firmware --features strict-config

nix build (hermetic, no dev shell)

The flake exposes the firmware as a package, so you can build a UF2 without entering the dev shell or having a Rust toolchain installed. Nix pins the toolchain, the cross target, and every dependency:

nix build .#firmware                 # default touch image
ls result/                           # firmware.elf  firmware.uf2

result/firmware.uf2 is functionally the image the dev-shell cargo build produces. Unlike the dev-shell build, it is bit-for-bit reproducible: the derivation remaps the two absolute build inputs out of the binary (the per-build sandbox dir and the toolchain store path; both land in panic-location strings in .rodata, plus DWARF in the .elf) with stable --remap-path-prefix, so one flake.lock yields one firmware.uf2 on every machine of a platform. The daily repro job in deep-checks proves it (nix build twice, the second with --rebuild so nix compares every output byte) and publishes the canonical sha256 in its run summary.

To verify a published image: nix build .#firmware at the release commit and compare hashes. A sealed image can’t be reproduced by a third party (the signature is the signer’s); verify the unsigned payload instead, then check the seal with picotool. The flavors mirror the CI matrix:

Two caveats:

• The output is UNSIGNED. On a secure-boot device you still seal it with your key. The signing key deliberately never enters the build sandbox:

  picotool seal --sign --hash result/firmware.uf2 firmware-signed.uf2 \
      ~/.rs-key-secrets/secure_boot_key.pem ~/.rs-key-secrets/otp_secureboot.json \
      --major 1 --minor 0
  

  The .pem is your signing key, the .json is where seal writes the boot-key fingerprint, and --major/--minor stamp an image version into the boot metadata: a plain major.minor label, separate from both the firmware version RS-Key reports (5.7.x) and the rollback version. The full meaning of each flag is in production.md.

  If you have enabled anti-rollback, the seal additionally needs --rollback <your board's floor>, a separate, deliberate step with its own rules and a finite OTP budget. Don’t add it blindly; the full flashing-with-rollback workflow is in anti-rollback.md.

• The env knobs above are declarative Nix args, not ambient env. A plain nix build bakes the defaults; to customize, pass them to the builder. For a config you reuse, add a one-line preset package (the flake ships firmware-pico = mkFirmware { name = "firmware-pico"; vidpid = "Pico"; } as a copy-me example) and build it:

  nix build .#firmware-pico
  

  For a one-off without committing a package, call the exposed builder. (The --impure here only lets getFlake read the working tree; the knobs themselves are pure. A committed/pushed flakeref needs no flag.)

  nix build --impure --expr \
    '(builtins.getFlake (toString ./.)).lib.${builtins.currentSystem}.mkFirmware
       { name = "fw"; vidpid = "Nitro3"; fwVersion = "2.0.0"; }'
  

  Knobs: vidpid, usbVid, usbPid, fwVersion, xoscDelayMult, flashSize, ledPin, presencePin, fakeMkek, fakeDevk (mirroring the env vars above). As a convenience each also falls back to the like-named env var, so VIDPID=Pico nix build --impure .#firmware works for a quick throwaway, but the declarative arg is the reproducible path and needs no --impure.

nix run — host tools without the dev shell

The host tooling is also exposed as flake apps, so it runs straight from the flake without nix develop (Nix pins every dependency):

nix run .#rsk -- status          # the Python device CLI (rsk --help for groups)
nix run .#rsk-tui                # the live ratatui dashboard (prebuilt binary)
nix run .#flash -- --help        # build + sign + flash, one command (secure boot)

#rsk wraps the bundled tools/rsk package on the pinned interpreter; #rsk-tui is a prebuilt host binary (no compile-on-run). Both are also buildable as packages (nix build .#rsk-tui).

nix run .#flash wraps the secure-boot flash ritual end to end: it seals (signs) an unsigned image, reboots the device into BOOTSEL, loads it, then reboots. With no argument it seals the reproducible default firmware (.#firmware); pass a path to seal a flavor you built yourself (nix run .#flash -- firmware-no-touch.uf2). It reads the signing key from the host (~/.rs-key-secrets/{secure_boot_key.pem,otp_secureboot.json} by default, override the directory with RS_KEY_SECRETS) and stamps --rollback 1 into the seal (set RSK_ROLLBACK to change). It prompts before flashing (-y skips). The device must already run secure boot with the matching boot key provisioned; the full ritual, the anti-rollback rules, and recovery are in production.md and anti-rollback.md.

Runtime overrides (phy record)

The rescue applet can store a small config record in flash (rsk / rsk-tui expose the safe fields). At boot, a stored VID/PID and product string override the compile-time defaults, useful to re-identify a device without rebuilding. A bad value can make the device enumerate strangely; recovery is a BOOTSEL reflash (which never reads the record) or rewriting the record over CCID.

The effective identity is resolved in this order:

flowchart TD
    a["VIDPID preset"] --> b["USB_VID / USB_PID raw override (compile time)"]
    b --> c["phy record (runtime, at boot)"]
    c --> d["effective VID/PID + product string"]

Notes

• The PC/SC reader name comes from the USB strings. The default build reads RS-Key RS-Key Security Key …, and the project’s own tools (rsk, rsk-tui) match the RS-Key token. ykman and Yubico Authenticator derive the device’s PID purely from that name. They need the Yubico YubiKey words and the OTP/FIDO/CCID tokens, which only the opt-in VIDPID=Yubikey5 flavor supplies (Yubico YubiKey RSK OTP+FIDO+CCID); on the default build those tools do not see the device. gpg, ssh -sk, browsers, libfido2 and OpenSC are identity-independent and work on either build.
• bcdDevice (USB device release) is an internal build counter, not the firmware version.
• The two UF2 flavors on a release build of this repo: firmware.uf2 (touch) and firmware-test.uf2 (no-touch). scripts/check.sh builds both.