labbench-comm 0.1.1__tar.gz

labbench_comm-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LabBench Society
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

labbench_comm-0.1.1/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: labbench_comm
+Version: 0.1.1
+Summary: Communication with LabBench devices
+Author: Kristian Hennings
+License: MIT License
+        
+        Copyright (c) 2025 LabBench Society
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://labbench.io/
+Project-URL: Repository, https://github.com/LabBench-Society/LabBench.Python
+Project-URL: Issues, https://github.com/LabBench-Society/LabBench.Python/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: typing-extensions>=4.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# labbench-comm
+
+**labbench-comm** is an asynchronous Python framework for communicating with LabBench hardware devices over serial connections.  
+It provides a robust, testable, and extensible protocol stack with concrete device implementations, starting with the **CPAR+** device.
+
+The package is designed for:
+- Scientific and clinical research setups
+- Hardware control and automation
+- Deterministic, protocol-driven device communication
+- Async-first Python applications (`asyncio`)
+
+---
+
+## Features
+
+- **Async-first architecture** using `asyncio`
+- **Robust serial communication** built on `pyserial`
+- **Protocol abstraction** (framing, packets, checksums, dispatch)
+- **Typed device functions and messages**
+- **Extensible device model** for adding new LabBench devices
+- **Unit tests + hardware integration tests**
+- **CPAR+ device support** (functions, messages, waveform control)
+
+---
+
+## Supported Devices
+
+- **CPAR+** (pressure stimulation device)
+
+Additional devices can be added by implementing new `Device`, `DeviceFunction`, and `DeviceMessage` classes.
+
+---
+
+## Requirements
+
+- Python **3.12+**
+- Supported platforms: Windows, Linux, macOS (serial access required)
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install labbench-comm

labbench_comm-0.1.1/README.md

@@ -0,0 +1,46 @@
+# labbench-comm
+
+**labbench-comm** is an asynchronous Python framework for communicating with LabBench hardware devices over serial connections.  
+It provides a robust, testable, and extensible protocol stack with concrete device implementations, starting with the **CPAR+** device.
+
+The package is designed for:
+- Scientific and clinical research setups
+- Hardware control and automation
+- Deterministic, protocol-driven device communication
+- Async-first Python applications (`asyncio`)
+
+---
+
+## Features
+
+- **Async-first architecture** using `asyncio`
+- **Robust serial communication** built on `pyserial`
+- **Protocol abstraction** (framing, packets, checksums, dispatch)
+- **Typed device functions and messages**
+- **Extensible device model** for adding new LabBench devices
+- **Unit tests + hardware integration tests**
+- **CPAR+ device support** (functions, messages, waveform control)
+
+---
+
+## Supported Devices
+
+- **CPAR+** (pressure stimulation device)
+
+Additional devices can be added by implementing new `Device`, `DeviceFunction`, and `DeviceMessage` classes.
+
+---
+
+## Requirements
+
+- Python **3.12+**
+- Supported platforms: Windows, Linux, macOS (serial access required)
+
+---
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install labbench-comm

labbench_comm-0.1.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "labbench_comm"
+version = "0.1.1"
+description = "Communication with LabBench devices"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Kristian Hennings" }
+]
+requires-python = ">=3.12"
+
+dependencies = [
+    "pyserial>=3.5",
+    "typing-extensions>=4.5",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Hardware :: Hardware Drivers",
+    "License :: OSI Approved :: MIT License",    
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.scripts]
+labbench-comm = "labbench_comm.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0"
+]
+
+[project.urls]
+Homepage = "https://labbench.io/"
+Repository = "https://github.com/LabBench-Society/LabBench.Python"
+Issues = "https://github.com/LabBench-Society/LabBench.Python/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "cpar: integration tests for the LabBench CPAR+ device",
+    "hardware: tests that require real hardware",
+    "unittest: unit tests of individual classes"
+]
+log_cli = true
+log_cli_level = "DEBUG"
+

labbench_comm-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

labbench_comm-0.1.1/src/labbench_comm/__init__.py

@@ -0,0 +1,3 @@
+from ._version import __version__
+
+__all__ = ["__version__"]

labbench_comm-0.1.1/src/labbench_comm/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

labbench_comm-0.1.1/src/labbench_comm/cli.py

@@ -0,0 +1,18 @@
+import argparse
+
+from labbench_comm import __version__
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="labbench-comm",
+        description="LabBench device communication toolkit",
+    )
+
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    parser.parse_args()

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/__init__.py

