update API for listing connected spacemouse to better handle multiple different types of spacemouse

Author: peter

examples/03_multi_device.py

@@ -11,20 +11,19 @@
 
 def main():
     # First, discover connected devices
-    connected = pyspacemouse.get_connected_devices()
-    print(f"Found {len(connected)} device(s): {connected}")
+    devices = pyspacemouse.get_connected_spacemice()
+    paths = [path for path, name in devices]
+    names = [name for path, name in devices]
+    print(f"Found {len(names)} spacemouse device(s): {names}")
 
-    if len(connected) < 2:
+    if len(names) < 2:
         print("This example requires 2 SpaceMouse devices connected.")
         print("Tip: Use a 3Dconnexion Universal Receiver with device_index parameter")
         return
 
-    # Open two devices using device_index
-    # device_index=0 is the first device, device_index=1 is the second
-    device_name = connected[0]
-
-    with pyspacemouse.open(device=device_name, device_index=0) as left_hand:
-        with pyspacemouse.open(device=device_name, device_index=1) as right_hand:
+    # Open two devices by path
+    with pyspacemouse.open_by_path(paths[0]) as left_hand:
+        with pyspacemouse.open_by_path(paths[1]) as right_hand:
             print(f"Left hand:  {left_hand.name}")
             print(f"Right hand: {right_hand.name}")
             print()
@@ -35,8 +34,8 @@ def main():
                 right = right_hand.read()
 
                 print(
-                    f"L: x={left.x:+.2f} y={left.y:+.2f} z={left.z:+.2f}  |  "
-                    f"R: x={right.x:+.2f} y={right.y:+.2f} z={right.z:+.2f}"
+                    f"Left: x={left.x:+.2f} y={left.y:+.2f} z={left.z:+.2f}  |  "
+                    f"Right: x={right.x:+.2f} y={right.y:+.2f} z={right.z:+.2f}"
                 )
                 time.sleep(0.02)
 

examples/05_discovery.py

@@ -15,9 +15,10 @@ def main():
 
     # 1. List connected SpaceMouse devices
     print("Connected SpaceMouse devices:")
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_spacemice()
+    connected_names = [name for _, name in connected]
     if connected:
-        for name in connected:
+        for name in connected_names:
             print(f"  ✓ {name}")
     else:
         print("  (none found)")
@@ -28,7 +29,7 @@ def main():
     supported = pyspacemouse.get_supported_devices()
     for name, vid, pid in supported:
         # Check if this device type is connected
-        is_connected = name in connected
+        is_connected = name in connected_names
         status = "✓" if is_connected else " "
         print(f"  [{status}] {name} (VID: {vid:#06x}, PID: {pid:#06x})")
     print()

examples/09_custom_config.py

@@ -23,16 +23,20 @@ def example_modify_existing():
     print(f"Available devices: {list(specs.keys())}")
 
     # Get connected devices
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_spacemice()
     if not connected:
         print("No devices connected!")
         return
+    if len(connected) > 1:
+        print("This example only works with one device connected.")
+        return
 
-    device_name = connected[0]
+    device = connected[0]
+    device_path, device_name = device
     print(f"Using device: {device_name}")
 
     # Get base spec and create modified version
-    base_spec = specs[device_name]
+    base_spec = specs[device_path]
     print(f"Original mappings: y scale = {base_spec.mappings['y'].scale}")
 
     # Create modified spec with inverted Y and Z (common for ROS)
@@ -62,18 +66,23 @@ def example_invert_rotations():
     print("Example 2: Fix rotation conventions")
     print("=" * 60)
 
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_spacemice()
     if not connected:
         print("No devices connected!")
         return
+    if len(connected) > 1:
+        print("This example only works with one device connected.")
+        return
 
+    device = connected[0]
+    device_path, device_name = device
     specs = pyspacemouse.get_device_specs()
-    base_spec = specs[connected[0]]
+    base_spec = specs[device_name]
 
     # Invert roll and yaw for right-handed coordinate system
     fixed_spec = pyspacemouse.modify_device_info(
         base_spec,
-        name=f"{connected[0]} (Fixed Rotations)",
+        name=f"{device_name} (Fixed Rotations)",
         invert_axes=["roll", "yaw"],
     )
 

pyspacemouse/__init__.py

@@ -37,7 +37,7 @@
 # Public API
 from .api import (
     get_all_hid_devices,
-    get_connected_devices,
+    get_connected_spacemice,
     get_supported_devices,
     open,
     open_by_path,
@@ -95,7 +95,7 @@
     "SpaceMouseDevice",
     # API
     "get_all_hid_devices",
-    "get_connected_devices",
+    "get_connected_spacemice",
     "get_supported_devices",
     "open",
     "open_by_path",

pyspacemouse/api.py

@@ -27,11 +27,11 @@
 from .types import DeviceInfo, SpaceMouseState
 
 
-def get_connected_devices() -> List[str]:
-    """Return a list of the supported devices currently connected.
+def get_connected_spacemice() -> List[Tuple[str, str]]:
+    """Return the paths and names of the supported devices currently connected.
 
     Returns:
-        List of device names that are both supported and connected.
+        Tuple of two lists: (device_paths, device_names)
         Empty list if no supported devices are found.
 
     Raises:
@@ -45,14 +45,14 @@ def get_connected_devices() -> List[str]:
         ) from e
 
     device_specs = get_device_specs()
-    devices = []
+    devices_by_path = {}
 
     for hid_device in hid.find():
         for name, spec in device_specs.items():
             if hid_device.vendor_id == spec.vendor_id and hid_device.product_id == spec.product_id:
-                devices.append(name)
+                devices_by_path[hid_device.path] = name
 
-    return devices
+    return list(devices_by_path.items())
 
 
 def get_supported_devices() -> List[Tuple[str, int, int]]:
@@ -253,10 +253,10 @@ def open(
 
     # Auto-detect device if not specified
     if device is None:
-        connected = get_connected_devices()
+        connected = get_connected_spacemice()
         if not connected:
             raise RuntimeError("No connected or supported devices found.")
-        device = connected[0]
+        device = connected[0][1]
 
     if device not in device_specs:
         raise ValueError(f"Unknown device: '{device}'. Available: {list(device_specs.keys())}")

pyspacemouse/pyspacemouse_cli.py

@@ -13,10 +13,10 @@ def print_version_cli():
 
 def list_spacemouse_cli():
     """List connected SpaceMouse devices."""
-    devices = pyspacemouse.get_connected_devices()
+    devices = pyspacemouse.get_connected_spacemice()
     if devices:
         print("Connected SpaceMouse devices:")
-        for device in devices:
+        for _, device in devices:
             print(f"  - {device}")
     else:
         print("No connected SpaceMouse devices found.")