Interface with Home Connect appliances in Python

This is a very, very beta interface for Bosch-Siemens Home Connect devices through their local network connection. Unlike most IoT devices that have a reputation for very bad security, BSG seem to have done a decent job of designing their system, especially since they allow a no-cloud local control configuration. The protocols seem sound, use well tested cryptographic libraries (TLS PSK with modern ciphres) or well understood primitives (AES-CBC with HMAC), and should prevent most any random attacker on your network from being able to take over your appliances to mine cryptocurrency.

WARNING: This tool not ready for prime time and is still beta!

Setup

HomeAssistant Addon

Follow the instructions in the wiki

Locally

To avoid running into issues later with your default python installs, it's recommended to use a py virtual env for doing this. Go to your desired test directory, and:

python3 -m venv venv
source venv/bin/activate
git clone https://github.com/hcpy2-0/hcpy
cd hcpy
pip3 install -r requirements.txt

Install the Python dependencies; the sslpsk one is a little weird and we might need to revisit it later.

Alternatively an environment can be built with docker and/or docker-compose which has the necessary dependencies.

For Mac Users

Installing sslpsk needs some extra steps:

1. The openssl package installed via brew: brew install openssl, and
2. Install sslpsk separately with flags: LDFLAGS="-L$(brew --prefix openssl)/lib" CFLAGS="-I$(brew --prefix openssl)/include" pip3 install sslpsk
3. Rest of the requirements should be fine with pip3 install -r requirements.txt

Authenticate to the cloud servers

The login process has changed as the HomeConnect SingleKey pages now implement a CAPTCHA. hc-login.py will now prompt users with a URL that they must follow in a normal browser window (Chromium), and use Development tools (F12) to monitor the network tab and retrieve the code and state values from the request to hcauth://auth

This step is time-sensitive, but we have not identified the expiry time for the challenge. There is time to perform this step without too much haste but consider performing this process within 60s to avoid issues.

hc-login.py config/devices.json

Visit the following URL in the browser, use the F12 developer tools to monitor the network responses, and look for the request starting hcauth://auth for the relevant authentication tokens:
https://api.home-connect.com/security/oauth/authorize?response_type=code&prompt=login&code_challenge=blah&code_challenge_method=S256&client_id=blah&scope=ReadOrigApi&nonce=blah&state=blah&redirect_uri=hcauth%3A%2F%2Fauth%2Fprod&redirect_target=icore
Input code:eyJblah
Input state:eXVblah

or

docker-compose -f compose.yaml build
docker-compose -f compose.yaml run app /app/hc-login.py config/devices.json

The hc-login.py script perfoms the OAuth process to login to your Home Connect account with your usename and password. It receives a bearer token that can then be used to retrieves a list of all the connected devices, their authentication and encryption keys, and XML files that describe all of the features and options.

This only needs to be done once or when you add new devices; the resulting configuration JSON file should be sufficient to connect to the devices on your local network, assuming that your mDNS or DNS server resolves the names correctly.

Home Connect to MQTT

Use the following ./config/config.ini example:

devices_file = "./config/devices.json"
mqtt_host = "localhost"
mqtt_username = "mqtt"
mqtt_password = "password"
mqtt_port = 1883
mqtt_prefix = "homeconnect/"
mqtt_ssl = False
mqtt_cafile = None
mqtt_certfile = None
mqtt_keyfile = None
mqtt_clientname="hcpy"
ha_discovery = True  # See section on "Home Assistant autodiscovery"

hc2mqtt.py --config config/config.ini

or

docker-compose -f compose.yaml up

This tool will establish websockets to the local devices and transform their messages into MQTT JSON messages. The exact format is likely to change; it is currently a thin translation layer over the XML retrieved from cloud servers during the initial configuration.

Dishwasher

The dishwasher has a local HTTPS port open, although attempting to connect to the HTTPS port with curl results in a cryptic protocol error due to the non-standard cipher selection, ECDHE-PSK-CHACHA20-POLY1305. PSK also requires that both sides agree on a symetric key, so a special hacked version of sslpsk is used to establish the connection and then hand control to the Python websock-client library.

Example message published to homeconnect/dishwasher:

{
    "state": "Run",
    "door":  "Closed",
    "remaining": "2:49",
    "power": true,
    "lowwaterpressure": false,
    "aquastop": false,
    "error": false,
    "remainingseconds": 10140
}

<details> <summary>Full state information</summary>

