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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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

On Windows and macOS the reader opened the first 3D-mouse interface it
could and read it until it failed. A 3Dconnexion Universal Receiver with
nothing paired opens fine, has a valid layout and never fails, so it kept
the reader for good. A SpaceMouse on a cable next to it was never read
("Not calibrated (hid 256f:c652)", every axis at zero).

The reader now opens every candidate and follows the one in use. The
first is followed from the start, as before. Another takes over once it
shows use (an axis off zero or a button down) while the followed one has
shown none for STALE_AFTER, so two devices moved together don't trade
the reading. A candidate that fails is dropped; if it was the followed
one the reading resets and the next is read. With one device the reader
behaves as before, down to the 100 ms read timeout. Several take 10 ms
turns, and reports queue in the system meanwhile.

The selection is `follow()`, written against a small `ReportSource`
trait, so it is tested with simulated devices on every platform: an idle
receiver next to a SpaceMouse, two devices in use at once, and devices
failing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* 3D mouse: a press that makes a device the one in use counts as a press

Since #3825 a HID device's first button report after it connects is its
baseline: a button down in it is held, not pressed. A device taking over
from another one was connected at that moment, so the press that took
over was swallowed. With an idle Universal Receiver found first, that is
the first button press on the SpaceMouse.

follow() now keeps the buttons each candidate last reported while another
was read, and the reader hands them to the reading as the baseline when
that candidate takes over. A device that reported no buttons before it
took over keeps the held-not-pressed rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Tyler Chiriboga <18270301+Tyler-Chiriboga@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
authored and GitHub committed 2026-10-25 01:18:34 +00:00
1 parent ecf57d131a
commit 2ff17c0fcb
2 files changed
+316 -28

No files matched your search

