Alternative Home Connect Integration for Home Assistant

This project is an alternative integration for Home Connect enabled home appliances manufactured by BSH under the Bosch, Siemens, Constructa and Neff brands. It is not affiliated with either BSH or Home Assistant.

If you're using this integration please star it on Github

Table of contents

• Main features
• Installation instructions
• Creating a Home Connect developer app
• Installing the integration
  • Pre-installation steps
  • Installation
• Configuration options
• Options settable in the UI
• Automation Notes
• Integration state
• Services
• Events
• Triggers
• Local vs. Server translation
• Troubleshooting and FAQ
• Dealing with API rate limits
• Known Issues
• Reporting issues / bugs
  • Bug report requirements
  • Enabling debug logging
  • Setting Log Mode
• Beta Releases
• Contributing Translations
• Legal Notice

Main features

Home Assistant already has a built-in integration for Home Connect, however, it is quite basic, generates entities that are not always supported by the connected appliances and tends to stop getting status updates after a while. This integration attempts to address those issues and has the following features: * All the entities are dynamically read from the API and reflect true capabilities of the appliance. * The integration exposes entities that provide complete control over programs, program options, and global settings. These entities are dynamically read from API and therefore are specifically applicable to the connected appliances. * Configurable options and settings are exposed for easy selection using "Select", "Switch" or "Number" entities, as appropriate. * Read only status values, as well as some selectable options are also made available either using "Sensor" or "Binary Sensor" entities for easier use when only wanting to display them. * Status events that are published by the Home Connect service are exposed as Home Assistant events. * "Program Started" and "Program Finished" events are exposed as triggers for easier building of automation scripts. * A "Start Program" Button entity is provided to start the operation of the selected program. * Program and option selections are also available as a service for easier integration in scripts. * The state of all entities is updated in real time with a cloud push type integration. * Clean handling of appliances disconnecting and reconnecting from the cloud. * Clean handling of new appliances being added or removed from the service. * All the names support translation, but currently only the English translation is provided. * Using pure async implementation for reduced load on the platform.

Installation instructions

Creating a Home Connect developer app

Before installing the integration you need to create an "application" in the Home Connect developers website. Note that if you have an existing application, that was created before July 2022 you will most likely have to update the redirect URI to the one specified below. It can take a few hours for the changes to existing applications to apply, so be patiant.

1. Navigate to the "Applications" page on the Home Connect developers website. You'll be prompted to create an account or sign in if you already have one.
   ➠ NOTE: You MUST use ONLY lowercase letters in the email addresses of both your regular user account and developer account or the integration won't work!
2. Click the "Register Application" link.
3. Fill in the application creation form:
   Application ID: A unique ID for the application, can be home-connect-alt, or whatever you like.
   OAuth Flow: Authorization Code Grant Flow
   Home Connect User Account for Testing: Enter the email address used in the Home Connect mobile app
   Redirect URI: https://my.home-assistant.io/redirect/oauth
   Add additional redirect URIs: Leave unchecked
   Enable One Time Token Mode: Leave unchecked
   Sync to China: Only check if you are located in China
4. Click "Save" then copy the Client ID and Client Secret and save them for use in the next step.

Installing the integration

Pre-installation steps

1. Navigate to https://my.home-assistant.io/ and make sure the Home Assistant Instance is configured correctly to point to your local Home Assistant instance.
2. Power on all your appliances.
3. Turn OFF the wifi on your phone and make sure all the appliances are operational in the Home Connect mobile app.
4. If this is not the first time you are installing the integration and anything changed with your credentials you should go the the Settings -> Devices & Services page on Home Assistant, then click the three-dot-menu on the top righthand corner and select "Application credentials". Locate the previous credentials row for this integration and delete it.

Installation

1. The easiest way to install the integration is using HACS. Just click the button bellow and follow the instructions:
   Alternatively, go to Settings -> Devices & Services in Home Assistance and click the "Add Integration" button. Search for "Home Connect Alt" and install it.
2. A dialog box will popup asking you to select your preferred Home Connect server. Select "China" if you are located in China and "Default" for any other location.
   If you just want to test the integration and see how it you can select the "Simulator" endpoint, which connect to the Home Connect developer simulator and shows all the appliances that exist there. Note that this option is only shown once so you will have to delete the config entry once you finished testing in order to be able to connect to the real API for you actual appliances.

3. Next you will be asked to provide the Home Connect developer app credentials you created earlier. Give these credentials set a name that will make it easy for you to reference them in the Home Assistant credentials manager :

