Owl Patch

Write Patches in Rust for many Rebel Technology devices based on the Owl2/3 modules.

#![no_main]
#![no_std]
extern crate alloc;
use alloc::boxed::Box;
use owl_patch::{
    patch,
    program_vector::{heap_bytes_used, ProgramVector},
    sample_buffer::{BufferByChannel, ConvertFrom, ConvertTo},
};

#[patch("Example Patch")]
fn main(mut pv: ProgramVector) -> ! {
    let audio_settings = pv.audio.settings;
    let mut buffer = BufferByChannel::<f32>::new(audio_settings.channels, audio_settings.blocksize);

    pv.meta.set_heap_bytes_used(heap_bytes_used());
    pv.audio.run(|input, output| {
        buffer.convert_from(input);
        // Do something clever with the samples in the buffer
        buffer.convert_to(output);
    });
}

Getting Started

1. Make sure you have the thumbv7em-none-eabihf Rust target installed:

rustup target add thumbv7em-none-eabihf

2. Install gcc-arm-none-eabi and FirmwareSender. See the instructions on https://github.com/RebelTechnology/OwlProgram for details.

3. Create a new binary package using Cargo, and add this repo as a dependency:

[dependencies]
owl_patch = "0.8.0"

It is also a good idea to add this to your Cargo.toml:

[profile.release]
codegen-units = 1
debug = 2
debug-assertions = false
incremental = false
lto = "fat"
opt-level = 3
overflow-checks = false

[profile.release.package."*"]
opt-level = 3

4. Create a .cargo/config.toml file:

[build]
target = "thumbv7em-none-eabihf"

# For Owl 2
[target.thumbv7em-none-eabihf]
rustflags = [
    "-C", "link-arg=--nmagic",
    "-C", "target-cpu=cortex-m4",
    "-C", "link-arg=-Towl2.ld",
]

# For Owl 3
#[target.thumbv7em-none-eabihf]
#rustflags = [
#    "-C", "link-arg=--nmagic",
#    "-C", "target-cpu=cortex-m7",
#    "-C", "link-arg=-Towl3.ld",
#]

5. Copy one of the examples into src/main.rs

6. Build your patch

cargo build --release

7. Use arm-none-eabi-objcopy to get the final binary:

arm-none-eabi-objcopy -O binary target/thumbv7em-none-eabihf/release/main target/thumbv7em-none-eabihf/release/main.bin

8. Use FirmwareSender to upload the patch to your device.

For further help, check the docs.

Supported devices

The examples in this repo have been tested on a Befaco Lich using Owl2 and Owl3 modules. They should work on others too, but I am unable to verify this. To give you the best chance of success, make sure your device is running the latest Firmware.

Crate Features

• talc (default): Uses the talc crate as the global allocator. If you want to use a different allocator, turn this feature off with default-features = false
• fastmaths (default): Enables the fast approximate maths functions in the fastmaths module.
• vpo_fastmaths (default): Use fastmaths functions in the volts_per_octave module to convert between Volts and Frequencies quicker (but less accurately). Requires fastmaths.
• stack_hack Uses a slightly dirty hack to get more stack memory - by default you only get 8Kb of stack (and > 8Mb of Heap).

Project state

Experimental, but already pretty usable.

Working features:

• Output correctly linked binary including patch header
• Safe API wrapper for the ProgramVector, allowing communication with the host OS
• Register Patch with host OS
• Global Allocator using talc
• Process Audio in i32 and f32 formats
• Simple Audio Buffer implementation, supporting different formats and layouts
• Register, get, and set Patch Parameters, with callback for button events
• Send & Receive Midi messages
• Debug / error messages
• Get i/o callibration data for volts-per-octave conversions
• Get system log / pow tables to perform fast maths functions
• Load resource files
• FFT init service calls
• Write to screen buffer (on devices with a screen)

Todo List:

• Wasm support
• Faust support

Maybe pile:

• Additional device support
• Invert some params for hardware_version == OWL_MODULAR_HARDWARE
• Support for lower checksum versions
• Create a Cargo project template
• Support for Colour screens

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this repository by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Note

The authors of this repository are not affiliated with Rebel Technology. The Owl Platform and associated published code is their copyright.