+311 -28
View File
@@ -521,6 +521,119 @@ fn hid_api() -> hidapi::HidResult<HidApi> {
HidApi::new()
}
/// An open 3D-mouse interface: the device, how its reports are laid out, and its vendor and
/// product ids.
#[cfg(any(target_os = "windows", target_os = "macos", test))]
struct Candidate<D> {
device: D,
layout: Layout,
ids: (u16, u16),
}
/// Input reports read with a timeout in milliseconds: hidapi's devices, and the tests' simulated
/// ones. `Ok(0)` is a timeout; an error means the device is gone.
#[cfg(any(target_os = "windows", target_os = "macos", test))]
trait ReportSource {
fn read_report(&self, report: &mut [u8], timeout_ms: i32) -> Result<usize, String>;
}
#[cfg(any(target_os = "windows", target_os = "macos"))]
impl ReportSource for hidapi::HidDevice {
fn read_report(&self, report: &mut [u8], timeout_ms: i32) -> Result<usize, String> {
self.read_timeout(report, timeout_ms).map_err(|error| error.to_string())
}
}
/// What following the candidates tells the reader.
#[cfg(any(target_os = "windows", target_os = "macos", test))]
enum Followed<'a> {
/// This device is the one read now, so its calibration applies. With the buttons it last
/// reported down, when it reported them while another was read: they are its baseline, so a
/// press that makes it the device in use counts as a press, not as a button already held.
Device((u16, u16), Option<u32>),
/// An input report from it.
Report(&'a Layout, &'a [u8]),
/// It is gone.
Gone,
}
/// Whether a report shows its device in use: an axis off zero or a button down. A cap at rest
/// sends zeros at most, and an idle 3Dconnexion Universal Receiver sends nothing at all.
#[cfg(any(target_os = "windows", target_os = "macos", test))]
fn shows_use(layout: Layout, report: &[u8]) -> bool {
layout.decode(report).is_some_and(|decoded| decoded.axes.iter().flatten().any(|axis| *axis != 0) || decoded.buttons.is_some_and(|down| down != 0))
}
/// Reads every candidate and follows the one in use (#3988). The first is followed from the start,
/// as when it was the only one read. Another takes over once it shows use while the followed one
/// has shown none for `STALE_AFTER`, so two devices moved together don't hand the reading back
/// and forth. An idle Universal Receiver opens fine and never fails; read on its own it kept a
/// SpaceMouse next to it from ever being read. A candidate that fails is dropped. If it was the
/// followed one, the reading is reset and the next takes over. Returns when none is left.
#[cfg(any(target_os = "windows", target_os = "macos", test))]
fn follow<D: ReportSource>(mut candidates: Vec<Candidate<D>>, now: impl Fn() -> Instant, mut emit: impl FnMut(Followed<'_>)) {
let Some(first) = candidates.first() else { return };
emit(Followed::Device(first.ids, None));
let mut followed = 0;
// When the followed device last showed use.
let mut used_at: Option<Instant> = None;
// The buttons each candidate last reported down, by index, as long as it has reported them.
let mut buttons: Vec<Option<u32>> = candidates.iter().map(|_| None).collect();
let mut report = [0_u8; REPORT_BUFFER_BYTES];
while !candidates.is_empty() {
// One device is waited on as before; several take turns, briefly, so none waits behind
// an idle one. Reports queue in the system meanwhile, so none is lost.
let timeout_ms = if candidates.len() == 1 { 100 } else { 10 };
let mut index = 0;
while let Some(candidate) = candidates.get(index) {
match candidate.device.read_report(&mut report, timeout_ms) {
Ok(0) => {}
Ok(size) => {
let bytes = report.get(..size).unwrap_or_default();
let before = buttons.get(index).copied().flatten();
if let (Some(seen), Some(down)) = (buttons.get_mut(index), candidate.layout.decode(bytes).and_then(|decoded| decoded.buttons)) {
*seen = Some(down);
}
if shows_use(candidate.layout, bytes) {
let at = now();
if index != followed && used_at.is_none_or(|used| at.duration_since(used) >= STALE_AFTER) {
let (vendor, product) = candidate.ids;
log::info!("3D mouse: reading {vendor:04x}:{product:04x}, the device in use");
followed = index;
emit(Followed::Device(candidate.ids, before));
}
if index == followed {
used_at = Some(at);
}
}
if index == followed {
emit(Followed::Report(&candidate.layout, bytes));
}
}
Err(error) => {
log::info!("3D mouse disconnected: {error}");
candidates.remove(index);
if index < buttons.len() {
buttons.remove(index);
}
if index == followed {
emit(Followed::Gone);
followed = 0;
used_at = None;
if let Some(next) = candidates.first() {
emit(Followed::Device(next.ids, buttons.first().copied().flatten()));
}
} else if index < followed {
followed -= 1;
}
continue;
}
}
index += 1;
}
}
}
#[cfg(any(target_os = "windows", target_os = "macos"))]
fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
let Ok(mut api) = hid_api() else {
@@ -528,36 +641,38 @@ fn reader(ctx: Context, shared: Arc<Mutex<Reading>>) {
return;
};
loop {
if let Some((device, layout, ids)) = candidates(&mut api).into_iter().find_map(|path| {
let device = api
.open_path(&path)
.inspect_err(|error| {
// On macOS: missing Input Monitoring permission, or the 3DxWare helper holding the device.
// The driver having the device is the reason it cannot be opened, not a problem.
if !DRIVER_CONNECTED.load(Ordering::Relaxed) && !DRIVER_REGISTERED.load(Ordering::Relaxed) {
log::warn!("3D mouse: cannot open the device: {error}");
}
})
.ok()?;
// Read when the device was opened, from this device alone.
let info = device.get_device_info().ok()?;
let layout = device_layout(&device, info.vendor_id())?;
Some((device, layout, (info.vendor_id(), info.product_id())))
}) {
connected(&ctx, &shared, Source::Hid(Some(ids)));
let mut report = [0_u8; REPORT_BUFFER_BYTES];
loop {
match device.read_timeout(&mut report, 100) {
Ok(0) => {}
Ok(size) => publish(&ctx, &shared, layout, report.get(..size).unwrap_or_default()),
Err(error) => {
log::info!("3D mouse disconnected: {error}");
break;
}
let open: Vec<_> = candidates(&mut api)
.into_iter()
.filter_map(|path| {
let device = api
.open_path(&path)
.inspect_err(|error| {
// On macOS: missing Input Monitoring permission, or the 3DxWare helper holding the device.
// The driver having the device is the reason it cannot be opened, not a problem.
if !DRIVER_CONNECTED.load(Ordering::Relaxed) && !DRIVER_REGISTERED.load(Ordering::Relaxed) {
log::warn!("3D mouse: cannot open the device: {error}");
}
})
.ok()?;
// Read when the device was opened, from this device alone.
let info = device.get_device_info().ok()?;
let layout = device_layout(&device, info.vendor_id())?;
Some(Candidate { device, layout, ids: (info.vendor_id(), info.product_id()) })
})
.collect();
follow(open, Instant::now, |event| match event {
Followed::Device(ids, buttons) => {
connected(&ctx, &shared, Source::Hid(Some(ids)));
// Taken over from another device: what it reported meanwhile is its baseline.
if let Some(buttons) = buttons
&& let Ok(mut reading) = shared.lock()
{
reading.set_buttons(buttons);
}
}
reset(&ctx, &shared);
}
Followed::Report(layout, report) => publish(&ctx, &shared, *layout, report),
Followed::Gone => reset(&ctx, &shared),
});
std::thread::sleep(RETRY_AFTER);
}
}
@@ -1294,6 +1409,174 @@ mod tests {
assert!(shared.lock().unwrap().arrived, "but the report did arrive");
}
/// A simulated 3D-mouse interface. Each read takes the next scripted step, a report or a
/// timeout (empty), and sets the shared clock to the step's time. Once the script runs out,
/// the device is unplugged.
struct Simulated<'a> {
clock: &'a std::cell::Cell<Instant>,
start: Instant,
steps: std::cell::RefCell<std::collections::VecDeque<(u64, Vec<u8>)>>,
}
impl ReportSource for Simulated<'_> {
fn read_report(&self, report: &mut [u8], _timeout_ms: i32) -> Result<usize, String> {
let (ms, bytes) = self.steps.borrow_mut().pop_front().ok_or_else(|| "unplugged".to_string())?;
self.clock.set(self.start + Duration::from_millis(ms));
report.get_mut(..bytes.len()).ok_or_else(|| "report too long".to_string())?.copy_from_slice(&bytes);
Ok(bytes.len())
}
}
#[derive(Debug, PartialEq)]
enum Seen {
/// The product id now read.
Device(u16),
/// The buttons it had reported down before it was read, its baseline.
Baseline(u32),
/// A report published, the product id read when it was, and whether it showed use.
Report(u16, Vec<u8>, bool),
Gone,
}
/// Follows simulated devices, given as (product id, scripted steps in ms), and returns what
/// the reader was told.
fn follow_simulated(devices: &[(u16, &[(u64, &[u8])])]) -> Vec<Seen> {
follow_simulated_with(Layout::default(), devices)
}
/// As `follow_simulated`, with every device's reports laid out as `layout`.
fn follow_simulated_with(layout: Layout, devices: &[(u16, &[(u64, &[u8])])]) -> Vec<Seen> {
let start = Instant::now();
let clock = std::cell::Cell::new(start);
let candidates = devices
.iter()
.map(|(product, steps)| Candidate {
device: Simulated {
clock: &clock,
start,
steps: std::cell::RefCell::new(steps.iter().map(|(ms, bytes)| (*ms, bytes.to_vec())).collect()),
},
layout,
ids: (0x256f, *product),
})
.collect();
let (mut seen, mut read) = (Vec::new(), 0);
follow(
candidates,
|| clock.get(),
|event| match event {
Followed::Device((_, product), buttons) => {
read = product;
seen.push(Seen::Device(product));
seen.extend(buttons.map(Seen::Baseline));
}
Followed::Report(layout, bytes) => seen.push(Seen::Report(read, bytes.to_vec(), shows_use(*layout, bytes))),
Followed::Gone => seen.push(Seen::Gone),
},
);
seen
}
const RECEIVER: u16 = 0xc652;
const SPACEMOUSE: u16 = 0xc63a;
const PUSH_X: &[u8] = &[1, 100, 0, 0, 0, 0, 0];
const AT_REST: &[u8] = &[1, 0, 0, 0, 0, 0, 0];
const TILT: &[u8] = &[2, 0, 0, 50, 0, 0, 0];
/// #3988: a Universal Receiver with nothing paired is found first and never fails, and a wired
/// SpaceMouse next to it was never read. The receiver is followed only until the SpaceMouse
/// moves; the SpaceMouse's reports, its zeros included, are read from then on.
#[test]
fn an_idle_receiver_does_not_keep_a_spacemouse_from_being_read() {
let receiver: &[(u64, &[u8])] = &[(0, &[]), (10, &[]), (20, &[]), (30, &[])];
let spacemouse: &[(u64, &[u8])] = &[(5, &[]), (15, PUSH_X), (25, AT_REST), (35, TILT)];
assert_eq!(
follow_simulated(&[(RECEIVER, receiver), (SPACEMOUSE, spacemouse)]),
[
Seen::Device(RECEIVER),
Seen::Device(SPACEMOUSE),
Seen::Report(SPACEMOUSE, PUSH_X.to_vec(), true),
Seen::Report(SPACEMOUSE, AT_REST.to_vec(), false),
Seen::Report(SPACEMOUSE, TILT.to_vec(), true),
// The receiver is unplugged first, then the SpaceMouse, the one being read.
Seen::Gone,
]
);
}
/// Two devices in use at once don't trade the reading: the other takes over only after the
/// followed one has shown no use for `STALE_AFTER`. A report at rest or with an id the layout
/// doesn't know shows no use, and only the followed device's reports are published.
#[test]
fn another_device_takes_over_only_once_the_followed_one_is_still() {
let unknown_id: &[u8] = &[0x17, 80];
let first: &[(u64, &[u8])] = &[(0, PUSH_X), (100, AT_REST), (200, &[])];
let second: &[(u64, &[u8])] = &[(50, PUSH_X), (150, unknown_id), (250, TILT)];
assert_eq!(
follow_simulated(&[(0xc635, first), (SPACEMOUSE, second)]),
[
Seen::Device(0xc635),
Seen::Report(0xc635, PUSH_X.to_vec(), true),
// The second moves 50 ms after the first did: not yet. The first's own rest
// report is read, and the second's unknown report is not.
Seen::Report(0xc635, AT_REST.to_vec(), false),
// 250 ms after the first last moved, the second takes over.
Seen::Device(SPACEMOUSE),
Seen::Report(SPACEMOUSE, TILT.to_vec(), true),
Seen::Gone,
]
);
}
/// One device is read as before: every report, until it fails. When the followed one of
/// several fails, the reading is reset and the next one is read.
#[test]
fn a_device_that_fails_hands_the_reading_to_the_next() {
let only: &[(u64, &[u8])] = &[(0, &[]), (1, AT_REST), (2, &[0x17, 80])];
assert_eq!(
follow_simulated(&[(SPACEMOUSE, only)]),
[
Seen::Device(SPACEMOUSE),
Seen::Report(SPACEMOUSE, AT_REST.to_vec(), false),
Seen::Report(SPACEMOUSE, vec![0x17, 80], false),
Seen::Gone
]
);
let unplugged: &[(u64, &[u8])] = &[];
let next: &[(u64, &[u8])] = &[(1, PUSH_X)];
assert_eq!(
follow_simulated(&[(SPACEMOUSE, unplugged), (RECEIVER, next)]),
[Seen::Device(SPACEMOUSE), Seen::Gone, Seen::Device(RECEIVER), Seen::Report(RECEIVER, PUSH_X.to_vec(), true), Seen::Gone]
);
assert_eq!(follow_simulated(&[]), []);
}
/// A button press that makes a device the one in use is a press. The buttons it reported while
/// another was read are its baseline; the reader keeps them, so the press isn't taken for a
/// button already held, as a device's first button report is.
#[test]
fn a_press_that_takes_over_counts_as_a_press() {
let mut layout = Layout::default();
layout.buttons[0] =
Some(solidcraft_space_mouse::Field { report_id: 3, bit_offset: 0, bits: 1, logical_min: 0, logical_max: 1, relative: false });
let (none_down, first_down): (&[u8], &[u8]) = (&[3, 0], &[3, 1]);
let receiver: &[(u64, &[u8])] = &[(0, &[]), (10, &[]), (20, &[])];
let spacemouse: &[(u64, &[u8])] = &[(5, none_down), (15, first_down), (25, &[])];
assert_eq!(
follow_simulated_with(layout, &[(RECEIVER, receiver), (SPACEMOUSE, spacemouse)]),
[Seen::Device(RECEIVER), Seen::Device(SPACEMOUSE), Seen::Baseline(0), Seen::Report(SPACEMOUSE, first_down.to_vec(), true), Seen::Gone,]
);
// What the reader does with that: the press after the baseline is a tap.
let mut reading = Reading { buttons_known: false, ..Reading::new(Instant::now()) };
reading.set_buttons(0);
assert!(decode_report(first_down, layout, &mut reading, Instant::now()));
assert_eq!((reading.buttons, reading.taps), (1, 1));
// Without one, the same report is the baseline: held, not pressed.
let mut unseen = Reading { buttons_known: false, ..Reading::new(Instant::now()) };
assert!(decode_report(first_down, layout, &mut unseen, Instant::now()));
assert_eq!((unseen.buttons, unseen.taps), (1, 0));
}
#[test]
fn a_held_reading_stays_until_the_next_one_and_a_hid_reading_goes_stale() {
let now = Instant::now();
+5
View File
@@ -33,6 +33,11 @@ vendor and product id. Reload with `sudo udevadm control --reload && sudo udevad
replug the device. The Flatpak sandbox does not expose hidraw devices, so the 3D mouse only works
with native builds there for now.
On Windows and macOS, with more than one 3D mouse connected, SolidCraft reads the one in use.
For example, a 3Dconnexion Universal Receiver with nothing paired may sit next to a SpaceMouse
on a cable. The first device found is read until another one moves, and then that one is. The
Navigation page names the device being read, and its calibration applies.
SolidCraft finds the axes from the device's report descriptor, so it doesn't matter how a device
lays them out: translation and rotation in separate reports (3Dconnexion's wired devices), all six
in one (its wireless ones and most homemade devices), after the buttons, or narrower than 16 bits.