3D mouse: read spacenavd on Linux so the spnavcfg settings apply (#1000)

SolidCraft read the HID device directly, which bypasses spacenavd and
everything set in spnavcfg (swapped and inverted axes, sensitivity, dead
zones). When the daemon's socket is there it is read instead, with a fixed
32-byte record decoder and no library; without it the hidraw path is
unchanged. The daemon sends a record only when values change, so its
readings are held until the next one rather than going stale.

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

README.md

@@ -221,8 +221,12 @@ With 3DxWare on Windows, SolidCraft follows 3DxWare's profile for it when there
 3DxWare's object mode (tilt to roll, twist to spin) until there is. The mouse-wheel turns that
 3DxWare makes from the cap's motion are ignored, so the view doesn't zoom in steps as the cap tilts.
 
-On Linux SolidCraft reads `/dev/hidrawN` directly, so the logged-in user needs access to the
-device. A udev rule that adds the `uaccess` tag does that, for example
+On Linux SolidCraft reads the 3D mouse through `spacenavd` when that daemon runs (its socket
+`/var/run/spnav.sock`), so what you set in `spnavcfg` (swapped or inverted axes, sensitivity, dead
+zones) applies as it does in other programs, and no udev rule is needed. With nothing set there,
+the motion is the same as without the daemon. Without `spacenavd`, SolidCraft reads `/dev/hidrawN`
+directly, so the logged-in user needs access to the device. A udev rule that adds the `uaccess`
+tag does that, for example
 `/etc/udev/rules.d/70-3d-mouse.rules` for devices with 3Dconnexion's vendor id:
 
 ```

apps/solidcraft/src/space_mouse.rs

@@ -1,10 +1,12 @@
-//! 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.
+//! 3Dconnexion HID navigation on Windows (through hidapi) and Linux (through spacenavd when it
+//! runs, else 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;
+#[cfg(target_os = "linux")]
+mod spacenavd;
 
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
@@ -156,14 +158,21 @@ struct Reading {
     axes: Axes,
     translation_at: Instant,
     rotation_at: Instant,
+    /// The source says when the cap is back at rest, so a reading stays until the next one.
+    /// A HID device repeats its report while the cap is held; spacenavd sends a record only when
+    /// the values change, and a steady hold can go seconds without one.
+    held: bool,
 }
 
 impl Reading {
     fn new(now: Instant) -> Self {
-        Self { axes: Axes::default(), translation_at: now, rotation_at: now }
+        Self { axes: Axes::default(), translation_at: now, rotation_at: now, held: false }
     }
 
     fn current(self, now: Instant) -> Axes {
+        if self.held {
+            return self.axes;
+        }
         Axes {
             translation: if now.duration_since(self.translation_at) < STALE_AFTER { self.axes.translation } else { [0; 3] },
             rotation: if now.duration_since(self.rotation_at) < STALE_AFTER { self.axes.rotation } else { [0; 3] },
@@ -226,6 +235,15 @@ fn publish(ctx: &Context, shared: &Mutex<Reading>, layout: Layout, report: &[u8]
     }
 }
 
+/// Publishes the cap's position from spacenavd.
+#[cfg(target_os = "linux")]
+fn publish_held(ctx: &Context, shared: &Mutex<Reading>, axes: Axes) {
+    if let Ok(mut reading) = shared.lock() {
+        *reading = Reading { axes, held: true, ..Reading::new(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() {
@@ -276,15 +294,21 @@ fn device_layout(device: &hidapi::HidDevice) -> Layout {
     }
 }
 
-/// 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.
+/// Reads the 3D mouse through spacenavd when it runs, so what `spnavcfg` sets (swapped and inverted
+/// axes, sensitivity, dead zones) applies here as in other programs. Without the daemon it 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() {
+        if let Some(daemon) = spacenavd::connect() {
+            log::info!("3D mouse: reading spacenavd, which applies the spnavcfg settings");
+            spacenavd::read(daemon, |axes| publish_held(&ctx, &shared, axes));
+            reset(&ctx, &shared);
+        } else if let Some(device) = hidraw::find() {
             match std::fs::File::open(&device.path) {
                 Ok(mut file) => {
                     denied = None;
@@ -410,6 +434,19 @@ mod tests {
         assert_eq!(reading.current(later), Axes { translation: [1, 2, 3], rotation: [4, 5, 6] });
     }
 
+    #[test]
+    fn a_held_reading_stays_until_the_next_one_and_a_hid_reading_goes_stale() {
+        let now = Instant::now();
+        let axes = Axes { translation: [0, 200, 0], rotation: [0; 3] };
+        let later = now + STALE_AFTER * 20;
+        // spacenavd sends nothing while the values stay the same: the push lasts.
+        let held = Reading { axes, held: true, ..Reading::new(now) };
+        assert_eq!(held.current(later), axes);
+        // A HID device repeats its report: silence means the cap, or the device, is gone.
+        let hid = Reading { axes, ..Reading::new(now) };
+        assert_eq!(hid.current(later), Axes::default());
+    }
+
     #[test]
     fn combined_report_one_carries_translation_and_rotation_together() {
         let now = Instant::now();

apps/solidcraft/src/space_mouse/spacenavd.rs

@@ -0,0 +1,144 @@
+//! Reading a 3D mouse through `spacenavd` on Linux. The daemon owns the device and applies what
+//! `spnavcfg` sets (swapped and inverted axes, sensitivity, dead zones) before it hands the motion
+//! to its clients, so a program that reads the HID device itself bypasses that setup. Over its
+//! socket the daemon sends fixed 32-byte records: eight native-endian `i32`, the first the kind of
+//! record (0 for motion, then x y z rx ry rz and the milliseconds since the last record).
+//! Other records (button presses, from newer daemons also configuration changes) are ignored.
+//!
+//! The socket is plain file I/O, so no library is needed, and it needs no udev rule: the daemon
+//! is what has access to the device.
+
+use std::io::Read;
+use std::os::unix::net::UnixStream;
+use std::path::Path;
+
+use solidcraft_ui_egui::space_mouse::{Axes, FULL_SCALE};
+
+/// Where the daemon listens. `/var/run` is a link to `/run` on current systems.
+const SOCKETS: [&str; 2] = ["/var/run/spnav.sock", "/run/spnav.sock"];
+
+const RECORD_BYTES: usize = 32;
+
+/// What the daemon reports at full deflection (seen with a SpaceMouse Compact and a default
+/// sensitivity). Our axes are in the raw HID units of [`FULL_SCALE`].
+const DAEMON_FULL_SCALE: i64 = 500;
+
+pub fn connect() -> Option<UnixStream> {
+    SOCKETS.iter().find_map(|path| connect_to(Path::new(path)))
+}
+
+fn connect_to(path: &Path) -> Option<UnixStream> {
+    UnixStream::connect(path).ok()
+}
+
+/// The axes of one record, or `None` for a record that is not motion.
+///
+/// The daemon's frame is right-handed with x to the right, y away from the user and z up; ours is
+/// the device's raw one, x right, y towards the user and z down, so y and z (and the rotations
+/// about them) change sign. With nothing set in `spnavcfg` the two give the same motion; what
+/// the user swaps or inverts there then carries over.
+fn decode(record: &[u8; RECORD_BYTES]) -> Option<Axes> {
+    let mut data = [0_i32; 8];
+    for (slot, bytes) in data.iter_mut().zip(record.as_chunks::<4>().0) {
+        *slot = i32::from_ne_bytes(*bytes);
+    }
+    let [kind, x, y, z, rx, ry, rz, _period] = data;
+    (kind == 0).then(|| Axes {
+        translation: [unit(x), unit(-i64::from(y)), unit(-i64::from(z))],
+        rotation: [unit(rx), unit(-i64::from(ry)), unit(-i64::from(rz))],
+    })
+}
+
+/// A daemon value in our raw units. Out-of-range values stay in `i16`: they are input from another
+/// process.
+fn unit(value: impl Into<i64>) -> i16 {
+    let scaled = value.into() * i64::from(FULL_SCALE) / DAEMON_FULL_SCALE;
+    i16::try_from(scaled.clamp(i64::from(i16::MIN), i64::from(i16::MAX))).unwrap_or_default()
+}
+
+/// Hands every motion record to `publish` until the daemon closes the connection or fails. A
+/// partial record at the end is dropped.
+pub fn read(mut stream: impl Read, mut publish: impl FnMut(Axes)) {
+    let mut record = [0_u8; RECORD_BYTES];
+    loop {
+        match stream.read_exact(&mut record) {
+            Ok(()) => {
+                if let Some(axes) = decode(&record) {
+                    publish(axes);
+                }
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => {}
+            Err(error) => {
+                log::info!("3D mouse: spacenavd connection ended: {error}");
+                return;
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+
+    fn record(data: [i32; 8]) -> [u8; RECORD_BYTES] {
+        let mut bytes = [0_u8; RECORD_BYTES];
+        for (chunk, value) in bytes.as_chunks_mut::<4>().0.iter_mut().zip(data) {
+            *chunk = value.to_ne_bytes();
+        }
+        bytes
+    }
+
+    #[test]
+    fn motion_records_become_axes_in_the_devices_raw_frame() {
+        // Full deflection of the daemon's x, y and z is the device's full scale, and y and z flip.
+        assert_eq!(decode(&record([0, 500, 500, 500, 0, 0, 0, 8])), Some(Axes { translation: [350, -350, -350], rotation: [0; 3] }));
+        // Rotations follow translations: right-handed in both frames, so ry and rz flip as y and z do.
+        assert_eq!(decode(&record([0, 0, 0, 0, 250, 250, 250, 8])), Some(Axes { translation: [0; 3], rotation: [175, -175, -175] }));
+        // Rest is a motion record of zeros.
+        assert_eq!(decode(&record([0, 0, 0, 0, 0, 0, 0, 1200])), Some(Axes::default()));
+    }
+
+    #[test]
+    fn what_spnavcfg_swaps_reaches_the_view() {
+        // The daemon sends a push away as y. With Y and Z swapped in spnavcfg it sends the same push
+        // as z, and the view gets a lift (raw z) instead of the zoom (raw y).
+        let before = decode(&record([0, 0, 500, 0, 0, 0, 0, 8])).map(|axes| axes.translation);
+        let after = decode(&record([0, 0, 0, 500, 0, 0, 0, 8])).map(|axes| axes.translation);
+        assert_eq!(before, Some([0, -350, 0]));
+        assert_eq!(after, Some([0, 0, -350]));
+    }
+
+    #[test]
+    fn other_records_and_hostile_values_are_harmless() {
+        // A button record (kind 1, press) and one of an unknown kind are not motion.
+        assert_eq!(decode(&record([1, 0, 1, 0, 0, 0, 0, 0])), None);
+        assert_eq!(decode(&record([7, 500, 500, 500, 500, 500, 500, 0])), None);
+        // Nothing overflows on the extremes of `i32`.
+        let extreme = decode(&record([0, i32::MIN, i32::MIN, i32::MAX, i32::MAX, i32::MIN, i32::MIN, -1]));
+        assert_eq!(extreme.map(|axes| axes.translation[0]), Some(i16::MIN));
+        assert_eq!(extreme.map(|axes| axes.translation[1]), Some(i16::MAX));
+        assert_eq!(extreme.map(|axes| axes.rotation[0]), Some(i16::MAX));
+    }
+
+    #[test]
+    fn a_stream_is_read_record_by_record_until_it_ends() {
+        let (mut daemon, client) = UnixStream::pair().expect("a socket pair");
+        let mut bytes = Vec::new();
+        bytes.extend(record([0, 100, 0, 0, 0, 0, 0, 8]));
+        bytes.extend(record([2, 1, 0, 0, 0, 0, 0, 0])); // a button release: skipped
+        bytes.extend(record([0, 0, 0, 0, 0, 0, 0, 900]));
+        bytes.extend([1, 2, 3]); // the daemon went away mid-record
+        daemon.write_all(&bytes).expect("written");
+        drop(daemon);
+        let mut seen = Vec::new();
+        read(client, |axes| seen.push(axes.translation));
+        assert_eq!(seen, [[70, 0, 0], [0, 0, 0]]);
+    }
+
+    #[test]
+    fn no_daemon_means_no_connection() {
+        let missing = std::env::temp_dir().join(format!("sc-no-spnav-{}.sock", std::process::id()));
+        assert!(connect_to(&missing).is_none());
+    }
+}