mod generated;
mod name;
#[cfg(feature = "serde")]
mod serde;
pub use generated::*;
pub use name::ProgramName;
use core::fmt;
use crate::effect::{Algorithm, Engine};
use crate::error::{Error, Result};
use crate::ids::{PROGRAMS_PER_BANK, ProgramNumber, ProtocolVersion};
use crate::param::{DEFAULT_FIRMWARE, PARAMETER_COUNT, ParamId};
use crate::sysex::inquiry::Version;
use crate::sysex::{Command, Message, PROGRAM_NAME_LEN, packed};
#[derive(Clone, PartialEq, Eq, Hash)]
pub struct Program {
version: ProtocolVersion,
data: [u8; Program::MAX_LEN],
}
impl Program {
pub const MAX_LEN: usize = ProtocolVersion::V7.program_data_len();
pub const PACKED_MAX_LEN: usize = packed::packed_len(Self::MAX_LEN);
#[must_use]
pub fn new(version: ProtocolVersion) -> Self {
let mut program = Self {
version,
data: [0; Self::MAX_LEN],
};
for parameter in ParamId::ALL.iter().copied() {
let min = u8::try_from(parameter.min()).unwrap_or(0);
program.set_clamped(parameter, min);
}
program
}
pub fn from_bytes(version: ProtocolVersion, bytes: &[u8]) -> Result<Self> {
let expected = version.program_data_len();
if bytes.len() != expected {
return Err(Error::ProgramLength {
expected,
found: bytes.len(),
});
}
let mut data = [0; Self::MAX_LEN];
for (slot, byte) in data.iter_mut().zip(bytes) {
*slot = *byte;
}
Ok(Self { version, data })
}
pub fn from_packed(version: ProtocolVersion, packed: &[u8]) -> Result<Self> {
let expected = version.program_data_len();
let found = packed::unpacked_len(packed.len())?;
if found < expected || found >= expected + packed::RAW_GROUP {
return Err(Error::ProgramLength { expected, found });
}
let mut scratch = [0; Self::MAX_LEN + packed::RAW_GROUP - 1];
packed::unpack_into(packed, &mut scratch)?;
let mut data = [0; Self::MAX_LEN];
for (slot, byte) in data.iter_mut().zip(scratch).take(expected) {
*slot = byte;
}
Ok(Self { version, data })
}
pub fn from_dump(message: &Message<'_>) -> Result<Self> {
match *message {
Message::ProgramDumpResponse {
version, packed, ..
}
| Message::EditBufferDumpResponse { version, packed } => {
Self::from_packed(version, packed)
}
other => Err(Error::NotAProgramDump(other.command().to_byte())),
}
}
#[must_use]
pub const fn version(&self) -> ProtocolVersion {
self.version
}
#[must_use]
pub fn as_bytes(&self) -> &[u8] {
self.data.get(..self.data_len()).unwrap_or(&self.data)
}
#[must_use]
pub fn reserved(&self) -> &[u8] {
self.as_bytes().get(PARAMETER_COUNT..).unwrap_or_default()
}
#[must_use]
pub fn packed_len(&self) -> usize {
packed::packed_len(self.data_len())
}
pub fn pack_into(&self, out: &mut [u8]) -> Result<usize> {
packed::pack_into(self.as_bytes(), out)
}
#[must_use]
pub fn get(&self, parameter: ParamId) -> u8 {
self.data
.get(usize::from(parameter.offset()))
.copied()
.unwrap_or(0)
}
#[must_use]
pub fn algorithm(&self, engine: Engine) -> Option<&'static Algorithm> {
self.algorithm_for(engine, DEFAULT_FIRMWARE)
}
#[must_use]
pub fn algorithm_for(&self, engine: Engine, firmware: Version) -> Option<&'static Algorithm> {
Algorithm::for_value(self.get(engine.algorithm_parameter()), firmware)
}
pub fn set(&mut self, parameter: ParamId, value: u8) -> Result<()> {
if !parameter.accepts(u16::from(value)) {
return Err(Error::ValueOutOfRange {
parameter: parameter.offset(),
value: u16::from(value),
max: parameter.max(),
});
}
self.write(parameter, value);
Ok(())
}
pub fn set_clamped(&mut self, parameter: ParamId, value: u8) -> u8 {
let clamped = u8::try_from(parameter.clamp(u16::from(value))).unwrap_or(value);
self.write(parameter, clamped);
clamped
}
pub fn values(&self) -> impl Iterator<Item = (ParamId, u8)> + '_ {
ParamId::ALL
.iter()
.copied()
.map(move |parameter| (parameter, self.get(parameter)))
}
pub fn changes<'a>(&'a self, target: &'a Self) -> impl Iterator<Item = (ParamId, u8)> + 'a {
ParamId::ALL.iter().copied().filter_map(move |parameter| {
let value = target.get(parameter);
(self.get(parameter) != value).then_some((parameter, value))
})
}
pub fn invalid(&self) -> impl Iterator<Item = (ParamId, u8)> + '_ {
self.values()
.filter(|(parameter, value)| !parameter.accepts(u16::from(*value)))
}
pub fn validate(&self) -> Result<()> {
match self.invalid().next() {
None => Ok(()),
Some((parameter, value)) => Err(Error::ValueOutOfRange {
parameter: parameter.offset(),
value: u16::from(value),
max: parameter.max(),
}),
}
}
#[must_use]
pub fn name(&self) -> ProgramName {
let start = usize::from(NAME_OFFSET);
ProgramName::from_field(
self.data
.get(start..start.saturating_add(NAME_LEN))
.unwrap_or_default(),
)
}
pub fn set_name(&mut self, name: ProgramName) {
let start = usize::from(NAME_OFFSET);
let field = self
.data
.get_mut(start..start.saturating_add(NAME_LEN))
.unwrap_or_default();
for (slot, byte) in field
.iter_mut()
.zip(name.as_bytes().iter().copied().chain(core::iter::repeat(0)))
{
*slot = byte;
}
}
#[must_use]
pub fn transpose(&self) -> i8 {
let raw = i16::from(self.get(ParamId::ProgramTranspose));
i8::try_from((raw - i16::from(transpose_centre())).clamp(-48, 48)).unwrap_or(0)
}
pub fn set_transpose(&mut self, semitones: i8) -> Result<()> {
let raw = i16::from(transpose_centre()) + i16::from(semitones);
let raw = u8::try_from(raw).unwrap_or(0);
self.set(ParamId::ProgramTranspose, raw)
}
fn data_len(&self) -> usize {
self.version.program_data_len()
}
fn write(&mut self, parameter: ParamId, value: u8) {
if let Some(slot) = self.data.get_mut(usize::from(parameter.offset())) {
*slot = value;
}
}
}
fn transpose_centre() -> u8 {
let parameter = ParamId::ProgramTranspose;
u8::try_from(parameter.min().midpoint(parameter.max())).unwrap_or(0)
}
impl fmt::Debug for Program {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Program")
.field("version", &self.version)
.field("name", &self.name())
.finish_non_exhaustive()
}
}
impl fmt::Display for Program {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Display::fmt(&self.name(), f)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct BankNames<'a> {
unpacked: &'a [u8],
}
impl<'a> BankNames<'a> {
pub const COUNT: usize = PROGRAMS_PER_BANK as usize;
pub const LEN: usize = PROGRAM_NAME_LEN * Self::COUNT;
pub fn new(unpacked: &'a [u8]) -> Result<Self> {
if unpacked.len() != Self::LEN {
return Err(Error::PayloadLength {
command: Command::BankProgramNamesDumpResponse.to_byte(),
expected: Self::LEN,
found: unpacked.len(),
});
}
Ok(Self { unpacked })
}
#[must_use]
pub fn get(&self, program: ProgramNumber) -> ProgramName {
let start = usize::from(program.get()) * PROGRAM_NAME_LEN;
ProgramName::from_field(
self.unpacked
.get(start..start.saturating_add(PROGRAM_NAME_LEN))
.unwrap_or_default(),
)
}
pub fn iter(&self) -> impl Iterator<Item = ProgramName> + '_ {
self.unpacked
.chunks_exact(PROGRAM_NAME_LEN)
.map(ProgramName::from_field)
}
}
#[cfg(test)]
#[expect(
clippy::expect_used,
reason = "a failed expectation is the test failure"
)]
mod tests {
use super::*;
use crate::ids::Bank;
use crate::param::Group;
use crate::sysex::inquiry::Version;
const FIRMWARE_1_0: Version = Version { major: 1, minor: 0 };
fn program() -> Program {
Program::new(ProtocolVersion::V6)
}
#[test]
fn the_name_is_the_parameters_at_the_offsets_the_field_occupies() {
assert_eq!(NAME_PARAMETERS.len(), NAME_LEN);
assert_eq!(
NAME_PARAMETERS.first().map(|parameter| parameter.offset()),
Some(NAME_OFFSET)
);
for (index, parameter) in NAME_PARAMETERS.iter().enumerate() {
let offset = NAME_OFFSET + u8::try_from(index).expect("seventeen fit in a byte");
assert_eq!(parameter.offset(), offset);
assert_eq!(parameter.group(), Group::Program);
}
assert_eq!(NAME_PARAMETERS.len(), ProgramName::MAX_CHARS + 1);
}
#[test]
fn naming_a_program_moves_only_the_characters_that_changed() {
let mut program = program();
program.set_name(ProgramName::new("Bass").expect("a name the display can write"));
let mut renamed = program.clone();
renamed.set_name(ProgramName::new("Bassy").expect("a name the display can write"));
assert!(
program
.changes(&renamed)
.eq([(ParamId::ProgramNameChar5, b'y')]),
"one character moved"
);
assert!(
program
.changes(&renamed)
.all(|(parameter, _)| NAME_PARAMETERS.contains(¶meter))
);
}
#[test]
fn a_dump_survives_the_round_trip_byte_for_byte() {
let mut bytes = [0; PARAMETER_COUNT];
for (offset, byte) in bytes.iter_mut().enumerate() {
*byte = u8::try_from(offset).unwrap_or(0).wrapping_mul(7);
}
let program = Program::from_bytes(ProtocolVersion::V6, &bytes).expect("a v6 program");
assert_eq!(program.as_bytes(), bytes);
let mut packed = [0; Program::PACKED_MAX_LEN];
let len = program.pack_into(&mut packed).expect("room to pack");
let read = Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("packed"))
.expect("a v6 program");
assert_eq!(read, program);
}
#[test]
fn padding_on_the_wire_is_not_part_of_the_program() {
let program = program();
assert_eq!(program.as_bytes().len(), 242);
assert_eq!(program.packed_len(), 280);
let mut packed = [0xFF; Program::PACKED_MAX_LEN];
let len = program.pack_into(&mut packed).expect("room to pack");
assert_eq!(len, 280);
let read = Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("packed"))
.expect("a v6 program");
assert_eq!(read, program);
}
#[test]
fn version_seven_keeps_its_reserved_bytes() {
let mut bytes = [0; 245];
for (index, byte) in bytes.iter_mut().enumerate().skip(PARAMETER_COUNT) {
*byte = u8::try_from(index).unwrap_or(0);
}
let seven = Program::from_bytes(ProtocolVersion::V7, &bytes).expect("a v7 program");
assert_eq!(seven.reserved(), &[242, 243, 244]);
assert_eq!(seven.as_bytes(), bytes);
assert!(program().reserved().is_empty());
}
#[test]
fn clamping_lands_inside_every_parameters_range() {
let mut program = program();
for parameter in ParamId::ALL.iter().copied() {
for value in 0..=u8::MAX {
let stored = program.set_clamped(parameter, value);
assert_eq!(program.get(parameter), stored);
assert!(
parameter.accepts(u16::from(stored)),
"{parameter} clamped {value} to {stored}"
);
}
}
}
#[test]
fn a_dump_of_the_wrong_length_is_refused() {
assert_eq!(
Program::from_bytes(ProtocolVersion::V6, &[0; 240]),
Err(Error::ProgramLength {
expected: 242,
found: 240,
})
);
}
#[test]
fn a_packed_run_may_carry_the_padding_of_its_last_group_and_no_more() {
let program = program();
let mut packed = [0; Program::PACKED_MAX_LEN + packed::PACKED_GROUP];
let len = program.pack_into(&mut packed).expect("room to pack");
assert_eq!(len, 280);
assert_eq!(
Program::from_packed(ProtocolVersion::V6, packed.get(..len).expect("in range")),
Ok(program.clone())
);
assert_eq!(
Program::from_packed(
ProtocolVersion::V6,
packed.get(..len + packed::PACKED_GROUP).expect("in range")
),
Err(Error::ProgramLength {
expected: 242,
found: 252,
})
);
assert_eq!(
Program::from_packed(
ProtocolVersion::V6,
packed.get(..len - packed::PACKED_GROUP).expect("in range")
),
Err(Error::ProgramLength {
expected: 242,
found: 238,
})
);
}
#[test]
fn transpose_is_clamped_to_the_range_the_manual_gives() {
let mut program = program();
program.set_clamped(ParamId::ProgramTranspose, 0);
assert_eq!(program.transpose(), -48);
program.set_clamped(ParamId::ProgramTranspose, 255);
assert_eq!(program.transpose(), 48);
}
#[test]
fn a_new_program_holds_what_every_parameter_accepts() {
let program = program();
assert_eq!(program.validate(), Ok(()));
assert_eq!(program.invalid().count(), 0);
assert_eq!(program.program_transpose(), 80);
assert_eq!(program.transpose(), -48);
}
#[test]
fn a_value_outside_the_range_is_kept_but_reported() {
let mut bytes = [0; PARAMETER_COUNT];
*bytes.get_mut(2).expect("offset 2") = 9;
let program = Program::from_bytes(ProtocolVersion::V6, &bytes).expect("a v6 program");
assert_eq!(program.get(ParamId::Lfo1Shape), 9);
assert_eq!(program.lfo1_shape(), None);
assert!(
program
.invalid()
.eq([(ParamId::Lfo1Shape, 9), (ParamId::ProgramTranspose, 0)]),
"both out-of-range bytes are reported, in offset order"
);
}
#[test]
fn setting_refuses_what_clamping_bends() {
let mut program = program();
assert_eq!(
program.set(ParamId::Lfo1Shape, 9),
Err(Error::ValueOutOfRange {
parameter: 2,
value: 9,
max: 6,
})
);
assert_eq!(program.set_clamped(ParamId::Lfo1Shape, 9), 6);
assert_eq!(program.lfo1_shape(), Some(LfoShape::SampleAndGlide));
}
#[test]
fn the_typed_accessors_are_the_bytes_under_another_name() {
let mut program = program();
program.set_lfo1_shape(LfoShape::Square);
program.set_lfo1_key_sync(true);
program.set_vcf_frequency(128);
assert_eq!(program.get(ParamId::Lfo1Shape), 2);
assert_eq!(program.get(ParamId::Lfo1KeySync), 1);
assert_eq!(program.get(ParamId::VcfFrequency), 128);
assert!(program.lfo1_key_sync());
assert_eq!(program.vcf_frequency(), 128);
}
#[test]
fn a_renumbered_table_reads_by_firmware() {
let mut program = program();
program.set_mod1_source(ModSource::Expression);
let raw = program.get(ParamId::Mod1Source);
assert_eq!(raw, 6);
assert_eq!(program.mod1_source(), Some(ModSource::Expression));
assert_eq!(
ModSource::from_raw_for(raw, FIRMWARE_1_0),
Some(ModSource::Lfo1)
);
assert_eq!(ModSource::Expression.raw_for(FIRMWARE_1_0), None);
assert_eq!(ModSource::Lfo1.raw_for(FIRMWARE_1_0), Some(6));
assert_eq!(ModSource::Expression.name(), "Expression");
assert_eq!(ModSource::Expression.name_for(FIRMWARE_1_0), None);
}
#[test]
fn every_value_of_every_table_survives_the_round_trip() {
for source in ModSource::ALL.iter().copied() {
assert_eq!(ModSource::from_raw(source.raw()), Some(source));
}
for destination in ModDestination::ALL.iter().copied() {
assert_eq!(
ModDestination::from_raw(destination.raw()),
Some(destination)
);
}
for effect in FxType::ALL.iter().copied() {
assert_eq!(FxType::from_raw(effect.raw()), Some(effect));
}
for shape in LfoShape::ALL.iter().copied() {
assert_eq!(LfoShape::from_raw(shape.raw()), Some(shape));
assert_eq!(
Some(shape.name()),
shape.name_for(crate::param::DEFAULT_FIRMWARE)
);
}
}
#[test]
fn a_name_is_written_and_read_back() {
let mut program = program();
program.set_name(ProgramName::new("Bass Sweep").expect("a valid name"));
assert_eq!(program.name().as_str(), "Bass Sweep");
assert_eq!(program.get(ParamId::ProgramNameChar1), b'B');
assert_eq!(program.get(ParamId::ProgramNameChar11), 0);
assert_eq!(program.get(ParamId::ProgramNameChar17), 0);
program.set_name(ProgramName::new("A").expect("a valid name"));
assert_eq!(program.name().as_str(), "A");
assert_eq!(program.get(ParamId::ProgramNameChar2), 0);
}
#[test]
fn transposition_counts_from_the_middle_of_its_range() {
let mut program = program();
program.set_transpose(0).expect("no transposition");
assert_eq!(program.program_transpose(), 128);
assert_eq!(program.transpose(), 0);
program.set_transpose(48).expect("four octaves up");
assert_eq!(program.program_transpose(), 176);
assert_eq!(program.transpose(), 48);
assert!(program.set_transpose(49).is_err());
assert!(program.set_transpose(-49).is_err());
}
#[test]
fn changes_are_the_edits_that_close_the_gap() {
let before = program();
let mut after = before.clone();
after.set_lfo1_rate(64);
after.set_lfo1_shape(LfoShape::Square);
assert!(
before
.changes(&after)
.eq([(ParamId::Lfo1Rate, 64), (ParamId::Lfo1Shape, 2)]),
"both edits are reported, in offset order"
);
let mut applied = before.clone();
for (parameter, value) in before.changes(&after) {
applied.set(parameter, value).expect("a value it accepts");
}
assert_eq!(applied, after);
assert_eq!(before.changes(&before).count(), 0);
}
#[test]
fn a_dump_message_carries_a_program_and_nothing_else_does() {
let program = program();
let mut packed = [0; Program::PACKED_MAX_LEN];
let len = program.pack_into(&mut packed).expect("room to pack");
let packed = packed.get(..len).expect("packed");
let dump = Message::EditBufferDumpResponse {
version: ProtocolVersion::V6,
packed,
};
assert_eq!(Program::from_dump(&dump), Ok(program.clone()));
let stored = Message::ProgramDumpResponse {
version: ProtocolVersion::V6,
bank: Bank::new(0).expect("bank A"),
program: ProgramNumber::new(0).expect("program 0"),
packed,
};
assert_eq!(Program::from_dump(&stored), Ok(program));
assert_eq!(
Program::from_dump(&Message::EditBufferDumpRequest),
Err(Error::NotAProgramDump(0x03))
);
}
#[test]
fn a_bank_of_names_is_read_where_it_lies() {
let mut unpacked = [0; BankNames::LEN];
let first = unpacked.get_mut(..4).expect("the first name");
first.copy_from_slice(b"Bass");
let second = unpacked
.get_mut(PROGRAM_NAME_LEN..PROGRAM_NAME_LEN + 16)
.expect("the second name");
second.copy_from_slice(b"SixteenCharacter");
let names = BankNames::new(&unpacked).expect("a bank of names");
assert_eq!(
names
.get(ProgramNumber::new(0).expect("program 0"))
.as_str(),
"Bass"
);
assert_eq!(
names
.get(ProgramNumber::new(1).expect("program 1"))
.as_str(),
"SixteenCharacter"
);
assert_eq!(names.iter().count(), 128);
assert_eq!(
BankNames::new(&[0; 16]),
Err(Error::PayloadLength {
command: Command::BankProgramNamesDumpResponse.to_byte(),
expected: BankNames::LEN,
found: 16,
})
);
}
}