home-disconnect

Talk to Home Connect appliances (Bosch, Siemens, Thermador, Neff, Gaggenau and the other BSH brands) directly over your local network, without the Home Connect cloud. It's the library behind the Home Connect Local Home Assistant integration.

The name is the point: once you have an appliance's profile, everything runs locally, and you can even tell the appliance to stop talking to BSH's servers altogether (see Disconnecting from the cloud).

What it does

• Connects to an appliance over its local encrypted WebSocket, in both schemes appliances use: TLS-PSK (port 443) and AES (port 80).
• Keeps the connection up: handshake, heartbeat, automatic reconnect with backoff, and a full re-read of the appliance's state after every reconnect, so values never go stale.
• Reads the appliance's profile (the DeviceDescription and FeatureMapping files) from a ZIP, uploaded bytes, a folder, or straight from your Home Connect account.
• Turns every feature into an entity with a typed value, live access and availability, callbacks on change, and checked writes.
• Selects and starts programs with the right options, following the rules different appliances need.
• Toggles the appliance's cloud connection.

Installation

pip install home-disconnect

Python 3.13 or newer (TLS-PSK needs the standard library support added in 3.13).

Quick start

import asyncio

import aiohttp

from home_disconnect import Appliance, load_profiles


async def main() -> None:
    # A profile from the Home Connect Profile Downloader (ZIP or folder).
    loaded = load_profiles("THERMADOR-DWHD660WFP-68A40E0FC8F1.zip")[0]
    connection = loaded.connection  # key, IV and connection type from the profile's JSON

    async with aiohttp.ClientSession() as session:
        appliance = Appliance(
            session,
            "192.168.1.130",  # the appliance's address
            loaded.profile,
            connection.psk64,
            connection.iv64,
            app_name="My app",
            app_id="my-app-1",
        )
        await appliance.connect()
        try:
            print(appliance.status["BSH.Common.Status.DoorState"].value)  # "Closed"
            print(appliance.selected_program.name if appliance.selected_program else None)
        finally:
            await appliance.close()


asyncio.run(main())

More in the usage guide: getting a profile, reading and writing values, callbacks, programs, connection states, errors and exporting profiles.

Disconnecting from the cloud

Most Home Connect appliances have a setting, BSH.Common.Setting.AllowBackendConnection, that decides whether they connect to BSH's servers at all. With it off, the appliance stays reachable on your network through this library, but stops reporting to, and taking commands from, the Home Connect cloud.

print(appliance.cloud_connection_allowed)  # True
print(appliance.cloud_connected)  # True: connected to BSH's servers right now

await appliance.set_cloud_connection(allowed=False)  # disconnect from the cloud
await appliance.set_cloud_connection(allowed=True)  # and back

Things to know before you turn it off:

• The official Home Connect app still works, but only on the same network: it talks to the appliance directly over your LAN. The app away from home stops reaching it.
• Every official third-party service is disconnected: voice assistants, the cloud-based Home Connect integration in Home Assistant and other partner services all go through the cloud, since BSH only uses the local connection for its own app. That includes services running on local hubs: Homey's Home Connect app, for example, loses the appliance even though Homey runs in your home like Home Assistant does.
• Software updates come from BSH's servers, so turn it back on now and then to get them.
• Pairing a new appliance still needs the cloud: the app pairs it, and its profile with the local key is stored in your Home Connect account. Once it's paired, the order doesn't matter: turning the cloud connection off doesn't remove the profile, so it can still be downloaded from the account afterwards. Deleting the Home Connect account after disconnecting might remove it, but that's untested and the consequences aren't known, especially if the cloud connection is turned back on later.
• It can only be turned back on over the local connection: from this library, or from the official app on the same network. The appliance's own settings menu can't do it. If the appliance's local WebSocket ever shuts down while the cloud is off, the appliance may become unreachable.
• Some appliances show an X on their Wi-Fi icon while the cloud connection is off. It means the appliance is on Wi-Fi but can't reach the cloud, which is expected.

Appliances without the setting raise AccessError from set_cloud_connection(), and both properties return None for them.

Contributing and licensing

The code is MIT-licensed (LICENSE). Parts are based on the MIT-licensed hcpy and on code moved from Home Connect Local; their notices are in THIRD_PARTY_NOTICES.md, and PROVENANCE.md lists where each module comes from. Code from homeconnect_websocket (and so from home-disconnect 1.x) must not be copied here, including its tests and protocol document.

uv sync
uv run pytest
uv run ruff check
uv run mypy