From 2ff17c0fcbcb6e3e4621355e100cc49af2eab214 Mon Sep 17 00:00:00 2001 From: Tyler Chiriboga Date: Sun, 25 Oct 2026 01:18:34 +0000 Subject: [PATCH] 3D mouse: follow the device that moves, not the first one found (#3988) (#4339) * claim: #3988 (3D mouse: follow the device that moves, not the first one found) Co-Authored-By: Claude Opus 5.5 * 3D mouse: follow the device that moves, not the first one found (#3988) On Windows and macOS the reader opened the first 3D-mouse interface it could and read it until it failed. A 3Dconnexion Universal Receiver with nothing paired opens fine, has a valid layout and never fails, so it kept the reader for good. A SpaceMouse on a cable next to it was never read ("Not calibrated (hid 256f:c652)", every axis at zero). The reader now opens every candidate and follows the one in use. The first is followed from the start, as before. Another takes over once it shows use (an axis off zero or a button down) while the followed one has shown none for STALE_AFTER, so two devices moved together don't trade the reading. A candidate that fails is dropped; if it was the followed one the reading resets and the next is read. With one device the reader behaves as before, down to the 100 ms read timeout. Several take 10 ms turns, and reports queue in the system meanwhile. The selection is `follow()`, written against a small `ReportSource` trait, so it is tested with simulated devices on every platform: an idle receiver next to a SpaceMouse, two devices in use at once, and devices failing. Co-Authored-By: Claude Opus 5.5 * 3D mouse: a press that makes a device the one in use counts as a press Since #3825 a HID device's first button report after it connects is its baseline: a button down in it is held, not pressed. A device taking over from another one was connected at that moment, so the press that took over was swallowed. With an idle Universal Receiver found first, that is the first button press on the SpaceMouse. follow() now keeps the buttons each candidate last reported while another was read, and the reader hands them to the reading as the baseline when that candidate takes over. A device that reported no buttons before it took over keeps the held-not-pressed rule. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Tyler Chiriboga <18270301+Tyler-Chiriboga@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 --- apps/solidcraft/src/space_mouse.rs | 339 ++++++++++++++++++++++++++--- docs/3d-mouse.md | 5 + 2 files changed, 316 insertions(+), 28 deletions(-) diff --git a/apps/solidcraft/src/space_mouse.rs b/apps/solidcraft/src/space_mouse.rs index a4c3f9d45..2951dca04 100644 --- a/apps/solidcraft/src/space_mouse.rs +++ b/apps/solidcraft/src/space_mouse.rs @@ -521,6 +521,119 @@ fn hid_api() -> hidapi::HidResult { HidApi::new() } +/// An open 3D-mouse interface: the device, how its reports are laid out, and its vendor and +/// product ids. +#[cfg(any(target_os = "windows", target_os = "macos", test))] +struct Candidate { + device: D, + layout: Layout, + ids: (u16, u16), +} + +/// Input reports read with a timeout in milliseconds: hidapi's devices, and the tests' simulated +/// ones. `Ok(0)` is a timeout; an error means the device is gone. +#[cfg(any(target_os = "windows", target_os = "macos", test))] +trait ReportSource { + fn read_report(&self, report: &mut [u8], timeout_ms: i32) -> Result; +} + +#[cfg(any(target_os = "windows", target_os = "macos"))] +impl ReportSource for hidapi::HidDevice { + fn read_report(&self, report: &mut [u8], timeout_ms: i32) -> Result { + self.read_timeout(report, timeout_ms).map_err(|error| error.to_string()) + } +} + +/// What following the candidates tells the reader. +#[cfg(any(target_os = "windows", target_os = "macos", test))] +enum Followed<'a> { + /// This device is the one read now, so its calibration applies. With the buttons it last + /// reported down, when it reported them while another was read: they are its baseline, so a + /// press that makes it the device in use counts as a press, not as a button already held. + Device((u16, u16), Option), + /// An input report from it. + Report(&'a Layout, &'a [u8]), + /// It is gone. + Gone, +} + +/// Whether a report shows its device in use: an axis off zero or a button down. A cap at rest +/// sends zeros at most, and an idle 3Dconnexion Universal Receiver sends nothing at all. +#[cfg(any(target_os = "windows", target_os = "macos", test))] +fn shows_use(layout: Layout, report: &[u8]) -> bool { + layout.decode(report).is_some_and(|decoded| decoded.axes.iter().flatten().any(|axis| *axis != 0) || decoded.buttons.is_some_and(|down| down != 0)) +} + +/// Reads every candidate and follows the one in use (#3988). The first is followed from the start, +/// as when it was the only one read. Another takes over once it shows use while the followed one +/// has shown none for `STALE_AFTER`, so two devices moved together don't hand the reading back +/// and forth. An idle Universal Receiver opens fine and never fails; read on its own it kept a +/// SpaceMouse next to it from ever being read. A candidate that fails is dropped. If it was the +/// followed one, the reading is reset and the next takes over. Returns when none is left. +#[cfg(any(target_os = "windows", target_os = "macos", test))] +fn follow(mut candidates: Vec>, now: impl Fn() -> Instant, mut emit: impl FnMut(Followed<'_>)) { + let Some(first) = candidates.first() else { return }; + emit(Followed::Device(first.ids, None)); + let mut followed = 0; + // When the followed device last showed use. + let mut used_at: Option = None; + // The buttons each candidate last reported down, by index, as long as it has reported them. + let mut buttons: Vec> = candidates.iter().map(|_| None).collect(); + let mut report = [0_u8; REPORT_BUFFER_BYTES]; + while !candidates.is_empty() { + // One device is waited on as before; several take turns, briefly, so none waits behind + // an idle one. Reports queue in the system meanwhile, so none is lost. + let timeout_ms = if candidates.len() == 1 { 100 } else { 10 }; + let mut index = 0; + while let Some(candidate) = candidates.get(index) { + match candidate.device.read_report(&mut report, timeout_ms) { + Ok(0) => {} + Ok(size) => { + let bytes = report.get(..size).unwrap_or_default(); + let before = buttons.get(index).copied().flatten(); + if let (Some(seen), Some(down)) = (buttons.get_mut(index), candidate.layout.decode(bytes).and_then(|decoded| decoded.buttons)) { + *seen = Some(down); + } + if shows_use(candidate.layout, bytes) { + let at = now(); + if index != followed && used_at.is_none_or(|used| at.duration_since(used) >= STALE_AFTER) { + let (vendor, product) = candidate.ids; + log::info!("3D mouse: reading {vendor:04x}:{product:04x}, the device in use"); + followed = index; + emit(Followed::Device(candidate.ids, before)); + } + if index == followed { + used_at = Some(at); + } + } + if index == followed { + emit(Followed::Report(&candidate.layout, bytes)); + } + } + Err(error) => { + log::info!("3D mouse disconnected: {error}"); + candidates.remove(index); + if index < buttons.len() { + buttons.remove(index); + } + if index == followed { + emit(Followed::Gone); + followed = 0; + used_at = None; + if let Some(next) = candidates.first() { + emit(Followed::Device(next.ids, buttons.first().copied().flatten())); + } + } else if index < followed { + followed -= 1; + } + continue; + } + } + index += 1; + } + } +} + #[cfg(any(target_os = "windows", target_os = "macos"))] fn reader(ctx: Context, shared: Arc>) { let Ok(mut api) = hid_api() else { @@ -528,36 +641,38 @@ fn reader(ctx: Context, shared: Arc>) { return; }; loop { - if let Some((device, layout, ids)) = candidates(&mut api).into_iter().find_map(|path| { - let device = api - .open_path(&path) - .inspect_err(|error| { - // On macOS: missing Input Monitoring permission, or the 3DxWare helper holding the device. - // The driver having the device is the reason it cannot be opened, not a problem. - if !DRIVER_CONNECTED.load(Ordering::Relaxed) && !DRIVER_REGISTERED.load(Ordering::Relaxed) { - log::warn!("3D mouse: cannot open the device: {error}"); - } - }) - .ok()?; - // Read when the device was opened, from this device alone. - let info = device.get_device_info().ok()?; - let layout = device_layout(&device, info.vendor_id())?; - Some((device, layout, (info.vendor_id(), info.product_id()))) - }) { - connected(&ctx, &shared, Source::Hid(Some(ids))); - let mut report = [0_u8; REPORT_BUFFER_BYTES]; - loop { - match device.read_timeout(&mut report, 100) { - Ok(0) => {} - Ok(size) => publish(&ctx, &shared, layout, report.get(..size).unwrap_or_default()), - Err(error) => { - log::info!("3D mouse disconnected: {error}"); - break; - } + let open: Vec<_> = candidates(&mut api) + .into_iter() + .filter_map(|path| { + let device = api + .open_path(&path) + .inspect_err(|error| { + // On macOS: missing Input Monitoring permission, or the 3DxWare helper holding the device. + // The driver having the device is the reason it cannot be opened, not a problem. + if !DRIVER_CONNECTED.load(Ordering::Relaxed) && !DRIVER_REGISTERED.load(Ordering::Relaxed) { + log::warn!("3D mouse: cannot open the device: {error}"); + } + }) + .ok()?; + // Read when the device was opened, from this device alone. + let info = device.get_device_info().ok()?; + let layout = device_layout(&device, info.vendor_id())?; + Some(Candidate { device, layout, ids: (info.vendor_id(), info.product_id()) }) + }) + .collect(); + follow(open, Instant::now, |event| match event { + Followed::Device(ids, buttons) => { + connected(&ctx, &shared, Source::Hid(Some(ids))); + // Taken over from another device: what it reported meanwhile is its baseline. + if let Some(buttons) = buttons + && let Ok(mut reading) = shared.lock() + { + reading.set_buttons(buttons); } } - reset(&ctx, &shared); - } + Followed::Report(layout, report) => publish(&ctx, &shared, *layout, report), + Followed::Gone => reset(&ctx, &shared), + }); std::thread::sleep(RETRY_AFTER); } } @@ -1294,6 +1409,174 @@ mod tests { assert!(shared.lock().unwrap().arrived, "but the report did arrive"); } + /// A simulated 3D-mouse interface. Each read takes the next scripted step, a report or a + /// timeout (empty), and sets the shared clock to the step's time. Once the script runs out, + /// the device is unplugged. + struct Simulated<'a> { + clock: &'a std::cell::Cell, + start: Instant, + steps: std::cell::RefCell)>>, + } + + impl ReportSource for Simulated<'_> { + fn read_report(&self, report: &mut [u8], _timeout_ms: i32) -> Result { + let (ms, bytes) = self.steps.borrow_mut().pop_front().ok_or_else(|| "unplugged".to_string())?; + self.clock.set(self.start + Duration::from_millis(ms)); + report.get_mut(..bytes.len()).ok_or_else(|| "report too long".to_string())?.copy_from_slice(&bytes); + Ok(bytes.len()) + } + } + + #[derive(Debug, PartialEq)] + enum Seen { + /// The product id now read. + Device(u16), + /// The buttons it had reported down before it was read, its baseline. + Baseline(u32), + /// A report published, the product id read when it was, and whether it showed use. + Report(u16, Vec, bool), + Gone, + } + + /// Follows simulated devices, given as (product id, scripted steps in ms), and returns what + /// the reader was told. + fn follow_simulated(devices: &[(u16, &[(u64, &[u8])])]) -> Vec { + follow_simulated_with(Layout::default(), devices) + } + + /// As `follow_simulated`, with every device's reports laid out as `layout`. + fn follow_simulated_with(layout: Layout, devices: &[(u16, &[(u64, &[u8])])]) -> Vec { + let start = Instant::now(); + let clock = std::cell::Cell::new(start); + let candidates = devices + .iter() + .map(|(product, steps)| Candidate { + device: Simulated { + clock: &clock, + start, + steps: std::cell::RefCell::new(steps.iter().map(|(ms, bytes)| (*ms, bytes.to_vec())).collect()), + }, + layout, + ids: (0x256f, *product), + }) + .collect(); + let (mut seen, mut read) = (Vec::new(), 0); + follow( + candidates, + || clock.get(), + |event| match event { + Followed::Device((_, product), buttons) => { + read = product; + seen.push(Seen::Device(product)); + seen.extend(buttons.map(Seen::Baseline)); + } + Followed::Report(layout, bytes) => seen.push(Seen::Report(read, bytes.to_vec(), shows_use(*layout, bytes))), + Followed::Gone => seen.push(Seen::Gone), + }, + ); + seen + } + + const RECEIVER: u16 = 0xc652; + const SPACEMOUSE: u16 = 0xc63a; + const PUSH_X: &[u8] = &[1, 100, 0, 0, 0, 0, 0]; + const AT_REST: &[u8] = &[1, 0, 0, 0, 0, 0, 0]; + const TILT: &[u8] = &[2, 0, 0, 50, 0, 0, 0]; + + /// #3988: a Universal Receiver with nothing paired is found first and never fails, and a wired + /// SpaceMouse next to it was never read. The receiver is followed only until the SpaceMouse + /// moves; the SpaceMouse's reports, its zeros included, are read from then on. + #[test] + fn an_idle_receiver_does_not_keep_a_spacemouse_from_being_read() { + let receiver: &[(u64, &[u8])] = &[(0, &[]), (10, &[]), (20, &[]), (30, &[])]; + let spacemouse: &[(u64, &[u8])] = &[(5, &[]), (15, PUSH_X), (25, AT_REST), (35, TILT)]; + assert_eq!( + follow_simulated(&[(RECEIVER, receiver), (SPACEMOUSE, spacemouse)]), + [ + Seen::Device(RECEIVER), + Seen::Device(SPACEMOUSE), + Seen::Report(SPACEMOUSE, PUSH_X.to_vec(), true), + Seen::Report(SPACEMOUSE, AT_REST.to_vec(), false), + Seen::Report(SPACEMOUSE, TILT.to_vec(), true), + // The receiver is unplugged first, then the SpaceMouse, the one being read. + Seen::Gone, + ] + ); + } + + /// Two devices in use at once don't trade the reading: the other takes over only after the + /// followed one has shown no use for `STALE_AFTER`. A report at rest or with an id the layout + /// doesn't know shows no use, and only the followed device's reports are published. + #[test] + fn another_device_takes_over_only_once_the_followed_one_is_still() { + let unknown_id: &[u8] = &[0x17, 80]; + let first: &[(u64, &[u8])] = &[(0, PUSH_X), (100, AT_REST), (200, &[])]; + let second: &[(u64, &[u8])] = &[(50, PUSH_X), (150, unknown_id), (250, TILT)]; + assert_eq!( + follow_simulated(&[(0xc635, first), (SPACEMOUSE, second)]), + [ + Seen::Device(0xc635), + Seen::Report(0xc635, PUSH_X.to_vec(), true), + // The second moves 50 ms after the first did: not yet. The first's own rest + // report is read, and the second's unknown report is not. + Seen::Report(0xc635, AT_REST.to_vec(), false), + // 250 ms after the first last moved, the second takes over. + Seen::Device(SPACEMOUSE), + Seen::Report(SPACEMOUSE, TILT.to_vec(), true), + Seen::Gone, + ] + ); + } + + /// One device is read as before: every report, until it fails. When the followed one of + /// several fails, the reading is reset and the next one is read. + #[test] + fn a_device_that_fails_hands_the_reading_to_the_next() { + let only: &[(u64, &[u8])] = &[(0, &[]), (1, AT_REST), (2, &[0x17, 80])]; + assert_eq!( + follow_simulated(&[(SPACEMOUSE, only)]), + [ + Seen::Device(SPACEMOUSE), + Seen::Report(SPACEMOUSE, AT_REST.to_vec(), false), + Seen::Report(SPACEMOUSE, vec![0x17, 80], false), + Seen::Gone + ] + ); + let unplugged: &[(u64, &[u8])] = &[]; + let next: &[(u64, &[u8])] = &[(1, PUSH_X)]; + assert_eq!( + follow_simulated(&[(SPACEMOUSE, unplugged), (RECEIVER, next)]), + [Seen::Device(SPACEMOUSE), Seen::Gone, Seen::Device(RECEIVER), Seen::Report(RECEIVER, PUSH_X.to_vec(), true), Seen::Gone] + ); + assert_eq!(follow_simulated(&[]), []); + } + + /// A button press that makes a device the one in use is a press. The buttons it reported while + /// another was read are its baseline; the reader keeps them, so the press isn't taken for a + /// button already held, as a device's first button report is. + #[test] + fn a_press_that_takes_over_counts_as_a_press() { + let mut layout = Layout::default(); + layout.buttons[0] = + Some(solidcraft_space_mouse::Field { report_id: 3, bit_offset: 0, bits: 1, logical_min: 0, logical_max: 1, relative: false }); + let (none_down, first_down): (&[u8], &[u8]) = (&[3, 0], &[3, 1]); + let receiver: &[(u64, &[u8])] = &[(0, &[]), (10, &[]), (20, &[])]; + let spacemouse: &[(u64, &[u8])] = &[(5, none_down), (15, first_down), (25, &[])]; + assert_eq!( + follow_simulated_with(layout, &[(RECEIVER, receiver), (SPACEMOUSE, spacemouse)]), + [Seen::Device(RECEIVER), Seen::Device(SPACEMOUSE), Seen::Baseline(0), Seen::Report(SPACEMOUSE, first_down.to_vec(), true), Seen::Gone,] + ); + // What the reader does with that: the press after the baseline is a tap. + let mut reading = Reading { buttons_known: false, ..Reading::new(Instant::now()) }; + reading.set_buttons(0); + assert!(decode_report(first_down, layout, &mut reading, Instant::now())); + assert_eq!((reading.buttons, reading.taps), (1, 1)); + // Without one, the same report is the baseline: held, not pressed. + let mut unseen = Reading { buttons_known: false, ..Reading::new(Instant::now()) }; + assert!(decode_report(first_down, layout, &mut unseen, Instant::now())); + assert_eq!((unseen.buttons, unseen.taps), (1, 0)); + } + #[test] fn a_held_reading_stays_until_the_next_one_and_a_hid_reading_goes_stale() { let now = Instant::now(); diff --git a/docs/3d-mouse.md b/docs/3d-mouse.md index 383da9294..9a7876585 100644 --- a/docs/3d-mouse.md +++ b/docs/3d-mouse.md @@ -33,6 +33,11 @@ vendor and product id. Reload with `sudo udevadm control --reload && sudo udevad replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works with native builds there for now. +On Windows and macOS, with more than one 3D mouse connected, SolidCraft reads the one in use. +For example, a 3Dconnexion Universal Receiver with nothing paired may sit next to a SpaceMouse +on a cable. The first device found is read until another one moves, and then that one is. The +Navigation page names the device being read, and its calibration applies. + SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.