Metadata-Version: 2.1
Name: octopus-sensing-plux
Version: 1.0.0
Summary: PLUX devices (biosignalsplux, BITalino) support for Octopus Sensing
Home-page: https://octopus-sensing.nastaran-saffar.me
License: GPL-3.0-or-later
Keywords: sensors,plux,biosignalsplux,bitalino,recorder
Author: Nastaran Saffaryazdi
Author-email: nsaffar@gmail.com
Requires-Python: >=3.11,<3.13
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: octopus-sensing (>=5.0.0,<6.0.0)
Project-URL: Repository, https://github.com/octopus-sensing/octopus-sensing-plux
Description-Content-Type: text/markdown

# Octopus Sensing PLUX

[PLUX](https://www.pluxbiosignals.com/) devices (biosignalsplux, BITalino, ...) support for
[Octopus Sensing](https://octopus-sensing.nastaran-saffar.me).

## Installation

```bash
pip install octopus-sensing-plux
```

It installs Octopus Sensing as well.

## Usage

```python
from octopus_sensing.device_coordinator import DeviceCoordinator
from octopus_sensing_plux import PluxStreaming

my_plux = PluxStreaming("BTH00:07:80:4D:2E:76",
                        sampling_rate=1000,
                        active_ports=[1, 2, 3],
                        name="plux",
                        output_path="./output")

device_coordinator = DeviceCoordinator()
device_coordinator.add_devices([my_plux])
```

The device should be paired via Bluetooth before running the code. The address is the device's
MAC address prefixed with `BTH` (Bluetooth) or `BLE` (Bluetooth Low Energy).

Data is recorded in `{output_path}/{name}` as CSV files with the following columns:
`nSeq, port_1, ..., port_n, timestamp, trigger`.

See [examples/plux_example.py](examples/plux_example.py) for a complete example:

```bash
python examples/plux_example.py BTH00:07:80:4D:2E:76 --ports 1 2 --trials 2 --duration 5
```

## Supported platforms

PLUX API is not available on PyPI. Its binaries from
[PLUX python-samples](https://github.com/pluxbiosignals/python-samples) are bundled in
`octopus_sensing_plux/plux_api` (Apache-2.0, see `octopus_sensing_plux/plux_api/LICENSE`)
for:

| Platform                         | Python      |
|----------------------------------|-------------|
| Linux x86_64                     | 3.11, 3.12  |
| Linux ARM32 (e.g. Raspberry Pi)  | 3.11        |
| MacOS Apple Silicon              | 3.11, 3.12  |

On other platforms, download the PLUX API for your platform and Python version and pass its
directory to `PluxStreaming` as `plux_api_path`.

On MacOS, if you see `The communication port could not be initialized`, follow the
"macOS Setup" section of the PLUX python-samples README for the files in
`octopus_sensing_plux/plux_api/M1_3xx`.

## Development

```bash
poetry install
poetry run pytest tests
poetry run mypy octopus_sensing_plux
```

## License

GPL-3.0-or-later. The bundled PLUX API binaries are licensed under Apache-2.0.