{
    'AllowBackendConnection': False,
    'BackendConnected': False,
    'RemoteControlLevel': 'ManualRemoteStart',
    'SoftwareUpdateAvailable': 'Off',
    'ConfirmPermanentRemoteStart': 'Off',
    'ActiveProgram': 0,
    'SelectedProgram': 8192,
    'RemoteControlStartAllowed': False,
    '520': '2022-02-21T16:48:54',
    'RemoteControlActive': True,
    'AquaStopOccured': 'Off',
    'DoorState': 'Open',
    'PowerState': 'Off',
    'ProgramFinished': 'Off',
    'ProgramProgress': 100,
    'LowWaterPressure': 'Off',
    'RemainingProgramTime': 0,
    'ProgramAborted': 'Off',
    '547': False,
    'RemainingProgramTimeIsEstimated': True,
    'OperationState': 'Inactive',
    'StartInRelative': 0,
    'EnergyForecast': 82,
    'WaterForecast': 70,
    'ConnectLocalWiFi': 'Off',
    'SoftwareUpdateTransactionID': 0,
    'SoftwareDownloadAvailable': 'Off',
    'SoftwareUpdateSuccessful': 'Off',
    'ProgramPhase': 'Drying',
    'SilenceOnDemandRemainingTime': 0,
    'EcoDryActive': False,
    'RinseAid': 'R04',
    'SensitivityTurbidity': 'Standard',
    'ExtraDry': False,
    'HotWater': 'ColdWater',
    'TimeLight': 'On',
    'EcoAsDefault': 'LastProgram',
    'SoundLevelSignal': 'Off',
    'SoundLevelKey': 'Medium',
    'WaterHardness': 'H04',
    'DryingAssistantAllPrograms': 'AllPrograms',
    'SilenceOnDemandDefaultTime': 1800,
    'SpeedOnDemand': False,
    'InternalError': 'Off',
    'CheckFilterSystem': 'Off',
    'DrainingNotPossible': 'Off',
    'DrainPumpBlocked': 'Off',
    'WaterheaterCalcified': 'Off',
    'LowVoltage': 'Off',
    'SaltLack': 'Off',
    'RinseAidLack': 'Off',
    'SaltNearlyEmpty': 'Off',
    'RinseAidNearlyEmpty': 'Off',
    'MachineCareReminder': 'Off',
    '5121': False,
    'HalfLoad': False,
    'IntensivZone': False,
    'VarioSpeedPlus': False,
    '5131': False,
    '5134': True,
    'SilenceOnDemand': False
}

</details>

Clothes washer

The clothes washer has a local HTTP port that also responds to websocket traffic, although the contents of the frames are AES-CBC encrypted with a key derived from HMAC(PSK,"ENC") and authenticated with SHA256-HMAC using another key derived from HMAC(PSK,"MAC"). The encrypted messages are send as binary data over the websocket (type 0x82).

Example message published to homeconnect/washer:

{
    "state": "Ready",
    "door": "Closed",
    "remaining": "3:48",
    "power": true,
    "lowwaterpressure": false,
    "aquastop": false,
    "error": false,
    "remainingseconds": 13680
}

<details> <summary>Full state information</summary>

{
    'BackendConnected': False,
    'CustomerEnergyManagerPaired': False,
    'CustomerServiceConnectionAllowed': False,
    'DoorState': 'Open',
    'FlexStart': 'Disabled',
    'LocalControlActive': False,
    'OperationState': 'Ready',
    'RemoteControlActive': True,
    'RemoteControlStartAllowed': False,
    'WiFiSignalStrength': -50,
    'LoadInformation': 0,
    'AquaStopOccured': 'Off',
    'CustomerServiceRequest': 'Off',
    'LowWaterPressure': 'Off',
    'ProgramFinished': 'Off',
    'SoftwareUpdateAvailable': 'Off',
    'WaterLevelTooHigh': 'Off',
    'DoorNotLockable': 'Off',
    'DoorNotUnlockable': 'Off',
    'DoorOpen': 'Off',
    'FatalErrorOccured': 'Off',
    'FoamDetection': 'Off',
    'DrumCleanReminder': 'Off',
    'PumpError': 'Off',
    'ReleaseRinseHoldPending': 'Off',
    'EnergyForecast': 20,
    'EstimatedTotalProgramTime': 13680,
    'FinishInRelative': 13680,
    'FlexFinishInRelative': 0,
    'ProgramProgress': 0,
    'RemainingProgramTime': 13680,
    'RemainingProgramTimeIsEstimated': True,
    'WaterForecast': 40,
    'LoadRecommendation': 10000,
    'ProcessPhase': 4,
    'ReferToProgram': 0,
    'LessIroning': False,
    'Prewash': False,
    'RinseHold': False,
    'RinsePlus': 0,
    'SilentWash': False,
    'Soak': False,
    'SpeedPerfect': False,
    'SpinSpeed': 160,
    'Stains': 0,
    'Temperature': 254,
    'WaterPlus': False,
    'AllowBackendConnection': False,
    'AllowEnergyManagement': False,
    'AllowFlexStart': False,
    'ChildLock': False,
    'Language': 'En',
    'PowerState': 'On',
    'EndSignalVolume': 'Medium',
    'KeySignalVolume': 'Loud',
    'EnableDrumCleanR