dexter-controller 0.3.0__tar.gz → 1.0.0a2__tar.gz

{dexter_controller-0.3.0 → dexter_controller-1.0.0a2}/PKG-INFO

@@ -1,21 +1,21 @@
 Metadata-Version: 2.3
 Name: dexter-controller
-Version: 0.3.0
+Version: 1.0.0a2
 Summary: Dexter device Controller
 Author: Hardware and Software Platform, Champalimaud Foundation
 Author-email: Hardware and Software Platform, Champalimaud Foundation <software@research.fchampalimaud.org>
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: bleak==2.1.1
-Requires-Dist: harp-loadcells>=0.1.0a3
+Requires-Dist: harp-protocol==0.5.0
+Requires-Dist: harp-serial==0.5.0
 Requires-Dist: pydoc-markdown>=4.8.2 ; extra == 'docs'
 Requires-Dist: pyarrow>=14.0.0 ; extra == 'parquet'
 Requires-Dist: dexter-controller[reader] ; extra == 'parquet'
 Requires-Dist: numpy>=1.25.0 ; extra == 'reader'
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Project-URL: Repository, https://github.com/fchampalimaud/dexter-controller/
 Project-URL: Bug Tracker, https://github.com/fchampalimaud/dexter-controller/issues
 Provides-Extra: docs
@@ -52,33 +52,35 @@ pip install dexter-controller[parquet]   # pyarrow + numpy, for Parquet format s
 
 ## Quick start
 
-At this moment, the recommended way to connect is over Bluetooth Low Energy. The controller auto-discovers and connects to the first Dexter device in range, but you can specify a particular device by name:
+Connect over BLE or UART using the `DexterDevice` factory:
 
 ```python
 import time
-from dexter_controller import DexterHandController, Finger
+from dexter_controller import DexterDevice, Finger
 
-controller = DexterHandController(use_ble=True,
-    # if you want to connect to a specific device by name
-    #ble_device_name="Dexter-001"
+device = DexterDevice.create_ble(
+    # connect to a specific device by name:
+    # device_name="Dexter-001"
 )
+device.connect()
+device.start_acquisition()
 
-device_name = controller.get_device_name()
-battery = controller.get_battery_level()
-rate = controller.get_sampling_rate()
+device_name = device.get_device_name()
+battery = device.get_battery_level()
+rate = device.get_sampling_rate()
 print(f"Device: {device_name} | Battery: {battery}% | Rate: {rate.value} Hz")
 
 try:
     while True:
         for finger in Finger:
-            data = controller.finger_data[finger]
+            data = device.finger_data[finger]
             print(f"{finger.name}: {data.raw_data}", end="  ")
         print(end="\r", flush=True)
         time.sleep(0.02)
 except KeyboardInterrupt:
     pass
 finally:
-    controller.close()
+    device.close()
 ```
 
 ## Force computation
@@ -87,23 +89,25 @@ Convert raw load-cell readings into calibrated 2D force vectors (Fx, Fy):
 
 ```python
 from dexter_controller import (
-    DEFAULT_CALIBRATION_3CH,
-    DexterHandController,
+    DEFAULT_CALIBRATION,
+    DexterDevice,
     Finger,
     ForceProcessor,
     get_default_orientation,
 )
 
-controller = DexterHandController(use_ble=True)
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
 
 processors = {}
 for finger in Finger:
     orientation = get_default_orientation(finger)
-    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION_3CH, orientation)
+    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION, orientation)
 
 # In your read loop:
-data = controller.finger_data[Finger.INDEX]
-fx, fy = processors[Finger.INDEX].process_3(data)
+data = device.finger_data[Finger.INDEX]
+fx, fy = processors[Finger.INDEX].process(data)
 ```
 
 Each `ForceProcessor` includes a `TareState` that lets you zero-out the baseline:
