Skip to main content

qualia_audio/midi/ump/
midi_ci.rs

1//! MIDI Capability Inquiry (MIDI-CI) Discovery message — minimal, spec-shaped.
2//!
3//! MIDI-CI messages are Universal Non-Real-Time System Exclusive messages:
4//! `F0 7E <device_id> 0D <sub_id2> <ci_version> <src MUID> <dst MUID> …payload… F7`.
5//! Multi-byte fields are little-endian groups of 7-bit bytes. The MUID is a
6//! 28-bit value carried as four 7-bit bytes, LSB first; the broadcast MUID is
7//! `0x0FFF_FFFF` (four `0x7F` bytes). This models the Discovery message
8//! (`sub_id2 = 0x70`); build/parse operate over caller buffers (zero-heap).
9
10use crate::types::AudioError;
11
12/// SysEx start.
13pub const SYSEX_START: u8 = 0xF0;
14/// SysEx end.
15pub const SYSEX_END: u8 = 0xF7;
16/// Universal Non-Real-Time SysEx ID.
17pub const UNIVERSAL_NON_REALTIME: u8 = 0x7E;
18/// MIDI-CI sub-ID#1.
19pub const MIDI_CI_SUB_ID: u8 = 0x0D;
20/// Discovery message sub-ID#2.
21pub const SUBID2_DISCOVERY: u8 = 0x70;
22/// Broadcast MUID (28 bits all set).
23pub const BROADCAST_MUID: u32 = 0x0FFF_FFFF;
24/// Serialized length of a Discovery frame (bytes), `F0`..`F7` inclusive.
25pub const DISCOVERY_LEN: usize = 32;
26
27/// A MIDI-CI Discovery message (initiator → responder).
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub struct MidiCiDiscovery {
30    /// Source device id (`0x7F` = whole MIDI port).
31    pub device_id: u8,
32    /// MIDI-CI version/format (e.g. `0x02` for MIDI-CI 1.2).
33    pub ci_version: u8,
34    /// Source MUID, 28-bit.
35    pub source_muid: u32,
36    /// Destination MUID, 28-bit (use [`BROADCAST_MUID`] for discovery).
37    pub destination_muid: u32,
38    /// Device manufacturer SysEx ID (3 bytes).
39    pub manufacturer: [u8; 3],
40    /// Device family, 14-bit.
41    pub family: u16,
42    /// Device family model number, 14-bit.
43    pub model: u16,
44    /// Software revision level (4 bytes).
45    pub software_revision: [u8; 4],
46    /// Capability Inquiry category-supported bitmap.
47    pub category_supported: u8,
48    /// Receivable maximum SysEx message size, 28-bit.
49    pub max_sysex_size: u32,
50    /// Initiator's output path id (MIDI-CI 1.2).
51    pub output_path_id: u8,
52}
53
54/// Encode a 28-bit value as four 7-bit bytes, LSB first.
55#[inline]
56fn muid_to_bytes(v: u32) -> [u8; 4] {
57    [
58        (v & 0x7F) as u8,
59        ((v >> 7) & 0x7F) as u8,
60        ((v >> 14) & 0x7F) as u8,
61        ((v >> 21) & 0x7F) as u8,
62    ]
63}
64
65/// Decode four 7-bit bytes (LSB first) into a 28-bit value.
66#[inline]
67fn muid_from_bytes(b: &[u8]) -> u32 {
68    (b[0] as u32 & 0x7F)
69        | ((b[1] as u32 & 0x7F) << 7)
70        | ((b[2] as u32 & 0x7F) << 14)
71        | ((b[3] as u32 & 0x7F) << 21)
72}
73
74impl MidiCiDiscovery {
75    /// Serialize the Discovery message into `out`, returning bytes written
76    /// ([`DISCOVERY_LEN`]). Errors [`AudioError::OutputBufferTooSmall`] if `out`
77    /// is too short, or [`AudioError::InvalidParameter`] on out-of-range fields.
78    pub fn encode(self, out: &mut [u8]) -> Result<usize, AudioError> {
79        if out.len() < DISCOVERY_LEN {
80            return Err(AudioError::OutputBufferTooSmall);
81        }
82        if self.device_id > 0x7F
83            || self.ci_version > 0x7F
84            || self.source_muid > BROADCAST_MUID
85            || self.destination_muid > BROADCAST_MUID
86            || self.family > 0x3FFF
87            || self.model > 0x3FFF
88            || self.category_supported > 0x7F
89            || self.max_sysex_size > BROADCAST_MUID
90            || self.output_path_id > 0x7F
91        {
92            return Err(AudioError::InvalidParameter);
93        }
94        let src = muid_to_bytes(self.source_muid);
95        let dst = muid_to_bytes(self.destination_muid);
96        let size = muid_to_bytes(self.max_sysex_size);
97        out[0] = SYSEX_START;
98        out[1] = UNIVERSAL_NON_REALTIME;
99        out[2] = self.device_id;
100        out[3] = MIDI_CI_SUB_ID;
101        out[4] = SUBID2_DISCOVERY;
102        out[5] = self.ci_version;
103        out[6..10].copy_from_slice(&src);
104        out[10..14].copy_from_slice(&dst);
105        out[14..17].copy_from_slice(&self.manufacturer);
106        out[17] = (self.family & 0x7F) as u8;
107        out[18] = ((self.family >> 7) & 0x7F) as u8;
108        out[19] = (self.model & 0x7F) as u8;
109        out[20] = ((self.model >> 7) & 0x7F) as u8;
110        out[21..25].copy_from_slice(&self.software_revision);
111        out[25] = self.category_supported;
112        out[26..30].copy_from_slice(&size);
113        out[30] = self.output_path_id;
114        out[31] = SYSEX_END;
115        Ok(DISCOVERY_LEN)
116    }
117
118    /// Parse a Discovery message from a complete SysEx frame. Errors
119    /// [`AudioError::MalformedAudio`] if the framing / header bytes do not
120    /// identify a MIDI-CI Discovery message of the expected length.
121    pub fn parse(frame: &[u8]) -> Result<Self, AudioError> {
122        if frame.len() != DISCOVERY_LEN
123            || frame[0] != SYSEX_START
124            || frame[1] != UNIVERSAL_NON_REALTIME
125            || frame[3] != MIDI_CI_SUB_ID
126            || frame[4] != SUBID2_DISCOVERY
127            || frame[DISCOVERY_LEN - 1] != SYSEX_END
128        {
129            return Err(AudioError::MalformedAudio);
130        }
131        Ok(Self {
132            device_id: frame[2],
133            ci_version: frame[5],
134            source_muid: muid_from_bytes(&frame[6..10]),
135            destination_muid: muid_from_bytes(&frame[10..14]),
136            manufacturer: [frame[14], frame[15], frame[16]],
137            family: (frame[17] as u16 & 0x7F) | ((frame[18] as u16 & 0x7F) << 7),
138            model: (frame[19] as u16 & 0x7F) | ((frame[20] as u16 & 0x7F) << 7),
139            software_revision: [frame[21], frame[22], frame[23], frame[24]],
140            category_supported: frame[25],
141            max_sysex_size: muid_from_bytes(&frame[26..30]),
142            output_path_id: frame[30],
143        })
144    }
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    fn sample() -> MidiCiDiscovery {
152        MidiCiDiscovery {
153            device_id: 0x7F,
154            ci_version: 0x02,
155            source_muid: 0x0123_4567 & BROADCAST_MUID,
156            destination_muid: BROADCAST_MUID,
157            manufacturer: [0x00, 0x21, 0x09],
158            family: 0x1234 & 0x3FFF,
159            model: 0x0055,
160            software_revision: [1, 0, 0, 0],
161            category_supported: 0b0001_1110,
162            max_sysex_size: 512,
163            output_path_id: 0,
164        }
165    }
166
167    #[test]
168    fn discovery_roundtrip() {
169        let d = sample();
170        let mut buf = [0u8; DISCOVERY_LEN];
171        let n = d.encode(&mut buf).unwrap();
172        assert_eq!(n, DISCOVERY_LEN);
173        // Header bytes are spec-shaped.
174        assert_eq!(buf[0], 0xF0);
175        assert_eq!(buf[1], 0x7E);
176        assert_eq!(buf[3], 0x0D);
177        assert_eq!(buf[4], 0x70);
178        assert_eq!(buf[DISCOVERY_LEN - 1], 0xF7);
179        let parsed = MidiCiDiscovery::parse(&buf).unwrap();
180        assert_eq!(parsed, d);
181        assert_eq!(parsed.destination_muid, BROADCAST_MUID);
182        assert_eq!(parsed.category_supported, 0b0001_1110);
183    }
184
185    #[test]
186    fn broadcast_muid_is_all_7f() {
187        assert_eq!(muid_to_bytes(BROADCAST_MUID), [0x7F, 0x7F, 0x7F, 0x7F]);
188        assert_eq!(muid_from_bytes(&[0x7F, 0x7F, 0x7F, 0x7F]), BROADCAST_MUID);
189    }
190
191    #[test]
192    fn rejects_bad_frame() {
193        let mut buf = [0u8; DISCOVERY_LEN];
194        sample().encode(&mut buf).unwrap();
195        buf[4] = 0x71; // not a discovery sub-id2
196        assert_eq!(
197            MidiCiDiscovery::parse(&buf),
198            Err(AudioError::MalformedAudio)
199        );
200        assert_eq!(
201            MidiCiDiscovery::parse(&buf[..10]),
202            Err(AudioError::MalformedAudio)
203        );
204    }
205
206    #[test]
207    fn buffer_too_small() {
208        let mut buf = [0u8; 8];
209        assert_eq!(
210            sample().encode(&mut buf),
211            Err(AudioError::OutputBufferTooSmall)
212        );
213    }
214}