Home Assistant Installation Guide - bosch-thermostat/home-assistant-bosch-custom-component GitHub Wiki

This page describes the installation of the Bosch integration.

You Home Assistant should have a HACS installed and fully working. Please follow the guide at HACS for guidance. Manual installation of the integration is possible, but not covered on this page.

The integration is using HTTP and XMPP to connect to the Bosch gateway. XMPP uses uport 5222 and 5223. HTTP communication requires port 80. Please ensure that your network has no blocking firewall for XMPP traffic.

Connection to a CT200 EasyControl requires a credentials. The gateway serial number and token are on the back of the device or on a separate sticker. The password needs to be set at the EasyControl App

In order to add the Bosch integration to HA via HACS, you need to download the repository. Go to HACS and select Integration. Add the repo by using the Plus button in the right lower corner. Search for Bosch and select the right repro (not Bosch SHC or Bosch Indego Mower).

Download the repository and restart Home Assistant.

You need to reboot HA core to make the newly downloaded repro available in HA.

Note that in a fresh install the HACS add on needs some time to collect all repos. You can check the HACS status by using About. .

Move to Configuration in your Home Assistant sidebar and select Integration:

Use the right lower corner button to add an integration.

A search dialog appears that shows all integrations available for your installation. If HACS is working successfully, your should be able to search for Bosch by entering it in the search line.

Select Bosch as integration for installation and click on it. Bosch SHC is the Smart Home Controller and NOT the integration for Buderus, Junkers etc.

NOTE: In case you only get the Bosch SHC as search result, please restart your HA installation and clear the browser cache.

After clicking on the integration, you need to select your heating control system.

For EasyControl CT200 select the respective button:

You will need to enter the gateway serial number, the token and the EasyControl password now. The device has preset serial number and token. These are printed on the back of the EasyControl and on the little manual provided by Bosch. They look like this: Serial 101042138, Access Code: 7Eq4jClmTLAlfbT6. The EasyControl password is set by you in the App on your Smartphone. NOTE: There were reports of issues with passwords longer than 8 letters and with passwords that contained special characters. If the integration does not work, please check the password.

For devices like Bosch CS7001i, Buderus KM50, KM100 or KM200 please select IVT.

IVT devices use HTTP as network protocol.

The IP address of the IVT device needs to be found in your router.

For the IVT you must enter the IP-address of the gateway, the device access token and the device password. Please find the IP address for your device in your network router.

The device password is not an account password. It is not your SingleKey ID, and it is not your MyBuderus / Bosch Home Comfort account password. On Buderus gateways it is also frequently not set by the app that prompts you for it — see Setting the device password on Buderus gateways if setup fails with a decryption error.

The access token for the device is found on a sticker attached to your IVT. It is listed on the sticker as password.

Be patient now. Your Home Assistant is connecting to the Bosch gateway and fetches the system configuration. This will take more than 10 seconds and should complete within 2 minutes. As a result, the integration will show your setup. Before pressing Finish, you may want to set the Area of the different devices.

In the case below, we have 4 zones or rooms set up. These have Bosch thermostats in each zone. This is equivalent to the rooms setup in the EasyControl app. The other devices are the gateway and the heater itself.

Pressing Finish will show the integrated Bosch heating system and it's entities. The thermostats will show up in your default Lovelace System Overview after a couple of seconds. Be patient again. NOTE: Many entities/sensors are NOT activated. This needs to be done next.

You will find serial and token on the back of your EasyControl. This sticker shows them as Login Name and Password.

Do not enter the - in the password. The printed password 7Eq4-jClm-TLAl-fbT6 should be entered as 7Eq4jClmTLAlfbT6.

1. Go to Settings:

2. Go to Personal

3. Next screen has option to Change your thermostat password. There were reports of issues with passwords longer than 8 letters and with passwords that contained special characters. If the integration does not work, please check the password.

If setup fails with a decryption error such as:

Wrong IP or credentials at <IP> - Unable to decrypt: 'utf-8' codec can't decode byte 0x82 in position 1: invalid start byte

then the most likely cause is that the device password was never actually set on the gateway, even though an app asked you to set one.

Why this happens. The MyBuderus app pairs with the gateway using its QR code, which carries the ID and access token. It does not need the device password at all — but it still prompts you for one, and does not write it to the gateway. Resetting the password at the boiler control panel can look the same way: the reset option disappears afterwards, which reads as success. In both cases the gateway ends up with no usable password, while you believe one is set.

The separate Buderus MyDevice app connects to the gateway locally, so it genuinely needs the password — and setting it there does write it to the gateway.

How to fix it

1. Install the Buderus MyDevice app. This is a different app from MyBuderus.
2. Add the gateway by scanning its QR code.
3. Set the device password when prompted. The app will say it is rewriting or resetting it.
4. Choose the local-only connection option if offered.
5. Verify from any computer on the same network before retrying in Home Assistant:

pip install bosch-thermostat-client
bosch_cli query --host <gateway IP> --token <access token without dashes> --password <password> --protocol HTTP --device ivt -p /gateway/uuid

If this returns the gateway UUID, the password is set correctly and Home Assistant will accept it too.

Notes

• Keep the password simple. There are reports of failures with passwords longer than 8 characters and with passwords containing special characters.
• The access token is the value printed on the gateway sticker as password, entered without the dashes.
• Re-pairing successfully in the MyBuderus app does not confirm the password is correct, since that app never uses it. Only a local check, such as the command above or the MyDevice app, confirms it.

Thanks to @starenchanter, @malkie-hass and @luhema for tracking this down in #548.

You can check the status of the HACS installation by selecting About in HACS. It should show more that 900 repos. If this is not the case, you need to check the HACS installation.