Homeconnect - hcpy for Bosch Dishwasher

Python tool to talk to Home Connect appliances over the local network (no cloud required)

Device

Dishwasher Bosch SMV4HCX48E/24

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!

More Information for details see:

Used devices

• Dishwasher Bosch SMV4HCX48E/24
• Powermeter Sonoff Pow
• Watermeter ESPHome+ESP32+CC1101

Requirements

• Python 3.11.9 or Docker app with Python 3.11.9
• Valid singlekey-id account (username, password)
• Device registered with singlekey-id account
• Application configuration (config.json)
• Homeconnect Devices configuration (devices.json)

Setup

To avoid running into issues later with your default python installs, it's recommended to use a py virtual env for doing this. I have had good experiences with pyenv With pyenv you can use your own Python versions / virtual environment for each application.

Python Setup

Go to your desired test directory (for example: /dockerapps/homeconnect), and:

⚡ root@linux: pyenv --version
⚡ root@linux: pyenv install 3.11.9
⚡ root@linux: pyenv virtualenv 3.11.9 apps
⚡ root@linux: cd /dockerapps
⚡ root@linux: git clone https://github.com/zibous/homeconnect-hcpy.git
⚡ root@linux: cd /dockerapps/homeconnect-hcpy
⚡ root@linux: pyenv local apps
⚡ root@linux: pip install -r requirements.txt
⚡ root@linux: pip install pipreqs
⚡ root@linux: pip install pyclean

Python APP

This application (bosch.py) 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.

Workflow

• Start App

  • Check and load config.json
  • Check and load devices.json
    • If not present login to Homeconnect to get the devices.json
  • Connect local to the device
    • Get the device state data
  • Publish the device state data
    • MQTT Payload
    • Wait for next device state data

APP Classes

Start Application

Template for the config.json see: config.json
After the config.json is valid in the ./config directory, the application can be started with the python command:

⚡ root@linux: /dockerapps/homeconnect: python bosch.py

First Start - creates the devices.json

If no devices.json is present, the application 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 and saves the data to the devices.json.

Requirements:

• Valid singlekey-id account (username, password) see devices.json
• Device registered with singlekey-id account

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.

TODO after first start

• check config.json

  • if no config.json is present (hc_username, hc_password)

• check devices.json

  • Check whether the device host is accessible via the network
  • Optional change hostentry to IP Address
  • Optional add resources section to prevent 400/404 errors
  • Optional add addons section if a power meter, water meter is present

• Logging

  • Change LOGLEVEL to DEBUG, see:devices.json

• Optiona Test hcpy Testcase

  • check Issues hcpy2-0

Result for Dishwasher Bosch SMV4HCX48E/24 s see: devices.json

Docker APP

The application can also be installed with a Docker installation. A local Docker image is created with build.sh and then installed.

Build script see: Docker build script

Go to your desired test directory, and:

⚡ root@linux: /dockerapps/homeconnect:  bash build.sh

Application logging loguru.logger

What's Changed

• NEW hcpy lib files

  • Replace print, dprint with loguru.logger

• h2mqtt.py

  • bosch.app instead of h2mqtt.py
  • bosch.app included hc-login to get the devices.json on first start
  • loading settings.json instead of settings.ini
  • simple dishwascher state manager
  • onStateChanged to get the energie- and water consumption

• HCDevice.py

  • Modified
    

    • self.device_id = base64url_encode(get_random_bytes(6)).decode("UTF-8")
      

  • Disabled Error 404,400

    • added section resources
      see: devices.json
      

    • added section addons
      With the entries in the addons section, additional components can be created. For example, to record the energy and water consumption per session, a Sonoff device is used as a power meter and an ESP water meter is used for water consumption. see: devices.json
      

• NEW paho-mqtt Version: 2.1.0
  MQTT version 5.0 client

MQTT Payload

The application always sends an MQTT message when something has changed in the states.
Sample output see: payload.json

---

Homeassisant

Instead of MQTT Discovery, I use an MQTT template (see directory /homeassistant/dishwasher.yaml) to use the device with the settings in Homeassistant.

• Homeassistant Template for Bosch Dishwasher

Questions & Open Tasks

• Why are the resource data evaluated but not translated (see payload.json)

  • 520: "2024-07-01T09:12:37"
  • 535: false
  • 547: false
  • 4632: 0
  • 4641: 0
  • 4654: 0
  • mqtt payload
    

• How do the options work for the appliance options (see HCDevice.py lines 134 -138)

      if "options" in data:
          for option in data["options"]:
              option_uid = option["uid"]
              if str(option_uid) not in self.features:
                  raise ValueError(f"Unable to configure appliance. Option UID
                                     {option_uid} is not" " valid for this device.")

Additional Informations

• Python tool to talk to Home Connect appliances osresearch/hcpy
• Python tool to talk to Home Connect appliances hcpy2-0/hcpy
• Issues hcpy2-0
• SingleKey ID, One Digital Key for Many Brands
• Bosch Products Homepage
• Home Connect – Connect your household
• Connect Developer Program
• Pynsource - UML for Python