dexter-controller 0.2.2__tar.gz → 1.0.0a1__tar.gz

dexter_controller-1.0.0a1/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.3
+Name: dexter-controller
+Version: 1.0.0a1
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: bleak==2.1.1
+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.11
+Project-URL: Repository, https://github.com/fchampalimaud/dexter-controller/
+Project-URL: Bug Tracker, https://github.com/fchampalimaud/dexter-controller/issues
+Provides-Extra: docs
+Provides-Extra: parquet
+Provides-Extra: reader
+Description-Content-Type: text/markdown
+
+# dexter-controller
+
+[![PyPI](https://img.shields.io/pypi/v/dexter-controller)](https://pypi.org/project/dexter-controller/)
+[![Python](https://img.shields.io/pypi/pyversions/dexter-controller)](https://pypi.org/project/dexter-controller/)
+
+Python library for the **Dexter** hand device. This library handles device communication, force computation, calibration, and data recording.
+
+## Installation
+
+The recommended way to install the library is via `uv`. In your project add the dependency with:
+
+```bash
+uv add dexter-controller
+# or use pip
+pip install dexter-controller
+```
+
+Optional extras for reading and writing recordings:
+
+```bash
+uv add dexter-controller[reader]    # numpy, for loading recordings
+uv add dexter-controller[parquet]   # pyarrow + numpy, for Parquet format support
+# or use pip
+pip install dexter-controller[reader]    # numpy, for loading recordings
+pip install dexter-controller[parquet]   # pyarrow + numpy, for Parquet format support
+```
+
+## Quick start
+
+Connect over BLE or UART using the `DexterDevice` factory:
+
+```python
+import time
+from dexter_controller import DexterDevice, Finger
+
+device = DexterDevice.create_ble(
+    # connect to a specific device by name:
+    # device_name="Dexter-001"
+)
+device.connect()
+device.start_acquisition()
+
+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 = 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:
+    device.close()
+```
+
+## Force computation
+
+Convert raw load-cell readings into calibrated 2D force vectors (Fx, Fy):
+
+```python
+from dexter_controller import (
+    DEFAULT_CALIBRATION,
+    DexterDevice,
+    Finger,
+    ForceProcessor,
+    get_default_orientation,
+)
+
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
+
+processors = {}
+for finger in Finger:
+    orientation = get_default_orientation(finger)
+    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION, orientation)
+
+# In your read loop:
+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:
+
+```python
+processors[Finger.INDEX].tare.start_tare(sample_count=20)
+```
+
+## Recording data
+
+Record sessions to disk in CSV, SQLite (**default**), or Parquet format:
+
+```python
+from dexter_controller import (
+    DEFAULT_CALIBRATION,
+    DataRecorder,
+    DexterDevice,
+    Finger,
+    ForceProcessor,
+    RecordingMetadata,
+    get_default_orientation,
+)
+from dexter_controller.recording_format import RecordingFormat
+
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
+
+processors = {}
+for finger in Finger:
+    processors[finger] = ForceProcessor(
+        DEFAULT_CALIBRATION, get_default_orientation(finger)
+    )
+
+recorder = DataRecorder(
+    "./recordings",
+    file_format=RecordingFormat.SQLITE,
+    metadata=RecordingMetadata(
+        device_name=device.get_device_name(),
+        sampling_rate_hz=device.get_sampling_rate().value,
+    ),
+)
+
+def on_sample(_data):
+    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)
+
+device.register_finger_callback(Finger.PINKY, on_sample)
+
+recorder.start_recording()
+# ... run until done ...
+recorder.stop_recording()
+device.close()
+```
+
+Each recording file includes session metadata.
+
+Session metadata has the following fields:
+
+- `session_id`: Unique identifier for the recording session.
+- `recording_started_at`: Timestamp when the recording started.
+- `recording_stopped_at`: Timestamp when the recording stopped.
+- `total_samples`: Total number of samples recorded.
+- `library_version`: Version of the library used for recording.
+- `timestamps`: Array of timestamps for each sample.
+- `device_name`: Name of the device used for recording.
+- `sampling_rate_hz`: Sampling rate in Hz.
+- `extras`: Dictionary for experiment-specific metadata.
+
+You can attach experiment-specific metadata via `RecordingMetadata.extras`:
+
+```python
+metadata = RecordingMetadata(
+    device_name="Dexter-001",
+    sampling_rate_hz=1000,
+    extras={"subject_id": "S01", "trial": "3", "condition": "baseline"},
+)
+```
+
+## Reading recordings
+
+Load recorded sessions back for analysis:
+
+```python
+from dexter_controller import RecordingReader
+
+recording = RecordingReader.read("recordings/session.db")
+print(f"Samples: {recording.num_rows}")
+print(f"Session: {recording.metadata.session_id}")
+print(f"Forces shape: {recording.forces.shape}")    # (N, 10) - Fx,Fy per finger
+print(f"Raw channels: {recording.raw_channels.shape}")  # (N, 15) - 3 channels per finger
+```
+
+For either the Sqlite and Parquet formats, you can use Pandas or Polars to load the data for analysis.
+
+```python
+import pandas as pd
+
+# for Sqlite format, use:
+conn = RecordingReader.open("recordings/session.db")
+df = pd.read_sql("SELECT * FROM samples", conn)
+print(df.head())
+
+# or for Parquet format, use:
+df = pd.read_parquet("recordings/session.parquet")
+print(df.head())
+```
+
+You can also convert those formats to CSV for easier analysis or interoperability:
+
+```python
+RecordingReader.to_csv("recordings/session.db")  # produces session.csv
+```
+
+## BLE device configuration
+
+When connected via BLE, you can read and write device settings:
+
+```python
+from dexter_controller import SamplingRate
+
+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]
+> The Visualizer application requires that the device's name must include "Dexter" within the name (e.g., "MyDexter").
+
+Available sampling rates: 100, 200, 400, 800, 1000, 2000 Hz.
+
+## Examples
+
+See the [example/](example/) directory for complete, runnable scripts:
+
+| File                                                         | Description                                                                       |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| [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_uart.py](example/example_uart.py)                   | UART (wired) connection                                                          |
+
+## UART connection
+
+For wired setups using UART:
+
+```python
+import sys
+from dexter_controller import DexterDevice, EventFlags, Finger, SamplingRate
+
+device = DexterDevice.create_uart("COM3")  # or /dev/ttyUSB0 on Linux
+
+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-1.0.0a1/README.md

@@ -0,0 +1,248 @@
+# dexter-controller
+
+[![PyPI](https://img.shields.io/pypi/v/dexter-controller)](https://pypi.org/project/dexter-controller/)
+[![Python](https://img.shields.io/pypi/pyversions/dexter-controller)](https://pypi.org/project/dexter-controller/)
+
+Python library for the **Dexter** hand device. This library handles device communication, force computation, calibration, and data recording.
+
+## Installation
+
+The recommended way to install the library is via `uv`. In your project add the dependency with:
+
+```bash
+uv add dexter-controller
+# or use pip
+pip install dexter-controller
+```
+
+Optional extras for reading and writing recordings:
+
+```bash
+uv add dexter-controller[reader]    # numpy, for loading recordings
+uv add dexter-controller[parquet]   # pyarrow + numpy, for Parquet format support
+# or use pip
+pip install dexter-controller[reader]    # numpy, for loading recordings
+pip install dexter-controller[parquet]   # pyarrow + numpy, for Parquet format support
+```
+
+## Quick start
+
+Connect over BLE or UART using the `DexterDevice` factory:
+
+```python
+import time
+from dexter_controller import DexterDevice, Finger
+
+device = DexterDevice.create_ble(
+    # connect to a specific device by name:
+    # device_name="Dexter-001"
+)
+device.connect()
+device.start_acquisition()
+
+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 = 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:
+    device.close()
+```
+
+## Force computation
+
+Convert raw load-cell readings into calibrated 2D force vectors (Fx, Fy):
+
+```python
+from dexter_controller import (
+    DEFAULT_CALIBRATION,
+    DexterDevice,
+    Finger,
+    ForceProcessor,
+    get_default_orientation,
+)
+
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
+
+processors = {}
+for finger in Finger:
+    orientation = get_default_orientation(finger)
+    processors[finger] = ForceProcessor(DEFAULT_CALIBRATION, orientation)
+
+# In your read loop:
+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:
+
+```python
+processors[Finger.INDEX].tare.start_tare(sample_count=20)
+```
+
+## Recording data
+
+Record sessions to disk in CSV, SQLite (**default**), or Parquet format:
+
+```python
+from dexter_controller import (
+    DEFAULT_CALIBRATION,
+    DataRecorder,
+    DexterDevice,
+    Finger,
+    ForceProcessor,
+    RecordingMetadata,
+    get_default_orientation,
+)
+from dexter_controller.recording_format import RecordingFormat
+
+device = DexterDevice.create_ble()
+device.connect()
+device.start_acquisition()
+
+processors = {}
+for finger in Finger:
+    processors[finger] = ForceProcessor(
+        DEFAULT_CALIBRATION, get_default_orientation(finger)
+    )
+
+recorder = DataRecorder(
+    "./recordings",
+    file_format=RecordingFormat.SQLITE,
+    metadata=RecordingMetadata(
+        device_name=device.get_device_name(),
+        sampling_rate_hz=device.get_sampling_rate().value,
+    ),
+)
+
+def on_sample(_data):
+    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)
+
+device.register_finger_callback(Finger.PINKY, on_sample)
+
+recorder.start_recording()
+# ... run until done ...
+recorder.stop_recording()
+device.close()
+```
+
+Each recording file includes session metadata.
+
+Session metadata has the following fields:
+
+- `session_id`: Unique identifier for the recording session.
+- `recording_started_at`: Timestamp when the recording started.
+- `recording_stopped_at`: Timestamp when the recording stopped.
+- `total_samples`: Total number of samples recorded.
+- `library_version`: Version of the library used for recording.
+- `timestamps`: Array of timestamps for each sample.
+- `device_name`: Name of the device used for recording.
+- `sampling_rate_hz`: Sampling rate in Hz.
+- `extras`: Dictionary for experiment-specific metadata.
+
+You can attach experiment-specific metadata via `RecordingMetadata.extras`:
+
+```python
+metadata = RecordingMetadata(
+    device_name="Dexter-001",
+    sampling_rate_hz=1000,
+    extras={"subject_id": "S01", "trial": "3", "condition": "baseline"},
+)
+```
+
+## Reading recordings
+
+Load recorded sessions back for analysis:
+
+```python
+from dexter_controller import RecordingReader
+
+recording = RecordingReader.read("recordings/session.db")
+print(f"Samples: {recording.num_rows}")
+print(f"Session: {recording.metadata.session_id}")
+print(f"Forces shape: {recording.forces.shape}")    # (N, 10) - Fx,Fy per finger
+print(f"Raw channels: {recording.raw_channels.shape}")  # (N, 15) - 3 channels per finger
+```
+
+For either the Sqlite and Parquet formats, you can use Pandas or Polars to load the data for analysis.
+
+```python
+import pandas as pd
+
+# for Sqlite format, use:
+conn = RecordingReader.open("recordings/session.db")
+df = pd.read_sql("SELECT * FROM samples", conn)
+print(df.head())
+
+# or for Parquet format, use:
+df = pd.read_parquet("recordings/session.parquet")
+print(df.head())
+```
+
+You can also convert those formats to CSV for easier analysis or interoperability:
+
+```python
+RecordingReader.to_csv("recordings/session.db")  # produces session.csv
+```
+
+## BLE device configuration
+
+When connected via BLE, you can read and write device settings:
+
+```python
+from dexter_controller import SamplingRate
+
+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]
+> The Visualizer application requires that the device's name must include "Dexter" within the name (e.g., "MyDexter").
+
+Available sampling rates: 100, 200, 400, 800, 1000, 2000 Hz.
+
+## Examples
+
+See the [example/](example/) directory for complete, runnable scripts:
+
+| File                                                         | Description                                                                       |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| [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_uart.py](example/example_uart.py)                   | UART (wired) connection                                                          |
+
+## UART connection
+
+For wired setups using UART:
+
+```python
+import sys
+from dexter_controller import DexterDevice, EventFlags, Finger, SamplingRate
+
+device = DexterDevice.create_uart("COM3")  # or /dev/ttyUSB0 on Linux
+
+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-1.0.0a1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "dexter-controller"
+version = "1.0.0a1"
+description = "Dexter device Controller"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "bleak==2.1.1",
+    "harp-protocol==0.5.0",
+    "harp-serial==0.5.0",
+]
+
+[[project.authors]]
+name = "Hardware and Software Platform, Champalimaud Foundation"
+email = "software@research.fchampalimaud.org"
+
+[project.optional-dependencies]
+reader = ["numpy>=1.25.0"]
+parquet = [
+    "pyarrow>=14.0.0",
+    "dexter-controller[reader]",
+]
+docs = ["pydoc-markdown>=4.8.2"]
+
+[project.urls]
+Repository = "https://github.com/fchampalimaud/dexter-controller/"
+"Bug Tracker" = "https://github.com/fchampalimaud/dexter-controller/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.13.0"]
+build-backend = "uv_build"