@@ -0,0 +1,92 @@
+"""
+CPAR+ device support.
+
+This package provides:
+- The CPARplusCentral device implementation
+- CPAR-specific functions and messages
+- Waveform and instruction utilities
+- Device-specific enums and definitions
+"""
+
+# ----------------------------------------------------------------------
+# Device
+# ----------------------------------------------------------------------
+
+from .cpar_central import CPARplusCentral
+
+# ----------------------------------------------------------------------
+# Definitions / enums
+# ----------------------------------------------------------------------
+
+from .definitions import (
+    DeviceChannelID,
+    DeviceState,
+    EcpError,
+    EventID,
+    OperatingMode,
+    StopCondition,
+    StopCriterion,
+    WaveformInstructionType,
+)
+
+# ----------------------------------------------------------------------
+# Waveform
+# ----------------------------------------------------------------------
+
+from .waveform import WaveformInstruction
+from .instruction_codec import InstructionCodec
+
+# ----------------------------------------------------------------------
+# Functions
+# ----------------------------------------------------------------------
+
+from .functions import (
+    SetWaveformProgram,
+    StartStimulation,
+    StopStimulation,
+    SetOperatingMode,
+    ClearWaveformPrograms,
+)
+
+# ----------------------------------------------------------------------
+# Messages
+# ----------------------------------------------------------------------
+
+from .messages import (
+    StatusMessage,
+    EventMessage,
+)
+
+# ----------------------------------------------------------------------
+# Public API
+# ----------------------------------------------------------------------
+
+__all__ = [
+    # Device
+    "CPARplusCentral",
+
+    # Enums / definitions
+    "DeviceChannelID",
+    "DeviceState",
+    "EcpError",
+    "EventID",
+    "OperatingMode",
+    "StopCondition",
+    "StopCriterion",
+    "WaveformInstructionType",
+
+    # Waveform
+    "WaveformInstruction",
+    "InstructionCodec",
+
+    # Functions
+    "SetWaveformProgram",
+    "StartStimulation",
+    "StopStimulation",
+    "SetOperatingMode",
+    "ClearWaveformPrograms",
+
+    # Messages
+    "StatusMessage",
+    "EventMessage",
+]

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/codec.py

@@ -0,0 +1,50 @@
+from enum import Enum
+from labbench_comm.devices.cpar.instruction_codec import InstructionCodec
+
+
+class CPARplusCodec:
+    class PressureType(Enum):
+        SUPPLY_PRESSURE = 0
+        STIMULATING_PRESSURE = 1
+
+    MAX_SUPPLY_PRESSURE = 1000.0
+    MAX_SCORE = 10.0
+
+    @staticmethod
+    def time_to_rate(time: float) -> int:
+        return round(time * InstructionCodec.UPDATE_RATE)
+
+    @staticmethod
+    def binary_to_pressure(
+        value: int,
+        pressure_type: "CPARplusCodec.PressureType" = PressureType.STIMULATING_PRESSURE,
+    ) -> float:
+        if pressure_type is CPARplusCodec.PressureType.SUPPLY_PRESSURE:
+            return CPARplusCodec.MAX_SUPPLY_PRESSURE * value / 4095
+        return InstructionCodec.MAX_PRESSURE * value / 4095
+
+    @staticmethod
+    def binary_to_score(value: int) -> float:
+        return CPARplusCodec.MAX_SCORE * value / 255
+
+    @staticmethod
+    def pressure_to_binary(pressure: float) -> int:
+        return InstructionCodec._pressure_to_binary(pressure)
+
+    @staticmethod
+    def delta_pressure_to_binary(delta: float) -> int:
+        return InstructionCodec._pressure_to_binary(
+            delta / InstructionCodec.UPDATE_RATE
+        )
+
+    @staticmethod
+    def count_to_time(count: int) -> float:
+        return count / InstructionCodec.UPDATE_RATE
+
+    @staticmethod
+    def time_to_count(time: float) -> int:
+        return int((time * InstructionCodec.UPDATE_RATE) + 0.9999)
+
+    @staticmethod
+    def get_time(samples: int) -> float:
+        return CPARplusCodec.count_to_time(samples)

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/cpar_central.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+from labbench_comm.protocols.device import Device
+from labbench_comm.protocols.device_function import DeviceFunction
+from labbench_comm.protocols.functions.device_identification import DeviceIdentification
+from labbench_comm.protocols.functions.ping import Ping
+from labbench_comm.devices.cpar.messages import (
+    StatusMessage,
+    EventMessage,
+)
+from labbench_comm.devices.cpar.definitions import (
+    DeviceState,
+    EcpError,
+)
+from labbench_comm.devices.cpar.instruction_codec import InstructionCodec
+from labbench_comm.protocols.manufacturer import Manufacturer
+
+
+class CPARplusCentral(Device):
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def __init__(self, bus) -> None:
+        super().__init__(bus)
+
+        self.baudrate = 38400
+        self.retries = 3
+
+        # --- CPAR+ messages ---
+        self.add_message(EventMessage())
+        self.add_message(StatusMessage())
+
+        # --- Runtime state ---
+        self.state: Optional[DeviceState] = None
+
+        self.actual_pressure_01 = 0.0
+        self.target_pressure_01 = 0.0
+        self.final_pressure_01 = 0.0
+
+        self.actual_pressure_02 = 0.0
+        self.target_pressure_02 = 0.0
+        self.final_pressure_02 = 0.0
+
+        self.response_connected = False
+        self.vas_is_low = False
+        self.vas_score = 0.0
+        self.final_vas_score = 0.0
+
+        self.status_received = []
+        self.event_received = []
+
+    # ------------------------------------------------------------------
+    # Error handling
+    # ------------------------------------------------------------------
+
+    def get_peripheral_error_string(self, error_code: int) -> str:
+        try:
+            return str(EcpError(error_code))
+        except ValueError:
+            return f"Unknown CPAR error ({error_code})"
+
+    # ------------------------------------------------------------------
+    # Message handlers
+    # ------------------------------------------------------------------
+
+    def on_status_message(self, message: StatusMessage) -> None:
+        if message is None:
+            return
+
+        self.actual_pressure_01 = message.actual_pressure_01
+        self.target_pressure_01 = message.target_pressure_01
+        self.final_pressure_01 = message.final_pressure_01
+
+        self.actual_pressure_02 = message.actual_pressure_02
+        self.target_pressure_02 = message.target_pressure_02
+        self.final_pressure_02 = message.final_pressure_02
+
+        self.response_connected = message.vas_connected
+        self.vas_is_low = message.vas_is_low
+        self.vas_score = message.vas_score
+        self.final_vas_score = message.final_vas_score
+
+        self.state = message.system_state
+
+        for cb in self.status_received:
+            cb(self, message)
+
+    def on_event_message(self, message: EventMessage) -> None:
+        if message is None:
+            return
+
+        for cb in self.event_received:
+            cb(self, message)
+
+    # ------------------------------------------------------------------
+    # Compatibility
+    # ------------------------------------------------------------------
+
+    def is_compatible(self, function: DeviceFunction) -> bool:
+        if not isinstance(function, DeviceIdentification):
+            return False
+
+        return (
+            function.manufacturer_id == Manufacturer.InventorsWay
+            and function.device_id == 4
+        )
+
+    # ------------------------------------------------------------------
+    # Representation
+    # ------------------------------------------------------------------
+
+    def __str__(self) -> str:
+        return "CPAR+ Device"

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/definitions.py

