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. Setting unit.set_message_spacing(0.3) (300ms between requests) on both units, plus a short (~1-2s) settle delay after connecting and after switching which unit you address, fixed this completely -- all 137 registers then read cleanly. This library does not set spacing itself (it only models registers, not connection policy); a consumer talking to the real gateway should configure it on the ModbusUnit it passes in. The Home Assistant integrations in the sibling repos do this already.

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 3.4.x.