aerosmart-modbus

A typed, async Python model of an aerosmart ventilation/heat-pump unit's Modbus registers. Backend-neutral: built on modbus-connection, so it runs over pymodbus, tmodbus, or an in-memory mock -- no Home Assistant dependency. A Home Assistant integration that consumes this library lives in a separate repository.

Features

• 137 registers across 16 sub-systems, transcribed 1:1 from a live installation's Modbus register map (address, scale, unit).
• Two Modbus units modelled as one device: unit 1 (ventilation controller, which also aggregates most fault/request flags) and unit 2 (heat pump / domestic hot water), read together via one AerosmartDevice object.
• Neutral per-field metadata (value_kind, writable, description, source_key) -- no Home Assistant concepts leak into this layer.
• Pooled block reads per unit (ComponentGroup), not one Modbus round-trip per register.
• A regression test that re-parses the original source YAML and checks every Python field's address/scale still matches it (see "Development", below -- there is no manufacturer register manual to check against instead).

Device structure

Basic usage

import asyncio
from modbus_connection.pymodbus import connect_tcp
from aerosmart_modbus import AerosmartDevice


async def main():
    connection = await connect_tcp("192.0.2.10", port=8899)
    device = AerosmartDevice(
        connection.for_unit(1),  # ventilation
        connection.for_unit(2),  # heat pump
    )
    await device.async_update()
    print(device.outside_temperature.temp_aussenluft, "°C outside")
    print(device.heat_pump.wp_status)


asyncio.run(main())

Known hardware quirk: request pacing

Live-tested against a real unit: this device sits behind a slow RS232-to-Modbus-TCP gateway. Issuing requests back-to-back with no pacing at all made the gateway return responses under stale/mismatched transaction IDs, and most reads timed out. AerosmartDevice therefore asks the shared Modbus transport for 300ms of quiet before and after either unit's requests and a one-second settle delay after connecting. Consumers do not need to add sleeps or configure connection timing themselves.

The device exposes async_update_readings() and async_update_settings() so consumers can poll operating data and the controller clock frequently while reading filter counters and slow-changing settings on a longer interval. async_update() still refreshes everything. Each returns an UpdateReport, allowing one failed sub-system to become unavailable without discarding fresh data from the others.

Metadata and writes

Every field carries a DatapointMetadata (see metadata.py): value_kind ("number", "boolean", or "enum"), writable, verified_writable, description (the original German label), source_key (the original Home Assistant entity id it was transcribed from, for traceability), and the matching value metadata.

meta = device.hot_water_heat_pump.require_metadata_for("wp_brauchwasser_soll_temp")
meta.writable  # True
meta.verified_writable  # True
meta.source_key  # "aerosmartm_wp_brauchwasser_soll_temp"

actual = await device.async_write_verified(
    "hot_water_heat_pump", "wp_brauchwasser_soll_temp", 52.0
)

Use async_write_verified() for consumer-facing controls. It only accepts registers whose write semantics and limits are confirmed by the manufacturer documentation, serializes writes across both controller units, validates the value, and reads the register back immediately. writable=True without verified_writable=True remains an unverified transcription and is rejected by this safe API.

Command-line query tool

python -m pip install -e ".[cli]"
python script/query.py tcp 192.0.2.10 --port 8899

Prints every sub-system's current values, plus how many Modbus reads it took. Not used by CI -- a manual diagnostic tool for probing a real unit.

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format .

Tests run against modbus_connection's in-memory mock (no real device needed) plus a YAML consistency check (tests/test_yaml_consistency.py) against the original source fragments under tests/fixtures/aerosmartm/. Tested against modbus-connection 4.12.x. Project metadata accepts compatible releases from 4.12 up to, but excluding, 5.