Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

3D mouse: follow the device that moves, not the first one found (#3988) (#4339)

Tyler Chiriboga2ff17c0fcbcb
diff --git a/apps/solidcraft/src/space_mouse.rs b/apps/solidcraft/src/space_mouse.rs
index a4c3f9d454..2951dca048 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> {
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<D> {
+ 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<usize, String>;
+}
+
+#[cfg(any(target_os = "windows", target_os = "macos"))]
+impl ReportSource for hidapi::HidDevice {
+ fn read_report(&self, report: &mut [u8], timeout_ms: i32) -> Result<usize, String> {
+ 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<u32>),
+ /// 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<D: ReportSource>(mut candidates: Vec<Candidate<D>>, 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<Instant> = None;
+ // The buttons each candidate last reported down, by index, as long as it has reported them.
+ let mut buttons: Vec<Option<u32>> = 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<Mutex<Reading>>) {
let Ok(mut api) = hid_api() else {
@@ -528,36 +641,38 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
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<Instant>,
+ start: Instant,
+ steps: std::cell::RefCell<std::collections::VecDeque<(u64, Vec<u8>)>>,
+ }
+
+ impl ReportSource for Simulated<'_> {
+ fn read_report(&self, report: &mut [u8], _timeout_ms: i32) -> Result<usize, String> {
+ 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<u8>, 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<Seen> {
+ 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<Seen> {
+ 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 383da9294d..9a78765858 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.