aerosmart-modbus 0.1.0

A typed Modbus device model for aerosmart ventilation/heat-pump units

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

Attribute	Unit	Sub-system
general	ventilation	weekday, time/date, software version, device type
outside_temperature	ventilation	outside air temperature + thresholds
room_temperature	ventilation	room air temperature + setpoint
fans	ventilation	fan speeds, run hours, faults
ventilation	ventilation	operating mode, airflow, shading/frost/de-icing
cooling	ventilation	cooling thresholds
summer_bypass	ventilation	summer bypass automation
carbon_dioxide	ventilation	CO2 sensor
fine_dust_filter / coarse_dust_filter	ventilation	filter run time / change flags
fire_alarm	ventilation	fire alarm system contact
aggregate_fault	ventilation	summary fault flags
boost_functions_ventilation	ventilation	HEIZUNG+ boost function (ventilation-side registers)
hot_water_ventilation	ventilation	hot water fault/request flags (as seen from the controller)
utility_lockout	heat pump	utility (EVU) lockout signals
heat_pump	heat pump	compressor, pressures, run hours, status
boost_functions_heat_pump	heat pump	BAD+ boost function (heat-pump-side registers)
hot_water_heat_pump	heat pump	boiler temperatures, hot water setpoint

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())

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.