aiomelcloudhome 0.1.5

Asynchronous Python client for the Melcloud Home API

aiomelcloudhome

Asynchronous Python client for MELCloud Home.

About

aiomelcloudhome is an async client for the MELCloud Home API, focused on:

• Fetching account context (buildings and devices)
• Controlling Air-to-Air units
• Controlling Air-to-Water units
• Reading telemetry (energy and actual measurements)

The library is under active development and endpoint coverage will keep expanding.

Installation

pip install aiomelcloudhome

Usage

Authenticate with username and password

import asyncio

from aiohttp import ClientSession

from aiomelcloudhome import MELCloudHome


async def main() -> None:
    async with ClientSession() as session:
        async with MELCloudHome(
            username="[e-mail]",
            password="your_password",
            session=session,
        ) as client:
            context = await client.get_context()

            for building in context.buildings:
                print(f"Building: {building.name}")

                for unit in building.air_to_air_units:
                    print(f"ATA: {unit.name} (room: {unit.room_temperature} C)")

                for unit in building.air_to_water_units:
                    print(f"ATW: {unit.name} (tank: {unit.tank_water_temperature} C)")


if __name__ == "__main__":
    asyncio.run(main())

Authenticate with an existing access token

from aiomelcloudhome import MELCloudHome


client = MELCloudHome(access_token="YOUR_ACCESS_TOKEN")

Control an Air-to-Air unit

from aiomelcloudhome import ATAFanSpeed, ATAOperationMode, MELCloudHome


await client.control_ata_unit(
    "ata-unit-id",
    power=True,
    operation_mode=ATAOperationMode.HEAT,
    set_temperature=21.0,
    set_fan_speed=ATAFanSpeed.AUTO,
)

Control an Air-to-Water unit

from aiomelcloudhome import ATWZoneMode


await client.control_atw_unit(
    "atw-unit-id",
    power=True,
    operation_mode_zone1=ATWZoneMode.HEAT_ROOM_TEMPERATURE,
    set_temperature_zone1=21.0,
    set_tank_water_temperature=50.0,
)

Fetch telemetry

from datetime import UTC, datetime, timedelta


energy = await client.get_energy_telemetry(
    "unit-id",
    from_dt=datetime.now(UTC) - timedelta(days=1),
    to_dt=datetime.now(UTC),
)

outdoor = await client.get_outdoor_temperature("ata-unit-id")

More examples can be found in the examples directory.

Documentation

Project documentation and API reference: https://github.com/erwindouna/aiomelcloudhome

Contributing

Contributions are welcome. Please open an issue or pull request.

For local development:

uv sync --all-groups && uv run pre-commit install

Run checks:

uv run pre-commit run --all-files

Run tests:

uv run pytest

Update snapshot tests:

uv run pytest --snapshot-update

License

MIT License

Copyright (c) 2026 Erwin Douna