@@ -118,9 +122,9 @@ Record sessions to disk in CSV, SQLite (**default**), or Parquet format:
 
 ```python
 from dexter_controller import (
-    DEFAULT_CALIBRATION_3CH,
+    DEFAULT_CALIBRATION,
     DataRecorder,
-    DexterHandController,
+    DexterDevice,
     Finger,
     ForceProcessor,
     RecordingMetadata,
@@ -128,35 +132,37 @@ from dexter_controller import (
 )
 from dexter_controller.recording_format import RecordingFormat
 
-controller = DexterHandController(use_ble=True)
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
 
 processors = {}
 for finger in Finger:
     processors[finger] = ForceProcessor(
-        DEFAULT_CALIBRATION_3CH, get_default_orientation(finger)
+        DEFAULT_CALIBRATION, get_default_orientation(finger)
     )
 
 recorder = DataRecorder(
     "./recordings",
     file_format=RecordingFormat.SQLITE,
     metadata=RecordingMetadata(
-        device_name=controller.get_device_name(),
-        sampling_rate_hz=controller.get_sampling_rate().value,
+        device_name=device.get_device_name(),
+        sampling_rate_hz=device.get_sampling_rate().value,
     ),
 )
 
 def on_sample(_data):
-    fingers = [controller.finger_data[f] for f in Finger]
-    forces = [processors[f].process_3(controller.finger_data[f]) for f in Finger]
+    fingers = [device.finger_data[f] for f in Finger]
+    forces = [processors[f].process(device.finger_data[f]) for f in Finger]
     baselines = [(processors[f].tare.baseline_x, processors[f].tare.baseline_y) for f in Finger]
     recorder.write_sample(fingers, forces, baselines)
 
-controller.register_finger_callback(Finger.PINKY, on_sample)
+device.register_finger_callback(Finger.PINKY, on_sample)
 
 recorder.start_recording()
 # ... run until done ...
 recorder.stop_recording()
-controller.close()
+device.close()
 ```
 
 Each recording file includes session metadata.
@@ -225,11 +231,11 @@ When connected via BLE, you can read and write device settings:
 ```python
 from dexter_controller import SamplingRate
 
-controller.get_device_name()                          # read name
-controller.set_device_name("MyDexter")                # rename device
-controller.get_sampling_rate()                        # current rate
-controller.set_sampling_rate(SamplingRate.HZ_1000)    # change rate
-controller.get_battery_level()                        # battery percentage
+device.get_device_name()                          # read name
+device.set_device_name("MyDexter")                # rename device
+device.get_sampling_rate()                        # current rate
+device.set_sampling_rate(SamplingRate.HZ_1000)    # change rate
+device.get_battery_level()                        # battery percentage
 ```
 
 > [!WARNING]
@@ -246,21 +252,22 @@ See the [example/](example/) directory for complete, runnable scripts:
 | [example_ble.py](example/example_ble.py)                     | BLE connection with raw data streaming and event rate monitoring                  |
 | [example_ble_force.py](example/example_ble_force.py)         | BLE connection with real-time force computation using `ForceProcessor`            |
 | [example_ble_recording.py](example/example_ble_recording.py) | Full recording session: BLE connect, force processing, and data recording to file |
-| [example_serial.py](example/example_serial.py)               | Serial (wired) connection with multi-port finger mapping                          |
+| [example_uart.py](example/example_uart.py)                   | UART (wired) connection                                                          |
 
-## Serial connection (old prototype only, to be deprecated)
+## UART connection
 
-For wired setups using Harp load-cell boards, provide a port-to-finger mapping:
+For wired setups using UART:
 
 ```python
-from dexter_controller import DexterHandController, Finger
-
-mapping = {
-    "COM3": [Finger.THUMB, Finger.INDEX],     # /dev/ttyUSB0 on Linux
-    "COM4": [Finger.MIDDLE, Finger.RING],
-    "COM5": [Finger.PINKY],
-}
-controller = DexterHandController(mapping)
-```
+import sys
+from dexter_controller import DexterDevice, EventFlags, Finger, SamplingRate
+
+device = DexterDevice.create_uart("COM3")  # or /dev/ttyUSB0 on Linux
 
-Each serial device supports up to two fingers (8 channels, 4 per finger).
+with device:
+    device.set_sampling_rate(SamplingRate.HZ_800)
+    device.set_event_enable(EventFlags.LOAD_CELL_DATA)
+    device.set_finger_channel_mapping([Finger.RING, None, None, None, None])
+    device.start_acquisition()
+    # ... read data via device.register_data_callback(callback)
+```

{dexter_controller-0.3.0 → dexter_controller-1.0.0a2}/README.md

@@ -27,33 +27,35 @@ pip install dexter-controller[parquet]   # pyarrow + numpy, for Parquet format s
 
 ## Quick start
 
-At this moment, the recommended way to connect is over Bluetooth Low Energy. The controller auto-discovers and connects to the first Dexter device in range, but you can specify a particular device by name:
+Connect over BLE or UART using the `DexterDevice` factory:
 
 ```python
 import time
-from dexter_controller import DexterHandController, Finger
+from dexter_controller import DexterDevice, Finger
 
