Skip to content

Installer internals ​

The installer flashes official RØDE firmware with RC2FX added to it. It builds a modified root filesystem image on the computer containing the runtime, the start-up shims and the saved settings, and the mixer's USB update mode installs it. A first install, a repair after a failed state, and any update that changes RØDE's firmware use this flash. When only RC2FX changes, the app installs the signed mixer payload in place over USB 1 instead (see signed mixer releases); the flash remains the recovery path. Firmware images are not stored in git.

The installer engine is crates/rc2fx-installer, written in Rust with no external tools. The installer page is crates/rc2fx-app/src/installer.

Inputs ​

The desktop executable embeds the firmware catalog, the mixer runtime and the installer scripts at build time. The installer and its privileged helper use only those embedded bytes. They ignore files beside the executable or in the working directory. Developer tools and tests can pass a folder explicitly.

Before embedding, the build checks the payload checksums, checks that the binaries are ARM64, and checks that the runtime matches the catalog. Missing or corrupt inputs fail the build. Official RØDE firmware is downloaded and checked at install time.

Working files go in RC2FX/installer under the user data folder:

OSData folder
Windows%LOCALAPPDATA%
macOS~/Library/Application Support
Linux$XDG_DATA_HOME, or ~/.local/share

RC2FX_INSTALLER_WORK overrides the location. The folder holds installer.json, the prepared firmware, settings backups and the command log. Only one installer can use a given folder at a time.

Platforms ​

  • Windows uses its built-in HID and volume APIs.
  • macOS uses IOKit, ioreg and diskutil.
  • Linux needs root for raw USB, mounting and ejecting. The app itself runs as the user, and so do checking the mixer, listing releases and saving settings. Preparing firmware, switching to update mode and flashing are done by a helper started through pkexec, which is the same executable in installer-helper mode. The cache folder belongs to the user, so the helper flashes only an RC2FX image it built itself. The helper starts when the user presses Grant access on the installer page, which opens the password prompt. Access lasts until the installer closes. Files the helper creates are owned by the invoking user.

HTTPS uses the operating system's trust store.

The plan ​

