myPyllant 0.9.17

A Python library to interact with the API behind the myVAILLANT app

myPyllant

A Python library to interact with the API behind the myVAILLANT app (and branded versions of it, such as the MiGo app from Saunier Duval and Glow-worm). Needs at least Python 3.10.

[!WARNING]
This integration is not affiliated with Vaillant, the developers take no responsibility for anything that happens to your devices because of this library.

• Documentation
• Home Assistant component

Install and Test

[!WARNING]

You need at least Python 3.10

pip install myPyllant

# Only on Windows, and other systems without a timezone database:
pip install tzdata

..or use Docker, if you just want to use it as a CLI tool:

docker run -ti ghcr.io/signalkraft/mypyllant:latest uv run -m myPyllant.export user password brand --country country

Usage

Exporting Data about your System

python3 -m myPyllant.export user password brand --country country
# See python3 -m myPyllant.export -h for more options and a list of countries

The --data argument exports historical data of the devices in your system. Without this keyword, information about your system will be exported as JSON.

Exporting Energy Reports

python3 -m myPyllant.report user password brand --country country
# Wrote 2023 report to energy_data_2023_ArothermPlus_XYZ.csv
# Wrote 2023 report to energy_data_2023_HydraulicStation_XYZ.csv

Writes a report for each heat generator, by default for the current year. You can provide --year to select a different year.

Using the API in Python

#!/usr/bin/env python3

import argparse
import asyncio
import logging
from datetime import datetime, timedelta

from myPyllant.api import MyPyllantAPI
from myPyllant.const import ALL_COUNTRIES, BRANDS, DEFAULT_BRAND

parser = argparse.ArgumentParser(description="Export data from myVaillant API   .")
parser.add_argument("user", help="Username (email address) for the myVaillant app")
parser.add_argument("password", help="Password for the myVaillant app")
parser.add_argument(
    "brand",
    help="Brand your account is registered in, i.e. 'vaillant'",
    default=DEFAULT_BRAND,
    choices=BRANDS.keys(),
)
parser.add_argument(
    "--country",
    help="Country your account is registered in, i.e. 'germany'",
    choices=ALL_COUNTRIES.keys(),
    required=False,
)
parser.add_argument(
    "-v", "--verbose", help="increase output verbosity", action="store_true"
)


async def main(user, password, brand, country):
    async with MyPyllantAPI(user, password, brand, country) as api:
        async for system in api.get_systems():
            if not system.zones:
                print(f"Skipping {system} because there are no active zones")
                continue
            print(await api.set_set_back_temperature(system.zones[0], 18))
            print(await api.quick_veto_zone_temperature(system.zones[0], 21, 5))
            print(await api.cancel_quick_veto_zone_temperature(system.zones[0]))
            setpoint = 10.0 if system.control_identifier.is_vrc700 else None
            print(
                await api.set_holiday(
                    system,
                    datetime.now(system.timezone),
                    datetime.now(system.timezone) + timedelta(days=7),
                    setpoint,  # Setpoint is only required for VRC700 systems
                )
            )
            print(await api.cancel_holiday(system))
            if system.domestic_hot_water:
                print(await api.boost_domestic_hot_water(system.domestic_hot_water[0]))
                print(await api.cancel_hot_water_boost(system.domestic_hot_water[0]))
                print(
                    await api.set_domestic_hot_water_temperature(
                        system.domestic_hot_water[0], 46
                    )
                )


if __name__ == "__main__":
    args = parser.parse_args()
    if args.verbose:
        logging.basicConfig(level=logging.DEBUG)
    asyncio.run(main(args.user, args.password, args.brand, args.country))

Tested Configurations

See https://github.com/signalkraft/mypyllant-component/blob/main/README.md#tested-setups

Contributing

[!WARNING]

You need at least Python 3.10 and uv installed

I'm happy to accept PRs, if you run the pre-commit checks and test your changes:

git clone https://github.com/signalkraft/myPyllant.git
cd myPyllant
uv tool install pre-commit --with pre-commit-uv
pre-commit install
uv run pytest

Contributing Test Data

Because the myVAILLANT API isn't documented, you can help the development of this library by contributing test data:

uv run -m myPyllant.tests.generate_test_data -h
uv run -m myPyllant.tests.generate_test_data username password brand --country country

..or use Docker:

docker run -v $(pwd)/test_data:/build/src/myPyllant/tests/json -ti ghcr.io/signalkraft/mypyllant:latest uv run -m myPyllant.tests.generate_test_data username password brand --country country

With docker, the results will be put into test_data/.

You can then either create a PR with the created folder, or zip it and attach it to an issue.

Acknowledgements

• Auth is loosely based on ioBroker.vaillant
• Most API endpoints are reverse-engineered from the myVaillant app, using mitmproxy
• Logo based on Hase Icons erstellt von Freepik - Flaticon & Ouroboros Icons erstellt von Freepik - Flaticon.