Merge pull request #47 from JakubAndrysek/fix-testing-and-examples

Add `get_connected_devices_by_path` API to more clearly handle multiple devices of different types

Author: peter-mitrano-ar

.github/instructions/review.instructions.md

@@ -0,0 +1,4 @@
+Focus on backwards compatibility and user experience.
+Point out any API changes.
+Keep your responses very short.
+Do not summarize the changes.

README.md

@@ -42,14 +42,18 @@ pip install pyspacemouse
 
 ## Quick Start
 
+Here we use `has_motion()` to check if any of the spatial axes have non-zero values.
+The optional argument is the threshold used, and is applied per-axis.
+
 ```python
 import pyspacemouse
 
 # Context manager (recommended) - automatically closes device
 with pyspacemouse.open() as device:
     while True:
         state = device.read()
-        print(state.x, state.y, state.z)
+        if state.has_motion(0.01):
+            print(state.x, state.y, state.z, state.roll, state.pitch, state.yaw)
 ```
 
 ## API Reference
@@ -66,6 +70,10 @@ import pyspacemouse
 pyspacemouse.get_connected_devices()
 # Returns: ["SpaceNavigator", "SpaceMouse Pro", ...]
 
+# List connected SpaceMouse devices with paths
+pyspacemouse.get_connected_devices_by_path()
+# Returns: {"/dev/hidraw0": "SpaceNavigator", ...}
+
 # List all supported device types
 pyspacemouse.get_supported_devices()
 # Returns: [(name, vendor_id, product_id), ...]
@@ -138,6 +146,9 @@ mapping table. Custom
 ### Callbacks
 
 ```python
+import pyspacemouse
+import time
+
 # Button callback
 def on_button(state, buttons, pressed):
     print(f"Button {pressed} pressed!")
@@ -164,6 +175,7 @@ with pyspacemouse.open(
 ) as device:
     while True:
         device.read()  # Triggers callbacks
+        time.sleep(0.001) # NOTE: avoid larger sleeps, which can cause data to buffer
 ```
 
 ### Custom Axis Mapping

docs/README.md

@@ -42,14 +42,18 @@ pip install pyspacemouse
 
 ## Quick Start
 
+Here we use `has_motion()` to check if any of the spatial axes have non-zero values.
+The optional argument is the threshold used, and is applied per-axis.
+
 ```python
 import pyspacemouse
 
 # Context manager (recommended) - automatically closes device
 with pyspacemouse.open() as device:
     while True:
         state = device.read()
-        print(state.x, state.y, state.z)
+        if state.has_motion(0.01):
+            print(state.x, state.y, state.z, state.roll, state.pitch, state.yaw)
 ```
 
 ## API Reference
@@ -66,6 +70,10 @@ import pyspacemouse
 pyspacemouse.get_connected_devices()
 # Returns: ["SpaceNavigator", "SpaceMouse Pro", ...]
 
+# List connected SpaceMouse devices with paths
+pyspacemouse.get_connected_devices_by_path()
+# Returns: {"/dev/hidraw0": "SpaceNavigator", ...}
+
 # List all supported device types
 pyspacemouse.get_supported_devices()
 # Returns: [(name, vendor_id, product_id), ...]
@@ -138,6 +146,9 @@ mapping table. Custom
 ### Callbacks
 
 ```python
+import pyspacemouse
+import time
+
 # Button callback
 def on_button(state, buttons, pressed):
     print(f"Button {pressed} pressed!")
@@ -164,6 +175,7 @@ with pyspacemouse.open(
 ) as device:
     while True:
         device.read()  # Triggers callbacks
+        time.sleep(0.001) # NOTE: avoid larger sleeps, which can cause data to buffer
 ```
 
 ### Custom Axis Mapping

examples/01_basic.py

@@ -4,8 +4,6 @@
 ensures the device is properly closed when you're done.
 """
 
-import time
-
 import pyspacemouse
 
 # Using context manager (recommended)
@@ -16,12 +14,8 @@
     while True:
         state = device.read()
 
-        if any(
-            abs(val) > 0.01
-            for val in [state.x, state.y, state.z, state.roll, state.pitch, state.yaw]
-        ):
+        if state.has_motion():
             print(
                 f"x={state.x:+.2f} y={state.y:+.2f} z={state.z:+.2f} "
                 f"roll={state.roll:+.2f} pitch={state.pitch:+.2f} yaw={state.yaw:+.2f}"
             )
-        time.sleep(0.01)

examples/03_multi_device.py

@@ -11,20 +11,21 @@
 
 def main():
     # First, discover connected devices
-    connected = pyspacemouse.get_connected_devices()
-    print(f"Found {len(connected)} device(s): {connected}")
+    connected = pyspacemouse.get_connected_devices_by_path()
+    print(f"Found {len(connected)} spacemouse device(s): {list(connected.values())}")
 
     if len(connected) < 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]
+    # Arbitrarily take the first two devices found
+    path0 = list(connected.keys())[0]
+    path1 = list(connected.keys())[1]
 
-    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(path0) as left_hand:
+        with pyspacemouse.open_by_path(path1) as right_hand:
             print(f"Left hand:  {left_hand.name}")
             print(f"Right hand: {right_hand.name}")
             print()
@@ -34,11 +35,13 @@ def main():
                 left = left_hand.read()
                 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}"
-                )
-                time.sleep(0.02)
+                if left.has_motion() or right.has_motion():
+                    print(
+                        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.01)
 
 
 if __name__ == "__main__":

examples/04_open_by_path.py

@@ -9,8 +9,6 @@
 - Windows: Uses different path format
 """
 
