valentine

protocol.rs (7814B)

---

 //! High-level scarlett2 operations built on a [`Transport`].
 //!
 //! These are the primitives the whole feature set rides on. Most controls
 //! (phantom power, air, pad, inst/line, mutes, monitor level, …) are just
 //! [`Scarlett::get_data`] / [`Scarlett::set_data`] at a per-feature offset, then
 //! an [`Scarlett::activate`]. The matrix mixer / routing / metering use their own
 //! opcodes and are layered on top in `matrix.rs`.
 
 use crate::packet::Response;
 use crate::transport::{Transport, TransportError};
 
 /// scarlett2 command opcodes (from the kernel driver, confirmed by the spike).
 pub mod op {
     pub const INIT_1: u32 = 0x0000_0000;
     pub const INIT_2: u32 = 0x0000_0002;
     pub const REBOOT: u32 = 0x0000_0003;
     pub const GET_METER: u32 = 0x0000_1001;
     pub const GET_MIX: u32 = 0x0000_2001;
     pub const SET_MIX: u32 = 0x0000_2002;
     pub const GET_MUX: u32 = 0x0000_3001;
     pub const SET_MUX: u32 = 0x0000_3002;
     pub const GET_SYNC: u32 = 0x0000_6004;
     pub const GET_DATA: u32 = 0x0080_0000;
     pub const SET_DATA: u32 = 0x0080_0001;
     pub const DATA_CMD: u32 = 0x0080_0002;
 }
 
 /// `activate` argument that persists the current settings to the device's flash
 /// (standalone mode).
 pub const CONFIG_SAVE: u32 = 6;
 
 /// A connected (or mocked) Scarlett, speaking the scarlett2 protocol.
 pub struct Scarlett<T: Transport> {
     transport: T,
     firmware: u32,
 }
 
 impl<T: Transport> Scarlett<T> {
     pub fn new(transport: T) -> Self {
         Self { transport, firmware: 0 }
     }
 
     /// Firmware version reported by [`Scarlett::init`] (0 until init runs).
     pub fn firmware(&self) -> u32 {
         self.firmware
     }
 
     /// Issue one raw scarlett2 command (used by the matrix/mux/meter ops in
     /// `matrix.rs`). Crate-internal so the wire stays encapsulated.
     pub(crate) fn command(
         &mut self,
         cmd: u32,
         payload: &[u8],
         resp_cap: usize,
     ) -> Result<Response, TransportError> {
         self.transport.command(cmd, payload, resp_cap)
     }
 
     /// Run the INIT handshake: a raw priming read, then INIT_1 and INIT_2 each
     /// with the sequence counter reset to 1.
     ///
     /// INIT_2 (which carries the firmware version at byte 8) is **best-effort**:
     /// on macOS its response is normally signalled on the interrupt endpoint,
     /// which we can't claim while FocusriteControlServer holds it, so the IN read
     /// times out. The Phase-0 spike confirmed every other command (GET_SYNC,
     /// GET_DATA, …) works regardless, so a timed-out INIT_2 must not abort init —
     /// we just report firmware 0. INIT_1 must still succeed.
     pub fn init(&mut self) -> Result<u32, TransportError> {
         let _ = self.transport.raw_in(0, 24); // step 0 (best-effort)
 
         self.transport.set_seq(1);
         self.transport.command(op::INIT_1, &[], 0)?;
 
         self.transport.set_seq(1);
         self.firmware = match self.transport.command(op::INIT_2, &[], 32) {
             Ok(resp) => resp
                 .payload
                 .get(8..12)
                 .map(|s| u32::from_le_bytes(s.try_into().unwrap()))
                 .unwrap_or(0),
             Err(_) => 0, // firmware unknown; not fatal
         };
         Ok(self.firmware)
     }
 
     /// Read `size` bytes from the device data space at `offset`.
     pub fn get_data(&mut self, offset: u32, size: u32) -> Result<Vec<u8>, TransportError> {
         let mut payload = Vec::with_capacity(8);
         payload.extend_from_slice(&offset.to_le_bytes());
         payload.extend_from_slice(&size.to_le_bytes());
         Ok(self
             .transport
             .command(op::GET_DATA, &payload, size as usize)?
             .payload)
     }
 
     /// Write a `size`-byte (1, 2, or 4) little-endian `value` at `offset`.
     /// Remember to [`Scarlett::activate`] afterwards to apply it.
     pub fn set_data(&mut self, offset: u32, size: u32, value: u32) -> Result<(), TransportError> {
         let size = size.clamp(1, 4);
         let mut payload = Vec::with_capacity(8 + size as usize);
         payload.extend_from_slice(&offset.to_le_bytes());
         payload.extend_from_slice(&size.to_le_bytes());
         payload.extend_from_slice(&value.to_le_bytes()[..size as usize]);
         self.transport.command(op::SET_DATA, &payload, 0)?;
         Ok(())
     }
 
     /// Apply previously uploaded `set_data` changes. `activate` is the per-item
     /// activation value (or [`CONFIG_SAVE`] to persist to flash).
     pub fn activate(&mut self, activate: u32) -> Result<(), TransportError> {
         self.transport
             .command(op::DATA_CMD, &activate.to_le_bytes(), 0)?;
         Ok(())
     }
 
     /// Persist the current configuration to the device's flash (standalone mode).
     pub fn save_to_flash(&mut self) -> Result<(), TransportError> {
         self.activate(CONFIG_SAVE)
     }
 
     /// Clock-sync lock status. The device returns a 4-byte value; non-zero = locked.
     pub fn get_sync(&mut self) -> Result<bool, TransportError> {
         let resp = self.transport.command(op::GET_SYNC, &[], 4)?;
         Ok(resp.payload.iter().any(|&b| b != 0))
     }
 
     /// Consume the wrapper and get the transport back (e.g. to re-issue init).
     pub fn into_transport(self) -> T {
         self.transport
     }
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
     use crate::transport::mock::MockTransport;
 
     #[test]
     fn init_resets_seq_and_extracts_firmware() {
         let mut m = MockTransport::new();
         m.push_response(op::INIT_1, &[]);
         let mut p = vec![0u8; 12];
         p[8..12].copy_from_slice(&0x1234u32.to_le_bytes());
         m.push_response(op::INIT_2, &p);
 
         let mut dev = Scarlett::new(m);
         let fw = dev.init().unwrap();
         assert_eq!(fw, 0x1234);
         assert_eq!(dev.firmware(), 0x1234);
 
         let m = dev.into_transport();
         assert_eq!(m.sent[0].0, op::INIT_1);
         assert_eq!(m.sent[1].0, op::INIT_2);
     }
 
     #[test]
     fn get_data_builds_offset_size_payload() {
         let mut m = MockTransport::new();
         m.push_response(op::GET_DATA, &[0xaa, 0xbb]);
         let mut dev = Scarlett::new(m);
 
         let data = dev.get_data(0x40, 2).unwrap();
         assert_eq!(data, vec![0xaa, 0xbb]);
 
         let m = dev.into_transport();
         let (cmd, payload) = &m.sent[0];
         assert_eq!(*cmd, op::GET_DATA);
         assert_eq!(payload, &vec![0x40, 0, 0, 0, 0x02, 0, 0, 0]);
     }
 
     #[test]
     fn set_data_packs_value_to_declared_width() {
         let mut m = MockTransport::new();
         m.push_response(op::SET_DATA, &[]);
         let mut dev = Scarlett::new(m);
 
         dev.set_data(0x9c, 1, 1).unwrap();
 
         let m = dev.into_transport();
         let (cmd, payload) = &m.sent[0];
         assert_eq!(*cmd, op::SET_DATA);
         assert_eq!(payload, &vec![0x9c, 0, 0, 0, 0x01, 0, 0, 0, 0x01]);
     }
 
     #[test]
     fn activate_and_save_send_data_cmd() {
         let mut m = MockTransport::new();
         m.push_response(op::DATA_CMD, &[]);
         m.push_response(op::DATA_CMD, &[]);
         let mut dev = Scarlett::new(m);
 
         dev.activate(0x05).unwrap();
         dev.save_to_flash().unwrap();
 
         let m = dev.into_transport();
         assert_eq!(m.sent[0], (op::DATA_CMD, 0x05u32.to_le_bytes().to_vec()));
         assert_eq!(m.sent[1], (op::DATA_CMD, CONFIG_SAVE.to_le_bytes().to_vec()));
     }
 
     #[test]
     fn get_sync_reads_lock_state() {
         let mut m = MockTransport::new();
         m.push_response(op::GET_SYNC, &[0x01, 0, 0, 0]); // locked (real spike bytes)
         let mut dev = Scarlett::new(m);
         assert!(dev.get_sync().unwrap());
 
         let mut m2 = MockTransport::new();
         m2.push_response(op::GET_SYNC, &[0, 0, 0, 0]); // unlocked
         let mut dev2 = Scarlett::new(m2);
         assert!(!dev2.get_sync().unwrap());
     }
 }