-controller = DexterHandController(use_ble=True,
-    # if you want to connect to a specific device by name
-    #ble_device_name="Dexter-001"
+device = DexterDevice.create_ble(
+    # connect to a specific device by name:
+    # device_name="Dexter-001"
 )
+device.connect()
+device.start_acquisition()
 
-device_name = controller.get_device_name()
-battery = controller.get_battery_level()
-rate = controller.get_sampling_rate()
+device_name = device.get_device_name()
+battery = device.get_battery_level()
+rate = device.get_sampling_rate()
 print(f"Device: {device_name} | Battery: {battery}% | Rate: {rate.value} Hz")
 
 try:
     while True:
         for finger in Finger:
-            data = controller.finger_data[finger]
+            data = device.finger_data[finger]
             print(f"{finger.name}: {data.raw_data}", end="  ")
         print(end="\r", flush=True)
         time.sleep(0.02)
 except KeyboardInterrupt:
     pass
 finally:
-    controller.close()
+    device.close()
 ```
 
 ## Force computation
@@ -62,23 +64,25 @@ Convert raw load-cell readings into calibrated 2D force vectors (Fx, Fy):
 
 ```python
 from dexter_controller import (
-    DEFAULT_CALIBRATION_3CH,
-    DexterHandController,
+    DEFAULT_CALIBRATION,
+    DexterDevice,
     Finger,
     ForceProcessor,
     get_default_orientation,
 )
 
-controller = DexterHandController(use_ble=True)
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
 
 processors = {}
 for finger in Finger:
     orientation = get_default_orientation(finger)
-    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION_3CH, orientation)
+    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION, orientation)
 
 # In your read loop:
-data = controller.finger_data[Finger.INDEX]
-fx, fy = processors[Finger.INDEX].process_3(data)
+data = device.finger_data[Finger.INDEX]
+fx, fy = processors[Finger.INDEX].process(data)
 ```
 
 Each `ForceProcessor` includes a `TareState` that lets you zero-out the baseline:
@@ -93,9 +97,9 @@ Record sessions to disk in CSV, SQLite (**default**), or Parquet format:
 
 ```python
 from dexter_controller import (
-    DEFAULT_CALIBRATION_3CH,
+    DEFAULT_CALIBRATION,
     DataRecorder,
-    DexterHandController,
+    DexterDevice,
     Finger,
     ForceProcessor,
     RecordingMetadata,
@@ -103,35 +107,37 @@ from dexter_controller import (
 )
 from dexter_controller.recording_format import RecordingFormat
 
-controller = DexterHandController(use_ble=True)
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
 
 processors = {}
 for finger in Finger:
     processors[finger] = ForceProcessor(
-        DEFAULT_CALIBRATION_3CH, get_default_orientation(finger)
+        DEFAULT_CALIBRATION, get_default_orientation(finger)
     )
 
 recorder = DataRecorder(
     "./recordings",
     file_format=RecordingFormat.SQLITE,
     metadata=RecordingMetadata(
-        device_name=controller.get_device_name(),
-        sampling_rate_hz=controller.get_sampling_rate().value,
+        device_name=device.get_device_name(),
+        sampling_rate_hz=device.get_sampling_rate().value,
     ),
 )
 
 def on_sample(_data):
-    fingers = [controller.finger_data[f] for f in Finger]
-    forces = [processors[f].process_3(controller.finger_data[f]) for f in Finger]
+    fingers = [device.finger_data[f] for f in Finger]
+    forces = [processors[f].process(device.finger_data[f]) for f in Finger]
     baselines = [(processors[f].tare.baseline_x, processors[f].tare.baseline_y) for f in Finger]
     recorder.write_sample(fingers, forces, baselines)
 
-controller.register_finger_callback(Finger.PINKY, on_sample)
+device.register_finger_callback(Finger.PINKY, on_sample)
 
 recorder.start_recording()
 # ... run until done ...
 recorder.stop_recording()
-controller.close()
+device.close()
 ```
 
 Each recording file includes session metadata.
@@ -200,11 +206,11 @@ When connected via BLE, you can read and write device settings:
 ```python
 from dexter_controller import SamplingRate
 
-controller.get_device_name()                          # read name
-controller.set_device_name("MyDexter")                # rename device
-controller.get_sampling_rate()                        # current rate
-controller.set_sampling_rate(SamplingRate.HZ_1000)    # change rate
-controller.get_battery_level()                        # battery percentage
+device.get_device_name()                          # read name
+device.set_device_name("MyDexter")                # rename device
+device.get_sampling_rate()                        # current rate
+device.set_sampling_rate(SamplingRate.HZ_1000)    # change rate
+device.get_battery_level()                        # battery percentage
 ```
 
 > [!WARNING]
@@ -221,21 +227,22 @@ See the [example/](example/) directory for complete, runnable scripts:
 | [example_ble.py](example/example_ble.py)                     | BLE connection with raw data streaming and event rate monitoring                  |
 | [example_ble_force.py](example/example_ble_force.py)         | BLE connection with real-time force computation using `ForceProcessor`            |
 | [example_ble_recording.py](example/example_ble_recording.py) | Full recording session: BLE connect, force processing, and data recording to file |
-| [example_serial.py](example/example_serial.py)               | Serial (wired) connection with multi-port finger mapping                          |
+| [example_uart.py](example/example_uart.py)                   | UART (wired) connection                                                          |
 
-## Serial connection (old prototype only, to be deprecated)
+## UART connection
 
-For wired setups using Harp load-cell boards, provide a port-to-finger mapping:
+For wired setups using UART:
 
 ```python
-from dexter_controller import DexterHandController, Finger
-
-mapping = {
-    "COM3": [Finger.THUMB, Finger.INDEX],     # /dev/ttyUSB0 on Linux
-    "COM4": [Finger.MIDDLE, Finger.RING],
-    "COM5": [Finger.PINKY],
-}
-controller = DexterHandController(mapping)
-```
+import sys
+from dexter_controller import DexterDevice, EventFlags, Finger, SamplingRate
+
+device = DexterDevice.create_uart("COM3")  # or /dev/ttyUSB0 on Linux
 
-Each serial device supports up to two fingers (8 channels, 4 per finger).
+with device:
+    device.set_sampling_rate(SamplingRate.HZ_800)
+    device.set_event_enable(EventFlags.LOAD_CELL_DATA)
+    device.set_finger_channel_mapping([Finger.RING, None, None, None, None])
+    device.start_acquisition()
+    # ... read data via device.register_data_callback(callback)
+```

{dexter_controller-0.3.0 → dexter_controller-1.0.0a2}/pyproject.toml

@@ -1,19 +1,19 @@
 [project]
 name = "dexter-controller"
-version = "0.3.0"
+version = "1.0.0a2"
 description = "Dexter device Controller"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
     "bleak==2.1.1",
-    "harp-loadcells>=0.1.0a3",
+    "harp-protocol==0.5.0",
+    "harp-serial==0.5.0",
 ]
 
 [[project.authors]]

