Support 3D mice on Linux and devices that send all six axes in report 1 (#343)

The space_mouse module was Windows-only (hidapi). On Linux it now finds the
multi-axis HID interface through /sys/class/hidraw and reads /dev/hidrawN with
plain std I/O, so there is no new dependency and no libudev needed.

A small report descriptor parser tells devices apart: a top-level Multi-Axis
Controller collection marks the 3D mouse, and report 1 declaring all six axes
selects the combined layout (X Y Z Rx Ry Rz in one report) that some homemade
devices use. Real split devices (report 1 translation, report 2 rotation) keep
their existing decoding. Windows reads the descriptor through hidapi and falls
back to the split layout if it is unavailable.

Co-authored-by: jochenhammes <[email protected]>
Co-authored-by: Claude Sonnet 5.5 <[email protected]>

apps/solvecraft/src/space_mouse.rs

@@ -1,10 +1,17 @@
-//! Windows 3Dconnexion HID navigation. The device reader never touches the document or UI;
-//! it publishes the latest axes, and the egui thread applies them once per frame.
+//! 3Dconnexion HID navigation on Windows (through hidapi) and Linux (through hidraw). The device
+//! reader never touches the document or UI; it publishes the latest axes, and the egui thread
+//! applies them once per frame.
+
+mod hid_descriptor;
+#[cfg(target_os = "linux")]
+mod hidraw;
 
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 
 use egui::Context;
+use hid_descriptor::Layout;
+#[cfg(target_os = "windows")]
 use hidapi::{DeviceInfo, HidApi};
 use quick_xml::Reader;
 use quick_xml::events::Event;
@@ -208,9 +215,14 @@ impl Reading {
 }
 
 /// The old SpaceNavigator uses Logitech's VID; newer 3Dconnexion devices use their own.
+fn is_3d_mouse_vendor(vendor_id: u16) -> bool {
+    matches!(vendor_id, 0x046d | 0x256f)
+}
+
 /// The HID usage excludes ordinary Logitech mice and the keyboard interfaces of SpaceMice.
+#[cfg(target_os = "windows")]
 fn is_3d_mouse(info: &DeviceInfo) -> bool {
-    matches!(info.vendor_id(), 0x046d | 0x256f) && info.usage_page() == 0x01 && info.usage() == 0x08
+    is_3d_mouse_vendor(info.vendor_id()) && info.usage_page() == 0x01 && info.usage() == 0x08
 }
 
 fn three_axes(bytes: &[u8]) -> Option<[i16; 3]> {
@@ -220,8 +232,18 @@ fn three_axes(bytes: &[u8]) -> Option<[i16; 3]> {
 
 /// SpaceNavigator reports 1 (translation) and 2 (rotation), each with three signed
 /// little-endian 16-bit values. The HID layer may pad either report to its maximum size.
-fn decode_report(report: &[u8], reading: &mut Reading, now: Instant) -> bool {
+/// Some homemade devices send all six values in report 1 instead (`Layout::Combined`): only the
+/// device's report descriptor can tell the two apart, because a padded split report 1 is as long.
+fn decode_report(report: &[u8], layout: Layout, reading: &mut Reading, now: Instant) -> bool {
     match report.first().copied() {
+        Some(1) if layout == Layout::Combined => {
+            let Some(body) = report.get(1..) else { return false };
+            let (Some(translation), Some(rotation)) = (body.get(..6).and_then(three_axes), body.get(6..).and_then(three_axes)) else { return false };
+            reading.axes = Axes { translation, rotation };
+            reading.translation_at = now;
+            reading.rotation_at = now;
+            true
+        }
         Some(1) => {
             let Some(translation) = report.get(1..).and_then(three_axes) else { return false };
             reading.axes.translation = translation;
@@ -238,6 +260,24 @@ fn decode_report(report: &[u8], reading: &mut Reading, now: Instant) -> bool {
     }
 }
 
+/// Publishes one input report from the device to the egui thread.
+fn publish(ctx: &Context, shared: &Mutex<Reading>, layout: Layout, report: &[u8]) {
+    if let Ok(mut reading) = shared.lock()
+        && decode_report(report, layout, &mut reading, Instant::now())
+    {
+        ctx.request_repaint();
+    }
+}
+
+/// The device is gone: stop reporting its last position.
+fn reset(ctx: &Context, shared: &Mutex<Reading>) {
+    if let Ok(mut reading) = shared.lock() {
+        *reading = Reading::new(Instant::now());
+    }
+    ctx.request_repaint();
+}
+
+#[cfg(target_os = "windows")]
 fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
     let Ok(mut api) = HidApi::new() else {
         log::warn!("3D mouse: HID initialization failed");
@@ -247,27 +287,72 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
         if let Err(error) = api.refresh_devices() {
             log::warn!("3D mouse: device scan failed: {error}");
         } else if let Some(device) = api.device_list().find(|info| is_3d_mouse(info)).and_then(|info| info.open_device(&api).ok()) {
+            let layout = device_layout(&device);
             let mut report = [0_u8; 64];
             loop {
                 match device.read_timeout(&mut report, 100) {
                     Ok(0) => {}
-                    Ok(size) => {
-                        if let Ok(mut reading) = shared.lock()
-                            && decode_report(&report[..size], &mut reading, Instant::now())
-                        {
-                            ctx.request_repaint();
-                        }
-                    }
+                    Ok(size) => publish(&ctx, &shared, layout, report.get(..size).unwrap_or_default()),
                     Err(error) => {
                         log::info!("3D mouse disconnected: {error}");
                         break;
                     }
                 }
             }
-            if let Ok(mut reading) = shared.lock() {
-                *reading = Reading::new(Instant::now());
+            reset(&ctx, &shared);
+        }
+        std::thread::sleep(RETRY_AFTER);
+    }
+}
+
+/// How the device packs its axes, from its report descriptor; the usual split layout if the
+/// descriptor cannot be read.
+#[cfg(target_os = "windows")]
+fn device_layout(device: &hidapi::HidDevice) -> Layout {
+    let mut descriptor = [0_u8; hidapi::MAX_REPORT_DESCRIPTOR_SIZE];
+    match device.get_report_descriptor(&mut descriptor) {
+        Ok(size) => hid_descriptor::Descriptor::parse(descriptor.get(..size).unwrap_or_default()).layout(),
+        Err(error) => {
+            log::info!("3D mouse: no report descriptor, assuming separate translation and rotation reports: {error}");
+            Layout::Split
+        }
+    }
+}
+
+/// Reads `/dev/hidrawN` with plain blocking reads, which end with an error when the device is
+/// unplugged. Opening needs permission: most distributions grant it to the logged-in user for
+/// devices that carry the `uaccess` udev tag, which a rule for the 3D mouse has to add.
+#[cfg(target_os = "linux")]
+fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
+    use std::io::Read;
+    let mut denied = None;
+    loop {
+        if let Some(device) = hidraw::find() {
+            match std::fs::File::open(&device.path) {
+                Ok(mut file) => {
+                    denied = None;
+                    log::info!("3D mouse: reading {} ({:?} reports)", device.path.display(), device.layout);
+                    let mut report = [0_u8; 64];
+                    loop {
+                        match file.read(&mut report) {
+                            Ok(0) => break,
+                            Ok(size) => publish(&ctx, &shared, device.layout, report.get(..size).unwrap_or_default()),
+                            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
+                            Err(error) => {
+                                log::info!("3D mouse disconnected: {error}");
+                                break;
+                            }
+                        }
+                    }
+                    reset(&ctx, &shared);
+                }
+                // Say so once per device node, not every retry.
+                Err(error) if denied.as_ref() != Some(&device.path) => {
+                    log::warn!("3D mouse: cannot open {}: {error}. A udev rule granting the logged-in user access is needed.", device.path.display());
+                    denied = Some(device.path);
+                }
+                Err(_) => {}
             }
-            ctx.request_repaint();
         }
         std::thread::sleep(RETRY_AFTER);
     }
@@ -371,19 +456,46 @@ mod tests {
     fn decodes_separate_reports_without_stale_motion_or_padding_interference() {
         let now = Instant::now();
         let mut reading = Reading::new(now);
-        assert!(!decode_report(&[1, 1, 2], &mut reading, now));
+        assert!(!decode_report(&[1, 1, 2], Layout::Split, &mut reading, now));
         assert_eq!(reading.current(now), Axes::default());
-        assert!(decode_report(&[1, 0x9c, 0xff, 0x2c, 0x01, 0, 0], &mut reading, now));
+        assert!(decode_report(&[1, 0x9c, 0xff, 0x2c, 0x01, 0, 0], Layout::Split, &mut reading, now));
         assert_eq!(reading.current(now).translation, [-100, 300, 0]);
-        assert!(decode_report(&[2, 0, 0, 1, 0, 0xff, 0xff], &mut reading, now));
+        assert!(decode_report(&[2, 0, 0, 1, 0, 0xff, 0xff], Layout::Split, &mut reading, now));
         assert_eq!(reading.current(now).rotation, [0, 1, -1]);
         let later = now + STALE_AFTER + Duration::from_millis(1);
         assert_eq!(reading.current(later), Axes::default());
-        assert!(decode_report(&[2, 4, 0, 5, 0, 6, 0], &mut reading, later));
-        assert!(decode_report(&[1, 1, 0, 2, 0, 3, 0, 0, 0, 0, 0, 0, 0], &mut reading, later));
+        assert!(decode_report(&[2, 4, 0, 5, 0, 6, 0], Layout::Split, &mut reading, later));
+        assert!(decode_report(&[1, 1, 0, 2, 0, 3, 0, 0, 0, 0, 0, 0, 0], Layout::Split, &mut reading, later));
         assert_eq!(reading.current(later), Axes { translation: [1, 2, 3], rotation: [4, 5, 6] });
     }
 
+    #[test]
+    fn combined_report_one_carries_translation_and_rotation_together() {
+        let now = Instant::now();
+        let mut reading = Reading::new(now);
+        // Report id 1, then X Y Z Rx Ry Rz as signed little-endian 16-bit values.
+        let report = [1, 0x9c, 0xff, 0x2c, 0x01, 0, 0, 1, 0, 0, 0, 0xff, 0xff];
+        assert!(decode_report(&report, Layout::Combined, &mut reading, now));
+        assert_eq!(reading.current(now), Axes { translation: [-100, 300, 0], rotation: [1, 0, -1] });
+        // The same bytes on a split device are only the translation report; its padding is not rotation.
+        let mut split = Reading::new(now);
+        assert!(decode_report(&report, Layout::Split, &mut split, now));
+        assert_eq!(split.current(now), Axes { translation: [-100, 300, 0], rotation: [0; 3] });
+    }
+
+    #[test]
+    fn combined_layout_ignores_short_and_other_reports() {
+        let now = Instant::now();
+        let mut reading = Reading::new(now);
+        assert!(!decode_report(&[1, 1, 0, 2, 0, 3, 0], Layout::Combined, &mut reading, now));
+        assert!(!decode_report(&[3, 1, 0, 0, 0, 0], Layout::Combined, &mut reading, now));
+        assert!(!decode_report(&[], Layout::Combined, &mut reading, now));
+        assert_eq!(reading.current(now), Axes::default());
+        // Extra padding after the six values is fine.
+        assert!(decode_report(&[1, 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0, 0, 0], Layout::Combined, &mut reading, now));
+        assert_eq!(reading.current(now), Axes { translation: [1, 2, 3], rotation: [4, 5, 6] });
+    }
+
     #[test]
     fn six_axes_move_the_camera_and_sketches_keep_their_orientation() {
         let mut cam = Camera::default();