Fix SpaceMouse detection failing when the HID backend reports no product string (#7498)

# 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

- [x] <!-- backport-active-release --> 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.

- [x] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./isaaclab.sh --format`
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] 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)
- [x] I have added my name to the `CONTRIBUTORS.md` or my name already
exists there

(cherry picked from commit 2887452)

Author: rwiltz

docs/source/overview/imitation-learning/teleop_imitation.rst

@@ -159,24 +159,41 @@ the key bindings are:
 
 .. tip::
 
-   If the SpaceMouse is not detected, you may need to grant additional user permissions by running ``sudo chmod 666 /dev/hidraw<#>`` where ``<#>`` corresponds to the device index
-   of the connected SpaceMouse.
+   If the SpaceMouse is not detected, you most likely need additional user permissions. The ``hidapi``
+   wheel installed by Isaac Lab bundles a backend that talks to the device over ``libusb``, so it needs
+   read and write access to the USB node under ``/dev/bus/usb`` -- granting access to ``/dev/hidraw*``
+   alone is **not** sufficient, and without USB access the device is enumerated without a product name.
 
-   To determine the device index, list all ``hidraw`` devices by running ``ls -l /dev/hidraw*``.
-   Identify the device corresponding to the SpaceMouse by running ``cat /sys/class/hidraw/hidraw<#>/device/uevent`` on each of the devices listed
-   from the prior step.
+   Grant the permission by installing a udev rule for the 3Dconnexion vendor id:
 
-   We recommend using local deployment of Isaac Lab to use the SpaceMouse. If using container deployment (:ref:`deployment-docker`), you must manually mount the SpaceMouse to the ``isaac-lab-base`` container by
-   adding a ``devices`` attribute with the path to the device in your ``docker-compose.yaml`` file:
+   .. code:: bash
 
-   .. code:: yaml
+      sudo groupadd -f plugdev && sudo usermod -aG plugdev "$USER"
+      sudo tee /etc/udev/rules.d/99-spacemouse.rules <<'EOF'
+      SUBSYSTEM=="usb", ATTR{idVendor}=="256f", TAG+="uaccess", GROUP="plugdev", MODE="0660"
+      KERNEL=="hidraw*", ATTRS{idVendor}=="256f", TAG+="uaccess", GROUP="plugdev", MODE="0660"
+      EOF
+      sudo udevadm control --reload-rules && sudo udevadm trigger
+
+   Then unplug and reconnect the SpaceMouse, and log out and back in so the new group membership
+   applies. The rule grants access to the user on the local seat (``uaccess``) and to members of
+   ``plugdev``, rather than to every account on the machine; the ``plugdev`` membership is what makes
+   it work over SSH, where there is no local seat. Older 3Dconnexion models such as the SpaceNavigator
+   for Notebooks enumerate under the Logitech vendor id, so replace ``256f`` with ``046d`` for those.
 
-      devices:
-         - /dev/hidraw<#>:/dev/hidraw<#>
+   We recommend using local deployment of Isaac Lab to use the SpaceMouse. If using container deployment (:ref:`deployment-docker`), you must give the ``isaac-lab-base`` container access to the USB bus by
+   mounting it and allowing its device cgroup in your ``docker-compose.yaml`` file:
+
+   .. code:: yaml
 
-   where ``<#>`` is the device index of the connected SpaceMouse.
+      volumes:
+         - /dev/bus/usb:/dev/bus/usb
+      device_cgroup_rules:
+         - "c 189:* rmw"
 
-   Isaac Lab is only compatible with the SpaceMouse Wireless and SpaceMouse Compact models from 3Dconnexion.
+   Isaac Lab supports the SpaceMouse Compact, SpaceMouse Wireless and SpaceNavigator for Notebooks
+   from 3Dconnexion. SE(3) teleoperation additionally supports the SpaceNavigator and the
+   3Dconnexion Universal Receiver.
 
 
 

source/isaaclab/changelog.d/rwiltz-fix-spacemouse-detection.rst

@@ -0,0 +1,13 @@
+Fixed
+^^^^^
+
+* Fixed :class:`~isaaclab.devices.Se2SpaceMouse` and :class:`~isaaclab.devices.Se3SpaceMouse` failing with
+  ``No device found by SpaceMouse`` when a supported 3Dconnexion device was connected. Detection matched the
+  HID product string exactly, which the ``libusb`` backend bundled in the ``hidapi`` wheels leaves empty
+  unless the process may open the USB node. Directly attached devices are now matched by their USB vendor
+  and product ids, with the product string kept as a fallback, and the errors raised when a device cannot be
+  found or opened name the enumerated devices and the required permissions.
+* Fixed SpaceMouse discovery giving up when the first supported device could not be opened. Discovery now
+  continues to the remaining devices and only reports the open failures if none of them could be opened.
+* Added the USB identifier of the 3Dconnexion SpaceNavigator, so the device added in :github:`7544` is also
+  detected when the HID backend cannot read its product string.

source/isaaclab/isaaclab/devices/spacemouse/se2_spacemouse.py

@@ -19,7 +19,7 @@
 from isaaclab.utils.array import convert_to_torch
 
 from ..device_base import DeviceBase
-from .utils import convert_buffer
+from .utils import convert_buffer, describe_open_failure, device_not_found_message, resolve_device_name
 
 if TYPE_CHECKING:
     from .se2_spacemouse_cfg import Se2SpaceMouseCfg
@@ -44,6 +44,9 @@ class Se2SpaceMouse(DeviceBase):
 
     """
 
+    SUPPORTED_DEVICES = ("SpaceMouse Compact", "SpaceNavigator for Notebooks")
+    """Product names of the 3Dconnexion models handled by this device."""
+
     def __init__(self, cfg: Se2SpaceMouseCfg):
         """Initialize the spacemouse layer.
 
@@ -115,27 +118,41 @@ def advance(self) -> torch.Tensor:
     def _find_device(self):
         """Find the device connected to computer."""
         found = False
+        enumerated_devices: list = []
+        open_failures: list[str] = []
+        last_error: OSError | None = None
         # implement a timeout for device search
         for _ in range(5):
-            for device in hid.enumerate():
-                if (
-                    device["product_string"] == "SpaceMouse Compact"
-                    or device["product_string"] == "SpaceNavigator for Notebooks"
-                ):
-                    # set found flag
-                    found = True
-                    vendor_id = device["vendor_id"]
-                    product_id = device["product_id"]
-                    # connect to the device
+            enumerated_devices = hid.enumerate()
+            # a supported device that cannot be opened must not hide another one that can, so keep
+            # scanning and only report the failures if no device could be opened at all
+            open_failures = []
+            for device in enumerated_devices:
+                device_name = resolve_device_name(device, self.SUPPORTED_DEVICES)
+                if device_name is None:
+                    continue
+                vendor_id = device["vendor_id"]
+                product_id = device["product_id"]
+                # connect to the device
+                try:
                     self._device.open(vendor_id, product_id)
+                except OSError as exc:
+                    open_failures.append(describe_open_failure(device_name, vendor_id, product_id, exc))
+                    last_error = exc
+                    continue
+                # set found flag
+                found = True
+                break
             # check if device found
             if not found:
                 time.sleep(1.0)
             else:
                 break
         # no device found: return false
         if not found:
-            raise OSError("No device found by SpaceMouse. Is the device connected?")
+            raise OSError(
+                device_not_found_message(self.SUPPORTED_DEVICES, enumerated_devices, open_failures)
+            ) from last_error
 
     def _run_device(self):
         """Listener thread that keeps pulling new messages."""

source/isaaclab/isaaclab/devices/spacemouse/se3_spacemouse.py

@@ -18,7 +18,7 @@
 from scipy.spatial.transform import Rotation
 
 from ..device_base import DeviceBase
-from .utils import convert_buffer
+from .utils import convert_buffer, describe_open_failure, device_not_found_message, resolve_device_name
 
 if TYPE_CHECKING:
     from .se3_spacemouse_cfg import Se3SpaceMouseCfg
@@ -46,6 +46,15 @@ class Se3SpaceMouse(DeviceBase):
 
     """
 
+    SUPPORTED_DEVICES = (
+        "SpaceMouse Compact",
+        "SpaceMouse Wireless",
+        "SpaceNavigator",
+        "SpaceNavigator for Notebooks",
+        "3Dconnexion Universal Receiver",
+    )
+    """Product names of the 3Dconnexion models handled by this device."""
+
     def __init__(self, cfg: Se3SpaceMouseCfg):
         """Initialize the space-mouse layer.
 
@@ -134,32 +143,42 @@ def advance(self) -> torch.Tensor:
     def _find_device(self):
         """Find the device connected to computer."""
         found = False
+        enumerated_devices: list = []
+        open_failures: list[str] = []
+        last_error: OSError | None = None
         # implement a timeout for device search
         for _ in range(5):
-            for device in hid.enumerate():
-                if (
-                    device["product_string"] == "SpaceMouse Compact"
-                    or device["product_string"] == "SpaceMouse Wireless"
-                    or device["product_string"] == "SpaceNavigator for Notebooks"
-                    or device["product_string"] == "3Dconnexion Universal Receiver"
-                    or device["product_string"] == "SpaceNavigator"
-                ):
-                    # set found flag
-                    found = True
-                    vendor_id = device["vendor_id"]
-                    product_id = device["product_id"]
-                    # connect to the device
-                    self._device.close()
+            enumerated_devices = hid.enumerate()
+            # a supported device that cannot be opened must not hide another one that can, so keep
+            # scanning and only report the failures if no device could be opened at all
+            open_failures = []
+            for device in enumerated_devices:
+                device_name = resolve_device_name(device, self.SUPPORTED_DEVICES)
+                if device_name is None:
+                    continue
+                vendor_id = device["vendor_id"]
+                product_id = device["product_id"]
+                # connect to the device
+                try:
                     self._device.open(vendor_id, product_id)
-                    self._device_name = device["product_string"]
+                except OSError as exc:
+                    open_failures.append(describe_open_failure(device_name, vendor_id, product_id, exc))
+                    last_error = exc
+                    continue
+                # set found flag
+                found = True
+                self._device_name = device_name
+                break
             # check if device found
             if not found:
                 time.sleep(1.0)
             else:
                 break
         # no device found: return false
         if not found:
-            raise OSError("No device found by SpaceMouse. Is the device connected?")
+            raise OSError(
+                device_not_found_message(self.SUPPORTED_DEVICES, enumerated_devices, open_failures)
+            ) from last_error
 
     def _run_device(self):
         """Listener thread that keeps pulling new messages."""

source/isaaclab/isaaclab/devices/spacemouse/utils.py

@@ -5,6 +5,11 @@
 
 """Helper functions for SpaceMouse."""
 
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
 # MIT License
 #
 # Copyright (c) 2022 Stanford Vision and Learning Lab and UT Robot Perception and Learning Lab
@@ -41,6 +46,99 @@ def convert_buffer(b1, b2):
     return _scale_to_control(_to_int16(b1, b2))
 
 
+# USB identifiers of the directly attached 3Dconnexion devices, mapped to the product name that
+# selects the HID report layout used by the device listener threads. Identifiers are taken from the
+# community-maintained USB ID repository at https://www.linux-usb.org/usb.ids.
+# Wireless receivers are deliberately left out: their report layout differs from the cabled devices
+# (see the Universal Receiver branch in the listener threads) and is unverified against hardware, so
+# they are matched by product string only.
+SPACEMOUSE_USB_IDS: dict[tuple[int, int], str] = {
+    (0x046D, 0xC626): "SpaceNavigator",
+    (0x256F, 0xC62E): "SpaceMouse Wireless",
+    (0x256F, 0xC635): "SpaceMouse Compact",
+}
+"""Mapping from the ``(vendor_id, product_id)`` of a supported SpaceMouse to its product name."""
+
+
+def resolve_device_name(device: dict[str, Any], supported_names: Sequence[str]) -> str | None:
+    """Resolve the product name of an enumerated HID device against the supported SpaceMouse models.
+
+    USB identifiers are matched first, because the ``hidapi`` wheels bundle a backend that reaches the
+    device through ``libusb`` and reports empty product strings unless the process is allowed to open
+    the USB node. Product strings are only used as a fallback, and are matched both verbatim and with
+    the ``"3Dconnexion "`` prefix that some HID backends prepend stripped off.
+
+    Args:
+        device: An entry returned by :func:`hid.enumerate`.
+        supported_names: Product names accepted by the caller.
+
+    Returns:
+        The matched product name, or None if the device is not a supported SpaceMouse.
+    """
+    name = SPACEMOUSE_USB_IDS.get((device["vendor_id"], device["product_id"]))
+    if name in supported_names:
+        return name
+    product_string = (device.get("product_string") or "").strip()
+    for candidate in (product_string, product_string.removeprefix("3Dconnexion ")):
+        if candidate in supported_names:
+            return candidate
+    return None
+
+
+_PERMISSION_HINT = (
+    " Note that on Linux the bundled HID backend reaches the device through libusb, so the user needs"
+    " read and write access to the USB node under '/dev/bus/usb'; granting access to '/dev/hidraw*'"
+    " alone is not sufficient. See the teleoperation documentation for the required udev rule."
+)
+"""Guidance appended to the discovery errors, which are almost always caused by USB permissions."""
+
+
+def device_not_found_message(
+    supported_names: Sequence[str],
+    enumerated_devices: Sequence[dict[str, Any]],
+    open_failures: Sequence[str] = (),
+) -> str:
+    """Compose the error raised when no supported SpaceMouse could be opened.
+
+    Args:
+        supported_names: Product names accepted by the caller.
+        enumerated_devices: The HID devices reported by :func:`hid.enumerate` during the search.
+        open_failures: Descriptions of the supported devices that were found but could not be opened.
+
+    Returns:
+        An error message naming either the devices that could not be opened, or, when none matched,
+        the supported models and the HID devices that were seen.
+    """
+    if open_failures:
+        return (
+            "Found a supported SpaceMouse but could not open it: " + "; ".join(open_failures) + "." + _PERMISSION_HINT
+        )
+    seen = ", ".join(
+        f"{device['vendor_id']:#06x}:{device['product_id']:#06x} ({device.get('product_string') or 'unnamed'})"
+        for device in enumerated_devices
+    )
+    return (
+        "No device found by SpaceMouse. Is the device connected?"
+        f" Supported models: {', '.join(supported_names)}."
+        f" Enumerated HID devices: {seen or 'none'}."
+    ) + _PERMISSION_HINT
+
+
+def describe_open_failure(device_name: str, vendor_id: int, product_id: int, error: OSError) -> str:
+    """Describe a supported device that was detected but could not be opened.
+
+    Args:
+        device_name: Product name of the detected device.
+        vendor_id: USB vendor identifier of the detected device.
+        product_id: USB product identifier of the detected device.
+        error: The error raised while opening the device.
+
+    Returns:
+        A short description naming the device and the underlying error.
+    """
+    return f"'{device_name}' ({vendor_id:#06x}:{product_id:#06x}): {error}"
+
+
 """
 Private methods.
 """