SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.
3D mouse: any HID multi-axis controller with motion axes (#1880)
The Nomade052d1987974
diff --git a/Cargo.lock b/Cargo.lockindex 82a4f8656d..cd011e4ffd 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -4078,6 +4078,7 @@ dependencies = ["rustls","serde_json","solidcraft-engine",+ "solidcraft-space-mouse","solidcraft-ui-egui","ureq","windows-sys 0.61.2",@@ -4236,6 +4237,10 @@ dependencies = ["ttf-parser",]+[[package]]+name = "solidcraft-space-mouse"+version = "0.14.0"+[[package]]name = "solidcraft-ui-egui"version = "0.14.0"diff --git a/Cargo.toml b/Cargo.tomlindex ab1687109e..9f53bb0e3a 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -23,6 +23,7 @@ solidcraft-doc = { path = "crates/doc" }solidcraft-io = { path = "crates/io" }solidcraft-engine = { path = "crates/engine" }solidcraft-ui-egui = { path = "crates/ui-egui" }+solidcraft-space-mouse = { path = "crates/space-mouse" }solidcraft-mcp = { path = "crates/mcp" }solidcraft-derive = { path = "crates/derive" }diff --git a/README.md b/README.mdindex 215caeac09..094dc3f3f4 100644--- a/README.md+++ b/README.md@@ -218,8 +218,9 @@ unaccepted artwork Open; run `cargo xtask icons` to check the collection.Windows builds: `cargo xwin build --release --target x86_64-pc-windows-msvc -p solidcraft`.-On Windows and Linux, SolidCraft detects a connected 3Dconnexion SpaceNavigator or SpaceMouse through its-multi-axis HID interface. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.+On Windows and Linux, SolidCraft detects a connected 3D mouse through its HID multi-axis+controller interface: a 3Dconnexion SpaceNavigator or SpaceMouse, or a homemade device that+declares itself one. Move the cap to pan and zoom, and tilt or twist it to rotate the 3D view.While editing a sketch, the cap pans and zooms without changing the sketch view. The Navigationpage in Preferences has an on/off switch, a speed control and, for each of the cap's six axes, aninvert switch and a speed for the 3D mouse. The web app reads@@ -236,17 +237,24 @@ zones) applies as it does in other programs, and no udev rule is needed. With nothe 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:+`/etc/udev/rules.d/70-3d-mouse.rules` for USB devices with 3Dconnexion's vendor id, and for its+Bluetooth ones (where `idVendor` isn't set, so the HID id is matched instead):```SUBSYSTEM=="hidraw", ATTRS{idVendor}=="256f", TAG+="uaccess"+SUBSYSTEM=="hidraw", KERNELS=="0005:256F:*", TAG+="uaccess"```-Older SpaceNavigators use Logitech's vendor id `046d`; add a rule with their product id (see `lsusb`)-instead of matching every Logitech device. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then replug the device. The Flatpak-sandbox does not expose hidraw devices, so the 3D mouse only works with native builds there for now.-Devices that send all six axes in HID report 1 (some homemade ones do) are recognised from their-report descriptor, so they work as well.+Older SpaceNavigators use Logitech's vendor id `046d`, so add a rule with their product id (see+`lsusb`) instead of matching every Logitech device. A homemade device needs a rule with its own+vendor and product id. Reload with `sudo udevadm control --reload && sudo udevadm trigger`, then+replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works+with native builds there for now.++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.+Each axis is scaled from the range the descriptor declares.In the browser: `cd apps/solidcraft-web && trunk build --release --public-url ./` (WebGPU, orWebGL2 with `?webgl`; `?sample` opens the sample part).diff --git a/apps/solidcraft/Cargo.toml b/apps/solidcraft/Cargo.tomlindex 20e0fa7fe6..df9e36ed5f 100644--- a/apps/solidcraft/Cargo.toml+++ b/apps/solidcraft/Cargo.toml@@ -23,6 +23,7 @@ neg_cmp_op_on_partial_ord = "allow"[dependencies]solidcraft-engine = { workspace = true }solidcraft-ui-egui = { workspace = true }+solidcraft-space-mouse = { workspace = true }eframe = { workspace = true, features = ["default_fonts", "wgpu", "accesskit", "wayland", "x11", "links"] }egui = { workspace = true }serde_json = { workspace = true }diff --git a/apps/solidcraft/src/space_mouse.rs b/apps/solidcraft/src/space_mouse.rsindex d261fd0efc..a6e3019507 100644--- a/apps/solidcraft/src/space_mouse.rs+++ b/apps/solidcraft/src/space_mouse.rs@@ -1,8 +1,8 @@-//! 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.+//! 3D mouse navigation on Windows (through hidapi) and Linux (through spacenavd when it runs, else+//! hidraw). Read directly, any HID multi-axis controller works: 3Dconnexion's and homemade ones.+//! 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")]@@ -12,17 +12,20 @@ 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;+use solidcraft_space_mouse::Layout;use solidcraft_ui_egui::SolveApp;use solidcraft_ui_egui::space_mouse::{Axes, AxisRule, DriverMapping, WheelGuard, navigate_frame};const STALE_AFTER: Duration = Duration::from_millis(150);const RETRY_AFTER: Duration = Duration::from_secs(2);const MAX_PROFILE_BYTES: u64 = 1024 * 1024;+/// Room for one input report: the 4096 bytes `solidcraft_space_mouse` places fields in, plus the+/// report id. A smaller buffer would cut a longer report short, and a cut report is dropped whole.+const REPORT_BUFFER_BYTES: usize = 4096 + 1;/// The mapping used when no 3DxWare profile is found: what the driver applies by default in/// object mode. On Linux there is no 3DxWare (#1172); on Windows 3DxWare has no profile for@@ -156,8 +159,9 @@ fn load_driver_mapping() -> Option<DriverMapping> {#[derive(Clone, Copy)]struct Reading {axes: Axes,- translation_at: Instant,- rotation_at: Instant,+ /// When each of X, Y, Z, Rx, Ry and Rz last arrived. Each ages on its own: a device may send+ /// translation and rotation in separate reports, or spread even one group over several.+ at: [Instant; 6],/// 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.@@ -166,64 +170,42 @@ struct Reading {impl Reading {fn new(now: Instant) -> Self {- Self { axes: Axes::default(), translation_at: now, rotation_at: now, held: false }+ Self { axes: Axes::default(), at: [now; 6], 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] },+ let mut axes = self.axes;+ if !self.held {+ for (value, at) in axes.translation.iter_mut().chain(axes.rotation.iter_mut()).zip(self.at) {+ if now.duration_since(at) >= STALE_AFTER {+ *value = 0;+ }+ }}+ axes}}-/// 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.+/// 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(target_os = "windows")]fn is_3d_mouse(info: &DeviceInfo) -> bool {- is_3d_mouse_vendor(info.vendor_id()) && info.usage_page() == 0x01 && info.usage() == 0x08+ info.usage_page() == 0x01 && info.usage() == 0x08}-fn three_axes(bytes: &[u8]) -> Option<[i16; 3]> {- let &[x0, x1, y0, y1, z0, z1] = bytes.get(..6)? else { return None };- Some([i16::from_le_bytes([x0, x1]), i16::from_le_bytes([y0, y1]), i16::from_le_bytes([z0, z1])])-}--/// 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.-/// 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.+/// Takes the axes an input report carries, as the device's descriptor laid them out, and leaves+/// the others as they were: translation and rotation may come in separate reports (3Dconnexion's+/// wired devices) or one (its wireless ones and most homemade devices).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;- reading.translation_at = now;- true- }- Some(2) => {- let Some(rotation) = report.get(1..).and_then(three_axes) else { return false };- reading.axes.rotation = rotation;- reading.rotation_at = now;- true+ let Some(decoded) = layout.decode(report) else { return false };+ let values = reading.axes.translation.iter_mut().chain(reading.axes.rotation.iter_mut());+ for ((value, at), new) in values.zip(reading.at.iter_mut()).zip(decoded.axes) {+ if let Some(new) = new {+ *value = new;+ *at = now;}- _ => false,}+ true}/// Publishes one input report from the device to the egui thread.@@ -261,9 +243,12 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {loop {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];+ } else if let Some((device, layout)) = api.device_list().filter(|info| is_3d_mouse(info)).find_map(|info| {+ let device = info.open_device(&api).ok()?;+ let layout = device_layout(&device, info.vendor_id())?;+ Some((device, layout))+ }) {+ let mut report = [0_u8; REPORT_BUFFER_BYTES];loop {match device.read_timeout(&mut report, 100) {Ok(0) => {}@@ -280,17 +265,28 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {}}-/// How the device packs its axes, from its report descriptor; the usual split layout if the-/// descriptor cannot be read.+/// How the device packs its axes, from its report descriptor, or None when it isn't one to read:+/// a controller whose descriptor names no motion axis. Without a descriptor to go on (it can't be+/// read, or it's empty), a 3Dconnexion device (Logitech's id for the old SpaceNavigator,+/// 3Dconnexion's own for the rest) gets 3Dconnexion's layout, and any other device is left alone+/// rather than guessed at.#[cfg(target_os = "windows")]-fn device_layout(device: &hidapi::HidDevice) -> Layout {+fn device_layout(device: &hidapi::HidDevice, vendor_id: u16) -> Option<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- }+ let read = device.get_report_descriptor(&mut descriptor);+ if let Ok(size @ 1..) = read {+ return solidcraft_space_mouse::Descriptor::parse(descriptor.get(..size).unwrap_or_default()).layout();+ }+ let why = match read {+ Err(error) => error.to_string(),+ Ok(_) => "it is empty".to_string(),+ };+ if matches!(vendor_id, 0x046d | 0x256f) {+ log::info!("3D mouse: no report descriptor ({why}), assuming separate translation and rotation reports");+ Some(Layout::default())+ } else {+ log::debug!("3D mouse: skipping a multi-axis controller without a report descriptor ({why})");+ None}}@@ -312,8 +308,8 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {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];+ log::info!("3D mouse: reading {}", device.path.display());+ let mut report = [0_u8; REPORT_BUFFER_BYTES];loop {match file.read(&mut report) {Ok(0) => break,@@ -418,60 +414,88 @@ mod tests {}#[test]- fn decodes_separate_reports_without_stale_motion_or_padding_interference() {+ fn each_axis_keeps_its_own_age_so_stale_motion_stops() {+ // Report layouts are tested in solidcraft-space-mouse; here, what the reader keeps.let now = Instant::now();let mut reading = Reading::new(now);- assert!(!decode_report(&[1, 1, 2], Layout::Split, &mut reading, now));+ let layout = Layout::default();+ assert!(!decode_report(&[1, 1, 2], layout, &mut reading, now));assert_eq!(reading.current(now), Axes::default());- 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], Layout::Split, &mut reading, now));- assert_eq!(reading.current(now).rotation, [0, 1, -1]);+ assert!(decode_report(&[1, 0x9c, 0xff, 0x2c, 0x01, 0, 0], layout, &mut reading, now));+ assert!(decode_report(&[2, 0, 0, 1, 0, 0xff, 0xff], layout, &mut reading, now));+ assert_eq!(reading.current(now), Axes { translation: [-100, 300, 0], rotation: [0, 1, -1] });+ // Only rotation arrives again: translation goes stale, rotation stays current.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], 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] });+ assert!(decode_report(&[2, 4, 0, 5, 0, 6, 0], layout, &mut reading, later));+ assert_eq!(reading.current(later), Axes { translation: [0; 3], rotation: [4, 5, 6] });+ // A device sending all six in one report updates both at once.+ let combined = solidcraft_space_mouse::Descriptor::parse(&[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x06, 0x19, 0x30, 0x29, 0x35, 0x81,+ 0x02, 0xC0,+ ])+ .layout()+ .expect("six axes declared");+ let mut both = Reading::new(now);+ assert!(decode_report(&[1, 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0], combined, &mut both, now));+ assert_eq!(both.current(now), 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() {+ fn a_group_spread_over_reports_keeps_the_axes_it_already_has() {+ // X in report 1, Y in report 2 (16-bit, -350..350): X arriving mustn't zero Y, and Y+ // arriving mustn't zero X.+ let split_x_y = solidcraft_space_mouse::Descriptor::parse(&[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x01, // 1 x 16 bit, -350..350+ 0x85, 0x01, 0x09, 0x30, 0x81, 0x02, // report 1: X+ 0x85, 0x02, 0x09, 0x31, 0x81, 0x02, // report 2: Y+ 0xC0,+ ])+ .layout()+ .expect("X and Y declared");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());+ let mut reading = Reading::new(now);+ assert!(decode_report(&[1, 100, 0], split_x_y, &mut reading, now));+ assert!(decode_report(&[2, 200, 0], split_x_y, &mut reading, now));+ assert_eq!(reading.current(now).translation, [100, 200, 0]);+ // Then only X keeps coming: Y goes stale on its own.+ let later = now + STALE_AFTER + Duration::from_millis(1);+ assert!(decode_report(&[1, 50, 0], split_x_y, &mut reading, later));+ assert_eq!(reading.current(later).translation, [50, 0, 0]);}#[test]- fn combined_report_one_carries_translation_and_rotation_together() {+ fn only_the_axis_itself_keeps_it_alive() {+ // 3Dconnexion's split layout, plus buttons in report 3 (one byte of bits).+ 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 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] });+ assert!(decode_report(&[1, 100, 0, 0, 0, 0, 0], layout, &mut reading, now));+ // Just before the timeout X is still there; at exactly the timeout it's stale.+ assert_eq!(reading.current(now + STALE_AFTER - Duration::from_millis(1)).translation, [100, 0, 0]);+ assert_eq!(reading.current(now + STALE_AFTER).translation, [0; 3]);+ // Button reports and reports with an id the layout doesn't know keep coming, but neither+ // refreshes X: it goes stale on time all the same.+ for step in 1..=10 {+ let at = now + STALE_AFTER * step / 10;+ assert!(decode_report(&[3, 1], layout, &mut reading, at));+ assert!(!decode_report(&[0x17, 80], layout, &mut reading, at));+ }+ assert_eq!(reading.current(now + STALE_AFTER).translation, [0; 3]);}#[test]- fn combined_layout_ignores_short_and_other_reports() {+ fn a_held_reading_stays_until_the_next_one_and_a_hid_reading_goes_stale() {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] });+ 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]diff --git a/apps/solidcraft/src/space_mouse/hid_descriptor.rs b/apps/solidcraft/src/space_mouse/hid_descriptor.rsdeleted file mode 100644index 3dfa5feacb..0000000000--- a/apps/solidcraft/src/space_mouse/hid_descriptor.rs+++ /dev/null@@ -1,253 +0,0 @@-//! Just enough of a HID report descriptor reader to recognise a 3D mouse and to see how it packs-//! its motion axes. Written from the public USB HID specification. Malformed input never panics;-//! it simply yields less information.--/// Generic Desktop usage page, and the usages in it that matter here.-const PAGE_GENERIC_DESKTOP: u32 = 0x01;-const USAGE_MULTI_AXIS_CONTROLLER: u32 = 0x08;-const FIRST_AXIS_USAGE: u32 = 0x30; // X, Y, Z, Rx, Ry, Rz are 0x30..=0x35-const AXIS_COUNT: u32 = 6;--/// Motion reports are report id 1 (translation, or everything) and report id 2 (rotation).-const MOTION_REPORT_ID: u8 = 1;--/// Descriptors are small (hidapi reserves 4 KiB). Anything past this is ignored.-const MAX_DESCRIPTOR_BYTES: usize = 4096;-/// Bound on the usages one main item can declare through a usage range.-const MAX_USAGES_PER_ITEM: u32 = 256;--/// How a device spreads its six motion axes over input reports.-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]-pub enum Layout {- /// Report 1 carries translation and report 2 carries rotation, three 16-bit values each.- /// This is how 3Dconnexion devices report, and it is the layout assumed when nothing is known.- #[default]- Split,- /// Report 1 carries all six axes: translation, then rotation. Homemade devices do this.- Combined,-}--#[derive(Clone, Copy)]-struct Item {- /// 0 main, 1 global, 2 local (3 is reserved).- kind: u8,- tag: u8,- value: u32,-}--/// Walks the short items of a descriptor. Long items are skipped; a truncated tail ends the walk.-fn items(descriptor: &[u8]) -> impl Iterator<Item = Item> + '_ {- let descriptor = descriptor.get(..MAX_DESCRIPTOR_BYTES).unwrap_or(descriptor);- let mut pos = 0_usize;- std::iter::from_fn(move || {- loop {- let prefix = *descriptor.get(pos)?;- pos += 1;- if prefix == 0xFE {- // Long item: a data length byte, a tag byte, then the data.- let length = usize::from(*descriptor.get(pos)?);- pos = pos.checked_add(2 + length)?;- continue;- }- let size = match prefix & 0b11 {- 0 => 0,- 1 => 1,- 2 => 2,- _ => 4,- };- let data = descriptor.get(pos..pos + size)?;- pos += size;- let value = data.iter().enumerate().fold(0_u32, |value, (index, byte)| value | (u32::from(*byte) << (8 * index)));- return Some(Item { kind: (prefix >> 2) & 0b11, tag: prefix >> 4, value });- }- })-}--/// What a descriptor says about a device, as far as 3D mouse support needs to know.-#[derive(Clone, Debug, Default, PartialEq, Eq)]-pub struct Descriptor {- multi_axis_controller: bool,- /// Distinct axes (X, Y, Z, Rx, Ry, Rz as bits 0..=5) that input report 1 carries.- motion_report_axes: u8,-}--impl Descriptor {- pub fn parse(descriptor: &[u8]) -> Self {- let mut summary = Self::default();- let mut page = 0_u32;- let mut report_id = 0_u8;- let mut depth = 0_u32;- // Local items belong to the next main item only.- let mut usages: Vec<u32> = Vec::new();- let mut usage_min = None;- for item in items(descriptor) {- match (item.kind, item.tag) {- // Global: usage page, report id.- (1, 0) => page = item.value,- (1, 8) => report_id = u8::try_from(item.value).unwrap_or(0),- // Local: usage, usage minimum, usage maximum.- (2, 0) => usages.push(Self::full_usage(page, item)),- (2, 1) => usage_min = Some(Self::full_usage(page, item)),- (2, 2) => {- if let Some(min) = usage_min.take() {- let max = Self::full_usage(page, item);- let count = max.saturating_sub(min).min(MAX_USAGES_PER_ITEM - 1);- usages.extend((0..=count).map(|offset| min.saturating_add(offset)));- }- }- // Main: input, collection, end collection.- (0, 8) => {- if report_id == MOTION_REPORT_ID || (report_id == 0 && depth > 0) {- summary.note_axes(&usages);- }- }- (0, 0xA) => {- // An application collection (1) at the top level names the device.- if depth == 0 && item.value == 1 && usages.first() == Some(&((PAGE_GENERIC_DESKTOP << 16) | USAGE_MULTI_AXIS_CONTROLLER)) {- summary.multi_axis_controller = true;- }- depth += 1;- }- (0, 0xC) => depth = depth.saturating_sub(1),- _ => {}- }- if item.kind == 0 {- usages.clear();- usage_min = None;- }- }- summary- }-- /// Usage items of up to two bytes name a usage on the current page, four bytes carry the page.- fn full_usage(page: u32, item: Item) -> u32 {- if item.value > 0xFFFF { item.value } else { (page << 16) | item.value }- }-- fn note_axes(&mut self, usages: &[u32]) {- for usage in usages {- let axis = usage.wrapping_sub((PAGE_GENERIC_DESKTOP << 16) | FIRST_AXIS_USAGE);- if axis < AXIS_COUNT {- self.motion_report_axes |= 1 << axis;- }- }- }-- /// True for a top-level Generic Desktop "Multi-Axis Controller" collection. This tells a- /// SpaceMouse's motion interface apart from its keyboard interface and from ordinary mice.- #[cfg_attr(not(target_os = "linux"), allow(dead_code))]- pub fn is_multi_axis_controller(&self) -> bool {- self.multi_axis_controller- }-- /// `Combined` when input report 1 declares all six axes, otherwise `Split`.- pub fn layout(&self) -> Layout {- if self.motion_report_axes.count_ones() == AXIS_COUNT { Layout::Combined } else { Layout::Split }- }-}--#[cfg(test)]-mod tests {- use super::*;-- /// Report 1 = X Y Z, report 2 = Rx Ry Rz, each as three signed 16-bit values.- const SPLIT: &[u8] = &[- 0x05, 0x01, // usage page: generic desktop- 0x09, 0x08, // usage: multi-axis controller- 0xA1, 0x01, // collection: application- 0x85, 0x01, // report id 1- 0x16, 0xA2, 0xFE, // logical minimum -350- 0x26, 0x5E, 0x01, // logical maximum 350- 0x75, 0x10, // report size 16- 0x95, 0x03, // report count 3- 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, // X Y Z- 0x81, 0x06, // input: data, variable, relative- 0x85, 0x02, // report id 2- 0x09, 0x33, 0x09, 0x34, 0x09, 0x35, // Rx Ry Rz- 0x81, 0x06, // input- 0xC0, // end collection- ];-- /// Report 1 = X Y Z Rx Ry Rz.- const COMBINED: &[u8] = &[- 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, // multi-axis controller, report id 1- 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x06, // 6 x 16 bit, -350..350- 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x09, 0x33, 0x09, 0x34, 0x09, 0x35, // X Y Z Rx Ry Rz- 0x81, 0x06, 0xC0,- ];-- /// The same six axes declared as a usage range, with report id 1 after the collection opens.- const COMBINED_RANGE: &[u8] = &[- 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, 0x75, 0x10, 0x95, 0x06, //- 0x19, 0x30, 0x29, 0x35, // usage minimum X, usage maximum Rz- 0x81, 0x06, 0xC0,- ];-- /// A boot keyboard-like interface: usage page 7 usages must not count as axes.- const KEYBOARD: &[u8] =- &[0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0xC0];-- /// An ordinary mouse: Generic Desktop X, Y but top-level usage is Mouse (2).- const MOUSE: &[u8] = &[- 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x09, 0x30, 0x09, 0x31, 0x15, 0x81, 0x25, 0x7F, 0x75, 0x08, 0x95, 0x02, 0x81,- 0x06, 0xC0, 0xC0,- ];-- #[test]- fn split_descriptor_is_a_multi_axis_controller_with_three_axes_in_report_one() {- let descriptor = Descriptor::parse(SPLIT);- assert!(descriptor.is_multi_axis_controller());- assert_eq!(descriptor.motion_report_axes, 0b000_111);- assert_eq!(descriptor.layout(), Layout::Split);- }-- #[test]- fn six_axes_in_report_one_are_a_combined_layout() {- for bytes in [COMBINED, COMBINED_RANGE] {- let descriptor = Descriptor::parse(bytes);- assert!(descriptor.is_multi_axis_controller());- assert_eq!(descriptor.layout(), Layout::Combined);- }- }-- #[test]- fn other_interfaces_are_not_3d_mice() {- for bytes in [KEYBOARD, MOUSE, &[][..]] {- let descriptor = Descriptor::parse(bytes);- assert!(!descriptor.is_multi_axis_controller());- assert_eq!(descriptor.layout(), Layout::Split);- }- }-- #[test]- fn four_byte_usages_carry_their_own_page() {- // Usage (4 bytes) 0x0007_0030 is on page 7, not an axis.- let descriptor = Descriptor::parse(&[0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, 0x0B, 0x30, 0x00, 0x07, 0x00, 0x81, 0x06, 0xC0]);- assert!(descriptor.is_multi_axis_controller());- assert_eq!(descriptor.motion_report_axes, 0);- }-- #[test]- fn truncated_and_hostile_descriptors_never_panic() {- for end in 0..=COMBINED.len() {- let _ = Descriptor::parse(&COMBINED[..end]);- }- // Long item with a length running past the end, huge usage ranges, deep nesting.- let _ = Descriptor::parse(&[0xFE, 0xFF, 0x00, 0x01]);- let _ = Descriptor::parse(&[0x05, 0x01, 0x1B, 0, 0, 0, 0, 0x2B, 0xFF, 0xFF, 0xFF, 0xFF, 0x81, 0x06]);- let _ = Descriptor::parse(&[0xC0; 64]);- let _ = Descriptor::parse(&[0xA1; 64]);- let mut state = 0x2545_F491_4F6C_DD1D_u64;- for _ in 0..200 {- let bytes: Vec<u8> = (0..64)- .map(|_| {- state ^= state << 13;- state ^= state >> 7;- state ^= state << 17;- state.to_le_bytes()[0]- })- .collect();- let _ = Descriptor::parse(&bytes);- }- }-}diff --git a/apps/solidcraft/src/space_mouse/hidraw.rs b/apps/solidcraft/src/space_mouse/hidraw.rsindex e238052aba..46ab294326 100644--- a/apps/solidcraft/src/space_mouse/hidraw.rs+++ b/apps/solidcraft/src/space_mouse/hidraw.rs@@ -1,10 +1,10 @@//! Finding a 3D mouse on Linux. The kernel exposes every HID interface as `/dev/hidrawN`, with-//! its identity and report descriptor under `/sys/class/hidraw/hidrawN/device/`. Reading both is-//! plain file I/O, so no udev or hidapi library is needed.+//! its report descriptor under `/sys/class/hidraw/hidrawN/device/`. Reading it is plain file+//! I/O, so no udev or hidapi library is needed.use std::path::{Path, PathBuf};-use super::hid_descriptor::{Descriptor, Layout};+use solidcraft_space_mouse::{Descriptor, Layout};const SYSFS: &str = "/sys/class/hidraw";const DEV: &str = "/dev";@@ -14,14 +14,7 @@ pub struct Device {pub layout: Layout,}-/// The vendor id from `HID_ID=<bus>:<vendor>:<product>` (all hexadecimal) in a sysfs `uevent`.-fn vendor_id(uevent: &str) -> Option<u16> {- let id = uevent.lines().find_map(|line| line.strip_prefix("HID_ID="))?;- let vendor = id.split(':').nth(1)?;- u32::from_str_radix(vendor.trim(), 16).ok().and_then(|vendor| u16::try_from(vendor).ok())-}--/// The first hidraw interface that is a 3D mouse's multi-axis controller.+/// The first hidraw interface that is a multi-axis controller with motion axes, whoever made it.pub fn find() -> Option<Device> {let mut names: Vec<_> = std::fs::read_dir(SYSFS).ok()?.filter_map(Result::ok).map(|entry| entry.file_name()).collect();names.sort();@@ -29,29 +22,8 @@ pub fn find() -> Option<Device> {}fn probe(sysfs: &Path, path: PathBuf) -> Option<Device> {- let uevent = std::fs::read_to_string(sysfs.join("device/uevent")).ok()?;- if !super::is_3d_mouse_vendor(vendor_id(&uevent)?) {- return None;- }let descriptor = Descriptor::parse(&std::fs::read(sysfs.join("device/report_descriptor")).ok()?);- descriptor.is_multi_axis_controller().then(|| Device { path, layout: descriptor.layout() })-}--#[cfg(test)]-mod tests {- use super::*;-- #[test]- fn reads_the_vendor_from_the_hid_id() {- let uevent = "DRIVER=hid-generic\nHID_ID=0003:0000256F:0000C631\nHID_NAME=Some Device\n";- assert_eq!(vendor_id(uevent), Some(0x256f));- assert_eq!(vendor_id("HID_ID=0003:0000046D:0000C077"), Some(0x046d));- }-- #[test]- fn malformed_ids_are_rejected() {- for uevent in ["", "HID_NAME=x", "HID_ID=", "HID_ID=0003", "HID_ID=0003:zzzz:0001", "HID_ID=0003:FFFFFFFF:0001"] {- assert_eq!(vendor_id(uevent), None, "{uevent:?}");- }- }+ // A controller that declares no motion axis (buttons only, say) isn't read.+ let layout = descriptor.is_multi_axis_controller().then(|| descriptor.layout()).flatten()?;+ Some(Device { path, layout })}diff --git a/crates/space-mouse/Cargo.toml b/crates/space-mouse/Cargo.tomlnew file mode 100644index 0000000000..7ae84345e4--- /dev/null+++ b/crates/space-mouse/Cargo.toml@@ -0,0 +1,9 @@+[package]+name = "solidcraft-space-mouse"+description = "SolidCraft 3D mouse input: HID report descriptors and reports, independent of the device API and the UI"+version.workspace = true+edition.workspace = true+license.workspace = true++[lints]+workspace = truediff --git a/crates/space-mouse/src/descriptor.rs b/crates/space-mouse/src/descriptor.rsnew file mode 100644index 0000000000..409f62079e--- /dev/null+++ b/crates/space-mouse/src/descriptor.rs@@ -0,0 +1,816 @@+//! Just enough of a HID report descriptor reader to recognise a 3D mouse and to find its six+//! motion axes and its buttons in its input reports. Written from the public USB HID+//! specification (Device Class Definition for HID 1.11, section 6.2.2, and the HID Usage Tables).+//! Malformed input never panics; it simply yields less information.++/// Generic Desktop usage page, and the usages in it that matter here.+const PAGE_GENERIC_DESKTOP: u32 = 0x01;+const USAGE_MULTI_AXIS_CONTROLLER: u32 = 0x08;+const FIRST_AXIS_USAGE: u32 = 0x30; // X, Y, Z, Rx, Ry, Rz are 0x30..=0x35+const AXIS_COUNT: usize = 6;+/// The Button usage page: usage N is button N, from 1.+const PAGE_BUTTON: u32 = 0x09;+/// Buttons 1 to this are read; [`Report::buttons`] has one bit for each.+pub const MAX_BUTTONS: usize = 32;++/// Descriptors are small (hidapi reserves 4 KiB). Anything past this is ignored.+const MAX_DESCRIPTOR_BYTES: usize = 4096;+/// Bound on the usages one main item can declare through a usage range, and on its fields.+const MAX_USAGES_PER_ITEM: u32 = 256;+/// Bound on a report's length in bits: hidraw reads at most 4096 bytes.+const MAX_REPORT_BITS: u32 = 4096 * 8;++/// What decoded axes are scaled to at full deflection: 3Dconnexion's own range, which the rest+/// of the 3D mouse code is tuned for. A device declaring ±350 is passed through unchanged.+pub const FULL_SCALE: i16 = 350;++/// Where one axis or button sits in the device's input reports.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct Field {+ /// The report that carries it; 0 when the device doesn't number its reports.+ pub report_id: u8,+ /// Its first bit in the report, not counting the report id byte.+ pub bit_offset: u32,+ /// Its width, 1 to 32 bits. A field of any other width reads as missing.+ pub bits: u32,+ /// The declared range. 64 bits wide so a 32-bit unsigned maximum fits.+ pub logical_min: i64,+ pub logical_max: i64,+ /// The descriptor's Relative flag. 3Dconnexion sets it on some spring-return caps and not on+ /// others, so it does not tell a joystick from a trackball.+ pub relative: bool,+}++impl Field {+ /// The `index`th signed 16-bit value of a report, ±350: how 3Dconnexion devices report.+ const fn sixteen_bit(report_id: u8, index: u32) -> Self {+ Self { report_id, bit_offset: index * 16, bits: 16, logical_min: -350, logical_max: 350, relative: true }+ }++ /// The field's raw value in `body` (the report without its id), or None if `body` is too short+ /// or the field isn't 1 to 32 bits wide. The fields are public, so a hand-built one is checked+ /// here too, not only the ones `Descriptor::parse` makes.+ fn read(&self, body: &[u8]) -> Option<i64> {+ if !(1..=32).contains(&self.bits) {+ return None;+ }+ let mut raw = 0_i64;+ for bit in 0..self.bits {+ let at = self.bit_offset.checked_add(bit)?;+ let byte = *body.get(usize::try_from(at / 8).ok()?)?;+ raw |= i64::from((byte >> (at % 8)) & 1) << bit;+ }+ // Signed fields are two's complement, as the logical minimum says.+ Some(if self.logical_min < 0 && (raw >> (self.bits - 1)) & 1 == 1 { raw - (1_i64 << self.bits) } else { raw })+ }++ /// `raw` scaled from the field's logical range so its middle is 0 and its ends are+ /// ±[`FULL_SCALE`]. A value past the declared range goes past ±FULL_SCALE rather than being cut+ /// off, and a field without a usable range is passed through. Either way the result is clamped+ /// to ±`i16::MAX`, never `i16::MIN`, so negating an axis can't overflow.+ fn scaled(&self, raw: i64) -> i16 {+ // i128: a hand-built Field can declare any i64 range, and `max - min` of i64::MIN..i64::MAX+ // overflows an i64.+ let (raw, min, max) = (i128::from(raw), i128::from(self.logical_min), i128::from(self.logical_max));+ let value = if min < max { (2 * raw - (min + max)) as f64 / (max - min) as f64 * f64::from(FULL_SCALE) } else { raw as f64 };+ value.round().clamp(-f64::from(i16::MAX), f64::from(i16::MAX)) as i16+ }+}++/// Where a device puts its six axes and its buttons.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct Layout {+ /// X, Y, Z, Rx, Ry, Rz, for each axis the device has.+ pub axes: [Option<Field>; AXIS_COUNT],+ /// Buttons 1 to [`MAX_BUTTONS`] at indices 0 to 31, for each the device has. Devices number+ /// them with gaps (3Dconnexion's do), so the index is the button's own number less one.+ pub buttons: [Option<Field>; MAX_BUTTONS],+ /// The descriptor declares report ids, so every report starts with its id byte.+ pub numbered: bool,+}++impl Default for Layout {+ /// 3Dconnexion's: report 1 carries X Y Z and report 2 Rx Ry Rz, three signed 16-bit values+ /// each. For a 3Dconnexion device whose descriptor can't be read; a device that isn't one+ /// should never be read with it. Where its buttons are differs from model to model, so it has+ /// none.+ fn default() -> Self {+ let translation = |index| Some(Field::sixteen_bit(1, index));+ let rotation = |index| Some(Field::sixteen_bit(2, index));+ Self {+ axes: [translation(0), translation(1), translation(2), rotation(0), rotation(1), rotation(2)],+ buttons: [None; MAX_BUTTONS],+ numbered: true,+ }+ }+}++/// What one input report carries: the axes it has, scaled to ±[`FULL_SCALE`], and the buttons.+/// An axis the report doesn't carry is None, not 0, so a device that spreads one group over+/// several reports (X in one, Y in another) doesn't zero the axes it sent a moment ago.+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]+pub struct Report {+ /// X, Y, Z, Rx, Ry, Rz.+ pub axes: [Option<i16>; AXIS_COUNT],+ /// When the report carries buttons, which are down: bit N for button N + 1. A report with+ /// every button up is how a device says they were released, so `Some(0)` matters.+ pub buttons: Option<u32>,+}++impl Layout {+ /// The axes and buttons in one input report, or None when it carries none of them or is too+ /// short for one of its fields. A truncated report is dropped whole, axes included, rather+ /// than half read: devices send each report at its full declared size, so a short one is+ /// damaged. Padding after the fields is ignored.+ pub fn decode(&self, report: &[u8]) -> Option<Report> {+ let (id, body) = if self.numbered { (*report.first()?, report.get(1..)?) } else { (0, report) };+ let mut decoded = Report::default();+ for (value, field) in decoded.axes.iter_mut().zip(&self.axes) {+ if let Some(field) = field.filter(|field| field.report_id == id) {+ *value = Some(field.scaled(field.read(body)?));+ }+ }+ for (bit, field) in self.buttons.iter().enumerate() {+ if let Some(field) = field.filter(|field| field.report_id == id) {+ let down = field.read(body)? != 0;+ decoded.buttons = Some(decoded.buttons.unwrap_or(0) | (u32::from(down) << bit));+ }+ }+ (decoded != Report::default()).then_some(decoded)+ }+}++#[derive(Clone, Copy)]+struct Item {+ /// 0 main, 1 global, 2 local (3 is reserved).+ kind: u8,+ tag: u8,+ /// Data bytes: 0, 1, 2 or 4.+ size: u8,+ value: u32,+}++impl Item {+ /// The data as a two's complement number of its own size (logical minimum and maximum).+ fn signed(self) -> i64 {+ match self.size {+ 1 => i64::from(self.value as u8 as i8),+ 2 => i64::from(self.value as u16 as i16),+ _ => i64::from(self.value as i32),+ }+ }+}++/// Walks the short items of a descriptor. Long items are skipped; a truncated tail ends the walk.+fn items(descriptor: &[u8]) -> impl Iterator<Item = Item> + '_ {+ let descriptor = descriptor.get(..MAX_DESCRIPTOR_BYTES).unwrap_or(descriptor);+ let mut pos = 0_usize;+ std::iter::from_fn(move || {+ loop {+ let prefix = *descriptor.get(pos)?;+ pos += 1;+ if prefix == 0xFE {+ // Long item: a data length byte, a tag byte, then the data.+ let length = usize::from(*descriptor.get(pos)?);+ pos = pos.checked_add(2 + length)?;+ continue;+ }+ let size = match prefix & 0b11 {+ 0 => 0,+ 1 => 1,+ 2 => 2,+ _ => 4,+ };+ let data = descriptor.get(pos..pos + size)?;+ pos += size;+ let value = data.iter().enumerate().fold(0_u32, |value, (index, byte)| value | (u32::from(*byte) << (8 * index)));+ return Some(Item { kind: (prefix >> 2) & 0b11, tag: prefix >> 4, size: size as u8, value });+ }+ })+}++/// The global items in force (PUSH and POP save and restore them).+#[derive(Clone, Copy, Default)]+struct Globals {+ page: u32,+ logical_min: i64,+ logical_max: Option<Item>,+ report_size: u32,+ report_count: u32,+ report_id: u8,+}++impl Globals {+ /// The logical maximum. With a non-negative minimum it is unsigned, so `0x26 0xFF 0xFF` is+ /// 65535 and `0x27 0xFF 0xFF 0xFF 0xFF` is 4294967295, rather than -1, as devices mean it.+ fn logical_max(&self) -> i64 {+ let Some(item) = self.logical_max else { return 0 };+ let signed = item.signed();+ if self.logical_min >= 0 && signed < 0 { i64::from(item.value) } else { signed }+ }+}++/// What a descriptor says about a device, as far as 3D mouse support needs to know.+#[derive(Clone, Debug, PartialEq, Eq)]+pub struct Descriptor {+ multi_axis_controller: bool,+ axes: [Option<Field>; AXIS_COUNT],+ buttons: [Option<Field>; MAX_BUTTONS],+ numbered: bool,+}++impl Descriptor {+ pub fn parse(descriptor: &[u8]) -> Self {+ let mut summary = Self { multi_axis_controller: false, axes: [None; AXIS_COUNT], buttons: [None; MAX_BUTTONS], numbered: false };+ let mut globals = Globals::default();+ // Every PUSH is kept, so every POP restores what its own PUSH saved. The descriptor is cut+ // at MAX_DESCRIPTOR_BYTES, which bounds the stack at that many entries.+ let mut pushed: Vec<Globals> = Vec::new();+ let mut depth = 0_u32;+ // The depth of the open Multi-axis Controller application collection; its fields count.+ let mut controller: Option<u32> = None;+ // The next free input bit of each report id.+ let mut offsets: Vec<(u8, u32)> = Vec::new();+ // Local items belong to the next main item only.+ let mut usages: Vec<u32> = Vec::new();+ let mut usage_min = None;+ for item in items(descriptor) {+ match (item.kind, item.tag) {+ // Global: usage page, logical extent, report size, id and count, push, pop.+ (1, 0) => globals.page = item.value,+ (1, 1) => globals.logical_min = item.signed(),+ (1, 2) => globals.logical_max = Some(item),+ (1, 7) => globals.report_size = item.value,+ (1, 8) => {+ globals.report_id = u8::try_from(item.value).unwrap_or(0);+ summary.numbered = true;+ }+ (1, 9) => globals.report_count = item.value,+ (1, 0xA) => pushed.push(globals),+ (1, 0xB) => {+ if let Some(saved) = pushed.pop() {+ globals = saved;+ }+ }+ // Local: usage, usage minimum, usage maximum.+ (2, 0) => usages.push(full_usage(globals.page, item)),+ (2, 1) => usage_min = Some(full_usage(globals.page, item)),+ (2, 2) => {+ if let Some(min) = usage_min.take() {+ let max = full_usage(globals.page, item);+ let count = max.saturating_sub(min).min(MAX_USAGES_PER_ITEM - 1);+ usages.extend((0..=count).map(|offset| min.saturating_add(offset)));+ }+ }+ // Main: input, collection, end collection.+ (0, 8) => {+ let start = match offsets.iter().position(|(id, _)| *id == globals.report_id) {+ Some(index) => offsets.get(index).map_or(0, |(_, bits)| *bits),+ None => {+ offsets.push((globals.report_id, 0));+ 0+ }+ };+ // Data (not constant) and variable (not an array): one value per usage.+ if controller.is_some() && item.value & 0b11 == 0b10 {+ summary.note_fields(&globals, &usages, start, item.value & 0b100 != 0);+ }+ let end = start.saturating_add(globals.report_size.saturating_mul(globals.report_count)).min(MAX_REPORT_BITS);+ if let Some((_, bits)) = offsets.iter_mut().find(|(id, _)| *id == globals.report_id) {+ *bits = end;+ }+ }+ (0, 0xA) => {+ // An application collection (1) at the top level names the device.+ if depth == 0 && item.value == 1 && usages.first() == Some(&((PAGE_GENERIC_DESKTOP << 16) | USAGE_MULTI_AXIS_CONTROLLER)) {+ summary.multi_axis_controller = true;+ controller = Some(depth);+ }+ depth = depth.saturating_add(1);+ }+ (0, 0xC) => {+ depth = depth.saturating_sub(1);+ if controller == Some(depth) {+ controller = None;+ }+ }+ _ => {}+ }+ if item.kind == 0 {+ usages.clear();+ usage_min = None;+ }+ }+ summary+ }++ /// Records the axes and buttons among an input item's fields: the `i`th field takes the `i`th+ /// usage, and fields past the last usage take the last one (HID 1.11, 6.2.2.8). The first+ /// declaration of an axis or button wins.+ fn note_fields(&mut self, globals: &Globals, usages: &[u32], start: u32, relative: bool) {+ let bits = globals.report_size;+ if !(1..=32).contains(&bits) {+ return;+ }+ for index in 0..globals.report_count.min(MAX_USAGES_PER_ITEM) {+ let Some(usage) = usages.get(index as usize).or(usages.last()) else { return };+ let Some(bit_offset) = index.checked_mul(bits).and_then(|offset| offset.checked_add(start)) else { return };+ if bit_offset.saturating_add(bits) > MAX_REPORT_BITS {+ return;+ }+ let axis = usage.wrapping_sub((PAGE_GENERIC_DESKTOP << 16) | FIRST_AXIS_USAGE) as usize;+ // Button usages start at 1; usage 0 on the page means "no button".+ let button = usage.wrapping_sub((PAGE_BUTTON << 16) | 1) as usize;+ let slot = match self.axes.get_mut(axis) {+ Some(slot) => Some(slot),+ None => self.buttons.get_mut(button),+ };+ if let Some(slot) = slot+ && slot.is_none()+ {+ *slot = Some(Field {+ report_id: globals.report_id,+ bit_offset,+ bits,+ logical_min: globals.logical_min,+ logical_max: globals.logical_max(),+ relative,+ });+ }+ }+ }++ /// True for a top-level Generic Desktop "Multi-Axis Controller" collection. This tells a+ /// 3D mouse's motion interface apart from its keyboard interface and from ordinary mice,+ /// whoever made it.+ pub fn is_multi_axis_controller(&self) -> bool {+ self.multi_axis_controller+ }++ /// Where the device's axes and buttons are, or None when the descriptor names no motion axis:+ /// a controller with only buttons isn't something to steer the view with, and guessing a+ /// layout for it would read its reports as motion.+ ///+ /// In a descriptor that numbers its reports, fields declared before the first report id carry+ /// id 0, which no report can have, so they're left out.+ pub fn layout(&self) -> Option<Layout> {+ let keep = |field: &Option<Field>| field.filter(|field| !self.numbered || field.report_id != 0);+ let axes = self.axes.each_ref().map(keep);+ axes.iter().any(Option::is_some).then(|| Layout { axes, buttons: self.buttons.each_ref().map(keep), numbered: self.numbered })+ }+}++/// Usage items of up to two bytes name a usage on the current page, four bytes carry the page.+fn full_usage(page: u32, item: Item) -> u32 {+ if item.size == 4 { item.value } else { (page << 16) | item.value }+}++#[cfg(test)]+mod tests {+ use super::*;++ /// Report 1 = X Y Z, report 2 = Rx Ry Rz, each as three signed 16-bit values (3Dconnexion's+ /// wired devices).+ const SPLIT: &[u8] = &[+ 0x05, 0x01, // usage page: generic desktop+ 0x09, 0x08, // usage: multi-axis controller+ 0xA1, 0x01, // collection: application+ 0xA1, 0x00, // collection: physical+ 0x85, 0x01, // report id 1+ 0x16, 0xA2, 0xFE, // logical minimum -350+ 0x26, 0x5E, 0x01, // logical maximum 350+ 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, // X Y Z+ 0x75, 0x10, // report size 16+ 0x95, 0x03, // report count 3+ 0x81, 0x06, // input: data, variable, relative+ 0xC0, // end collection+ 0xA1, 0x00, // collection: physical+ 0x85, 0x02, // report id 2+ 0x09, 0x33, 0x09, 0x34, 0x09, 0x35, // Rx Ry Rz+ 0x75, 0x10, 0x95, 0x03, 0x81, 0x06, // 3 x 16 bit, relative+ 0xC0, // end collection+ 0xA1, 0x02, // collection: logical+ 0x85, 0x03, // report id 3+ 0x05, 0x09, 0x19, 0x01, 0x29, 0x0F, // buttons 1 to 15+ 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x0F, 0x81, 0x02, // 15 x 1 bit, absolute+ 0x95, 0x01, 0x81, 0x03, // 1 bit of padding+ 0xC0, 0xC0,+ ];++ /// Report 1 = X Y Z Rx Ry Rz, absolute (3Dconnexion's wireless devices).+ const COMBINED: &[u8] = &[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0xA1, 0x00, 0x85, 0x01, // multi-axis controller, report id 1+ 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, // -350..350+ 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x09, 0x33, 0x09, 0x34, 0x09, 0x35, // X Y Z Rx Ry Rz+ 0x75, 0x10, 0x95, 0x06, 0x81, 0x02, // 6 x 16 bit, absolute+ 0xC0, 0xC0,+ ];++ /// The same six axes declared as a usage range, with report id 1 after the collection opens.+ const COMBINED_RANGE: &[u8] = &[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, 0x75, 0x10, 0x95, 0x06, //+ 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, //+ 0x19, 0x30, 0x29, 0x35, // usage minimum X, usage maximum Rz+ 0x81, 0x06, 0xC0,+ ];++ /// A homemade trackball: report 1 is eight button bits, then six 16-bit relative axes over+ /// the full signed range.+ const BUTTONS_FIRST: &[u8] = &[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, 0x85, 0x01, // multi-axis controller, report id 1+ 0x05, 0x09, 0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, // buttons 1 to 8, 0..1+ 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, // 8 x 1 bit+ 0x05, 0x01, 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x09, 0x33, 0x09, 0x34, 0x09, 0x35, // X..Rz+ 0x16, 0x00, 0x80, 0x26, 0xFF, 0x7F, // -32768..32767+ 0x75, 0x10, 0x95, 0x06, 0x81, 0x06, // 6 x 16 bit, relative+ 0xC0,+ ];++ /// A homemade joystick without report ids: four 8-bit axes from 0 to 255, a byte of constant+ /// padding first, and the rotation pushed and popped around a narrower range.+ const UNNUMBERED_UNSIGNED: &[u8] = &[+ 0x05, 0x01, 0x09, 0x08, 0xA1, 0x01, //+ 0x75, 0x08, 0x95, 0x01, 0x81, 0x03, // one constant byte+ 0x15, 0x00, 0x26, 0xFF, 0x00, // 0..255+ 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x95, 0x03, 0x81, 0x02, // X Y Z+ 0xA4, // push+ 0x26, 0x7F, 0x00, // 0..127+ 0x09, 0x35, 0x95, 0x01, 0x81, 0x02, // Rz+ 0xB4, // pop+ 0xC0,+ ];++ /// A boot keyboard-like interface: usage page 7 usages must not count as axes.+ const KEYBOARD: &[u8] =+ &[0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0xC0];++ /// An ordinary mouse: Generic Desktop X, Y but top-level usage is Mouse (2).+ const MOUSE: &[u8] = &[+ 0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x09, 0x01, 0xA1, 0x00, 0x09, 0x30, 0x09, 0x31, 0x15, 0x81, 0x25, 0x7F, 0x75, 0x08, 0x95, 0x02, 0x81,+ 0x06, 0xC0, 0xC0,+ ];++ fn field(report_id: u8, bit_offset: u32, bits: u32, (logical_min, logical_max): (i64, i64), relative: bool) -> Option<Field> {+ Some(Field { report_id, bit_offset, bits, logical_min, logical_max, relative })+ }++ fn layout(bytes: &[u8]) -> Layout {+ Descriptor::parse(bytes).layout().expect("the descriptor declares motion axes")+ }++ /// One report's axes, X to Rz, from a list of (axis, value).+ fn axes(values: &[(usize, i16)]) -> [Option<i16>; AXIS_COUNT] {+ let mut axes = [None; AXIS_COUNT];+ for &(axis, value) in values {+ if let Some(slot) = axes.get_mut(axis) {+ *slot = Some(value);+ }+ }+ axes+ }++ /// A Multi-axis Controller application collection around `body`.+ fn controller(body: &[u8]) -> Vec<u8> {+ [&[0x05, 0x01, 0x09, 0x08, 0xA1, 0x01][..], body, &[0xC0]].concat()+ }++ #[test]+ fn split_reports_put_translation_in_report_one_and_rotation_in_report_two() {+ let descriptor = Descriptor::parse(SPLIT);+ assert!(descriptor.is_multi_axis_controller());+ let layout = layout(SPLIT);+ assert!(layout.numbered);+ let r = (-350, 350);+ assert_eq!(+ layout.axes,+ [+ field(1, 0, 16, r, true),+ field(1, 16, 16, r, true),+ field(1, 32, 16, r, true),+ field(2, 0, 16, r, true),+ field(2, 16, 16, r, true),+ field(2, 32, 16, r, true)+ ]+ );+ // The same axes as are assumed for a 3Dconnexion device whose descriptor can't be read.+ assert_eq!(layout.axes, Layout::default().axes);+ // Buttons 1 to 15 are report 3's first 15 bits; the 16th is padding.+ assert_eq!(layout.buttons[0], field(3, 0, 1, (0, 1), false));+ assert_eq!(layout.buttons[14], field(3, 14, 1, (0, 1), false));+ assert_eq!(layout.buttons[15], None);+ // Buttons 1, 3 and 15 down; then all up, which is a report too.+ assert_eq!(layout.decode(&[3, 0b101, 0b0100_0000]), Some(Report { axes: [None; 6], buttons: Some(0b101 | 1 << 14) }));+ assert_eq!(layout.decode(&[3, 0, 0]).map(|r| r.buttons), Some(Some(0)));+ // A motion report says nothing about the buttons.+ assert_eq!(layout.decode(&[1, 1, 0, 2, 0, 3, 0]).map(|r| r.buttons), Some(None));+ }++ #[test]+ fn buttons_keep_their_own_numbers_across_gaps() {+ // X in report 1; buttons 1 to 3, a constant bit, then buttons 5 and 6 in report 3, as+ // 3Dconnexion numbers them.+ let layout = layout(&controller(&[+ 0x85, 0x01, 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02, // report 1: X+ 0x85, 0x03, 0x05, 0x09, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, // report 3, 1-bit fields+ 0x19, 0x01, 0x29, 0x03, 0x95, 0x03, 0x81, 0x02, // buttons 1 to 3+ 0x95, 0x01, 0x81, 0x03, // a constant bit+ 0x19, 0x05, 0x29, 0x06, 0x95, 0x02, 0x81, 0x02, // buttons 5 and 6+ ]));+ assert_eq!(layout.buttons[3], None);+ assert_eq!(layout.buttons[4], field(3, 4, 1, (0, 1), false));+ assert_eq!(layout.buttons[5], field(3, 5, 1, (0, 1), false));+ // Bits 0 and 5 set: buttons 1 and 6.+ assert_eq!(layout.decode(&[3, 0b10_0001]).and_then(|r| r.buttons), Some(0b10_0001));+ }++ #[test]+ fn a_controller_without_motion_axes_has_no_layout() {+ // Buttons only, in report 1. With a guessed 3Dconnexion layout, its report+ // `01 01 00 00 00 00 00` would read as X = 1. It must not be read at all.+ let buttons_only = controller(&[+ 0x85, 0x01, 0x05, 0x09, 0x19, 0x01, 0x29, 0x08, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x95, 0x08, 0x81, 0x02, //+ 0x75, 0x08, 0x95, 0x05, 0x81, 0x03, // padding up to 6 bytes+ ]);+ assert!(Descriptor::parse(&buttons_only).is_multi_axis_controller());+ assert_eq!(Descriptor::parse(&buttons_only).layout(), None);+ // Axes wider than 32 bits aren't supported, so they don't count either.+ let wide = controller(&[0x75, 0x40, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]);+ assert_eq!(Descriptor::parse(&wide).layout(), None);+ // A page-7 usage that happens to be 0x30 isn't an axis.+ let four_byte = controller(&[0x85, 0x01, 0x75, 0x10, 0x95, 0x01, 0x0B, 0x30, 0x00, 0x07, 0x00, 0x81, 0x06]);+ assert_eq!(Descriptor::parse(&four_byte).layout(), None);+ }++ #[test]+ fn six_axes_in_report_one_follow_each_other() {+ for (bytes, relative) in [(COMBINED, false), (COMBINED_RANGE, true)] {+ assert!(Descriptor::parse(bytes).is_multi_axis_controller());+ for (index, axis) in layout(bytes).axes.iter().enumerate() {+ assert_eq!(*axis, field(1, 16 * index as u32, 16, (-350, 350), relative), "axis {index}");+ }+ }+ }++ #[test]+ fn axes_after_the_buttons_start_after_the_buttons() {+ let layout = layout(BUTTONS_FIRST);+ assert_eq!(layout.axes[0], field(1, 8, 16, (-32768, 32767), true));+ assert_eq!(layout.axes[5], field(1, 8 + 5 * 16, 16, (-32768, 32767), true));+ // A report: buttons 0b101, then X = -100, Rz = 32767; the rest 0.+ let mut report = vec![1, 0b101];+ report.extend((-100_i16).to_le_bytes());+ report.extend([0; 8]);+ report.extend(32767_i16.to_le_bytes());+ let decoded = layout.decode(&report).expect("report 1 carries the axes");+ assert_eq!(decoded.axes, axes(&[(0, -1), (1, 0), (2, 0), (3, 0), (4, 0), (5, 350)]));+ // The same report carries buttons 1 to 8: 1 and 3 are down.+ assert_eq!(decoded.buttons, Some(0b101));+ }++ #[test]+ fn unnumbered_unsigned_axes_after_padding_are_centred() {+ let layout = layout(UNNUMBERED_UNSIGNED);+ assert!(!layout.numbered);+ assert_eq!(layout.axes[0], field(0, 8, 8, (0, 255), false));+ assert_eq!(layout.axes[2], field(0, 24, 8, (0, 255), false));+ assert_eq!(layout.axes[3], None);+ // PUSH and POP: Rz has its own range, and the size and count it was declared with.+ assert_eq!(layout.axes[5], field(0, 32, 8, (0, 127), false));+ // No id byte: padding, X at its minimum, Y at the top, Z near the middle, Rz at the top.+ let decoded = layout.decode(&[0xEE, 0, 255, 128, 127]).expect("one report carries everything");+ assert_eq!(decoded.axes, axes(&[(0, -350), (1, 350), (2, 1), (5, 350)]));+ }++ #[test]+ fn other_interfaces_are_not_3d_mice() {+ for bytes in [KEYBOARD, MOUSE, &[][..]] {+ let descriptor = Descriptor::parse(bytes);+ assert!(!descriptor.is_multi_axis_controller());+ assert_eq!(descriptor.layout(), None);+ }+ // A mouse's X and Y aren't axes, even though the generic desktop usages are the same.+ assert!(Descriptor::parse(MOUSE).axes.iter().all(Option::is_none));+ }++ #[test]+ fn an_end_collection_closes_the_controller() {+ // X Y Z in the controller; Rx in a top-level Mouse collection after it isn't the+ // controller's.+ let bytes =+ [+ &controller(&[+ 0x85, 0x01, 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x03, 0x09, 0x30, 0x09, 0x31, 0x09, 0x32, 0x81, 0x02,+ ])[..],+ &[0x05, 0x01, 0x09, 0x02, 0xA1, 0x01, 0x85, 0x02, 0x09, 0x33, 0x75, 0x10, 0x95, 0x01, 0x81, 0x02, 0xC0],+ ]+ .concat();+ let layout = layout(&bytes);+ assert!(layout.axes[0].is_some());+ assert_eq!(layout.axes[3], None);+ }++ #[test]+ fn decodes_separate_reports_and_ignores_short_ones_and_padding() {+ let layout = Layout::default();+ assert_eq!(layout.decode(&[1, 1, 2]), None);+ assert_eq!(layout.decode(&[]), None);+ assert_eq!(layout.decode(&[3, 1, 0, 0, 0, 0, 0]), None);+ assert_eq!(layout.decode(&[1, 0x9c, 0xff, 0x2c, 0x01, 0, 0]), Some(Report { axes: axes(&[(0, -100), (1, 300), (2, 0)]), buttons: None }));+ assert_eq!(layout.decode(&[2, 0, 0, 1, 0, 0xff, 0xff]), Some(Report { axes: axes(&[(3, 0), (4, 1), (5, -1)]), buttons: None }));+ // A padded translation report: its padding is not rotation.+ assert_eq!(layout.decode(&[1, 1, 0, 2, 0, 3, 0, 9, 9, 9, 9, 9, 9]), Some(Report { axes: axes(&[(0, 1), (1, 2), (2, 3)]), buttons: None }));+ }++ #[test]+ fn combined_reports_carry_both_groups() {+ let layout = layout(COMBINED);+ let report = [1, 0x9c, 0xff, 0x2c, 0x01, 0, 0, 1, 0, 0, 0, 0xff, 0xff, 0, 0];+ assert_eq!(layout.decode(&report).map(|r| r.axes), Some(axes(&[(0, -100), (1, 300), (2, 0), (3, 1), (4, 0), (5, -1)])));+ // One byte short of Rz: dropped whole rather than half read.+ assert_eq!(layout.decode(&report[..12]), None);+ }++ #[test]+ fn a_group_spread_over_reports_reports_only_what_each_carries() {+ // X in report 1, Y in report 2: each report says nothing about the other axis.+ let layout = layout(&controller(&[+ 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x01, //+ 0x85, 0x01, 0x09, 0x30, 0x81, 0x02, // report 1: X+ 0x85, 0x02, 0x09, 0x31, 0x81, 0x02, // report 2: Y+ ]));+ assert_eq!(layout.decode(&[1, 100, 0]).map(|r| r.axes), Some(axes(&[(0, 100)])));+ assert_eq!(layout.decode(&[2, 200, 0]).map(|r| r.axes), Some(axes(&[(1, 200)])));+ }++ #[test]+ fn a_short_report_is_dropped_whole_axes_included() {+ // Report 1: X (16 bits), then a button. A report one byte short has X but not the button:+ // it's damaged, so neither is taken.+ let layout = layout(&controller(&[+ 0x85, 0x01, 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02, // X+ 0x05, 0x09, 0x09, 0x01, 0x15, 0x00, 0x25, 0x01, 0x75, 0x01, 0x81, 0x02, 0x75, 0x07, 0x81, 0x03, // button 1, padding+ ]));+ assert_eq!(layout.decode(&[1, 100, 0]), None);+ assert_eq!(layout.decode(&[1, 100, 0, 1]), Some(Report { axes: axes(&[(0, 100)]), buttons: Some(1) }));+ }++ #[test]+ fn fields_declared_before_the_first_report_id_are_left_out() {+ // X before any report id, then Y in report 1. In a numbered descriptor X would have to be+ // in a report with id 0, which can't exist.+ let layout = layout(&controller(&[+ 0x16, 0xA2, 0xFE, 0x26, 0x5E, 0x01, 0x75, 0x10, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02, // X, no id yet+ 0x85, 0x01, 0x09, 0x31, 0x81, 0x02, // report 1: Y+ ]));+ assert_eq!(layout.axes[0], None);+ assert_eq!(layout.axes[1], field(1, 0, 16, (-350, 350), false));+ assert_eq!(layout.decode(&[0, 100, 0]), None);+ assert_eq!(layout.decode(&[1, 100, 0]).map(|r| r.axes), Some(axes(&[(1, 100)])));+ }++ #[test]+ fn push_and_pop_restore_the_globals_however_deep() {+ // PUSH, a 4-bit constant field, POP: X then takes the pushed 8-bit size, so it starts at+ // bit 4 and is 8 bits wide.+ let pushed = layout(&controller(&[+ 0x15, 0x00, 0x26, 0xFF, 0x00, 0x75, 0x08, 0x95, 0x01, // 0..255, 8 bits, 1 field+ 0xA4, 0x75, 0x04, 0x81, 0x03, 0xB4, // push, 4 constant bits, pop+ 0x09, 0x30, 0x81, 0x02, // X+ ]));+ assert_eq!(pushed.axes[0], field(0, 4, 8, (0, 255), false));+ assert_eq!(pushed.decode(&[0xF0, 0x0F]).map(|r| r.axes), Some(axes(&[(0, 350)])));+ // 20 PUSHes, the Nth saving the size before it and then setting the size to N. Every POP+ // restores what its own PUSH saved: the first POP gives back 19, the 20th gives back 8.+ let mut deep = vec![0x15, 0x00, 0x25, 0x01, 0x95, 0x01, 0x75, 0x08];+ for depth in 1..=20_u8 {+ deep.extend([0xA4, 0x75, depth]);+ }+ deep.extend([0x81, 0x03]); // 20 constant bits at the deepest size+ deep.extend([0xB4, 0x09, 0x31, 0x81, 0x02]); // one POP: Y is 19 bits+ deep.extend([0xB4; 19]);+ deep.extend([0x09, 0x30, 0x81, 0x02]); // 19 more POPs: X is 8 bits+ let deep = layout(&controller(&deep));+ assert_eq!(deep.axes[1].map(|f| (f.bit_offset, f.bits)), Some((20, 19)));+ assert_eq!(deep.axes[0].map(|f| (f.bit_offset, f.bits)), Some((39, 8)));+ }++ #[test]+ fn a_long_item_is_skipped_whole() {+ // A long item (prefix 0xFE, 3 data bytes) in front changes nothing.+ let with_long_item = [&[0xFE, 0x03, 0x00, 0x01, 0x02, 0x03][..], COMBINED].concat();+ assert_eq!(layout(&with_long_item), layout(COMBINED));+ }++ #[test]+ fn negative_and_one_byte_ranges_keep_their_signs() {+ // -127..127 in one-byte items: 0x81 is -127, the bottom of the range.+ let one_byte = layout(&controller(&[0x15, 0x81, 0x25, 0x7F, 0x75, 0x08, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]));+ assert_eq!(one_byte.axes[0].map(|f| (f.logical_min, f.logical_max)), Some((-127, 127)));+ assert_eq!(one_byte.decode(&[0x81]).map(|r| r.axes), Some(axes(&[(0, -350)])));+ // -128..-1: a negative maximum stays negative, so 0xFF (-1) is the top.+ let negative = layout(&controller(&[0x15, 0x80, 0x25, 0xFF, 0x75, 0x08, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]));+ assert_eq!(negative.axes[0].map(|f| f.logical_max), Some(-1));+ assert_eq!(negative.decode(&[0xFF]).map(|r| r.axes), Some(axes(&[(0, 350)])));+ }++ #[test]+ fn ranges_scale_to_full_scale() {+ let f = |min, max, bits| Field { report_id: 0, bit_offset: 0, bits, logical_min: min, logical_max: max, relative: false };+ assert_eq!(f(-350, 350, 16).scaled(-350), -350);+ assert_eq!(f(-350, 350, 16).scaled(123), 123);+ assert_eq!(f(-32768, 32767, 16).scaled(32767), 350);+ assert_eq!(f(-32768, 32767, 16).scaled(-32768), -350);+ assert_eq!(f(0, 1023, 10).scaled(0), -350);+ assert_eq!(f(0, 1023, 10).scaled(1023), 350);+ // No usable range: passed through, clamped to 16 bits.+ assert_eq!(f(0, 0, 32).scaled(40), 40);+ assert_eq!(f(5, 5, 32).scaled(1 << 20), i16::MAX);+ // Past the declared range: beyond ±350, but never i16::MIN, whose negation overflows.+ assert_eq!(f(-350, 350, 32).scaled(700), 700);+ assert_eq!(f(-350, 350, 32).scaled(-(1 << 30)), -i16::MAX);+ assert_eq!(f(5, 5, 32).scaled(-(1 << 20)), -i16::MAX);+ // Unsigned maxima: with a minimum of 0, 0x26 0xFF 0xFF is 65535 and the 4-byte+ // 0x27 0xFF 0xFF 0xFF 0xFF is 4294967295, so full deflection of a 32-bit field is 350.+ let two_byte = layout(&controller(&[0x15, 0x00, 0x26, 0xFF, 0xFF, 0x75, 0x10, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]));+ assert_eq!(two_byte.axes[0].map(|f| f.logical_max), Some(65535));+ assert_eq!(two_byte.decode(&[0xFF, 0xFF]).map(|r| r.axes), Some(axes(&[(0, 350)])));+ let four_byte = layout(&controller(&[0x15, 0x00, 0x27, 0xFF, 0xFF, 0xFF, 0xFF, 0x75, 0x20, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]));+ assert_eq!(four_byte.axes[0].map(|f| f.logical_max), Some(4_294_967_295));+ assert_eq!(four_byte.decode(&[0xFF; 4]).map(|r| r.axes), Some(axes(&[(0, 350)])));+ }++ #[test]+ fn a_field_must_be_1_to_32_bits_wide() {+ // Fields are public, so a hand-built one can be any width; reading it mustn't panic.+ for bits in [0, 33, 64, 65, u32::MAX] {+ let layout =+ Layout { axes: [field(0, 0, bits, (-1, 1), false), None, None, None, None, None], buttons: [None; MAX_BUTTONS], numbered: false };+ assert_eq!(layout.decode(&[0; 16]), None, "{bits} bits");+ }+ // Nor can any range: the extremes of i64 don't overflow the scaling.+ for (min, max) in [(i64::MIN, i64::MAX), (i64::MIN, 0), (0, i64::MAX), (i64::MAX, i64::MIN)] {+ for (bits, report) in [(1, [0xFF; 4]), (32, [0xFF; 4]), (32, [0; 4])] {+ let layout = Layout {+ axes: [field(0, 0, bits, (min, max), false), None, None, None, None, None],+ buttons: [None; MAX_BUTTONS],+ numbered: false,+ };+ assert!(layout.decode(&report).is_some(), "{min}..{max}, {bits} bits");+ }+ }+ }++ #[test]+ fn fields_reach_the_end_of_the_biggest_report_and_no_further() {+ // An 8-bit X after 514 bytes of padding is still inside a report.+ let far = layout(&controller(&[0x15, 0x00, 0x26, 0xFF, 0x00, 0x75, 0x08, 0x96, 0x02, 0x02, 0x81, 0x03, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02]));+ assert_eq!(far.axes[0].map(|f| f.bit_offset), Some(514 * 8));+ let mut report = vec![0; 515];+ if let Some(last) = report.last_mut() {+ *last = 0xFF;+ }+ assert_eq!(far.decode(&report).map(|r| r.axes), Some(axes(&[(0, 350)])));+ // A 32-bit X that ends exactly at the last bit is kept; one byte later it's outside.+ let at_end = |padding: u16| {+ let [low, high] = padding.to_le_bytes();+ Descriptor::parse(&controller(&[0x75, 0x08, 0x96, low, high, 0x81, 0x03, 0x75, 0x20, 0x95, 0x01, 0x09, 0x30, 0x81, 0x02])).layout()+ };+ assert_eq!(at_end(4092).and_then(|l| l.axes[0]).map(|f| f.bit_offset), Some(4092 * 8));+ assert_eq!(at_end(4093), None);+ }++ #[test]+ fn truncated_and_hostile_input_never_panics() {+ for bytes in [SPLIT, COMBINED, BUTTONS_FIRST, UNNUMBERED_UNSIGNED] {+ for end in 0..=bytes.len() {+ if let Some(layout) = Descriptor::parse(&bytes[..end]).layout() {+ let _ = layout.decode(&[1, 2, 3]);+ }+ }+ }+ // Long item with a length running past the end, huge usage ranges and counts, deep nesting,+ // pops without pushes, pushes without pops, 32-bit fields at the end of the biggest report.+ let _ = Descriptor::parse(&[0xFE, 0xFF, 0x00, 0x01]);+ let _ = Descriptor::parse(&[0x05, 0x01, 0x1B, 0, 0, 0, 0, 0x2B, 0xFF, 0xFF, 0xFF, 0xFF, 0x81, 0x06]);+ let _ = Descriptor::parse(&controller(&[0x77, 0xFF, 0xFF, 0xFF, 0xFF, 0x97, 0xFF, 0xFF, 0xFF, 0xFF, 0x09, 0x30, 0x81, 0x02]));+ let _ = Descriptor::parse(&controller(&[0x75, 0x20, 0x96, 0xFF, 0x03, 0x09, 0x30, 0x81, 0x02, 0x09, 0x31, 0x81, 0x02]));+ let _ = Descriptor::parse(&[0xC0; 64]);+ let _ = Descriptor::parse(&[0xA1; 64]);+ let _ = Descriptor::parse(&[0xB4; 64]);+ let _ = Descriptor::parse(&[0xA4; MAX_DESCRIPTOR_BYTES * 2]);+ let mut state = 0x2545_F491_4F6C_DD1D_u64;+ let mut next = || {+ state ^= state << 13;+ state ^= state >> 7;+ state ^= state << 17;+ state.to_le_bytes()[0]+ };+ for _ in 0..500 {+ let bytes: Vec<u8> = [0x05, 0x01, 0x09, 0x08, 0xA1, 0x01].into_iter().chain((0..64).map(|_| next())).collect();+ let report: Vec<u8> = (0..16).map(|_| next()).collect();+ if let Some(layout) = Descriptor::parse(&bytes).layout() {+ let _ = layout.decode(&report);+ }+ }+ }+}diff --git a/crates/space-mouse/src/lib.rs b/crates/space-mouse/src/lib.rsnew file mode 100644index 0000000000..6ab8099db1--- /dev/null+++ b/crates/space-mouse/src/lib.rs@@ -0,0 +1,15 @@+//! 3D mouse input that doesn't depend on how the device is read or what the motion drives. The+//! apps open the device their own way (hidraw on Linux, hidapi on Windows), pass its report+//! descriptor to [`Descriptor::parse`] and each input report to [`Layout::decode`], and apply the+//! six axes and the buttons they get back to their own camera and commands.+//!+//! Any device that declares a HID Multi-axis Controller is read the same way: 3Dconnexion's,+//! which send translation and rotation in two reports and their buttons in a third, and homemade+//! ones, which often send all six axes in one report, sometimes after their buttons. The+//! descriptor says where each axis and button is.+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]+#![forbid(unsafe_code)]++mod descriptor;++pub use descriptor::{Descriptor, FULL_SCALE, Field, Layout, MAX_BUTTONS, Report};diff --git a/xtask/src/layers.rs b/xtask/src/layers.rsindex 2118c8e0dd..7bc55bf974 100644--- a/xtask/src/layers.rs+++ b/xtask/src/layers.rs@@ -36,6 +36,8 @@ impl Class {/// prefix.pub const TABLE: &[(&str, Class)] = &[("geom", Class::Layer(0)),+ // 3D mouse descriptors and reports (no workspace dependencies; the apps read the device)+ ("space-mouse", Class::Layer(0)),// the derive macros (proc-macro, no workspace dependencies)("derive", Class::Standalone),("sketch", Class::Layer(1)),