dexter_controller-1.0.0a1/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "dexter-controller"
+version = "1.0.0a1"
+description = "Dexter device Controller"
+readme = "README.md"
+authors = [
+    { name = "Hardware and Software Platform, Champalimaud Foundation", email = "software@research.fchampalimaud.org" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "bleak==2.1.1",
+    "harp-protocol==0.5.0",
+    "harp-serial==0.5.0",
+]
+
+[project.optional-dependencies]
+reader = ["numpy>=1.25.0"]
+parquet = ["pyarrow>=14.0.0", "dexter-controller[reader]"]
+docs = [
+    "pydoc-markdown>=4.8.2",
+]
+
+[project.urls]
+Repository = "https://github.com/fchampalimaud/dexter-controller/"
+"Bug Tracker" = "https://github.com/fchampalimaud/dexter-controller/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.13.0"]
+build-backend = "uv_build"

dexter_controller-1.0.0a1/src/dexter_controller/__init__.py

@@ -0,0 +1,58 @@
+from .ble_dexter_device import BLEDexterDevice
+from .calibration import (
+    DEFAULT_CALIBRATION,
+    CalibrationProfile,
+    ChannelCalibration,
+    LoadCellCalibration,
+    LoadCellCoefficients,
+    calibration_from_channel,
+    create_calibration,
+)
+from .data_recorder import DataRecorder
+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 .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",
+    "BLEDexterDevice",
+    "CalibrationProfile",
+    "ChannelCalibration",
+    "DataMode",
+    "DataRecorder",
+    "DexterDevice",
+    "ErrorStatus",
+    "EventFlags",
+    "Finger",
+    "FingerData",
+    "FingerOrientation",
+    "ForceProcessor",
+    "HandSelection",
+    "LoadCellCalibration",
+    "LoadCellCoefficients",
+    "Recording",
+    "RecordingFormat",
+    "RecordingMetadata",
+    "RecordingReader",
+    "SamplingRate",
+    "TareState",
+    "UartDexterDevice",
+    "calibration_from_channel",
+    "create_calibration",
+    "get_default_orientation",
+]