added .nonzero() API to spacemouse state

just for making printing/sleeping in examples simpler
also added a warning about sleeps

Author: peter

README.md

@@ -49,7 +49,8 @@ import pyspacemouse
 with pyspacemouse.open() as device:
     while True:
         state = device.read()
-        print(state.x, state.y, state.z)
+        if state.nonzero(0.01):
+            print(state.x, state.y, state.z, state.roll, state.pitch, state.yaw)
 ```
 
 ## API Reference
@@ -145,6 +146,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.nonzero():
             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/02_callbacks.py

@@ -49,4 +49,4 @@ def on_any_button(state, buttons):
 
     while True:
         device.read()  # Must call read() to process callbacks
-        time.sleep(0.01)
+        time.sleep(0.01)  # NOTE: large sleeps can cause data to buffer

examples/03_multi_device.py

@@ -4,24 +4,26 @@
 useful for dual-hand control or controlling multiple robots.
 """
 
-import time
-
 import pyspacemouse
 
 
 def main():
     # First, discover connected devices
-    paths, names = pyspacemouse.get_connected_paths_and_names()
-    print(f"Found {len(names)} spacemouse device(s): {names}")
+    connected = pyspacemouse.get_connected_paths_and_names()
+    print(f"Found {len(connected)} spacemouse device(s): {list(connected.values())}")
 
-    if len(names) < 2:
+    if len(connected) < 2:
         print("This example requires 2 SpaceMouse devices connected.")
         print("Tip: Use a 3Dconnexion Universal Receiver with device_index parameter")
         return
 
+    # Arbitrarily take the first two devices found
+    path0 = list(connected.keys())[0]
+    path1 = list(connected.keys())[1]
+
     # 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:
+    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()
@@ -31,11 +33,11 @@ def main():
                 left = left_hand.read()
                 right = right_hand.read()
 
-                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.02)
+                if left.nonzero() or right.nonzero():
+                    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}"
+                    )
 
 
 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.nonzero():
+                    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_paths_and_names()
     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,15 +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_paths_and_names()
     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
@@ -54,7 +54,7 @@ def example_modify_existing():
 
         for _ in range(500):  # Run for ~5 seconds
             state = device.read()
-            if any([state.x, state.y, state.z]):
+            if state.nonzero():
                 print(f"x={state.x:+.2f} y={state.y:+.2f} z={state.z:+.2f} (Y/Z inverted)")
             time.sleep(0.01)
 
@@ -65,15 +65,15 @@ def example_invert_rotations():
     print("Example 2: Fix rotation conventions")
     print("=" * 60)
 
-    connected = pyspacemouse.get_connected_devices()
+    connected = pyspacemouse.get_connected_paths_and_names()
     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]
     specs = pyspacemouse.get_device_specs()
     base_spec = specs[device_name]
 
@@ -90,7 +90,7 @@ def example_invert_rotations():
 
         for _ in range(500):
             state = device.read()
-            if any([state.roll, state.pitch, state.yaw]):
+            if state.nonzero():
                 print(f"roll={state.roll:+.2f} pitch={state.pitch:+.2f} yaw={state.yaw:+.2f}")
             time.sleep(0.01)
 

pyspacemouse/api.py

@@ -17,7 +17,7 @@
 from __future__ import annotations
 
 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
 
@@ -256,7 +256,7 @@ def open(
         connected = get_connected_devices()
         if not connected:
             raise RuntimeError("No connected or supported devices found.")
-        device = connected[0][1]
+        device = connected[0]
 
     if device not in device_specs:
         raise ValueError(f"Unknown device: '{device}'. Available: {list(device_specs.keys())}")
@@ -323,12 +323,11 @@ def open_with_config(
     )
 
 
-def get_connected_paths_and_names() -> Tuple[List[str], List[str]]:
+def get_connected_paths_and_names() -> Dict[str, str]:
     """Return the paths and names of the supported devices currently connected.
 
     Returns:
-        Tuple of two lists: (device_paths, device_names).
-        Tuple of empty lists if no supported devices are found.
+        Dict of paths: device names (e.g., {"/dev/hidraw0": "SpaceMouse Pro"}).
 
     Raises:
         RuntimeError: If HID API is not installed.
@@ -341,15 +340,13 @@ def get_connected_paths_and_names() -> Tuple[List[str], List[str]]:
         ) from e
 
     device_specs = get_device_specs()
-    device_paths = []
-    device_names = []
+    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:
-                device_paths.append(hid_device.path)
-                device_names.append(name)
+                devices_by_path[hid_device.path] = name
 
-    return device_paths, device_names
+    return devices_by_path

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()
-    if devices:
+    connected = pyspacemouse.get_connected_paths_and_names()
+    if connected:
         print("Connected SpaceMouse devices:")
-        for path, device in devices:
+        for path, device in connected.items():
             print(f"  - {device} ({path})")
     else:
         print("No connected SpaceMouse devices found.")
@@ -59,15 +59,11 @@ def test_connect_cli():
 
             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.nonzero():
                     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)
 
     except RuntimeError as e:
         print(f"Failed to open SpaceMouse: {e}")

pyspacemouse/types.py

@@ -87,6 +87,13 @@ def __getitem__(self, key: str) -> float:
         """Allow dict-like access for backward compatibility."""
         return getattr(self, key)
 
+    def nonzero(self, threshold: float = 0.01) -> bool:
+        """
+        Check if any axis value exceeds the given threshold.
+        Used in example scripts to avoid printing zero values when the device is at rest.
+        """
+        return any(abs(getattr(self, axis)) > threshold for axis in AXIS_NAMES)
+
 
 @dataclass(frozen=True, slots=True)
 class DeviceInfo: