pluggeasy-modbus Python library

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 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:

Write API

# 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

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.

Support for the Home Assistant integration is maintained separately in pluggeasy-core (HA core integration) and pluggeasy-hacs (HACS custom integration).