Metadata-Version: 2.5
Name: home-disconnect
Version: 2.0.0b1
Summary: Local WebSocket client for Home Connect appliances
Project-URL: Homepage, https://github.com/vemboy200/home-disconnect
Project-URL: Issues, https://github.com/vemboy200/home-disconnect/issues
Author: vemboy200
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiohttp>=3.11
Requires-Dist: cryptography>=44
Description-Content-Type: text/markdown

# 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](https://github.com/vemboy200/homeconnect_local_hass) 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](#disconnecting-from-the-cloud)).

> [!NOTE]
> 2.0.0 is a new, MIT-licensed library written for this repository. Versions up to 1.7.0 came from [home-disconnect-old](https://github.com/vemboy200/home-disconnect-old), a fork of [homeconnect_websocket](https://github.com/chris-mc1/homeconnect_websocket), which has no license; that repository is archived and none of its code is used here. The 2.x API is not compatible with 1.x. See [PROVENANCE.md](https://github.com/vemboy200/home-disconnect/blob/main/PROVENANCE.md) for where every part comes from.

## 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

```bash
pip install home-disconnect
```

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

## Quick start

```python
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](https://github.com/vemboy200/home-disconnect/blob/main/docs/usage.md): 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.

```python
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](https://github.com/vemboy200/home-disconnect/blob/main/LICENSE)). Parts are based on the MIT-licensed [hcpy](https://github.com/hcpy2-0/hcpy) and on code moved from Home Connect Local; their notices are in [THIRD_PARTY_NOTICES.md](https://github.com/vemboy200/home-disconnect/blob/main/THIRD_PARTY_NOTICES.md), and [PROVENANCE.md](https://github.com/vemboy200/home-disconnect/blob/main/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.

```bash
uv sync
uv run pytest
uv run ruff check
uv run mypy
```
