Fix SpaceMouse detection failing when the HID backend reports no product string

[rwiltz]

Description

QA reported that isaaclab teleop run --teleop_device spacemouse aborts with
No device found by SpaceMouse. Is the device connected? while a SpaceMouse Compact
(256f:c635) is connected and visible on /dev/hidraw4, even after applying the
sudo chmod 666 /dev/hidraw<#> workaround our teleoperation guide documents.

Root cause

The hidapi wheel we depend on bundles a libusb-backed HID backend, not the hidraw one:

  $ readelf -d .venv/.../hid.cpython-312-x86_64-linux-gnu.so | grep NEEDED
    NEEDED  libusb-1-150b88da.0.so.0.1.0
  $ python -c "import hid; print(hid.enumerate()[0]['path'])"
    b'7-6:1.0'      # a USB path, not /dev/hidraw*

That backend reaches the device through /dev/bus/usb, and it can only read USB string
descriptors for devices the process is allowed to open. Without that access, hid.enumerate()
still lists the device but returns product_string == ''. Detection compared the product
string against an exact list:

  if device["product_string"] == "SpaceMouse Compact" or ...

so an empty string matched nothing and the device was reported as absent. The documented
chmod 666 /dev/hidraw<#> grants nothing to this backend, which is why the workaround
appeared to have no effect.

This reproduces on any USB HID device the user lacks USB permissions for — no SpaceMouse
required:

  0x048d:0x5702 product_string='' -> open failed        # kernel HID_NAME is "ITE Tech. Inc. ITE Device"
  0x1050:0x0407 product_string='YubiKey OTP+FIDO+CCID'  # has a udev rule, so strings resolve

The exact match is fragile in the other direction too: on a hidraw-backed hidapi the
product string can come back as the kernel's combined name, e.g.
3Dconnexion SpaceMouse Compact, which also fails to equal SpaceMouse Compact.

Changes

• Se2SpaceMouse/Se3SpaceMouse now match enumerated devices by USB vendor/product id
  (SPACEMOUSE_USB_IDS in devices/spacemouse/utils.py, ids taken from the USB ID
  repository at https://www.linux-usb.org/usb.ids), covering exactly the models each device
  class already supported. The product string is kept as a fallback so devices with ids we
  do not list keep working, and is matched both verbatim and with a leading 3Dconnexion
  stripped.
• The "no device found" error now lists the enumerated HID devices and explains that the
  backend needs access to /dev/bus/usb, not /dev/hidraw*.
• A detected-but-unopenable device now raises that same guidance instead of a bare
  OSError: open failed.
• teleop_imitation.rst: replaced the ineffective chmod 666 /dev/hidraw<#> tip with a
  udev rule for vendor 256f (covering both SUBSYSTEM=="usb" and hidraw), and corrected
  the Docker recipe to mount /dev/bus/usb with the matching device_cgroup_rules.

Fixes # (issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)

Release backport

• Backport this pull request to the active release branch after it merges into develop

Checklist

Docker and GPU tests run on demand. Push the commits you want tested, then
comment run-ci on the pull request.

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have added a changelog fragment under source/<pkg>/changelog.d/ for every touched package (do not edit CHANGELOG.rst or bump extension.toml — CI handles that)
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

The PR makes SpaceMouse discovery independent of optional HID product strings and improves permission diagnostics. It also completes the prior review fixes:

• Discovery continues after an inaccessible supported device and can open a later usable model.
• The documented udev rules now scope access to local-seat users and the plugdev group instead of every local account.
• Constructor tests cover USB-ID detection, continued discovery, and actionable failure messages.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/devices/spacemouse/utils.py	Adds USB-ID and normalized-product-name resolution plus clearer discovery and permission diagnostics.
source/isaaclab/isaaclab/devices/spacemouse/se2_spacemouse.py	Uses shared device resolution and continues discovery after supported devices fail to open.
source/isaaclab/isaaclab/devices/spacemouse/se3_spacemouse.py	Uses shared device resolution, preserves the resolved model name, and continues to later candidates after open failures.
docs/source/overview/imitation-learning/teleop_imitation.rst	Replaces global USB permissions with group/local-seat access and documents the libusb container configuration.
source/isaaclab/test/devices/test_device_constructors.py	Covers missing and prefixed product strings, fallback to a later accessible device, and diagnostic errors.

_{Reviews (2): Last reviewed commit: "Address review feedback on SpaceMouse di..." | Re-trigger Greptile}

[isaaclab-review-bot]

Isaac Lab Review Bot

The USB-id-based SpaceMouse detection and permission guidance are coherent overall, but the updated teleoperation tip introduces contradictory compatibility guidance for older supported devices.

• Design and architecture: The shared detection helpers centralize USB-id and product-name resolution while preserving distinct supported-device sets for the SE(2) and SE(3) implementations. No architectural issue was identified.
• API: Constructor signatures and exception types remain unchanged, and USB-id matching extends the previous product-string behavior. However, the documentation now gives setup instructions for SpaceNavigator for Notebooks while the same tip still claims only SpaceMouse Wireless and Compact are compatible; the documented support surface must be made consistent.
• Implementation: The changed detection paths correctly map known USB identifiers to the report-layout names consumed by the listeners, retain product-string fallback behavior, and preserve the original open failure through exception chaining. The actionable issue is limited to reconciling the contradictory supported-model statements in the teleoperation documentation.

Minor fixes needed. Posted 1 actionable finding inline.

Automated review; human maintainers own approval decisions.

[rwiltz]

@greptile

[rwiltz]

run-ci