Install

• Use the following link to add the repository or follow the additional instructions:

• open Add-ons in HomeAssistant Settings
• Go to "Add-On Store"
• add new repository:

• add https://github.com/hcpy2-0/hcpy

• reload the page. The Addon should appear.
• Click on Addon and install.
• Start the addon (this creates the relevant config folder for later steps, we don't expect it to run properly yet)

Configure from Advanced SSH & Web Terminal Addon (Preferred)

• Add a user to the SSH addon via the configuration menu
• Turn off Protection Mode and restart the SSH addon
• Type docker images to show installed addon images, take a note of the hcpy IMAGE ID value:

• Type ls /addon_configs, take a note of your hcpy configuration directory unique identifier (if this folder doesn't exist ensure you have started the HCPY addon). This short path will not be used, ensure you use the full /mnt/data/supervisor/addon_configs path in the next step:

• Run the following command (replacing the FOLDERID and IMAGE_ID identifiers with those obtained above) to retrieve the devices.json file by copy and pasting the generated URL into a browser and observing the relevant code and state values from the network tab.

docker run -ti -v /mnt/data/supervisor/addon_configs/FOLDERID_hcpy:/config IMAGE_ID /app/hc-login.py /config/devices.json

• See the later section on Obtaining Code and State for advice on completing the OAUTH challenge/response if required.

Configure from HAOS command line

• Make sure you are able to copy and paste from the Hypervisor console or later steps will be difficult to retype
• Access the command line of your HAOS either via SSH or Hypervisor:
• Type login to get a shell via the prompt
• Type docker images to show installed addon images and take a note of the IMAGE ID value:

• Type ls /mnt/data/supervisor/addon_configs/ and take a note of your hcpy configuration directory
• Run the following command (replacing the FOLDERID and IMAGE_ID identifiers with those obtained above) to retrieve the devices.json file by copy and pasting the generated URL into a browser and observing the relevant code and state values from the network tab.

docker run -ti -v /mnt/data/supervisor/addon_configs/FOLDERID_hcpy:/config IMAGE_ID /app/hc-login.py /config/devices.json

Obtaining authentication code and state:

The challenge response in this step is time-sensitive. Recommend that it is performed within 60s to prevent issues, as we haven't determined the expiry period.

• Generate the api-home-connect.com OAUTH URL using the hc-login.py script as detailed above (this can also be performed on a local Python install and the devices.json file can be copied to the HA host.
• Access the URL in the browser (Chrome is recommended):
• Press F12 to access developer tools and view the network panel:
• Login to the first HomeConnect page and you will be redirected to a SingleKeyID login:
• View the prod redirect to hcauth (filter by Doc in the network filter can help):
• Copy and paste the code and state values (between = and &) into the the Input code: and Input state:: prompts to generate devices.json
• The code value will normally end with a %3D value, there is no need to URL decode this value

Final configuration

• Open the devices.json file and check the value of the host key. if the host is not a full qualified domain name, add your local domain. eg.: "host": "SIEMENS-Dishwasher", change to "host": "SIEMENS-Dishwasher.fritz.box", or use the IP address of the device (but then make sure that the device has a static ip).

• now go to the addon configuration page and fill out like in the image above.
• In case you use the mosquitto mqtt addon, simply create an user in homeassistant. Sometimes a reload of the addon is necessary. Then you can use this user for the mqtt auth.
• Restart HCPY addon and check the logs to ensure it is working as intended