@@ -0,0 +1,88 @@
+from enum import IntEnum
+
+
+class DeviceChannelID(IntEnum):
+    CH01 = 0
+    CH02 = 1
+    NONE = 2
+
+class DeviceState(IntEnum):
+    STATE_NOT_CONNECTED = 0
+    STATE_IDLE = 1
+    STATE_STIMULATING = 2
+    STATE_EMERGENCY = 3
+    STATE_PENDING = 4
+
+class EcpError(IntEnum):
+    NO_ERROR = 0
+    UNKNOWN_FUNCTION_ERR = 1
+    INVALID_REQUEST_LENGTH_ERR = 2
+    SYSTEM_NOT_IDLE_ERR = 3
+    INCORRECT_CHANNEL_ERR = 4
+    NO_REPONSE_DEVICE_CONNECTED_ERR = 5
+    RATING_IS_NOT_ZERO_ERR = 6
+    NO_SUPPLY_PRESSURE_ERR = 7
+    NO_POWER_ERR = 8
+    INVALID_START_CONFIGURATION = 9
+    STOP_NOT_POSSIBLE_ERR = 10
+    INVALID_EVENT_ADDRESS_ERR = 11
+    MAX_WAVEFORM_DURATION_EXCEEDED_ERR = 12
+    INVALID_ADDRESS_ERR = 13
+    COULD_NOT_SAVE_TO_EEPROM_ERR = 14
+    INVALID_CHANNEL_ID_ERR = 15
+    CANNOT_SET_BUILT_EVENT_ERR = 16
+    INVALID_RUN_LEVEL_ERR = 17
+
+class EventID(IntEnum):
+    EVT_NO_EVENT = 0
+    EVT_STATUS_UPDATE = 1
+    EVT_START_STIMULATION = 2
+    EVT_STOP_STIMULATION = 3
+    EVT_STOP_BUTTON01_PRESSED = 4
+    EVT_STOP_BUTTON01_RELEASED = 5
+    EVT_STOP_BUTTON02_PRESSED = 6
+    EVT_STOP_BUTTON02_RELEASED = 7
+    EVT_MAX_VAS_SCORED = 8
+    EVT_RESPONSE_DISCONNECTED = 9
+    EVT_RESPONSE_CONNECTED = 10
+    EVT_EMERGENCY_ACTIVATED = 11
+    EVT_EMERGENCY_DEACTIVATED = 12
+    EVT_WAVEFORMS_COMPLETED = 13
+    EVT_TIMELIMIT_EXCEEDED = 14
+    EVT_COMM_WATCHDOG_TRIGGERED = 15
+    EVT_CUFF01_OUT_OF_COMPLIANCE = 16
+    EVT_CUFF02_OUT_OF_COMPLIANCE = 17
+    EVT_SUPPLY_PRESSURE_LOW = 18
+    EVT_12V_POWER_OFF = 19
+    EVT_12V_POWER_ON = 20
+    EVT_AIR_LEAK = 21
+    EVT_TRIG_IN = 22
+
+class OperatingMode(IntEnum):
+    RESPONSE_ENABLED = 0
+    RESPONSE_DISABLED = 1
+
+class StopCondition(IntEnum):
+    STOPCOND_NO_CONDITION = 0
+    STOPCOND_STOP_BUTTON_PRESSED = 1
+    STOPCOND_MAXIMAL_VAS_SCORED = 2
+    STOPCOND_STIMULATION_COMPLETED = 3
+    STOPCOND_MAXIMAL_TIME_EXCEEDED = 4
+    STOPCOND_VASMETER_DISCONNECTED = 5
+    STOPCOND_EMERGENCY_STOP_ACTIVATED = 6
+    STOPCOND_CONTROL_SOFTWARE = 7
+    STOPCOND_OUT_OF_COMPLIANCE = 8
+    STOPCOND_COMM_WATCHDOG = 9
+    STOPCOND_12V_POWER_OFF = 10
+    STOPCOND_SUPPLY_PRESSURE_LOW = 11
+
+class StopCriterion(IntEnum):
+    STOP_CRITERION_ON_BUTTON_VAS = 0
+    STOP_CRITERION_ON_BUTTON_PRESSED = 1
+    STOP_CRITERION_ON_BUTTON_RELEASED = 2
+
+class WaveformInstructionType(IntEnum):
+    TRIG = 0x00
+    INC = 0x01
+    DEC = 0x02
+    STEP = 0x03

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/functions/__init__.py

