synchroni-sensor-sdk 2.2.0__tar.gz → 2.2.1__tar.gz

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synchroni-sensor-sdk
-Version: 2.2.0
+Version: 2.2.1
 Summary: SDK for interfacing with Synchroni BLE devices
 License-File: LICENSE.txt
 Author: it@synchroni.co
@@ -86,7 +86,9 @@ poetry run python examples/v2_cli.py clean -y
 ```
 
 Useful env vars: `SYNCHRONI_WINUSB_INSTALLER`, `SYNCHRONI_SDK_ASSETS_MANIFEST_URL`,
-`SYNCHRONI_RTK_FIRMWARE_AUTO=0` (disable Realtek host firmware auto-download).
+`SYNCHRONI_RTK_FIRMWARE_AUTO=1` (opt in to Realtek host firmware downloads;
+disabled by default). Otherwise provide local firmware through
+`BUMBLE_RTK_FIRMWARE_DIR`.
 
 ## Quick start (v2)
 
@@ -199,7 +201,7 @@ The sync API runs BLE I/O on a **background event loop** thread (`EventLoopRunne
 | Thread | Sync callbacks run on a **thread-pool worker** via `asyncio.to_thread` — not the main thread and not the BLE loop thread itself |
 | Main thread | **Not blocked** by callbacks while it is free (e.g. sleeping or in your own loop) |
 | Ordering | Dispatch for a given callback type is sequential: each invocation is awaited before the next |
-| Throughput | Slow handlers can cause the drop-oldest data buffer (default 64 packets) to discard data; that is buffer pressure, not main-thread blocking |
+| Throughput | A full data buffer (default 64 packets) rejects new data and reports a scientific delivery fault; already accepted packets drain before the final error callback. Start a new stream explicitly to recover. |
 
 **Do not call blocking hub/sensor methods from a sync callback** (`connect`, `disconnect`, `start_streaming`, `stop_streaming`, etc.). Those schedule work on the same background loop the dispatch task is waiting on and will **deadlock**.
 

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/README.md

@@ -66,7 +66,9 @@ poetry run python examples/v2_cli.py clean -y
 ```
 
 Useful env vars: `SYNCHRONI_WINUSB_INSTALLER`, `SYNCHRONI_SDK_ASSETS_MANIFEST_URL`,
-`SYNCHRONI_RTK_FIRMWARE_AUTO=0` (disable Realtek host firmware auto-download).
+`SYNCHRONI_RTK_FIRMWARE_AUTO=1` (opt in to Realtek host firmware downloads;
+disabled by default). Otherwise provide local firmware through
+`BUMBLE_RTK_FIRMWARE_DIR`.
 
 ## Quick start (v2)
 
@@ -179,7 +181,7 @@ The sync API runs BLE I/O on a **background event loop** thread (`EventLoopRunne
 | Thread | Sync callbacks run on a **thread-pool worker** via `asyncio.to_thread` — not the main thread and not the BLE loop thread itself |
 | Main thread | **Not blocked** by callbacks while it is free (e.g. sleeping or in your own loop) |
 | Ordering | Dispatch for a given callback type is sequential: each invocation is awaited before the next |
