Metadata-Version: 2.4
Name: labbench_comm
Version: 0.1.3
Summary: Communication with LabBench devices
Author: Kristian Hennings
License-Expression: MIT
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: Programming Language :: Python :: 3
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"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Requires-Dist: myst-parser>=4.0; extra == "docs"
Requires-Dist: furo>=2024.8.6; extra == "docs"
Dynamic: license-file

# labbench-comm

**labbench-comm** is an asynchronous Python framework for communicating with LabBench hardware devices over serial connections.

It provides a testable protocol stack for deterministic device communication, with typed device functions, messages, packet framing, checksums, and concrete device implementations.

## Features

- Async-first communication using `asyncio`
- Serial transport support using `pyserial`
- Protocol primitives for frames, packets, stuffing, checksums, dispatch, and device functions
- Typed device-specific functions and messages
- Hardware-oriented examples for supported LabBench devices
- Unit tests plus optional hardware integration tests

## Supported Devices

- **CPAR+**: pressure stimulation device support, including waveform control and status/event messages
- **LabBench I/O (LIO)**: response ports, trigger I/O, analog input/status messages, waveform output, stimulus programs, calibration/event records

## Requirements

- Python **3.12+**
- Windows, Linux, or macOS
- Serial access to compatible LabBench hardware for hardware examples and integration tests

## Installation

Install the package:

```bash
pip install labbench-comm
```

The Python import package is named `labbench_comm`:

```python
import labbench_comm.devices.lio as lio
import labbench_comm.devices.cpar as cpar
```

## Quick Start

```python
import asyncio

from labbench_comm.protocols.bus_central import BusCentral
from labbench_comm.serial.async_serial_connection import AsyncSerialConnection
from labbench_comm.serial.connection import PySerialIO
import labbench_comm.devices.lio as lio


async def main() -> None:
    serial_io = PySerialIO(port="COM3", baudrate=57600)
    connection = AsyncSerialConnection(serial_io)
    bus = BusCentral(connection)
    device = lio.LIOCentral(bus)

    async with device:
        count = await device.ping()
        print("Ping:", count)


asyncio.run(main())
```

## Examples

Examples live in [`examples/`](examples/README.md).

LIO examples include device identification, input monitoring, analog reads, direct voltage output, stimulus programs, waveforms, trigger sequences, and calibration/event records.

Some examples directly drive hardware outputs. Review the script and connected setup before running output-driving examples such as:

```bash
python examples/lio/manual_voltage.py --port COM3 --voltage 1.0
python examples/lio/stimulus_program.py --port COM3
```

## Documentation

- Package documentation starts at [`docs/index.md`](docs/index.md).
- Public API reference is in [`docs/api/index.md`](docs/api/index.md).
- Agent-oriented documentation maps are available in [`llms.txt`](llms.txt) and [`docs/agents.md`](docs/agents.md).
- Release documentation is published with GitHub Pages at `https://labbench-society.github.io/LabBench.Python/` after `v*` release tags are deployed.

Build local documentation:

```bash
python -m pip install -e .[dev,docs]
python -m sphinx -W --keep-going -b html docs docs/_build/html
```

Update package docs when public API, examples, packet semantics, safety behavior, or device workflows change.

## Development Setup

This repository uses a `src/` layout. Install it into the same environment that will run tests or examples:

```bash
python -m pip install -e .[dev]
```

Run unit tests:

```bash
python -m pytest -m unittest -v
```

Build and verify distributions:

```bash
python -m build
twine check dist/*
```

## Project Status

This project is in alpha. APIs may change while device support and protocol coverage mature.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing guidance, and contribution expectations.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).