The installer checks the mixer on USB 1 (normal or update mode, and its serial number) and asks the app's connection whether RC2FX is running. It then builds a single plan and skips any step the mixer already satisfies. One confirmation starts the plan, which runs to the end unattended. It stops at the first error and offers Retry from that step.

  1. Save settings. If RC2FX is running, the app reads its settings file over USB with GET /api/v1/settings. This is state.json, containing effects and presets. The installer stores it against the mixer's USB serial.

  2. Prepare firmware. The installer downloads the chosen release, checks RØDE's MD5 and the catalog's SHA-256, and builds a copy of the root filesystem with these additions, all owned by root:

    • /opt/rc2fx/: the runtime bundle with bundle.sha256, mixer-release.json (the RC2FX mixer software version, listed in the bundle's SHA256SUMS and reported by GET /api/v1/version), data/state.json (the newest saved settings for this mixer) and logs/.
    • /usr/sbin/rc_audio_mixer: the audio engine shim (see Architecture).
    • /usr/sbin/rc_gui_juce: the matching shim for the screen program.
    • /opt/rc2fx/image.sha256: the SHA-256 of each of RØDE's regular files in the image, for the mixer's image check. It leaves out the files RØDE rewrites or removes itself (authorized_keys, /boot/extlinux/extlinux.conf, which RØDE's updater points at the second root when it installs there, /etc/asound.conf, /etc/timestamp, /usr/bin/first-boot and /var/lib/alsa/asound.state) and RC2FX's own files, which the bundle's SHA256SUMS covers.

    authorized_keys stays empty, as RØDE ships it. SSH access is managed after installing, over USB 1 (see Developer SSH). A cached image built by an older installer with its SSH option is never reused or flashed.

    Files in RØDE's image are left as they are. The installer refuses an image that already contains any of these paths, requires the audio binaries to match a supported profile, and requires the runtime to support that profile. A prepared image is reused when the release, runtime and settings all match.

    RØDE's updater unpacks the image into whichever of its two root partitions is not running: 476,546 blocks of 1 KiB (465 MiB) and 142,585 blocks of 4 KiB (557 MiB) on a Pro II with 1.7.7. The installer estimates the unpacked size for each, rounding every file to whole blocks and counting a block per directory, and refuses an image that would leave either with less than 48 MiB free. On 1.7.7 the estimate came within 0.3 MiB of the space used on both partitions; the 0.2.0 image leaves about 90 MiB free on the smaller one.

  3. USB update mode. HID command M puts the mixer in update mode. Audio stops and the screen shows "Updating via USB". Nothing has been written yet. A mixer whose USB serial is a placeholder (two letters and zeros, such as RD0000000) is refused here and in the next step: RØDE's USB setup reports that when unit-serial.txt is missing because its settings partition did not mount, and the update drive lives on that partition too.

  4. Flash. When the mixer's update drive appears, the installer identifies it by the mixer's USB serial, checks that the firmware fits, copies archive.tar.gz and archive.md5 to it, reads them back, flushes, and ejects it. It then checks that the drive is gone and that the same mixer is still in update mode, and sends HID U. Any failure stops the plan before U is sent. Up to that point, removing power for 30 seconds returns the mixer to its current firmware.

    The drive's size varies between mixers. RØDE's engine creates it with dd count=560000 on its staging partition, so 286,720,000 bytes is a ceiling. A 224 MB drive has been seen on one Pro II.

  5. Wait for RC2FX. The mixer installs the update and restarts. On its first boot after the update it reflashes its controllers and restarts again, and the shim runs stock during that boot. On the following boot the first engine start loads RC2FX. The app keeps reconnecting over USB 1. The plan finishes when RC2FX reports the engine running, audio advancing and the saved settings applied, and then waits for the image check. The computer sends nothing to the mixer during these boots.

Image check ​

On each boot the launcher (rc2fx.sh launch) starts rc2fx.sh image-check in the background, unless it is RØDE's first boot after an update or the check has already passed for this image. The check runs sha256sum -c against image.sha256 from /, at the lowest CPU and I/O priority. For each file that does not match, it mounts the other root partition read-only and, if that copy has exactly the listed hash, writes it back: over the file's own blocks when the size is the same, so it works on a full root, otherwise through a copy beside it. Nothing else is ever written. The outcome goes to /opt/rc2fx/data/image-check as key=value lines, with the manifest's SHA-256 so a record for an older image is never reported, and rc2fxd serves it as GET /api/v1/image-check.

The installer asks for it every 3 seconds once RC2FX is running:

  • ok, or none (no manifest, or mixer software from before the check): the plan finishes.
  • repaired: RØDE's boot already ran with the damaged files, so the installer asks for a restart and waits; the next boot's check passes.
  • damaged: the plan stops and asks to install again.

This exists because a flash once left /usr/bin/rode-init-update-env.sh zero-filled on the new root: the right size and none of its contents. That script mounts the settings partition, so the mixer ran without it and lost its setup at every start, and RØDE's engine then filled the root with its update-drive image. Flashing the same image again worked, so the cause was in the unpack, not the image.

Offered releases ​

RC2FX is built only into the catalog's releases for the connected model, newest first. The download URL is built from the model's firmware folder and the pinned version, for example https://update.rode.com/rcp2/1.7.7/os.tar.gz with os.md5 beside it. The archive must match the catalog's SHA-256 and MD5.

Stock firmware ​

The Stock firmware tab flashes a release exactly as RØDE publishes it. This removes RC2FX and any SSH key RC2FX added. The releases come from RØDE's manifest for the model, the same lists the RØDECaster App reads: https://update.rode.com/manifest.json for the Pro II and https://update.rode.com/rcp2-mini-manifest.json for the Duo. Only the stable (main-version) and beta (beta-version) entries are used, and only when both URLs are in the model's own folder on update.rode.com (rcp2/ or rcp2-duo/). RØDE's other channels are not public downloads and are never offered. Downloads and redirects are accepted only from update.rode.com.

Each archive must match RØDE's os.md5, and the catalog's SHA-256 and MD5 as well when the catalog pins that version. The helper records a stock image the catalog doesn't pin when it stages it, and flashes it only if it still matches that record. Settings are saved first. The plan finishes when the mixer is back in normal USB mode.

USB commands ​

Each M and U is logged before it is sent and then marked as acknowledged or unacknowledged. The mixer may have received a command even without an acknowledgement, so the installer does not resend commands automatically. A flash within the last 20 minutes is treated as an update in progress. Windows can pad a HID write and report more bytes written than were sent, so only a short write count is treated as an error.

The command sequence comes from a published write-up of the Duo's update process and its traces. The Pro II's USB product IDs come from RØDE's uac2_gadget.sh: 0037, 0078, 008d, 0092 and 0094 in normal modes, and 0030 in update mode.

Release package ​

just package, or cargo xtask package, writes the release packages for the current system to target/package (see packaging): on Windows and macOS an installer, a portable zip and the update package and feed, made by Velopack's vpk; on Linux an AppImage with its update package and feed, also made by vpk. Each holds:

  • the self-contained app,
  • the project licence, third-party notices, training-data credits and every crate's licence text, built into the app under Settings › About › View licenses (the AppImage also carries them as LICENSES.html).

Release builds download the mixer payload. With --embedded, the runtime, catalog, mixer-release.json and scripts are embedded in the app instead and are not shipped as separate files. Packaging inspects the executable's payload mode, and for an embedded build its payload, and fails if it is missing, corrupt, stale or from the wrong build kind. This check also runs with --skip-build.

--target TRIPLE builds another architecture for the same OS when that toolchain is installed. --skip-build reuses an existing release build, and --build-only stops after building. Windows and macOS packages are signed only when signing is configured; see Signing.

Test status ​

The installer has flashed a real Pro II from Windows, and RC2FX came up afterwards with its settings applied. Flashing from Linux and macOS has not been tried on hardware, and the macOS backend has not yet been built on a Mac.

The automated tests cover image patching, the added files, runtime integrity, settings backups, key generation, the command log, HID write quirks, update-drive ownership, ejection failures, cancellation, and plan steps and retries. They do not replace testing on hardware.