-| Throughput | Slow handlers can cause the drop-oldest data buffer (default 64 packets) to discard data; that is buffer pressure, not main-thread blocking |
+| Throughput | A full data buffer (default 64 packets) rejects new data and reports a scientific delivery fault; already accepted packets drain before the final error callback. Start a new stream explicitly to recover. |
 
 **Do not call blocking hub/sensor methods from a sync callback** (`connect`, `disconnect`, `start_streaming`, `stop_streaming`, etc.). Those schedule work on the same background loop the dispatch task is waiting on and will **deadlock**.
 

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synchroni-sensor-sdk"
-version = "2.2.0"
+version = "2.2.1"
 description = "SDK for interfacing with Synchroni BLE devices"
 url = "https://github.com/SynchroniSI/synchroni-sensor-sdk"
 authors = [

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/synchroni_sensor_sdk/__init__.py

@@ -22,6 +22,30 @@ from synchroni_sensor_sdk.core.bluetooth import (
     ClaimResult,
     SensorRoute,
 )
+from synchroni_sensor_sdk.core.device import (
+    BREATHE_PRODUCT_SPECIFICATION,
+    GFORCE_OCT_PRODUCT_SPECIFICATION,
+    GFORCE_PRO_PRODUCT_SPECIFICATION,
+    NATIVE_DEVICE_PROFILES,
+    NURA_NEO_PRODUCT_SPECIFICATION,
+    NURA_OCTO_PRODUCT_SPECIFICATION,
+    NURA_PENTO_PRODUCT_SPECIFICATION,
+    NURA_PRODUCT_SPECIFICATION,
+    NURA_TRIO_PRODUCT_SPECIFICATION,
+    NURA_UNO_PRODUCT_SPECIFICATION,
+    OB3000_PRODUCT_SPECIFICATION,
+    ORION_A_PRODUCT_SPECIFICATION,
+    ORION_B_PRODUCT_SPECIFICATION,
+    ORION_C_PRODUCT_SPECIFICATION,
+    ORION_PRODUCT_SPECIFICATION,
+    OYWW1000_PRODUCT_SPECIFICATION,
+    NativeDeviceProfile,
+    ProductSpecification,
+    SignalAcquisitionMode,
+    native_device_profile,
+    native_device_profile_by_id,
+    published_product_specification,
+)
 from synchroni_sensor_sdk.core.exceptions import (
     AdapterFirmwareError,
     BluetoothAdapterBusyError,
@@ -64,6 +88,7 @@ __all__ = [
     "BluetoothAdapterClaimRequiredError",
     "BluetoothAdapterNotFoundError",
     "BluetoothCapability",
+    "BREATHE_PRODUCT_SPECIFICATION",
     "ClaimFailedError",
     "ClaimResult",
     "clear_winusb_installer_cache",
@@ -74,9 +99,27 @@ __all__ = [
     "DataContextStopStreamingError",
     "DataNotificationInProgressError",
     "ensure_winusb_installer",
+    "GFORCE_OCT_PRODUCT_SPECIFICATION",
+    "GFORCE_PRO_PRODUCT_SPECIFICATION",
     "InvalidDeviceServiceError",
     "ManagedUsbUnavailableError",
     "MultiAdapterDisabledError",
+    "NATIVE_DEVICE_PROFILES",
+    "NURA_NEO_PRODUCT_SPECIFICATION",
+    "NURA_OCTO_PRODUCT_SPECIFICATION",
+    "NURA_PENTO_PRODUCT_SPECIFICATION",
+    "NURA_PRODUCT_SPECIFICATION",
+    "NURA_TRIO_PRODUCT_SPECIFICATION",
+    "NURA_UNO_PRODUCT_SPECIFICATION",
+    "NativeDeviceProfile",
+    "ORION_A_PRODUCT_SPECIFICATION",
+    "ORION_B_PRODUCT_SPECIFICATION",
+    "ORION_C_PRODUCT_SPECIFICATION",
+    "ORION_PRODUCT_SPECIFICATION",
+    "OYWW1000_PRODUCT_SPECIFICATION",
+    "OB3000_PRODUCT_SPECIFICATION",
+    "ProductSpecification",
+    "SignalAcquisitionMode",
     "SYSTEM_DEFAULT_ADAPTER_ID",
     "ScanResult",
     "SensorError",
@@ -90,6 +133,9 @@ __all__ = [
     "StopDataNotificationError",
     "WindowsClaimUnavailableError",
     "configure_logging",
+    "native_device_profile",
+    "native_device_profile_by_id",
+    "published_product_specification",
     "sensor_hub",
     "winusb_installer_cache_dir",
 ]

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/synchroni_sensor_sdk/async_api/driver/base.py

@@ -16,7 +16,7 @@ class Driver(ABC):
 
     All methods are async and must be awaited from the caller's event loop.
 
-    Sensor data uses a bounded :class:`DropOldestBuffer`; power, state, and error
+    Sensor data uses a bounded buffer that faults on overflow; power, state, and error
     events use unbounded asyncio queues.
 
     **Publishing sensor data**
@@ -40,7 +40,11 @@ class Driver(ABC):
         self._logger = logging.getLogger(__name__)
         self._address = address
         self._loop: asyncio.AbstractEventLoop | None = None
-        self._data_buffer: DropOldestBuffer[SensorData] = DropOldestBuffer(data_buffer_maxsize)
+        self._data_buffer: DropOldestBuffer[SensorData] = DropOldestBuffer(data_buffer_maxsize, reject_on_full=True)
+        self._scientific_delivery_fault: str | None = None
+        self._accepted_data_sequence = 0
+        self._delivery_generation = 0
+        self._scientific_fault_boundary: tuple[int, int] | None = None
         self._power_queue: asyncio.Queue[int] = asyncio.Queue()
         self._state_queue: asyncio.Queue[DeviceState] = asyncio.Queue()
         self._error_queue: asyncio.Queue[str] = asyncio.Queue()
@@ -66,13 +70,62 @@ class Driver(ABC):
 
     async def publish_data(self, data: SensorData) -> None:
         """
-        Enqueue sensor data, dropping the oldest packet when the buffer is full.
+        Enqueue sensor data, reporting a scientific-delivery fault if full.
 
         Use when the caller is already on the driver's event loop. For BLE
         notification handlers that may run on a platform thread, use
         :meth:`schedule_publish_data` instead.
         """
-        await self._data_buffer.publish(data)
+        self.publish_data_on_loop(data)
+
+    def report_scientific_delivery_fault(self, reason: str) -> None:
+        """Latch one fault on the driver loop; recovery requires an explicit new stream."""
+        if self._scientific_delivery_fault is not None:
+            return
+        self._scientific_delivery_fault = reason
+        self._scientific_fault_boundary = (self._delivery_generation, self._accepted_data_sequence)
+        self._publish_error_on_loop(
+            f"SDK_SCIENTIFIC_DELIVERY_FAULT|delivery_generation={self._delivery_generation}"
+            f"|accepted_sequence={self._accepted_data_sequence}|{reason}"
+        )
+
+    @property
+    def scientific_fault_boundary(self) -> tuple[int, int] | None:
+        """Generation and last public packet accepted by this driver's bounded buffer."""
+        return self._scientific_fault_boundary
+
+    def reset_scientific_delivery(self) -> None:
+        """Reset only when starting a new stream, never from the parser watchdog."""
+        if self._data_buffer.qsize:
+            raise RuntimeError("Previous sensor stream still has undelivered data")
+        self._data_buffer.clear_on_loop()
+        self._scientific_delivery_fault = None
+        self._scientific_fault_boundary = None
+        self._delivery_generation += 1
+
+    @property
+    def pending_data_packets(self) -> int:
+        return self._data_buffer.qsize
+
+    def publish_data_on_loop(self, data: SensorData) -> None:
+        """Nonblocking parser handoff without a deferred callback for each packet."""
+        if self._scientific_delivery_fault is not None:
+            return
+        if self._data_buffer.closed:
+            self.report_scientific_delivery_fault("stage=parsed_buffer_closed")
+            return
+        try:
+            self._data_buffer.publish_on_loop(data)
+            self._accepted_data_sequence += 1
+            # publish_on_loop cannot yield; fill the accepted packet's boundary
+            # before its consumer can run. Rejected packets receive no sequence.
+            data.delivery_sequence = self._accepted_data_sequence
+            data.delivery_generation = self._delivery_generation
+        except BufferError:
+            self.report_scientific_delivery_fault(
+                f"stage=parsed_buffer|capacity={self._data_buffer.maxsize}"
+                f"|packet_counter={data.last_package_counter}|received_monotonic_ns={data.received_monotonic_ns}"
+            )
 
     def schedule_publish_data(self, data: SensorData) -> None:
         """
@@ -92,7 +145,7 @@ class Driver(ABC):
         """
         if self._loop is None:
             raise RuntimeError("Driver event loop is not bound; call connect() first")
-        self._loop.call_soon_threadsafe(self._data_buffer.publish_on_loop, data)
+        self._loop.call_soon_threadsafe(self.publish_data_on_loop, data)
 
     def _publish_power_on_loop(self, level: int) -> None:
         self._power_queue.put_nowait(level)

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/synchroni_sensor_sdk/async_api/driver/buffer.py

@@ -23,11 +23,12 @@ class DropOldestBuffer(Generic[T]):
     the loop thread.
     """
 
-    def __init__(self, maxsize: int = DEFAULT_DATA_BUFFER_MAXSIZE) -> None:
+    def __init__(self, maxsize: int = DEFAULT_DATA_BUFFER_MAXSIZE, *, reject_on_full: bool = False) -> None:
         self._logger = logging.getLogger(__name__)
         if maxsize < 1:
             raise ValueError("maxsize must be >= 1")
         self._maxsize = maxsize
+        self._reject_on_full = reject_on_full
         self._buffer: deque[T] = deque(maxlen=maxsize)
         self._lock = asyncio.Lock()
         self._event = asyncio.Event()
@@ -64,6 +65,8 @@ class DropOldestBuffer(Generic[T]):
             return
         if len(self._buffer) == self._maxsize:
             self.dropped += 1
+            if self._reject_on_full:
+                raise BufferError("Parsed sensor data buffer is full")
         self._buffer.append(item)
         self._event.set()
 
@@ -72,8 +75,15 @@ class DropOldestBuffer(Generic[T]):
             return
         if len(self._buffer) == self._maxsize:
             self.dropped += 1
+            if self._reject_on_full:
+                raise BufferError("Parsed sensor data buffer is full")
         self._buffer.append(item)
 
+    def clear_on_loop(self) -> None:
+        """Discard the previous stream's tail only at an explicit stream-start boundary."""
+        self._buffer.clear()
+        self._event.clear()
+
     async def close(self) -> None:
         async with self._lock:
             self._closed = True

{synchroni_sensor_sdk-2.2.0 → synchroni_sensor_sdk-2.2.1}/synchroni_sensor_sdk/async_api/driver/gforce/convert.py

@@ -16,8 +16,11 @@ from synchroni_sensor_sdk.core.data import NtfDataType, Sample, SensorData
 def _sample_to_public(sample: ParseSample) -> Sample:
     return Sample(
         raw_data=sample.rawData,
-        data=int(sample.data) if isinstance(sample.data, float) else sample.data,
-        impedance=int(sample.impedance),
+        # Converted biosignal values and impedance are intentionally kept as
+        # floats.  Casting here silently quantizes scientific data before it
+        # reaches application callbacks.
+        data=float(sample.data),
+        impedance=float(sample.impedance),
         saturation=float(sample.saturation),
         sample_index=sample.sampleIndex,
         is_lost=sample.isLost,
@@ -42,4 +45,5 @@ def sensor_data_to_public(packet: ParseSensorData) -> SensorData:
         min_package_sample_count=packet.minPackageSampleCount,
         K=packet.K,
         lost_package_count=getattr(packet, "lostPackageCount", 0),
+        received_monotonic_ns=max(0, int(getattr(packet, "receivedMonotonicNs", 0))),
     )