{dexter_controller-0.3.0 → dexter_controller-1.0.0a2}/pyproject.toml.orig

@@ -1,22 +1,22 @@
 [project]
 name = "dexter-controller"
-version = "0.3.0"
+version = "1.0.0a2"
 description = "Dexter device Controller"
 readme = "README.md"
 authors = [
     { name = "Hardware and Software Platform, Champalimaud Foundation", email = "software@research.fchampalimaud.org" }
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
     "bleak==2.1.1",
-    "harp-loadcells>=0.1.0a3",
+    "harp-protocol==0.5.0",
+    "harp-serial==0.5.0",
 ]
 
 [project.optional-dependencies]

{dexter_controller-0.3.0 → dexter_controller-1.0.0a2}/src/dexter_controller/__init__.py

@@ -1,44 +1,58 @@
-from .ble_loadcell_device import BLELoadCellDevice, DataMode, SamplingRate
+from .ble_dexter_device import BLEDexterDevice
 from .calibration import (
     DEFAULT_CALIBRATION,
-    DEFAULT_CALIBRATION_3CH,
     CalibrationProfile,
+    ChannelCalibration,
     LoadCellCalibration,
-    create_3channel,
+    LoadCellCoefficients,
+    calibration_from_channel,
+    create_calibration,
 )
 from .data_recorder import DataRecorder
-from .dexter_hand_controller import DexterHandController
+from .dexter_device import (
+    DataMode,
+    DexterDevice,
+    ErrorStatus,
+    EventFlags,
+    HandSelection,
+    SamplingRate,
+)
 from .finger import Finger, FingerData
 from .finger_orientation import FingerOrientation
 from .finger_orientation import get_default as get_default_orientation
 from .force_processor import ForceProcessor
-from .loadcell_device import LoadCellDevice
 from .recording import Recording
 from .recording_format import RecordingFormat
 from .recording_metadata import RecordingMetadata
 from .recording_reader import RecordingReader
 from .tare import TareState
+from .uart_dexter_device import UartDexterDevice
 
 __all__ = [
     "DEFAULT_CALIBRATION",
-    "DEFAULT_CALIBRATION_3CH",
-    "BLELoadCellDevice",
+    "BLEDexterDevice",
     "CalibrationProfile",
+    "ChannelCalibration",
     "DataMode",
     "DataRecorder",
-    "DexterHandController",
+    "DexterDevice",
+    "ErrorStatus",
+    "EventFlags",
     "Finger",
     "FingerData",
     "FingerOrientation",
     "ForceProcessor",
+    "HandSelection",
     "LoadCellCalibration",
-    "LoadCellDevice",
+    "LoadCellCoefficients",
     "Recording",
     "RecordingFormat",
     "RecordingMetadata",
     "RecordingReader",
     "SamplingRate",
     "TareState",
-    "create_3channel",
+    "UartDexterDevice",
+    "calibration_from_channel",
+    "create_calibration",
     "get_default_orientation",
 ]