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" or "boolean"), writable, description (the original German label), source_key (the original Home Assistant entity id it was transcribed from, for traceability), and either NumberMetadata or BooleanMetadata.

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

await device.hot_water_heat_pump.write("wp_brauchwasser_soll_temp", 52.0)

Caution: writable=True here reflects a naming heuristic against an unverified register map, not a confirmed manufacturer specification -- treat every writable field as unverified until checked against the real unit.

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.