Deluge SDK

The Deluge SDK — write apps for the Synthstrom Deluge in async Rust.

A single attribute, #[deluge::app], absorbs all of the platform bring-up (heaps, clocks, interrupts, the async executor, and a panic handler), and a Deluge capability handle hands you the hardware: OLED, pads, buttons, encoders, LEDs, audio DSP, CV/gate, MIDI, the SD card, and more. No unsafe, no register pokes, no linker flags.

It is built on Embassy and targets the Deluge's onboard Renesas RZ/A1L (ARM Cortex-A9, R7S721020).

#![no_std]
#![no_main]
#![feature(impl_trait_in_assoc_type)]
use deluge::prelude::*;
use embassy_time::Timer;

#[deluge::app]
async fn main(dlg: Deluge) {
    let mut led = dlg.sync_led();
    loop {
        led.toggle();                  // heaps, clocks, IRQs, executor: already up
        Timer::after_millis(200).await;
    }
}

New here? Start with the Getting started guide — toolchain, cargo deluge, and your first app in five minutes.

[!Note] The Deluge SDK is intended for the OLED Deluge only. Legacy (i.e. 7SEG) Deluges are not supported and use of the App Loader and SDK are untested on the 7SEG Deluge.

Safe to hack on

Apps are ELF binaries that run from RAM, loaded by the on-device app-loader either straight over USB (dev mode) or from the /APPS/ folder on the SD card. That means:

• You can't easily brick the device. Apps never touch flash; power-cycle to recover.
• Iteration is push-to-run. With dev mode on, cargo deluge run uploads the ELF over USB and the loader launches it from RAM — no SD shuffling, no debug probe.

Quick start

rustup show                          # installs the pinned nightly + target
cargo install --path tools/cargo-deluge

cargo deluge new myapp
cd myapp
cargo deluge run                     # build + upload over USB, launch from RAM

cargo deluge run needs a Deluge running the app-loader with dev mode on. Flashing the app-loader is a one-time step — see Installing the loader. Without dev mode, cargo deluge deploy copies the ELF to a mounted SD card's /APPS/ instead. No hardware at all? cargo deluge sim runs the app in the desktop simulator.

The capability handle

#[deluge::app] async fn main(dlg: Deluge) receives a Deluge handle. Each accessor takes ownership of one peripheral (takeable once — a second call panics), so the type system keeps two parts of your app from driving the same hardware. Async accessors bring the peripheral up and wait for it before returning.

use deluge::prelude::*; brings the handle, all capability types, the #[deluge::app] macro, controls (named button/encoder ids), and the log macros (info!, warn!, …) into scope. Fixed-point DSP types live under deluge::fixed (Q31, Q16, …) for audio callbacks.

Optional features (on the deluge crate)

cargo deluge

The host subcommand so you never touch -Zbuild-std, linker flags, or the embedded target triple by hand:

Examples

Every example under examples/ is a complete, buildable app. Build and run any of them with cargo deluge run from its directory (CI compile-proves all of them on the firmware target).

Documentation

• Getting started — toolchain, cargo deluge, and a tour of every capability. Read this first.
• App Loader Manual — installing the loader, the boot menu, dev mode, storing apps to flash, and recovery.
• Desktop simulator — build and debug apps without hardware: the panel, audio/MIDI/SD bridges, and headless golden-frame testing.
• Advanced developer guide — Embassy tasks, interrupts, the HAL/BSP layers, and Cortex-A9 trace tooling.
• Wren scripting — live-code the Deluge in Wren: see the deluge-wren repo.
• Linux examples — apps for the Deluge's Linux userland.

Repository layout

The deluge SDK facade depends only on the BSP and HAL — it does not pull in the GPL UI toolkit, so an app stays permissively licensed unless it opts in.

Target

Licensing

The SDK and core libraries are MIT OR Apache-2.0. The OLED UI toolkit (crates/deluge-ui-toolkit), its fonts (crates/deluge-fonts) and the pad-grid toolkit (crates/deluge-grid-toolkit) are GPL-3.0-or-later (see LICENSE-GPL). They are standalone crates: the permissive deluge facade does not depend on them, so an app stays MIT/Apache unless it opts into the toolkit, in which case that app becomes GPL.

Working on the SDK itself

The sections below are for hacking on the firmware and SDK internals rather than writing apps. App authors can stop at cargo deluge.

Building firmware images

.cargo/config.toml sets target = "armv7a-none-eabihf" and defines build aliases that pass the required -Zbuild-std=core flags — always use them over a bare cargo build:

The app-loader and other firmwares have their own aliases (cargo build-app-loader / -bin, cargo build-controller-bin, cargo build-msc / -bin); see each crate's README. Every image is a RAM-linked ELF (loaded at SRAM 0x20020000).

Testing

The default target is bare-metal, so tests run on two host-side targets: QEMU ARM (armv7-unknown-linux-gnueabihf) for crates using ARM asm/intrinsics, and the host triple for pure-logic crates. Run everything with:

./tools/test.sh

One-time setup:

rustup target add armv7-unknown-linux-gnueabihf x86_64-unknown-linux-gnu
# Debian/Ubuntu: sudo apt-get install qemu-user gcc-arm-linux-gnueabihf libudev-dev
# Arch:          sudo pacman -S qemu-user-static arm-linux-gnueabihf-gcc

The qemu-arm runner and ARM cross-linker are wired up in .cargo/config.toml.

Debugging

Two probe backends are supported: J-Link (stable, recommended) and a custom probe-rs fork with Cortex-A9 PTM/ETF trace support (trace-a9 branch).

For J-Link, open the project in VS Code with Cortex-Debug and use the launch configs in .vscode/launch.json — they load the ELF via rza1_debug.JLinkScript and attach RTT (written to rtt.log). cargo deluge debug / cargo deluge trace wrap the probe-rs-fork commands with the right chip preset and flags; see the Advanced developer guide for the full trace workflow.

CI

The CI workflow runs on every push to main and on pull requests:

• Images — builds the app-loader and the demo/controller firmwares.
• Examples — compile-proves every SDK example on the firmware target.
• Tests — the host + QEMU-ARM unit suite.