Skip to content

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

3D mouse: find devices on Windows without asking every HID device for its strings (#2614) (#3653)

Tyler Chiriboga6f5d0038abff
diff --git a/AGENTS.md b/AGENTS.md
index 5551a0e9e7..0720afeeff 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,9 +33,11 @@ People trust SolidCraft with their designs; a crash loses their work. **This out
and calls through its function pointers), two functions in
`apps/solidcraft/src/open_documents.rs` (macOS hands Finder files only to an Objective-C
method), the Windows-only `apps/solidcraft/src/native_crash.rs` (the exception filter that
- records crashes inside native code such as graphics drivers) and the Windows-only
+ records crashes inside native code such as graphics drivers), the Windows-only
`apps/solidcraft/src/native_frame.rs` (the window procedure that answers the resize-border hit
- test of the window without OS decorations).
+ test of the window without OS decorations) and the Windows-only
+ `apps/solidcraft/src/space_mouse/windows_hid.rs` (asks Plug and Play which HID interfaces are 3D
+ mice, so no other device is sent anything).
- **Errors are `Result<T, E>`** through the crate's error type and `?`. An unfinished feature
returns an error ("not supported yet: …"); it never panics.
- **Input-derived numbers are hostile** (command parameters, design files, control-channel
diff --git a/apps/solidcraft/Cargo.toml b/apps/solidcraft/Cargo.toml
index 0fcde99f5c..5078470dd5 100644
--- a/apps/solidcraft/Cargo.toml
+++ b/apps/solidcraft/Cargo.toml
@@ -50,7 +50,11 @@ hidapi = { version = "2.6.7", default-features = false, features = ["windows-nat
raw-window-handle = "0.6"
# Native crash capture (src/native_crash.rs): the exception filter, the faulting module, a minidump.
# The window's resize border and DPI size (src/native_frame.rs): the window procedure, hit test, DPI.
+# Finding 3D mice through Plug and Play without asking other devices anything (src/space_mouse/windows_hid.rs).
windows-sys = { version = "0.61", features = [
+ "Win32_Devices_DeviceAndDriverInstallation",
+ "Win32_Devices_HumanInterfaceDevice",
+ "Win32_Devices_Properties",
"Win32_Foundation",
"Win32_Graphics_Gdi",
"Win32_Security",
diff --git a/apps/solidcraft/src/space_mouse.rs b/apps/solidcraft/src/space_mouse.rs
index 245107f2bb..8a9c31818a 100644
--- a/apps/solidcraft/src/space_mouse.rs
+++ b/apps/solidcraft/src/space_mouse.rs
@@ -7,7 +7,11 @@
mod hidraw;
#[cfg(target_os = "linux")]
mod spacenavd;
+#[cfg(target_os = "windows")]
+mod windows_hid;
+#[cfg(any(target_os = "windows", target_os = "macos"))]
+use std::ffi::CString;
#[cfg(target_os = "linux")]
use std::sync::atomic::AtomicU8;
use std::sync::atomic::{AtomicBool, Ordering};
@@ -15,8 +19,10 @@ use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use egui::Context;
+#[cfg(target_os = "macos")]
+use hidapi::DeviceInfo;
#[cfg(any(target_os = "windows", target_os = "macos"))]
-use hidapi::{DeviceInfo, HidApi};
+use hidapi::HidApi;
use quick_xml::Reader;
use quick_xml::events::Event;
use solidcraft_space_mouse::Layout;
@@ -256,8 +262,9 @@ fn at_rest(calibration: Option<Calibration>) -> Axes {
}
/// The Generic Desktop "Multi-Axis Controller" usage names a 3D mouse's motion interface, whoever
-/// made it, and excludes ordinary mice and the keyboard interfaces of 3D mice.
-#[cfg(any(target_os = "windows", target_os = "macos"))]
+/// made it, and excludes ordinary mice and the keyboard interfaces of 3D mice. (Windows asks Plug
+/// and Play for the same usage: `windows_hid`.)
+#[cfg(target_os = "macos")]
fn is_3d_mouse(info: &DeviceInfo) -> bool {
info.usage_page() == 0x01 && info.usage() == 0x08
}
@@ -317,18 +324,48 @@ fn reset(ctx: &Context, shared: &Mutex<Reading>) {
ctx.request_repaint();
}
+/// The HID interfaces that are 3D mice, by path. Windows asks Plug and Play, which sends nothing to
+/// the devices: hidapi's enumeration would ask every keyboard and mouse for its strings on each scan
+/// (#2614, `windows_hid`).
+#[cfg(target_os = "windows")]
+fn candidates(_api: &mut HidApi) -> Vec<CString> {
+ windows_hid::multi_axis_controllers()
+}
+
+/// The HID interfaces that are 3D mice, by path, from hidapi's enumeration (IOKit's registry).
+#[cfg(target_os = "macos")]
+fn candidates(api: &mut HidApi) -> Vec<CString> {
+ if let Err(error) = api.refresh_devices() {
+ log::warn!("3D mouse: device scan failed: {error}");
+ return Vec::new();
+ }
+ api.device_list().filter(|info| is_3d_mouse(info)).map(|info| info.path().to_owned()).collect()
+}
+
+/// The HID context. On Windows hidapi's own device discovery is off, so making it asks no device
+/// anything either (`candidates` finds the 3D mice). Turning discovery off panics only once a
+/// context with discovery exists; the reader is the one place the app makes a context, once.
+#[cfg(target_os = "windows")]
+fn hid_api() -> hidapi::HidResult<HidApi> {
+ HidApi::disable_device_discovery();
+ HidApi::new()
+}
+
+#[cfg(target_os = "macos")]
+fn hid_api() -> hidapi::HidResult<HidApi> {
+ HidApi::new()
+}
+
#[cfg(any(target_os = "windows", target_os = "macos"))]
fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
- let Ok(mut api) = HidApi::new() else {
+ let Ok(mut api) = hid_api() else {
log::warn!("3D mouse: HID initialization failed");
return;
};
loop {
- if let Err(error) = api.refresh_devices() {
- log::warn!("3D mouse: device scan failed: {error}");
- } else if let Some((device, layout, ids)) = api.device_list().filter(|info| is_3d_mouse(info)).find_map(|info| {
- let device = info
- .open_device(&api)
+ 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.
@@ -337,6 +374,8 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
}
})
.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())))
}) {
diff --git a/apps/solidcraft/src/space_mouse/windows_hid.rs b/apps/solidcraft/src/space_mouse/windows_hid.rs
new file mode 100644
index 0000000000..473798ed60
--- /dev/null
+++ b/apps/solidcraft/src/space_mouse/windows_hid.rs
@@ -0,0 +1,172 @@
+//! Windows: finding 3D mice without asking any other device anything (#2614).
+//!
+//! hidapi's enumeration opens every HID interface and reads its serial number, manufacturer and
+//! product strings: on USB, three control requests to every keyboard, mouse and touchscreen. The
+//! reader repeated it every two seconds while no 3D mouse was plugged in, and on some machines the
+//! keyboard then kept dropping off the bus and the cursor jumped. Plug and Play already names each
+//! interface's top-level usage in its hardware IDs (`HID_DEVICE_UP:0001_U:0008`: Generic Desktop,
+//! Multi-Axis Controller), so the reader asks it, which sends nothing to any device, and opens only
+//! the interfaces that are 3D mice.
+//!
+//! The configuration manager has no safe API, hence the `unsafe_code` allowance on this module
+//! (the app crate denies it; see `native_crash.rs`).
+#![allow(unsafe_code)]
+
+use std::ffi::CString;
+use std::ptr::{null, null_mut};
+
+use windows_sys::Win32::Devices::DeviceAndDriverInstallation::{
+ CM_GET_DEVICE_INTERFACE_LIST_PRESENT, CM_Get_DevNode_PropertyW, CM_Get_Device_Interface_List_SizeW, CM_Get_Device_Interface_ListW,
+ CM_Get_Device_Interface_PropertyW, CM_LOCATE_DEVNODE_NORMAL, CM_Locate_DevNodeW, CONFIGRET, CR_BUFFER_SMALL, CR_SUCCESS,
+};
+use windows_sys::Win32::Devices::HumanInterfaceDevice::GUID_DEVINTERFACE_HID;
+use windows_sys::Win32::Devices::Properties::{
+ DEVPKEY_Device_HardwareIds, DEVPKEY_Device_InstanceId, DEVPROP_TYPE_STRING, DEVPROP_TYPE_STRING_LIST, DEVPROPTYPE,
+};
+use windows_sys::Win32::Foundation::DEVPROPKEY;
+
+/// The hardware ID Windows gives a top-level collection with the Generic Desktop page's
+/// Multi-Axis Controller usage.
+const MULTI_AXIS_CONTROLLER: &str = "HID_DEVICE_UP:0001_U:0008";
+/// Largest property read, in bytes: hardware IDs are a few hundred.
+const MAX_PROPERTY_BYTES: u32 = 64 * 1024;
+/// Tries at reading the interface list, which can grow between asking its size and reading it.
+const LIST_TRIES: usize = 4;
+
+/// The paths of the present HID interfaces whose top-level collection is a multi-axis controller.
+pub fn multi_axis_controllers() -> Vec<CString> {
+ interfaces()
+ .into_iter()
+ .filter(|path| {
+ let Some(instance) = interface_strings(path, &DEVPKEY_Device_InstanceId).and_then(|ids| ids.into_iter().next()) else {
+ return false;
+ };
+ devnode_strings(&instance, &DEVPKEY_Device_HardwareIds).is_some_and(|ids| is_multi_axis(&ids))
+ })
+ .filter_map(|path| CString::new(path).ok())
+ .collect()
+}
+
+/// Whether a device with these hardware IDs is a multi-axis controller.
+fn is_multi_axis(hardware_ids: &[String]) -> bool {
+ hardware_ids.iter().any(|id| id.eq_ignore_ascii_case(MULTI_AXIS_CONTROLLER))
+}
+
+/// The strings of a nul-separated list (`REG_MULTI_SZ`, or one string), without empty ones.
+fn split_multi_sz(buffer: &[u16]) -> Vec<String> {
+ buffer.split(|c| *c == 0).filter(|s| !s.is_empty()).map(String::from_utf16_lossy).collect()
+}
+
+/// `s` as a nul-terminated wide string.
+fn wide(s: &str) -> Vec<u16> {
+ s.encode_utf16().chain(std::iter::once(0)).collect()
+}
+
+/// The paths of the present HID interfaces.
+fn interfaces() -> Vec<String> {
+ for _ in 0..LIST_TRIES {
+ let mut len = 0u32;
+ // SAFETY: `len` is a valid place for the size; the class GUID is a static; no device filter.
+ let sized = unsafe { CM_Get_Device_Interface_List_SizeW(&mut len, &GUID_DEVINTERFACE_HID, null(), CM_GET_DEVICE_INTERFACE_LIST_PRESENT) };
+ if sized != CR_SUCCESS || len == 0 {
+ return Vec::new();
+ }
+ let mut buffer = vec![0u16; len as usize];
+ // SAFETY: `buffer` holds `len` wide characters, the length the call is given.
+ let listed =
+ unsafe { CM_Get_Device_Interface_ListW(&GUID_DEVINTERFACE_HID, null(), buffer.as_mut_ptr(), len, CM_GET_DEVICE_INTERFACE_LIST_PRESENT) };
+ match listed {
+ CR_SUCCESS => return split_multi_sz(&buffer),
+ CR_BUFFER_SMALL => continue,
+ _ => return Vec::new(),
+ }
+ }
+ Vec::new()
+}
+
+/// A string or string-list property, read by `get` (property type, buffer, its size in bytes) in
+/// two calls: the size, then the value.
+fn property_strings(get: impl Fn(*mut DEVPROPTYPE, *mut u8, *mut u32) -> CONFIGRET) -> Option<Vec<String>> {
+ let mut kind: DEVPROPTYPE = 0;
+ let mut size = 0u32;
+ if get(&mut kind, null_mut(), &mut size) != CR_BUFFER_SMALL || size == 0 || size > MAX_PROPERTY_BYTES {
+ return None;
+ }
+ let mut buffer = vec![0u16; (size as usize).div_ceil(2)];
+ let mut size = (buffer.len() * 2) as u32;
+ if get(&mut kind, buffer.as_mut_ptr().cast(), &mut size) != CR_SUCCESS || (kind != DEVPROP_TYPE_STRING && kind != DEVPROP_TYPE_STRING_LIST) {
+ return None;
+ }
+ Some(split_multi_sz(&buffer))
+}
+
+/// A string property of the device interface at `path`.
+fn interface_strings(path: &str, key: &DEVPROPKEY) -> Option<Vec<String>> {
+ let path = wide(path);
+ property_strings(|kind, buffer, size| {
+ // SAFETY: `path` is nul-terminated and outlives the call; `buffer` is null (asking the size)
+ // or holds `*size` bytes, as `property_strings` sets up.
+ unsafe { CM_Get_Device_Interface_PropertyW(path.as_ptr(), key, kind, buffer, size, 0) }
+ })
+}
+
+/// A string property of the device with instance ID `instance`.
+fn devnode_strings(instance: &str, key: &DEVPROPKEY) -> Option<Vec<String>> {
+ let instance = wide(instance);
+ let mut devnode = 0u32;
+ // SAFETY: `instance` is nul-terminated and outlives the call; `devnode` is a valid place for the result.
+ if unsafe { CM_Locate_DevNodeW(&mut devnode, instance.as_ptr(), CM_LOCATE_DEVNODE_NORMAL) } != CR_SUCCESS {
+ return None;
+ }
+ property_strings(|kind, buffer, size| {
+ // SAFETY: `buffer` is null (asking the size) or holds `*size` bytes, as `property_strings` sets up.
+ unsafe { CM_Get_DevNode_PropertyW(devnode, key, kind, buffer, size, 0) }
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ /// The hardware IDs Windows gives a wired 3Dconnexion device's motion interface, and a
+ /// keyboard's: only the first is a multi-axis controller.
+ #[test]
+ fn only_the_multi_axis_usage_is_a_3d_mouse() {
+ let ids = |list: &[&str]| list.iter().map(|s| s.to_string()).collect::<Vec<_>>();
+ let space_mouse = ids(&["HID\\VID_256F&PID_C635&REV_0437&MI_00", "HID\\VID_256F&UP:0001_U:0008", "HID_DEVICE_UP:0001_U:0008", "HID_DEVICE"]);
+ let keyboard = ids(&[
+ "HID\\VID_046D&PID_C31C&REV_6400&MI_00",
+ "HID\\VID_046D&UP:0001_U:0006",
+ "HID_DEVICE_SYSTEM_KEYBOARD",
+ "HID_DEVICE_UP:0001_U:0006",
+ "HID_DEVICE",
+ ]);
+ let vendor = ids(&["HID\\VID_256F&UP:FF00_U:0001", "HID_DEVICE_UP:FF00_U:0001", "HID_DEVICE_UPR:FF00-FFFF", "HID_DEVICE"]);
+ assert!(is_multi_axis(&space_mouse));
+ assert!(is_multi_axis(&ids(&["hid_device_up:0001_u:0008"])), "IDs compare without regard to case");
+ assert!(!is_multi_axis(&keyboard) && !is_multi_axis(&vendor) && !is_multi_axis(&[]));
+ }
+
+ #[test]
+ fn nul_separated_lists_split_into_their_strings() {
+ let buffer: Vec<u16> = "a\\b\0HID_DEVICE\0\0".encode_utf16().collect();
+ assert_eq!(split_multi_sz(&buffer), ["a\\b", "HID_DEVICE"]);
+ assert_eq!(split_multi_sz(&wide("one")), ["one"]);
+ assert!(split_multi_sz(&[0, 0]).is_empty() && split_multi_sz(&[]).is_empty());
+ }
+
+ /// The scan asks Plug and Play only: on any machine it returns, and every path it returns is a
+ /// present HID interface whose hardware IDs name the multi-axis usage.
+ #[test]
+ fn the_scan_returns_only_multi_axis_interfaces() {
+ let found = multi_axis_controllers();
+ let all = interfaces();
+ for path in &found {
+ let path = path.to_str().unwrap_or_default();
+ assert!(all.iter().any(|p| p == path), "{path}");
+ let instance = interface_strings(path, &DEVPKEY_Device_InstanceId).and_then(|ids| ids.into_iter().next()).unwrap_or_default();
+ assert!(devnode_strings(&instance, &DEVPKEY_Device_HardwareIds).is_some_and(|ids| is_multi_axis(&ids)), "{path}");
+ }
+ eprintln!("{} HID interfaces present, {} multi-axis controllers", all.len(), found.len());
+ }
+}