@@ -0,0 +1,13 @@
+from .set_waveform_program import SetWaveformProgram
+from .start_stimulation import StartStimulation
+from .stop_stimulation import StopStimulation
+from .set_operating_mode import SetOperatingMode
+from .clear_waveform_programs import ClearWaveformPrograms
+
+__all__ = [
+    "SetWaveformProgram",
+    "StartStimulation",
+    "StopStimulation",
+    "SetOperatingMode",
+    "ClearWaveformPrograms",
+]

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/functions/clear_waveform_programs.py

@@ -0,0 +1,20 @@
+from labbench_comm.protocols.device_function import DeviceFunction
+from labbench_comm.protocols.function_dispatcher import FunctionDispatcher
+
+
+class ClearWaveformPrograms(DeviceFunction):
+    @property
+    def code(self) -> int:
+        return 0x21
+
+    def __init__(self) -> None:
+        super().__init__(request_length=0, response_length=0)
+
+    def create_dispatcher(self) -> FunctionDispatcher:
+        return FunctionDispatcher(self.code, lambda: ClearWaveformPrograms())
+
+    def dispatch(self, listener):
+        return listener.accept(self)
+
+    def __str__(self) -> str:
+        return "[0x21] Clear Waveform Programs"

labbench_comm-0.1.1/src/labbench_comm/devices/cpar/functions/set_operating_mode.py

@@ -0,0 +1,42 @@
+from labbench_comm.protocols.device_function import DeviceFunction
+from labbench_comm.protocols.function_dispatcher import FunctionDispatcher
+from labbench_comm.devices.cpar.definitions import OperatingMode
+
+
+class SetOperatingMode(DeviceFunction):
+    @property
+    def code(self) -> int:
+        return 0x20
+
+    def __init__(self) -> None:
+        super().__init__(request_length=1, response_length=0)
+        self.mode = OperatingMode.RESPONSE_ENABLED
+
+    # ------------------------------------------------------------------
+    # Dispatcher
+    # ------------------------------------------------------------------
+
+    def create_dispatcher(self) -> FunctionDispatcher:
+        return FunctionDispatcher(self.code, lambda: SetOperatingMode())
+
+    def dispatch(self, listener):
+        return listener.accept(self)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def mode(self) -> OperatingMode:
+        return OperatingMode(self.request.get_byte(0))
+
+    @mode.setter
+    def mode(self, value: OperatingMode) -> None:
+        self.request.insert_byte(0, int(value))
+
+    # ------------------------------------------------------------------
+    # Representation
+    # ------------------------------------------------------------------
+
+    def __str__(self) -> str:
+        return "[0x20] Set Operating Mode"