Metadata-Version: 2.4
Name: pluggeasy-modbus
Version: 0.3.0
Summary: Read a Pluggeasy ventilation unit over Modbus.
Project-URL: Homepage, https://github.com/paschdan/pluggeasy-modbus
Author: Pluggeasy Modbus contributors
License: Apache-2.0
License-File: LICENSE
Keywords: home-automation,hvac,modbus,pluggeasy,pluggit,ventilation
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Requires-Dist: modbus-connection>=3.6
Provides-Extra: cli
Requires-Dist: modbus-connection[pymodbus]>=3.6; extra == 'cli'
Description-Content-Type: text/markdown

# `pluggeasy-modbus` Python library

[![CI](https://github.com/paschdan/pluggeasy-modbus/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/paschdan/pluggeasy-modbus/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/pluggeasy-modbus.svg)](https://pypi.org/project/pluggeasy-modbus/)
[![Python](https://img.shields.io/pypi/pyversions/pluggeasy-modbus.svg)](https://pypi.org/project/pluggeasy-modbus/)
[![License](https://img.shields.io/github/license/paschdan/pluggeasy-modbus.svg)](LICENSE)

`pluggeasy-modbus` is an asynchronous Python library for reading from and writing to a **Pluggeasy ventilation / heat-recovery unit** over Modbus.

## Purpose and scope of this library

The library `pluggeasy-modbus`:

- is intended for operational monitoring and control of a Pluggeasy HRV (heat-recovery ventilation) unit. It covers the full register and coil map exposed by the unit's Modbus interface.
- contains the device-specific data model. It knows the available registers and coils, their data types and metadata (unit, scale), and provides safe grouped reads and validated coil writes.
- does _NOT_ create or own the Modbus transport. Applications utilizing the library provide a [`modbus_connection.ModbusUnit`](https://github.com/home-assistant-libs/modbus-connection) and may use any backend supported by `modbus-connection` (pymodbus, tmodbus, …).

## Data provided by the library

`pluggeasy-modbus` exposes four component groups:

- **Status** — 11 read-only discrete-input flags: active alarms, filter alarm, sensor faults, fan faults, bypass active, boost states. The `boost_active` property correctly inverts the raw register value (register 10030: 0 = boost active).
- **Controls** — 5 writable coils: manual bypass, allow automatic bypass, summer mode, manual boost, snooze mode.
- **Measurements** — 21 read-only input-register sensors: air temperatures (extract, exhaust, outdoor, supply), relative humidity (4 channels), motor voltages and RPMs, bypass damper position, VOC, and four human-readable enum sensors (actual working mode, defrost status, communication error, bypass damper position).
- **Parameters** — 8 read/write holding-register values: bypass temperature thresholds, selected airflow (writable speed preset), manual bypass timer, and Modbus communication settings.

Neutral datapoint metadata such as unit and scale lives on the field descriptors — the model IS the datasheet.

## Enums

The library defines five `IntEnum` classes in `pluggeasy_modbus.enums`:

| Enum | Field | Values |
| :--- | :--- | :--- |
| `SelectedAirflow` | `parameters.selected_airflow` (writable) | `LOW`, `MEDIUM`, `NOMINAL`, `AUTO`, `SNOOZE` |
| `ActualWorkingMode` | `measurements.actual_working_mode` | `SNOOZE`, `LOW`, `MEDIUM`, `HIGH`, `BOOST`, `AUTO_HUMIDITY`, `AUTO_VOC`, `AUTO_0_10V`, `BOOST_IN_AUTO`, `WEEKLY_1`–`WEEKLY_4` |
| `DefrostStatus` | `measurements.defrost_status` | `NOT_ACTIVE`, `FIREPLACE_DEFROST`, `WITH_PRE_HEATER`, `UNBALANCED_AIRFLOWS` |
| `CommunicationError` | `measurements.communication_error` | `NO_ERROR`, `REMOTE_CONTROLLER`, `MODBUS_RTU` |
| `BypassDamperPosition` | `measurements.bypass_damper_position` | `CLOSED`, `OPEN`, `ERROR` |

## Write API

```python
# Set ventilation speed preset
await device.parameters.write("selected_airflow", SelectedAirflow.AUTO)

# Toggle boost mode
await device.async_set_boost(True)

# Reset filter alarm (momentary write)
await device.async_reset_filter_alarm()
```

## Supported device

| Device | Notes |
| :--- | :--- |
| Pluggeasy ventilation / HRV unit | Single fixed station address (slave 1), TCP port 8899 |

## Testing and validation

All register decoding is validated against an in-memory mock backend — no real hardware is required to run the test suite:

```
PYTHONPATH=src python -m pytest
```

The mock backend ships with `modbus-connection` and is imported explicitly in `tests/conftest.py` (no pytest entry-point autoloading).

## Documentation and development

Architecture, usage examples, development setup, and branch workflow are documented in the [project wiki](https://github.com/paschdan/pluggeasy-modbus/wiki).

---

Support for the Home Assistant integration is maintained separately in
[`pluggeasy-core`](https://github.com/paschdan/pluggeasy-core) (HA core integration) and
[`pluggeasy-hacs`](https://github.com/paschdan/pluggeasy-hacs) (HACS custom integration).
