dexter-controller 0.1.2__tar.gz → 0.2.0__tar.gz

{dexter_controller-0.1.2 → dexter_controller-0.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.3
 Name: dexter-controller
-Version: 0.1.2
+Version: 0.2.0
 Summary: Dexter Controller for the HARP Load Cells
 Author: Hardware and Software Platform, Champalimaud Foundation
 Author-email: Hardware and Software Platform, Champalimaud Foundation <software@research.fchampalimaud.org>
+Requires-Dist: bleak==2.1.1
 Requires-Dist: harp-loadcells>=0.1.0a3
 Requires-Python: >=3.10
 Project-URL: Bug Tracker, https://github.com/fchampalimaud/dexter-controller/issues

{dexter_controller-0.1.2 → dexter_controller-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dexter-controller"
-version = "0.1.2"
+version = "0.2.0"
 description = "Dexter Controller for the HARP Load Cells"
 readme = "README.md"
 authors = [
@@ -8,6 +8,7 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
+    "bleak==2.1.1",
     "harp-loadcells>=0.1.0a3",
 ]
 

{dexter_controller-0.1.2 → dexter_controller-0.2.0}/src/dexter_controller/__init__.py

@@ -1,10 +1,12 @@
-from .finger import Finger, FingerData
-from .loadcell_device import LoadCellDevice
-from .dexter_hand_controller import DexterHandController
-
-__all__ = [
-    "Finger",
-    "FingerData",
-    "LoadCellDevice",
-    "DexterHandController",
-]
+from .finger import Finger, FingerData
+from .ble_loadcell_device import BLELoadCellDevice
+from .loadcell_device import LoadCellDevice
+from .dexter_hand_controller import DexterHandController
+
+__all__ = [
+    "Finger",
+    "FingerData",
+    "LoadCellDevice",
+    "BLELoadCellDevice",
+    "DexterHandController",
+]

dexter_controller-0.2.0/src/dexter_controller/ble_loadcell_device.py

@@ -0,0 +1,137 @@
+import asyncio
+import struct
+import threading
+from collections import deque
+from dataclasses import dataclass
+from typing import Optional
+
+from bleak import BleakClient, BleakScanner
+
+
+DEVICE_NAME = "Dexter"
+SERVICE_UUID = "a88278d1-7009-4bee-a6f8-e1dc3ff02b92"
+CHAR_UUID = "a88278d2-7009-4bee-a6f8-e1dc3ff02b92"
+
+LOAD_CELLS = 15
+NUM_READINGS = 2
+BLOCK_SIZE = 8 + (LOAD_CELLS * 2)
+PACKET_SIZE = 4 + (NUM_READINGS * BLOCK_SIZE)
+
+
+@dataclass
+class BLELoadCellEvent:
+    payload: list[int]
+    counter: int
+    timestamp_us: int
+
+
+class BLELoadCellDevice:
+    def __init__(self):
+        self.identifier = f"BLE:{DEVICE_NAME}"
+        self._queue = deque()
+        self._queue_lock = threading.Lock()
+
+        self._stop_event = threading.Event()
+        self._ready_event = threading.Event()
+
+        self._client: Optional[BleakClient] = None
+        self._connection_error: Optional[Exception] = None
+        self._is_connected = False
+
+        self._thread = threading.Thread(target=self._thread_main, daemon=True)
+        self._thread.start()
+        self._ready_event.wait(timeout=15.0)
+
+        if not self._is_connected:
+            error = self._connection_error or RuntimeError(
+                "No matching BLE peripheral found"
+            )
+            raise error
+
+    def _thread_main(self):
+        try:
+            asyncio.run(self._run())
+        except Exception as exc:
+            self._connection_error = exc
+            self._ready_event.set()
+        finally:
+            self._is_connected = False
+
+    async def _discover_target(self):
+        target = DEVICE_NAME.lower()
+        discovered = await BleakScanner.discover(timeout=10, return_adv=True)
+
+        for _, (candidate, adv_data) in discovered.items():
+            name = (candidate.name or adv_data.local_name or "").lower()
+            if target in name:
+                self.identifier = (
+                    f"BLE:{candidate.name or DEVICE_NAME} ({candidate.address})"
+                )
+                return candidate
+
+        return None
+
+    def _notification_callback(self, _, data: bytearray):
+        if len(data) < PACKET_SIZE:
+            return
+
+        counter = struct.unpack_from("<i", data, 0)[0]
+
+        with self._queue_lock:
+            for reading_index in range(NUM_READINGS):
+                base = 4 + (reading_index * BLOCK_SIZE)
+                timestamp_us = struct.unpack_from("<Q", data, base)[0]
+                load_cells = list(struct.unpack_from(f"<{LOAD_CELLS}H", data, base + 8))
+                self._queue.append(
+                    BLELoadCellEvent(
+                        payload=load_cells,
+                        counter=counter,
+                        timestamp_us=timestamp_us,
+                    )
+                )
+
+    async def _run(self):
+        print("Searching for BLE device...")
+        device = await self._discover_target()
+        if not device:
+            self._connection_error = RuntimeError("No matching BLE peripheral found")
+            self._ready_event.set()
+            return
+
+        self._client = BleakClient(
+            device,
+            disconnected_callback=lambda _: self._stop_event.set(),
+        )
+
+        try:
+            await self._client.connect()
+            await self._client.start_notify(CHAR_UUID, self._notification_callback)
+            self._is_connected = True
+            self._ready_event.set()
+
+            while not self._stop_event.is_set():
+                await asyncio.sleep(0.05)
+
+        except Exception as exc:
+            self._connection_error = exc
+            self._ready_event.set()
+
+        finally:
+            self._is_connected = False
+            if self._client and self._client.is_connected:
+                try:
+                    await self._client.stop_notify(CHAR_UUID)
+                finally:
+                    await self._client.disconnect()
+
+    def get_events(self):
+        events = []
+        with self._queue_lock:
+            while self._queue:
+                events.append(self._queue.popleft())
+        return events
+
+    def close(self):
+        self._stop_event.set()
+        if self._thread.is_alive():
+            self._thread.join()

{dexter_controller-0.1.2 → dexter_controller-0.2.0}/src/dexter_controller/dexter_hand_controller.py

@@ -2,22 +2,32 @@ import threading
 import time
 from collections import defaultdict
 
-from dexter_controller import Finger, FingerData, LoadCellDevice
+from .finger import Finger, FingerData
+from .ble_loadcell_device import BLELoadCellDevice
+from .loadcell_device import LoadCellDevice
 
 
 class DexterHandController:
-    def __init__(self, mapping):
-        if not mapping:
-            raise ValueError("mapping cannot be empty")
-
-        self._mapping = dict(mapping)  # for reconnects
+    def __init__(
+        self,
+        mapping: dict | None = None,  # {com_port: [Finger, ...]}
+        use_ble=False,  # use BLE instead of serial
+    ):
+        if not use_ble and not mapping:
+            raise ValueError("mapping cannot be empty when use_ble is False")
+
+        self._mapping = dict(mapping or {})
+        self._use_ble = use_ble
         self._lock = threading.Lock()
 
-        self._finger_to_device = {}  # {Finger: (device, 0|1)}
-        self._device_index_to_finger = {}  # {(device, 0|1): Finger}
+        self._finger_to_binding = {}  # {Finger: (device, start, stop)}
+        self._device_to_bindings = defaultdict(
+            list
+        )  # {device: [(Finger, start, stop), ...]}
         self._devices = []
 
-        self.finger_data = defaultdict(lambda: FingerData([0, 0, 0, 0]))
+        default_width = 3 if use_ble else 4
+        self.finger_data = defaultdict(lambda: FingerData([0] * default_width))
         self._finger_has_data = defaultdict(bool)  # {Finger: bool}
         self._finger_last_update_ts = defaultdict(float)  # {Finger: float}
 
@@ -28,13 +38,32 @@ class DexterHandController:
         self.available_ports = []
         self.unavailable_ports = []
 
-        # Initial connect attempt (tolerates missing devices)
-        self._connect_from_mapping(self._mapping)
+        if self._use_ble:
+            self._connect_ble()
+        else:
+            self._connect_from_mapping(self._mapping)
 
         # Poll loop works in background thread
         self._poll_thread = threading.Thread(target=self._poll_loop, daemon=True)
         self._poll_thread.start()
 
+    def _reset_connections(self):
+        for device in self._devices:
+            try:
+                device.close()
+            except Exception:
+                pass
+
+        self._devices.clear()
+        self._finger_to_binding.clear()
+        self._device_to_bindings.clear()
+        self.available_ports.clear()
+        self.unavailable_ports.clear()
+
+    def _bind_finger(self, finger, device, start, stop):
+        self._finger_to_binding[finger] = (device, start, stop)
+        self._device_to_bindings[device].append((finger, start, stop))
+
     def _connect_from_mapping(self, mapping):
         """
         Disconnect any existing devices and try to connect everything described by mapping.
@@ -43,17 +72,7 @@ class DexterHandController:
         """
         with self._lock:
             # Tear down existing connections
-            for d in self._devices:
-                try:
-                    d.close()
-                except Exception:
-                    pass
-
-            self._devices.clear()
-            self._finger_to_device.clear()
-            self._device_index_to_finger.clear()
-            self.available_ports.clear()
-            self.unavailable_ports.clear()
+            self._reset_connections()
 
             # Reconnect all configured ports
             for com_port, fingers in mapping.items():
@@ -67,43 +86,71 @@ class DexterHandController:
                 self._devices.append(device)
                 self.available_ports.append(com_port)
 
-                # A LoadCellDevice yields two indices (0 and 1). Ignore extra configured fingers.
+                # A serial LoadCellDevice yields two 4-value finger slices.
                 if len(fingers) > 2:
                     print(
                         f"Warning: device {com_port} configured with {len(fingers)} fingers; "
-                        "only the first two will be used (indices 0 and 1)."
+                        "only the first two will be used."
                     )
 
                 for i, finger in enumerate(fingers[:2]):
-                    self._finger_to_device[finger] = (device, i)
-                    self._device_index_to_finger[(device, i)] = finger
+                    start = i * 4
+                    stop = start + 4
+                    self._bind_finger(finger, device, start, stop)
+
+    def _connect_ble(self):
+        with self._lock:
+            self._reset_connections()
+
+            try:
+                device = BLELoadCellDevice()
+            except Exception as e:
+                self.unavailable_ports.append("BLE:Dexter")
+                print(f"Failed to connect to BLE device: {e}")
+                return
+
+            self._devices.append(device)
+            self.available_ports.append(device.identifier)
+
+            for finger in (
+                Finger.THUMB,
+                Finger.INDEX,
+                Finger.MIDDLE,
+                Finger.RING,
+                Finger.PINKY,
+            ):
+                # BLE device sends all fingers in one payload, so start/stop indices are fixed
+                start = finger.value * 3
+                stop = start + 3
+                self._bind_finger(finger, device, start, stop)
 
     def _poll_loop(self):
         while not self._stop_event.is_set():
             # Snapshot under lock to avoid races with reconnect()/close()
             with self._lock:
                 devices = list(self._devices)
-                device_index_to_finger = dict(self._device_index_to_finger)
+                device_to_bindings = {
+                    device: list(bindings)
+                    for device, bindings in self._device_to_bindings.items()
+                }
 
             for device in devices:
                 for event in device.get_events():
                     data = getattr(event, "payload", None)
-                    if not data or len(data) < 8:
+                    if not data:
                         continue  # ignore malformed/partial events
 
-                    # 8 values: 4 per index (0 and 1)
-                    for i in (0, 1):
-                        finger = device_index_to_finger.get((device, i))
-                        if finger is None:
-                            continue
+                    for finger, start, stop in device_to_bindings.get(device, ()):
+                        if len(data) < stop:
+                            continue  # ignore malformed/partial events
 
-                        finger_data = list(data[i * 4 : (i + 1) * 4])
+                        finger_data = list(data[start:stop])
                         self.finger_data[finger].raw_data = finger_data
                         self._finger_has_data[finger] = True
                         self._finger_last_update_ts[finger] = time.time()
 
-                        for cb in self._callbacks[finger]:
-                            cb(finger_data)
+                        for callback in self._callbacks[finger]:
+                            callback(finger_data)
 
             time.sleep(0.001)
 
@@ -126,7 +173,7 @@ class DexterHandController:
           - fingers: {Finger: {has_data: bool, last_update_ts: float, mapped: bool}}
         """
         with self._lock:
-            mapped_fingers = set(self._finger_to_device.keys())
+            mapped_fingers = set(self._finger_to_binding.keys())
             available_ports = list(self.available_ports)
             unavailable_ports = list(self.unavailable_ports)
 
@@ -148,7 +195,10 @@ class DexterHandController:
         Disconnect any existing devices and try to reconnect everything from the original mapping.
         Returns: (available_ports, unavailable_ports)
         """
-        self._connect_from_mapping(self._mapping)
+        if self._use_ble:
+            self._connect_ble()
+        else:
+            self._connect_from_mapping(self._mapping)
         return list(self.available_ports), list(self.unavailable_ports)
 
     def close(self):
@@ -159,8 +209,8 @@ class DexterHandController:
             for device in self._devices:
                 device.close()
             self._devices.clear()
-            self._finger_to_device.clear()
-            self._device_index_to_finger.clear()
+            self._finger_to_binding.clear()
+            self._device_to_bindings.clear()
 
         self._callbacks.clear()
 

{dexter_controller-0.1.2 → dexter_controller-0.2.0}/src/dexter_controller/finger.py

@@ -1,16 +1,16 @@
-from enum import Enum
-
-
-class Finger(Enum):
-    THUMB = 0
-    INDEX = 1
-    MIDDLE = 2
-    RING = 3
-    PINKY = 4
-
-
-class FingerData:
-    def __init__(self, raw_data):
-        if raw_data is None or len(raw_data) != 4:
-            raise ValueError("raw_data must have exactly 4 elements")
-        self.raw_data = raw_data
+from enum import Enum
+
+
+class Finger(Enum):
+    THUMB = 0
+    INDEX = 1
+    MIDDLE = 2
+    RING = 3
+    PINKY = 4
+
+
+class FingerData:
+    def __init__(self, raw_data):
+        if raw_data is None or len(raw_data) == 0:
+            raise ValueError("raw_data must have at least one element")
+        self.raw_data = raw_data