4. Finally, a new window will popup where you will be asked to login to to your Home Connect account and allow Home Assistant to access your appliances. After you approve that you will be redirected back to Home Assistant, continue as instructed.

5. Congratulations, you're done!
   Home Connect Alt will now start downloading the data for your appliances and will add the entities for them to Home Assistant.
   Note that the integration dynamically discovers entities as they are made available by the API, so expect new entities to be added in the first few uses of the appliances.

Configuration options

Starting with version 0.7.0 the integration supports the UI configuration flow for most configuration options. Existing config values will be read however, once the options are saved in the UI they will override the values from the config file.

Options settable in the UI

• Language (optional - default = "en") - Indicates the language to use for entity names and values. The translation is automatically loaded from the Home Connect service and must be one of its supported languages.

• Translation Mode - Indicates how sensor values and select boxes should be translated to friendly names:

• Local - The integration will use the raw ENUM values documented in the Home Connect documentation for sensors with string values. In that case the integration relies on the Home Assistant translation mechanism and translation files to translate these values into friendly names. The benefit of this approach is that the values used by the integration are language independent and match the values documented in the Home Connect API.

• Server - Sensor values are translated to friendly names using the Home Connect service. In this mode the internal values of string sensors will be translated and the translated values must be used in scripts referring to those sensors.

• Delayed start behavior (experimental) - Sets the behavior of the delayed start UI.
  By default the integration will use the standard delay method supported by the appliance. Typically this would be the delay time until the start of the program for dish washers and the delay time until the end of the program for washing machines and dryers. However, it can be annoying to have to work out the time to set instead of just setting and absolute time when the program should finish.
  Setting this option to "Absolute time" will replace the delay entity with a time entity that will always show the expected end time of the selected program. The value of this entity can be changed to set the desired end time for the program. Notes:

• The time will always be interpreted as a future time so anything earlier than "now" will be interpreted as tomorrow.
• The time can't be set for something closer than the duration of the selected program.
• Remote start has to be enabled for this feature to work.

• This feature is still experimental and may have issues

• Name Template - Defines the template used for rendering entity names. The following placeholders are supported and will be replaced dynamically when rendering the name:
  $brand - The brand name of the appliance ("Bosch", "Siemens", etc.)
  $appliance - The type of the appliance ("Washing machine", "Dishwasher", etc.)
  $name - The name of the entity
  The default template is "$brand $appliance - $name"

• Log mode - Defines the log verbosity level. Should normally be set to 0. Don't change this unless asked to do so while working on a bug you reported.

• SSE Timeout -
  Define the timeout, in minutes, to renew the event stream connection with the HC server.
  The default value of 15 minutes is designed to prevent situations of zombie streams that appear to be connected but don't receive events from HC.

The following advanced options that can only be defined using YAML. Generally you should not change them unless you really know what you're doing.

• appliance_settings (optional) - Overrides some settings for specific appliances.
  This setting requires specifying the identifier (HAID) of the appliance. The easiest way to find it is to look at the entity ID of the "Connected" sensor of the appliance. This would look something like binary_sensor.bosch_wat286h0gb_68a64f51deb_connected, and the HAID in this case is bosch_wat286h0gb_68a64f51deb.
  However, if the string after the brand name starts with a digit then you should only use the part of the ID that is to the right of the brand name. For example, if the entity ID is: binary_sensor.bosch_6732863023_68a64f51deb_connected then the HAID is 6732863023_68a64f51deb

Currently supported settings:
name_template - override the global name_template setting
disabled - set to true to disable loading the specified appliance (default=false)

For example: bosch_wat286h0gb_68a64f51deb: name_template: My appliance $name disabled: false

• entity_settings (optional) - Overrides internal entity settings.
  Currently supported settings to override are:
  unit: The units to use for numeric values
  icon: The Material Design icon to use for the entity in the format "mdi:\
  class: The Home Assistant class of the entity (must be a class which is already supported for that entity type) For example: ConsumerProducts.CoffeeMaker.Status.BeverageCounterCoffee: unit: cups icon: mdi:coffee

After the integration is configured READ THE FAQ then add it from the Home-Assistant UI.

Automation Notes

Integration state

• There is a special sensor called Home Connect Status which shows the status of the integration. It has the following values:
• INIT - The integration is initializing
• RUNNING - The integration has started running
• LOADED - The integration finished loading the initial data from the Home Connect service
• READY - The integration has successfully subscribed to real time updates from the cloud service and is now fully functional.
• BLOCKED - The Home Connect service has blocked additional API calls for a period of time due to exceeding the service rate limits *It may take up to one minut