pluggeasy-modbus is an asynchronous Python library for reading from and writing to a Pluggeasy ventilation / heat-recovery unit over Modbus.
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.ModbusUnitand may use any backend supported bymodbus-connection(pymodbus, tmodbus, …).
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_activeproperty 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.
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 |
# 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()| Device | Notes |
|---|---|
| Pluggeasy ventilation / HRV unit | Single fixed station address (slave 1), TCP port 8899 |
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).
Architecture, usage examples, development setup, and branch workflow are documented in the project wiki.
Support for the Home Assistant integration is maintained separately in
pluggeasy-core (HA core integration) and
pluggeasy-hacs (HACS custom integration).