myPyllant

GitHub Workflow Status

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). Needs at least Python 3.10.

Not affiliated with Vaillant, the developers take no responsibility for anything that happens to your devices because of this library.

myPyllant

Install and Test

Warning

You need at least Python 3.10

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

..or use Docker:

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

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

Usage

#!/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():
            print(await api.get_time_zone(system))
            print(
                await api.set_holiday(
                    system, datetime.now(), datetime.now() + timedelta(days=7)
                )
            )
            print(await api.cancel_holiday(system))
            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]))
            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

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
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pip install -e .
pre-commit install
pytest

Supporting new Countries

The myVAILLANT app uses Keycloak and OIDC for authentication, with a realm for each country and brand. There is a script to check which countries are supported:

python3 -m myPyllant.tests.find_countries

Copy the resulting dictionary into src/myPyllant/const.py

Contributing Test Data

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

python3 -m myPyllant.tests.generate_test_data -h
python3 -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 python3 -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.

Reverse Engineering API requests of the myVAILLANT app

You'll need an Android device and a computer with ADB on the same network.

Run mitmproxy, for example in Docker: docker run --rm -it -v ~/.mitmproxy:/home/mitmproxy/.mitmproxy -p 0.0.0.0:8080:8080 -p 127.0.0.1:8081:8081 mitmproxy/mitmproxy mitmweb --web-host 0.0.0.0
In the WIFI connection settings of your Android device, set a manual proxy to the IP of the computer running mitmproxy on port 8080, with an exception for identity.vaillant-group.com (which opens in your browser and uses HSTS)
Visit http://mitm.it/ on your Android device, download the CA cert & install it through the settings app
Install ADB and connect your Android device to USB in debug mode
Look for the myVAILLANT APK and download it
Run https://github.com/mitmproxy/android-unpinner on the APK and wait for it to launch the modified app on your Android device with ADB
You should see all API calls in mitmproxy's web interface on http://127.0.0.1:8081 now. If you can't log in because of a certificate error, make sure you added the exception to the proxy settings. If you can log in, but the app reports an error, the unpinning didn't work. You can try https://github.com/NVISOsecurity/MagiskTrustUserCertson if you have a rooted Android device

Notes

Auth is loosely based on https://github.com/TA2k/ioBroker.vaillant
Most API endpoints are reverse-engineered from the myVaillant app, using https://github.com/mitmproxy/mitmproxy
Setting weekly time tables for heating and domestic hot water is still missing
There is a home assistant component based on this library here: https://github.com/signalkraft/mypyllant-component

Logo based on Hase Icons erstellt von Freepik - Flaticon & Ouroboros Icons erstellt von Freepik - Flaticon.

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for myPyllant 0.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for myPyllant 0.5.3
File	Size	Uploaded
mypyllant-0.5.3.tar.gz	77.4 kB	Sep 29, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for myPyllant 0.5.3
File	Interpreter	ABI	Platform	Reset
mypyllant-0.5.3-py3-none-any.whl 49.2 kB Sep 29, 2023	Python 3	none	any	Details

Total release size: 126.7 kB

Release files / mypyllant-0.5.3.tar.gz

Download URL	mypyllant-0.5.3.tar.gz
Size	77.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`443aa2d7514418f0ba94d4be55084e6fa911741f052f153b69b82e087625efca`
BLAKE2b-256 checksum How to use checksums	`e2ff6f42b83738865fba9c79f5b81e188547235a7d23fec3fb4bde221f94aa0b`
Upload date	Sep 29, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/4.0.2 CPython/3.11.5`

Release files / mypyllant-0.5.3-py3-none-any.whl

Download URL	mypyllant-0.5.3-py3-none-any.whl
Size	49.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`67efd9af68fcfbf6e986e1d48d4ac48b3163cf733e57673bb0f85b5a0d2a6f6c`
BLAKE2b-256 checksum How to use checksums	`e2e18c334b3ab49c0fd2544927b4d47c70941bfa0a1b0874783e616aa4eaee6f`
Upload date	Sep 29, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/4.0.2 CPython/3.11.5`