Contributing - rmalbrecht/VaillantCloud GitHub Wiki

Debugging

When debugging or reporting issues, turn on debug logging by adding this to your configuration.yaml and restarting Home Assistant:

logger:
  default: warning
  logs:
    custom_components.myVaillant: debug
    myVaillant: debug

Then you can check for errors in System :arrow_right: Logs and attach the logs when creating an issue.

If you would like to see a value added to the integration, check if it's available when you generate test data.

Contributing Test Data

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

== "Home Assistant Service"

Go to Developer Tools :arrow_right: Services and select myVaillant.generate_test_data. Then call the service and copy the resulting output.

Open your Home Assistant instance and show your service developer tools with a specific service selected.

== "Shell"

python3 -m myVaillant.tests.generate_test_data -h
python3 -m myVaillant.tests.generate_test_data username password brand --country country

== "Docker"

docker run -v $(pwd)/test_data:/build/src/myVaillant/tests/json -ti ghcr.io/rmalbrecht/myVaillant:latest python3 -m myVaillant.tests.generate_test_data 'username' 'password' brand --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.

Contributing to the HA Component

!!! warning

You need at least Python 3.10.

Fork and clone the VaillantCloud repository, then from within the directory run:

python3 -m venv .venv
source .venv/bin/activate
pip install -r dev-requirements.txt
pre-commit install
# Make your changes
git commit -m ...  # Code formatting, analysis, and tests are run automatically before the commit

If you also need to modify the underlying myVaillant library, clone & install it in editable mode in VaillantCloud:

# From within the VaillantCloud directory
git clone https://github.com/rmalbrecht/myVaillant.git ../myVaillant
pip install -e ../myVaillant

Now you can modify myVaillant/src and directly develop against these changes in VaillantCloud.

VSCode Dev Container

There's also a VSCode dev container available in .devcontainer.json, provided by github.com/ml1nk.

Testing in Docker

To test your changes, you can spin up a quick Docker environment:

  1. Follow the installation steps above
  2. Copy .env.sample to .env and add your credentials in the new file
  3. Run docker compose up

After HA started, open http://localhost:8123 in your browser and sign in with user test and password test.

The integration should be configured and show entities on the default dashboard.

default-dashboard

Contributing to the underlying myVaillant library

!!! warning

You need at least Python 3.10

Fork and clone the myVaillant repository, then from within the directory run:

python3 -m venv .venv
source .venv/bin/activate
pip install -r dev-requirements.txt
pip install -e .
pre-commit install
# Make your changes
git commit -m ...  # Code formatting, analysis, and tests are run automatically before the commit

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 myVaillant.tests.find_countries

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

::: myVaillant.tests.find_countries.main options: show_source: true heading_level: 0

Adding new API endpoints

If your myVAILLANT app has more features than this integration, chances are you have a more complex system then me. You can reverse engineer the API endpoints and open an issue with the requests + responses. See Reverse Engineering for a tutorial.

Running commands on your Home Assistant installation in Docker

If you're using this component in a Home Assistant installation that uses docker compose, you can run these commands directly (from the folder that contains your docker-compose.yml):

docker compose exec homeassistant python3 -m myVaillant.tests.generate_test_data username password brand --country country
# Note the output folder
docker compose cp homeassistant:<testdata folder> .
# Test data will be copied to your current directory

Acknowledgements