Reference

This page lists every setting, how the plugin uses your network, and what it does not do. You do not need any of it to get started: every imported appliance works with the defaults.

Where the settings live

Homebridge keeps all its settings in one file, config.json, in its storage folder. You do not have to edit it by hand. The plugin’s settings page shows the same settings as a form: on the Home Connect Local card, click the three dots, then click Plugin Config. Change a setting for one appliance walks through it.

No key or password ever goes into config.json. The plugin only reads it, and never writes to it.

This is what the plugin’s part of config.json looks like with one appliance entry:

{
  "platforms": [
    {
      "platform": "HomeConnectLocal",
      "name": "Home Connect Local",
      "appliances": [
        {
          "haId": "BOSCH-KSN36VICG-000000000000",
          "name": "Fridge",
          "host": "192.0.2.50",
          "enabled": true,
          "setpoint": "thermostat"
        }
      ]
    }
  ]
}

Config options

The first column is the key in config.json. The second is the label on the settings page.

Key	Label	Type	Default	What it does
`platform`	none	text	none	Must be `HomeConnectLocal`. Homebridge allows only one block for this plugin.
`name`	Name	text	`Home Connect Local`	The plugin’s name at the start of its lines in the Homebridge log. Required.
`appliances`	Appliance overrides	list	empty	Settings for single appliances. You only need an entry to change something.
`appliances[].haId`	Appliance ID (haId)	text	none	Required in every entry. The appliance ID, as shown under “Imported appliances” on the settings page. Letters, digits, `-` and `_` only.
`appliances[].name`	Accessory name	text	“Fridge”, “Freezer” or “Fridge Freezer”	The accessory’s name when the plugin first adds it to Home. Changing it later does not rename an accessory already in Home.
`appliances[].host`	Host	text	empty, so the plugin finds the appliance itself	A fixed IP address or hostname for the appliance. A hostname is turned into an IPv4 address. When this is set, the plugin never waits to find the appliance on the network.
`appliances[].enabled`	Enabled	true or false	`true`	Set to `false` to leave the appliance out of Home without deleting its profile.
`appliances[].setpoint`	Setpoint	`thermostat`, `separate` or `none`	`thermostat`	`thermostat` puts the thermostats on the appliance’s accessory. `separate` puts them on a second accessory named after the appliance followed by “Temperature”. `none` leaves them out.
`appliances[].hostHeader`	Advanced: Host header override	text	empty	Leave it empty. It sends this text as the HTTP `Host` header, for appliance firmware that drops a connection when that header holds an IP address. It is only for debugging a connection that drops while it is being set up.

The appliance ID is also called the haId. It is the name Home Connect gives one appliance.

How entries are matched

Each entry under Appliance overrides applies to the appliance whose ID matches its Appliance ID (haId). An appliance with no entry runs with the defaults.

A mistake in config.json never stops the plugin from loading. The plugin skips the entry, or uses the default, and writes a warning to the Homebridge log:

Log line	What happened
`no stored profile for haId <ID>; import its profile in the plugin settings`	An entry names an appliance you have not imported.
`<ID>: setpoint must be thermostat, separate or none; using thermostat`	Setpoint has some other value.
`<ID>: more than one appliances entry in config.json; the last one wins`	Two entries name the same appliance.
`ignoring an appliances entry in config.json: haId is missing or not an appliance id`	An entry has no appliance ID, or one with characters other than letters, digits, `-` and `_`.
`ignoring an appliances entry in config.json: expected an object`	An entry is not a set of settings. This only happens if you edit `config.json` by hand.
`ignoring appliances in config.json: expected a list of appliance overrides`	`appliances` is not a list. This only happens if you edit `config.json` by hand.

There is no debug setting in the plugin. It uses Homebridge’s own debug mode. See Debug logging.

Network

The plugin only connects out, from Homebridge to the appliance. The appliance never connects to Homebridge.

Ports. A port is a numbered door on a device that one kind of connection uses. The plugin connects to the appliance on port 443 or port 80, whichever the appliance’s profile says. Port 443 is used with TLS-PSK, an encrypted connection that both sides open with the same shared key. Port 80 is used with AES, which encrypts each message with the key. AES is the weaker of the two. Security and privacy explains why.
Finding the appliance. Appliances announce themselves with mDNS, the way devices on a home network tell each other where they are. Their announcements are named _homeconnect._tcp. To hear them, the plugin listens on UDP port 5353, like any mDNS program. It opens no other port of its own.
IPv4 only. The plugin only uses IPv4 addresses, the four-number kind such as 192.0.2.50. A hostname in Host is turned into one IPv4 address.
Retries. When a connection fails, the plugin tries again after 5 seconds, then waits twice as long after each failure, up to 5 minutes between tries. Each wait varies by up to a fifth, at random. It never gives up. Between tries it asks the network for the appliance again.
“No Response”. Tiles keep showing their last values until the appliance has been unreachable for 5 minutes without a break. Only then does the Home app show “No Response”. The first successful connection clears it.
Rejected keys. If the appliance rejects the key three times in a row, the plugin writes one error to the log that names the appliance. It then tries that appliance only once every 30 minutes until a connection works.

Troubleshooting explains what to do about each of these.

Import limits

The plugin checks each profile zip before it stores anything. A zip is refused if:

it is larger than 5 MiB
it holds more than 64 files
a file name inside it is longer than 256 characters
the files the plugin reads would unpack to more than 20 MiB in total

Importing an appliance again replaces its stored profile. That is also how you replace a key after you pair the appliance again.

The plugin refuses an appliance ID that differs from one it already has only in upper and lower case letters. On macOS, on Windows and on most network shares, the two would be stored as the same file, and you would lose both.

Limitations

Do not run another local integration for the same appliance at the same time. That includes Home Assistant’s homeconnect_ws, hcpy and the openHAB Home Connect Direct binding. Nobody has checked whether the appliances accept two local connections at once. For the same reason, the settings page has no button to test a connection: it would open a second connection while the plugin holds one.
Only fridges, freezers and fridge-freezers. The plugin does not support any other kind of Home Connect appliance.
Few models have been tested. The tiles were built from protocol research and checked against a simulated appliance in tests. Two real appliances have been tested: one Bosch KSN36VICG fridge and one Bosch GSN36VICG freezer. Some older feature names are taken on trust. If a tile is missing, see If a tile is missing.
Changes are not queued. A change you make while the appliance is disconnected fails straight away. A change the appliance refuses, such as a setpoint locked by Vacation Mode, is logged with the reason, and the tile goes back to the real value.
Temperatures are always Celsius. Switching the Home app to Fahrenheit only changes the display.

Features deliberately not exposed

The plugin leaves these features out on purpose. With debug logging on, it writes one line for each, with the reason.

Power state: on these appliances it always reads “On” and cannot be changed, so a switch would do nothing.
Wi-Fi signal strength, the freezer’s memory temperature, and defrost status: Home has no standard tile for them.
The Fahrenheit setpoints and the temperature unit setting: the plugin always works in Celsius.
The door assistant settings, and any duration setting, including the Sabbath mode duration: Home has no tile for choosing from a list or setting a duration.
The open door command: it is for built-in appliances only.
Acknowledging or rejecting events, and the software update, download and customer service events: never exposed.
Water and ice dispensers, and chiller, bottle cooler, wine, flex and extra fridge compartments: the appliances the plugin was built for do not have them.

How you know it worked

After you save a setting and restart the plugin, the Homebridge log shows none of the warnings in How entries are matched.