-import time
-
 import pyspacemouse
 
 
@@ -34,8 +32,11 @@ def main():
 
             while True:
                 state = device.read()
-                print(f"x={state.x:+.2f} y={state.y:+.2f} z={state.z:+.2f}")
-                time.sleep(0.01)
+                if state.has_motion():
+                    print(
+                        f"x={state.x:+.2f} y={state.y:+.2f} z={state.z:+.2f} "
+                        f"r={state.roll:+.2f} p={state.pitch:+.2f} y={state.yaw:+.2f}"
+                    )
 
     except FileNotFoundError as e:
         print(f"Device path not found: {e}")

examples/05_discovery.py

@@ -15,9 +15,9 @@ def main():
 
     # 1. List connected SpaceMouse devices
     print("Connected SpaceMouse devices:")
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_devices_by_path()
     if connected:
-        for name in connected:
+        for name in connected.values():
             print(f"  ✓ {name}")
     else:
         print("  (none found)")
@@ -26,11 +26,17 @@ def main():
     # 2. List all supported device types
     print("Supported device types:")
     supported = pyspacemouse.get_supported_devices()
-    for name, vid, pid in supported:
+    for supported_name, vid, pid in supported:
         # Check if this device type is connected
-        is_connected = name in connected
-        status = "✓" if is_connected else " "
-        print(f"  [{status}] {name} (VID: {vid:#06x}, PID: {pid:#06x})")
+        status = " "
+        path_if_connected = ""
+        for path, name in connected.items():
+            if name == supported_name:
+                status = "✓"
+                path_if_connected = f"   (path: {path})"
+        print(
+            f"  [{status}] {supported_name} (VID: {vid:#06x}, PID: {pid:#06x}){path_if_connected}"
+        )
     print()
 
     # 3. List ALL HID devices (for debugging)

examples/09_custom_config.py

@@ -23,12 +23,15 @@ def example_modify_existing():
     print(f"Available devices: {list(specs.keys())}")
 
     # Get connected devices
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_devices_by_path()
     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_name = list(connected.values())[0]
     print(f"Using device: {device_name}")
 
     # Get base spec and create modified version
@@ -49,11 +52,11 @@ def example_modify_existing():
         print("Move the SpaceMouse (Ctrl+C to exit)")
         print("Y and Z axes are now inverted!\n")
 
-        for _ in range(50):  # Run for ~5 seconds
+        for _ in range(500):  # Run for ~5 seconds
             state = device.read()
-            if any([state.x, state.y, state.z]):
+            if state.has_motion():
                 print(f"x={state.x:+.2f} y={state.y:+.2f} z={state.z:+.2f} (Y/Z inverted)")
-            time.sleep(0.1)
+            time.sleep(0.01)
 
 
 def example_invert_rotations():
@@ -62,30 +65,34 @@ def example_invert_rotations():
     print("Example 2: Fix rotation conventions")
     print("=" * 60)
 
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_devices_by_path()
     if not connected:
         print("No devices connected!")
         return
+    if len(connected) > 1:
+        print("This example only works with one device connected.")
+        return
 
+    device_name = list(connected.values())[0]
     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"],
     )
 
     with pyspacemouse.open(device_spec=fixed_spec) as device:
         print(f"Connected to: {device.name}")
         print("Roll and Yaw are now inverted!\n")
 
-        for _ in range(30):
+        for _ in range(500):
             state = device.read()
-            if any([state.roll, state.pitch, state.yaw]):
+            if state.has_motion():
                 print(f"roll={state.roll:+.2f} pitch={state.pitch:+.2f} yaw={state.yaw:+.2f}")
-            time.sleep(0.1)
+            time.sleep(0.01)
 
 
 def example_create_custom():

pyspacemouse/__init__.py

@@ -38,6 +38,7 @@
 from .api import (
     get_all_hid_devices,
     get_connected_devices,
+    get_connected_devices_by_path,
     get_supported_devices,
     open,
     open_by_path,
@@ -98,6 +99,7 @@
     # API
     "get_all_hid_devices",
     "get_connected_devices",
+    "get_connected_devices_by_path",
     "get_supported_devices",
     "open",
     "open_by_path",

pyspacemouse/api.py

@@ -18,7 +18,7 @@
 
 import warnings
 from pathlib import Path
-from typing import Callable, List, Optional, Sequence, Tuple
+from typing import Callable, Dict, List, Optional, Sequence, Tuple
 
 from easyhid import Enumeration
 
@@ -369,3 +369,32 @@ def open_with_config(
         device_index=device_index,
         axis_convention=axis_convention,
     )
+
+
+def get_connected_devices_by_path() -> Dict[str, str]:
+    """Return the paths and names of the supported devices currently connected.
+
+    Returns:
+        Dict of paths: device names (e.g., {"/dev/hidraw0": "SpaceMouse Pro"}).
+
+    Raises:
+        RuntimeError: If HID API is not installed.
+    """
+    try:
+        hid = Enumeration()
+    except AttributeError as e:
+        raise RuntimeError(
+            "HID API is probably not installed. See https://spacemouse.kubaandrysek.cz for details."
+        ) from e
+
+    device_specs = get_device_specs()
+    devices_by_path = {}
+
+    # hid.find() is all connected HID devices,
+    # device_specs is all supported Spacemouse devices.
+    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_by_path[hid_device.path] = name
+
+    return devices_by_path