add new read_latest() function and improve documentation on USB buffering and slow read loops

Author: peter

README.md

@@ -49,7 +49,7 @@ The optional argument is the threshold used, and is applied per-axis.
 import pyspacemouse
 
 # Context manager (recommended) - automatically closes device
-with pyspacemouse.open() as device:
+with pyspacemouse.open(nonblocking=False) as device:
     while True:
         state = device.read()
         if state.has_motion(0.01):
@@ -172,10 +172,10 @@ dof_callbacks = [
 with pyspacemouse.open(
     button_callbacks=button_callbacks,
     dof_callbacks=dof_callbacks,
+    nonblocking=False
 ) 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
@@ -195,12 +195,30 @@ custom = pyspacemouse.modify_device_info(
     invert_axes=["y", "z", "roll", "yaw"],  # Invert these
 )
 
-with pyspacemouse.open(device_spec=custom) as device:
+with pyspacemouse.open(device_spec=custom, nonblocking=False) as device:
     state = device.read()
 ```
 
 See [Custom Device Configuration](./docs/mouseApi/index.md#custom-device-configuration) for full API.
 
+## Blocking, Non-Blocking, sleeps, and callbacks
+
+The default `open()` function uses `nonblocking=True`, which means `read()` can return without any data if none is available.
+However, the spacemouse device sends data very quickly and the operating system may buffer this data if it is not being read quickly enough.
+This means that you are very unlikely to ever _not_ get data from `read()`, even in non-blocking mode.
+This also means that if you have a loop that calls `read()` and it is slow, for example if you add `sleep(0.01)`, you might start to see the data start lagging behind a bit.
+For instance, if you poke the spacemouse it will take a few dozen/hundred milliseconds for non-zero data to be return from `read()`.
+This is why you see many of our examples us `nonblocking=False` and no sleep at all.
+This is an attempt to read as quickly as possible to avoid buffering data.
+If you want to minimize the effects of buffering while still operating at a lower rate, consider something like this:
+```python
+with pyspacemouse.open() as device:
+    while True:
+        state = device.read()
+        if
+```
+
+
 ## CLI
 
 ```bash

examples/01_basic.py

@@ -8,7 +8,7 @@
 from pyspacemouse import AxisConvention
 
 # Using context manager (recommended)
-with pyspacemouse.open(axis_convention=AxisConvention.HID_Z_UP) as device:
+with pyspacemouse.open(axis_convention=AxisConvention.HID_Z_UP, nonblocking=False) as device:
     print(f"Connected to: {device.name}")
     print("Move the SpaceMouse to see values (Ctrl+C to exit)")
 

examples/02_callbacks.py

@@ -5,8 +5,6 @@
 - Axis movements with filtering
 """
 
-import time
-
 import pyspacemouse
 from pyspacemouse import AxisConvention
 
@@ -44,11 +42,11 @@ def on_any_button(state, buttons):
     dof_callback=pyspacemouse.print_state,  # Built-in DOF printer
     button_callback=on_any_button,
     button_callbacks=button_callbacks,
+    nonblocking=False,
 ) as device:
     print(f"Connected to: {device.name}")
     print("Move the SpaceMouse or press buttons (Ctrl+C to exit)")
     print()
 
     while True:
         device.read()  # Must call read() to process callbacks
-        time.sleep(0.01)

examples/03_multi_device.py

@@ -35,16 +35,16 @@ def main():
             print("Move both devices (Ctrl+C to exit)")
 
             while True:
-                left = left_hand.read()
-                right = right_hand.read()
+                left = left_hand.read_latest()
+                right = right_hand.read_latest()
 
                 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)
+                time.sleep(0.1)
 
 
 if __name__ == "__main__":

examples/04_open_by_path.py

@@ -28,6 +28,7 @@ def main():
     try:
         with pyspacemouse.open_by_path(
             device_path,
+            nonblocking=False,
             axis_convention=AxisConvention.HID_Z_UP,
         ) as device:
             print(f"Connected to: {device.name} at {device_path}")

examples/05_discovery.py

@@ -28,14 +28,15 @@ def main():
     supported = pyspacemouse.get_supported_devices()
     for supported_name, vid, pid in supported:
         # Check if this device type is connected
-        status = " "
+        count = 0
         path_if_connected = ""
         for path, name in connected.items():
             if name == supported_name:
-                status = "✓"
+                count += 1
                 path_if_connected = f"   (path: {path})"
+        count_str = " " if count == 0 else str(count)
         print(
-            f"  [{status}] {supported_name} (VID: {vid:#06x}, PID: {pid:#06x}){path_if_connected}"
+            f"  [{count_str}] {supported_name} (VID: {vid:#06x}, PID: {pid:#06x}){path_if_connected}"
         )
     print()
 

examples/06_axis_callbacks.py

@@ -58,4 +58,4 @@ def on_z_move(state, value):
 
     while True:
         device.read()
-        time.sleep(0.01)
+        time.sleep(0.001)

examples/08_buttons.py

@@ -36,4 +36,4 @@ def on_button_change(state, buttons):
 
     while True:
         device.read()
-        time.sleep(0.01)
+        time.sleep(0.001)

examples/09_invert_rotations.py

@@ -34,7 +34,7 @@ def example_invert_rotations():
         invert_axes=["roll", "pitch", "yaw"],
     )
 
-    with pyspacemouse.open(device_spec=fixed_spec) as device:
+    with pyspacemouse.open(device_spec=fixed_spec, nonblocking=False) as device:
         print(f"Connected to: {device.name}")
         print("Rotations are now inverted!\n")
 
@@ -45,7 +45,6 @@ def example_invert_rotations():
                     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)
 
 
 if __name__ == "__main__":

pyspacemouse/api.py

@@ -139,6 +139,7 @@ def _create_and_open_device(
     )
     mouse.open()
     hid_device.set_nonblocking(nonblocking)
+    mouse._nonblocking = nonblocking
     return mouse