search

thoukydides / homebridge-homeconnect

Home Connect home appliances plugin for Homebridge
https://www.thouky.co.uk
ISC License
134 stars 14 forks source link
bosch cleaningrobot coffeemaker cookprocessor dishwasher fridgefreezer gaggenau hob home-connect homebridge homebridge-plugin homeconnect homekit homekit-accessory hood neff oven siemens thermador washerdryer

readme

homebridge-homeconnect

npm npm npm Build and Lint verified-by-homebridge

Home Connect home appliances plugin for Homebridge.

Home Connect, Balay, Bosch, Constructa, Gaggenau, NEFF, Pitsos, Profilo, Siemens, and Thermador, are trademarks of BSH Home Appliances.

Installation

Step 1 - Setup Home Connect Appliances

  1. Connect your home appliances with Home Connect:
    1. Install Home Connect from the Apple App Store for your country (e.g. UK or USA).
    2. Create an account using your email address, click on the validation link in the email that will be received, and then return to the app and login.
    3. Connect the appliances to your home network, either via the app or using Wi-Fi Protected Setup (WPS).
    4. Connect the appliances to the app (by following the installation guide provided with the appliance).
  2. If you are using a legacy Home Connect account then also create a SingleKey ID using the same email address, ensuring that it is all in lowercase. Verify that the SingleKey ID works in the Home Connect app.

Step 2 - Obtain a Home Connect Client ID

  1. Sign-up for a free Home Connect Developer Program account and login.
  2. Register a new application, ensuring that
    • OAuth Flow is set to Device Flow
    • Home Connect User Account for Testing is the same as the SingleKey ID email address
    • Redirect URI is left blank
    • Enable One Time Token Mode is not ticked
  3. If the application is subsequently edited then additionally ensure that:
    • Forces the usage of PKCE is not ticked
    • Status is Enabled
    • Client Secret Always Required is No
  4. Copy and save the displayed Client ID; it will be required to configure this plugin.
  5. Wait 15 minutes for changes to the application to be deployed to the Home Connect authorisation servers.

Step 3(a) - Homebridge Plugin Installation (recommended approach using Homebridge UI)

  1. On the Homebridge UI Plugins page search for and install the HomeConnect plugin.
  2. Open the HomeConnect plugin settings and set the Client ID to the value obtained from the Home Connect Developer Program for the created Device Flow application.
  3. Click on the AUTHORISE button to open a new Home Connect browser window. Login to your Home Connect account and approve access.
  4. Save the plugin settings and restart Homebridge.

Step 3(b) - Homebridge Plugin Installation (alternative method using command line)

  1. Install this plugin using: npm install -g homebridge-homeconnect
  2. Edit config.json and add the HomeConnect platform (see example below).
  3. Run (or restart) Homebridge.
  4. The Homebridge log output will include an authorisation URL. Copy the listed URL into a web browser, login to your Home Connect account, and approve access.

Example config.json

{
    "platforms":
    [{
        "platform":     "HomeConnect",
        "clientid":     "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF"
    }]
}

The clientid should be set to the Client ID obtained from the Home Connect Developer Program for the created Device Flow application.

Additional configuration is recommended to customise the appliance programs, and to select optional features. See config.json for a description of all supported configuration options.

The easiest way to configure this plugin is via the Homebridge UI configuration editor. This plugin implements a custom user interface that dynamically updates with the appropriate options for the connected appliances. Manual configuration via the config.json file is possible, but not recommended.

Appliance Support

This plugin supports most capabilities of the Home Connect API that can be sensibly mapped to Apple-defined HomeKit services and characteristics. More details can be found in the functionality summary.

Apple's Home app does not support all of the features of this plugin. Some third-party HomeKit apps are recommended due to their extra functionality.

Cooking Appliances

Cleaning Appliances

Cooling Appliances

Changelog

All notable changes to this project are documented in the CHANGELOG.md file.

Reporting Issues

Report any issues on GitHub.

Before raising an issue please check whether it relates to an expected error message and whether any similar issues already exist. If the issue relates to a problem connecting to the Home Connect servers or with controlling an appliance then please also:

Please attach the relevant section of the Homebridge log file, either pasted into the issue or attached as a text file (not a screenshot). Extra debug should be enabled and captured if appropriate:

License

ISC License (ISC)
Copyright © 2019-2024 Alexander Thoukydides

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.