Home Connect Local

The Home Connect Local allows users to integrate their home appliances supporting the Home Connect standard for Bosch and Siemens using direct communication over the local network.

Use Cases

Monitor the multiple sensors of the appliance and trigger automations based on these sensors.
Start programs on your appliances from your dashboard.
Monitor the program status of the appliances.
Control the light of your appliances.
Adjust the appliance settings.

Install the Integration

Go to the HACS -> Custom Repositories and add this repository as a Custom Repository See HACS Documentation for help
Click the button bellow and click 'Download' to install the Integration:
Restart Home Assistant.

Supported Devices

Any Home Connect device that

Allows a local connection (not all do) (View trouble shooting for more info to make sure your device supports a local connection)
On the same local network as your Home Assistant instance

Prerequisites

To use this integration, you must first create a Home Connect account and connect your appliances.

Setup

Note

Both of these methods aren't something Home Connect has authorized for third-party use, and the endpoints involved are undocumented and could change or be locked down without notice. If that's not something you're comfortable with, dont use this integration and instead use the core home connect integration.

There are two ways to add an appliance. Signing in is quicker and doesn't require a separate tool.

Option A: Sign in with Home Connect

Click the button below or use "Add Integration" in Home Assistant and select "Home Connect Local".
Choose "Sign in with Home Connect" and select the region your Home Connect account is registered in.
Open the shown URL in a browser and sign in with your Home Connect account. The page will fail to load afterward. That's expected.
Copy the full URL from your browser's address bar and paste it back into Home Assistant.
Select the Appliance you want to setup (skipped automatically if it's the only one left to add).
When the initial connection to the Appliance fails, you're asked to manually enter your Appliance IP-Address.
Repeat from Step 1 if you want to setup more than one Appliance.

Option B: Upload Profile File

Use the Home Connect Profile Downloader to download your Appliance profiles, select "Home Assistant - Home Connect Local" as target. The downloaded ZIP-file contains each Appliance encryption Key and feature descriptions
Click the button below or use "Add Integration" in Home Assistant and select "Home Connect Local".
Choose "Upload Profile File" and upload the downloaded Profile file.
Select the Appliance you want to setup.
When the initial connection to the Appliance fails, your asked to manually enter your Appliance IP-Address.
Repeat from Step 2 if you want to setup more than one Appliances.

Important

Do NOT delete your Home Connect account after this. If you do then

The device may disconnect itself from your Wi-Fi
You cannot troubleshoot if the appliance does not connect to Home Assistant
You cannot connect any more devices to Home Connect

If you value your privacy you can instead go to the app settings an disable all the data collection stuff in the "Privacy and Legal" section of the app

Configuration parameters

Region: The region your Home Connect account is registered in (Option A only)
Redirect URL: The URL from your browser's address bar after signing in and being redirected (Option A only)
Profile file: The Profile File you've downloaded with the Home Connect Profile Downloader (Option B only)
Select Appliance: Select the Appliance you want to setup
Host / IP-Address: Manually enter your Appliance Hostname or IP-Address if auto discovery did not work

Tip

If you want to, once you have connected the appliance to Home Assistant you can disable its cloud access.

Through Home Assistant

(OPTIONAL) Before starting, in the Home Connect app, make sure the bottom line (direct connection between your phone and device) is green in case if something goes wrong.
In the configuration section there is a disabled entity called "Allow Cloud Connection" enable it and turn off the switch
(OPTIONAL) Enable the "Cloud Connection" diagnostic entity to verify its disconnected from the cloud.

If you see the "Cloud Connection" entity saying disconnected then you have succesfully disabled cloud access for your appliance.

Through Home Connect

Open the Home Connect app and go to your appliance's settings.
Scroll down until you get the "network" and tap the details button.
(OPTIONAL) Make sure the bottom line (direct connection between your phone and device) is green in case if something goes wrong.
Scroll down (again) until you see the connection to the server toggle.
Turn off the toggle and ignore the scare screen (they have it there so they can continue collecting your data)
Then save

You'll know if you have successfully done it if you see the line between your appliance and their cloud is grayed out and disconnected.

Note

Do note that your device will not get firmware updates once disconnected, if you want to, you can occasionally (once every 1-3 months) reenable the cloud connection for 1-2 days so the device can check for an update.

Here's an example automation that occasionally reenables the cloud connection, checks for and installs a firmware update if one's available, then disables it again:

Trigger: time trigger at "03:00:00".
Conditions: only runs on the 1st of the month (now().day == 1).
Actions: turn on switch.dishwasher_allow_cloud_connection → wait up to 24 hours for an update entity to report one available → install it if found → wait up to 30 minutes for the install to finish → turn switch.dishwasher_allow_cloud_connection back off.

YAML example for periodically reconnecting the cloud to check for firmware updates

alias: Periodically check for and install Home Connect firmware updates
description: >-
  Re-enables the appliance's cloud connection on the 1st of every month so it
  has a chance to check in, then downloads (if supported) and installs any
  available firmware update via the Update entities before disabling cloud
  access again.
triggers:
  - trigger: time
    at: "03:00:00"
conditions:
  - condition: template
    value_template: "{{ now().day == 1 }}"
actions:
  - action: switch.turn_on
    target:
      # Replace with your appliance's "Allow Cloud Connection" entity
      entity_id: switch.dishwasher_allow_cloud_connection
  - wait_template: >-
      {{ is_state('update.dishwasher_software_download', 'on')
         or is_state('update.dishwasher_software_update', 'on') }}
    timeout:
      hours: 24
    continue_on_timeout: true
  - if:
      # Skip if your appliance has no separate download stage
      - condition: state
        entity_id: update.dishwasher_software_download
        state: "on"
    then:
      - action: update.install
        target:
          entity_id: update.dishwasher_software_download
      - wait_template: "{{ is_state('update.dishwasher_software_download', 'off') }}"
        timeout:
          minutes: 30
        continue_on_timeout: true
  - if:
      - condition: state
        entity_id: update.dishwasher_software_update
        state: "on"
    then:
      - action: update.install
        target:
          entity_id: update.dishwasher_software_update
      - wait_template: "{{ is_state('update.dishwasher_software_update', 'off') }}"
        timeout:
          minutes: 30
        continue_on_timeout: true
  - action: switch.turn_off
    target:
      entity_id: switch.dishwasher_allow_cloud_connection
mode: single

Exporting an Appliance Profile

Once an appliance is set up, you can export its profile from Settings → Devices & Services → Home Connect Local → the appliance's device page → gear/settings icon:

Export Safe Profile: the two XML files (renamed to {brand}_{model}, no encryption key or other sensitive data), delivered as a download link in a notification. This is what you want for Requesting a New Feature.
Export Full Profile: the same two XML files plus the local encryption key, in the same shape as the Profile Downloader ZIP (re-importable via Upload Profile File). Meant for transferring an appliance to another system - not just Home Assistant, but other local-control projects like openHAB's Home Connect Direct Binding or the Homey Home Connect (Local) app - not something most users need. Written to a homeconnect_ws_export folder in your config directory rather than offered as a download link, since a link to a file containing your encryption key would be a real (if brief) exposure window - retrieve it via Samba, SSH, or another file-access method.

Note

Two things noticed so far that aren't specific to this integration:

The Safe export's download link didn't work in the Arc desktop browser (opened fine on mobile Safari) - if a link doesn't work, try a different browser.
Home Assistant's File Editor add-on's own download button returned a 401 error trying to retrieve the Full export file. A Samba share worked without issue. If File Editor's download button fails for you too, use Samba (or SSH) instead.

Data Updates

This integration is almost entirely push based, receiving updates from the appliance the moment something happens to it. Post setup, this integration can work completely offline, unlike the Home Connect app.

The one exception is the Wi-Fi Signal Strength sensor. The entity can only be polled from the appliance, so that entity is polled once an hour instead. It is polled infrequently due to the fact appliances dont move.

Supported Functions

Supported Functions (very long).

The following entities are available. Which ones appear depends on the appliance type and its feature set. Not every device supports every entity listed here.

Supported across multiple kinds of appliances

Entity	Type	Description
Active Program	Sensor	Currently running program
Operation State	Sensor	Device state (e.g. Ready, Running, Finished)
Remaining Program Time	Sensor	Time left in the current program
Program Progress	Sensor	Progress as a percentage
Start In	Sensor / Number	Delay before the program starts
Finish In	Sensor / Number	Target time until the program finishes
Select Program	Select	Choose a program to run
Start / Abort / Pause / Resume	Button	Control the active program
Power State	Switch / Select	Turn the appliance on or off
Child Lock	Switch	Lock the physical controls
Remote Start Allowed	Binary Sensor	Whether remote control is enabled on the device
Door State	Binary Sensor / Sensor	Whether the door is open or closed
Program Finished	Binary Sensor	Turns on when the current cycle completes
Wi-Fi Signal Strength	Sensor	Device's Wi-Fi signal strength - polled hourly (see Data Updates), not pushed like everything else
Cloud Connection	Binary Sensor	Whether the appliance is currently connected to the Home Connect cloud
Allow Cloud Connection	Switch	Enable or disable the appliance's connection to the Home Connect cloud
Allow Consumer Insights	Switch	Enable or disable usage data collection by the Home Connect cloud
Synchronize Time with Server	Switch	Whether the appliance keeps its clock in sync with a time server
Time Format	Select	12-hour or 24-hour clock display
Software Update	Update	Tracks/triggers installing an available firmware update
Software Download	Update	Tracks/triggers downloading an available firmware update (only on appliances that support a separate download stage)

A few additional diagnostic entities (Local Control Active, Remote Control Active) are also available, disabled by default.

The Home Connect protocol only signals that a firmware update exists, not which version it is, so the Update entities show a generic "New Version" placeholder rather than a real version number when one is available. Also, as mentioned before, if you disabled cloud access for your appliance, or it cannot reach the Home Connect Cloud, then it cannot get new firmware updates.

Some entites are excluded from this integration on purpose, even though the Home Connect Protocol Supports it

Entity/featureDescription	UID (hex)	Reason for exclusion
BSH.Common.Command.ApplyFactoryReset	0229	Irreversible change
BSH.Common.Command.ApplyNetworkReset	022A	Also an irreversible change
BSH.Common.Command.DeactivateWiFi	0001	Reversible, but will prevent HA from accessing the appliance until physically activated again

Dishwasher

Wash program selection and options (half load, hygiene plus, extra dry, extra rinse, speed-on-demand, silence-on-demand, sanitize), FlexSpray zone configuration, rinse aid and salt level sensors, maintenance reminders (filter check, machine care, smart filter), water hardness and rinse aid dose settings, auto power off, and time light (floor projector).

Washing Machine / Dryer

Program options including temperature, spin speed, prewash, rinse plus, gentle cycle, and hygienic steam; iDos automatic dosing (levels 1 & 2); drum light and door ring LED control (brightness and color mode); anti-wrinkle guard; maintenance reminders (drum clean, lint filter full); condensate container alert (dryer).

Oven / Hob / Hood

Oven current and setpoint temperature, meat probe temperature and plugged-in status, heating mode selection, fast preheat, sabbath mode, convection conversion, dim display on standby, clock display (analogue/digital); hood fan speed control, ambient and work lighting, automatic shutoff delay, interval ventilation, grease and carbon filter saturation sensors and one-tap reset buttons; hob ventilation level.

Coffee Maker

Bean container and amount, grind coarseness, coffee strength, temperature, brew size, shot count, milk ratio; cup warmer; maintenance countdowns for cleaning, descaling, and water filter replacement; water tank and drip tray level sensors; per-drink brew counters (coffee, espresso, milk-based drinks, and more).

Refrigerator / Freezer

Fridge, freezer, and chiller setpoint temperatures (°C and °F); door open and door alarm binary sensors; super-freeze and super-cool modes; eco, vacation, and fresh-food modes; interior light with brightness control; water filter alert; sabbath mode duration.

Actions

This integration provides the following actions:

homeconnect_ws.start_program: Start the currently selected program. Optionally set a start delay and/or a target finish time.
homeconnect_ws.set_start_in: Set the start delay of the currently selected program.
homeconnect_ws.set_finish_in: Set the target finish time of the currently selected program.

Automation examples

Get started with these automation examples

Send a notification when the appliance ends the program

Trigger: sensor.appliance_operation_state changes to finished.
Actions: notify.notify with a message that the program has finished.

YAML example for notifying when the appliance's program ends

alias: "Notify when program ends"
triggers:
  - trigger: state
    entity_id:
      - sensor.appliance_operation_state
    to: finished
actions:
  - action: notify.notify
    data:
      message: "The appliance has finished the program."

Start a program when electricity is cheap

Because electricity is typically cheaper at night, this automation will activate the silent mode when starting the program at night.

Trigger: sensor.electricity_price drops to "0.10".
Conditions: sensor.diswasher_door is closed.
Actions: home_connect.set_program_and_options — between 22:00 and 06:00, starts the Eco 50 program with silent mode on; otherwise starts it without silent mode.

YAML example for starting a program when electricity is cheap

alias: "Start program when electricity is cheap"
triggers:
  - trigger: state
    entity_id: sensor.electricity_price
    to: "0.10"
conditions:
  - condition: state
    entity_id: sensor.diswasher_door
    state: closed
actions:
  - if:
      - condition: time
        after: '22:00:00'
        before: '06:00:00'
    then:
      - action: home_connect.set_program_and_options
        data:
          device_id: "your_device_id"
          affects_to: "active_program"
          program: "dishcare_dishwasher_program_eco_50"
          dishcare_dishwasher_option_silence_on_demand: true
    else:
      - action: home_connect.set_program_and_options
        data:
          device_id: "your_device_id"
          affects_to: "active_program"
          program: "dishcare_dishwasher_program_eco_50"

Known Limitations

While this integration can (in theory) support all the functions supported in the Home Connect app, in reality, the functions have to reverse engineered
The mDNS on Home Connect devices is wonky and fail to connect. The best example of this is that in the App, unless if the phone is on the same Wireless Access Point as the appliance theres a chance a local connection may fail to establish.
Home Assistant may overload the device's local capacity causing it to not accept new connections for 24 hours. This is called a Websocket Shutdown. See this section for more info and how to resolve it.
The Appliance must be online and reachable on your local network during initial setup. The config flow actively tests the connection before letting you finish adding the device, so it cannot be added while powered off or unreachable. Once added, the appliance can go offline/online freely and its entities will simply go unavailable and recover automatically. See issues chris-mc1#274 and chris-mc1#293 for info about why it is like this.

Requesting a New Feature

Entity coverage for the appliances the maintainer actually owns (Thermador dishwasher/oven/freezer) is essentially complete. Since every entity has to be reverse engineered from a real appliance's profile (see Known Limitations), there's no way to add entities for other appliances, brands, or models without someone who owns one providing their own profile dump. If you want support for a feature this integration doesn't have yet, submitting that data yourself (see below) isn't just helpful, it's the only way it happens.

Since this integration's functions have to be reverse engineered (see Known Limitations), the more information you provide when requesting a new entity, the easier it is for a developer to add it. There are two ways to do this, depending on how much effort you want to put in.

Basic method

Use the Export Safe Profile option to get a ZIP with the two XML files, already renamed and with no sensitive data - safe to share as-is.
- Alternatively, use the Home Connect Profile Downloader tool and manually remove the .json file (contains your encryption key - don't share it) and the MAC address segment from the two XML filenames.
Download the Diagnostics of the appliance's Config Entry.
Open a feature request describing, in plain terms, the feature/entity you'd like added (e.g. "I want a sensor for my appliance's door state"), and attach the two XML files from the ZIP along with the Diagnostics.

Advanced method

If you're comfortable digging a bit deeper, you can help pinpoint exactly which feature maps to the entity you want, which makes it much faster for a developer to add:

Follow steps 1-2 of the Basic method above.
Enable debug logging for the integration.
Trigger the feature on the appliance itself (e.g. open the door, change a setting, start a program) and watch the debug log for the corresponding update message.
Note the UID logged for that update. It will be in decimal, while the UIDs inside the *_DeviceDescription.xml/*_FeatureMapping.xml files are in hexadecimal. Convert between the two to match them up. For example, on a Thermador oven, the live oven temperature in fahrenheit logs as UID 5959 (decimal), which is 1747 in hex, matching Cooking.Oven.Status.Cavity.340.CurrentTemperatureFahrenheit in the FeatureMapping file.
Include that UID/feature name (and what it corresponds to) in your issue, alongside everything from the Basic method, so developers know exactly which feature to wire up.

Trouble Shooting

Home Assistant cannot connect to my Appliance, what should I do?

If Home Assistant cannot connect to your appliance (during setup) despite correctly entering the right profile file and IP address, here are some tips:

Try to see if Home Connect can establish a local connection on the same network as Home Assistant.
To do this, open the Home Connect App, go to your appliance(s), then to its settings, then scroll down to the network section.
- If you see the bottom line lit up green, this could mean two things:
  1. You have the wrong/outdated profile file. Make sure you have the correct file, and if it's outdated, get a new one.
  2. As noted in the known limitations, the mDNS on the device is wonky, and if mDNS fails, even a direct IP connection may fail.
- If you don't see the bottom line lit up green, this could mean a few things:
  1. If you're on the same wireless access point as the device, your device is most likely offline or does not support a local connection.
  2. If you're not on the same wireless access point, make sure you are.
  3. The device may be offline; check it physically to see if there's no Wi-Fi signal indicator on it.
  4. If the device does have a Wi-Fi signal, then Home Assistant may have overloaded the device's local capacity, causing a websocket shutdown. See below on how to resolve it.

How to resolve a websocket shutdown

This integration has built in measures (measures not fully tested yet) to prevent a websocket shutdown, however unexpectedly shutting down Home Assistant bypasses these measures. If enough unexpected shutdowns of Home Assistant happen, then Home Assistant will leave half-dead sessions that overload the device's session capacity, leading to a websocket shutdown.

There are three ways to resolve a websocket shutdown:

Disable the cloud: Disabling the cloud (follow the protip section on how to do it), then waiting 24 hours, can allow the device to reopen its local websocket. Note that since you're doing this during a local websocket shutdown, the smart features of the device will be inoperable until the device reopens its websocket. The device will still stay connected to your Wi-Fi.
Power cycle the appliance: Cutting the power from your appliance for 1-5 minutes, then reapplying it, can help resolve the issue.
Re-pair the appliance (not recommended): Resetting the device's network settings and re-pairing it to the Home Connect App resolves the issue. However, doing that is not only time consuming, but you also have to get a new profile file, remove the entry, and re-add it with the new file.

Reporting Issues and Bugs

A full debug log of at least reloading the config entry and any actions leading to an error
The Diagnostics of the Config Entry
For reports relating to adding a new Appliance: the *_DeviceDescription.xml and *_FeatureMapping.xml files from the Profile File

Enabling debug logging

Use one of these two methods enable debug logging:

Through the UI:
1. Enable Debug logging on the detail page of the integration
2. Reload the config entry
3. Perform the actions that lead to an error
4. Disable Debug logging on the detail page of the integration
OR -
Through configuration.yaml:
1. Add the following to your configuration.yaml file:
```
logger:
logs:
    custom_components.homeconnect_ws: debug # Home Connect Local Integration
    homeconnect_ws: debug
    home_disconnect: debug # home-disconnect Python package
```
2. Restart Home Assistant
3. Perform the actions that lead to an error
4. Click the button below or navigate to "Settings" -> "Logs".
5. Download the log file using download button on the left

Integration Removal

This integration follows standard integration removal, no extra steps are required.

Select the Config entry you want to delete
Click the 3 dots in the top right of the entry
Click the delete button

At a Glance

IoT Class: Local Push
Secondary IoT Class: Local Polling: The WiFi signal-strength diagnostic sensor is polled every hour
Internet Requirement: Setup: obtaining your appliance's encryption keys via the Home Connect Profile Downloader needs a one-time connection to the Home Connect cloud. Day-to-day operation after that is entirely local and works without an internet connection
Quality Scale: 🥇 Gold
View source on GitHub
View known issues
Request a feature
home-disconnect - a fork of the local WebSocket protocol library this integration talks to appliances through

Name		Name	Last commit message	Last commit date
Latest commit History 881 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
custom_components/homeconnect_ws		custom_components/homeconnect_ws
docs		docs
script		script
tests		tests
.pre-commit-config.yaml		.pre-commit-config.yaml
.python-version		.python-version
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
pyproject.toml		pyproject.toml
ruff.toml		ruff.toml

Folders and files

Latest commit

History

Repository files navigation

Home Connect Local

Use Cases

Install the Integration

Supported Devices

Prerequisites

Setup

Option A: Sign in with Home Connect

Option B: Upload Profile File

Configuration parameters

Through Home Assistant

Through Home Connect

Exporting an Appliance Profile

Data Updates

Supported Functions

Supported across multiple kinds of appliances

Dishwasher

Washing Machine / Dryer

Oven / Hob / Hood

Coffee Maker

Refrigerator / Freezer

Actions

Automation examples

Send a notification when the appliance ends the program

Start a program when electricity is cheap

Known Limitations

Requesting a New Feature

Basic method

Advanced method

Trouble Shooting

Home Assistant cannot connect to my Appliance, what should I do?

How to resolve a websocket shutdown

Reporting Issues and Bugs

Enabling debug logging

Integration Removal

At a Glance

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages