config.json
A JSON object should be included for this plugin in the "platforms" array of Homebridge's config.json file.
The easiest way to configure this plugin is via the homebridge-config-ui-x (version 4.8.1 or later) graphical settings editor.
The plugin dynamically updates its configuration schema with the Home Connect authorisation URL and the appropriate options for the connected appliances. This is stored as ~/.homebridge/.homebridge-homeconnect-v1.schema.json (or in
Homebridge configuration directory specified using -U if different).
The supported programs and their options are read from the appliances when the plugin is started. Some appliances do not return all of the options supported by a program unless the program is first selected. Hence, the first time that the plugin is started, or when the HomeKit Identify routine is invoked, it switches the appliance on (if necessary), selects each program in turn to read their options, and then restores the previously selected program and power state. It also updates the supported program options each time that a program is manually selected.
| Component | Definition | |
|---|---|---|
"platforms" : [ { platform-member [ , name-member ] , clientid-member [ , simulator-member ] [ , language-member ] [ , debug-member ] ( , appliance-member ) * } ]
|
||
| platform-member | = |
"platform" : "HomeConnect"
|
| name-member | = |
"name" : name-string
|
| clientid-member | = |
"clientid" : clientid-string
|
| simulator-member | = |
"simulator" : true
|
| china-member | = |
"china" : true
|
| language-member | = |
"language" : { language-api-member }
|
| language-api-member | = |
"api" : language-api-string
|
| debug-member | = |
"debug" : [ [ debug-literal ( , debug-literal ) * ] ]
|
| debug-literal | = |
"Log API Headers" | "Log API Bodies" | "Log Appliance IDs" | "Log Debug as Info" | "Mock Appliances"
|
| appliance-member | = |
haid-string : { enabled-member [ names-member , ] [ features-member , ] [ addprograms-member , ] [ programs-list-member ] }
|
| enabled-member | = |
"enabled" : true | false
|
| names-member | = |
"names" : { "prefix" : { prefix-programs-member , prefix-other-member } }
|
| prefix-programs-member | = |
"programs" : true | false
|
| prefix-other-member | = |
"programs" : true | false
|
| features-member | = |
"features" : { [ features-option-member ( , features-option-member ) * ] }
|
| features-option-member | = |
feature-name : true | false
|
| addprograms-member | = |
"addprograms" : "none" | "auto" | "custom"
|
| programs-list-member | = |
"programs" : [ [ program-object ( , program-object ) * ] ]
|
| program-object | = |
{ program-name-member , program-key-member [ , program-selectonly-member ] [ , program-options-list-member ] }
|
| program-name-member | = |
"name" : program-name-string
|
| program-key-member | = |
"key" : program-key-string
|
| program-selectonly-member | = |
"selectonly" : true
|
| program-options-list-member | = |
"options" : { [ program-option-member ( , program-option-member ) * ] }
|
| program-option-member | = |
program-option-key-string : program-option-value
|
The value for the platform key must always be "HomeConnect" to identify this plugin.
The name-string may be set to an alternative display name for the plugin. This is used to prefix entries in the Homebridge log.
The clientid-string must be set to a valid Client ID obtained from the Home Connect Developer Program. The should be 64 hexadecimal digits, enclosed within double quotation marks (") to form a valid JSON string.
To operate physical appliances a Home Connect application must be created with the OAuth Flow set to Device Flow, and the Home Connect User Account matching the email address that was used within the Home Connect app.
Alternatively, test with the Home Connect simulated appliances by setting clientid-string to the Client ID of the automatically provided API Web Client. If this done then simulator-member must also be added to the configuration.
Set the value for the simulator key to true when using the Home Connect simulated appliances (i.e. when the clientid-member is set to the Client ID of the API Web Client). This changes the URL used to connect to the Home Connect API endpoint and the authorisation mechanism. When this is done authorisation is completely automatic; it is not necessary to copy an authorisation URL into a web browser.
This member should be omitted (or have its value set to false) when connecting to physical appliances.
Set the value for the china key to true when using appliances located in China. This changes the URL used to connect to the Home Connect API endpoint to servers located within China.
This member should be omitted (or have its value set to false) for all locations outside of China.
The value for the api key (within the language object) can be used to specify the language that is used for the Home Connect API. Use one of the Supported Language Tags listed in the Home Connect documentation. If this option is not specified then the default is en-GB for British English.
This setting currently only affects the names of the Switch services used to start programs.
Enable additional logging for debug purposes by setting the value for the debug key to an array of string literals identifying the required features.
The supported debug features are:
-
Log API Headers: Log the HTTP headers of all Home Connect API requests and responses. -
Log API Bodies: Log the body of all Home Connect API requests and responses. -
Log Appliance IDs: Log fullhaIdvalues instead of redacting the unique IDs. -
Log Debug as Info: Redirect all logging that would normally be performed at debug level to info level. This allows debug logging to be captured without needing to launchhomebridgewith its-Dcommand line option. -
Mock Appliances: Operate with local mock appliances instead of the Home Connect API.
Each appliance-member customises the behaviour of a single appliance. A separate instance is required for each appliance to be customised. There can be zero or more instances, each with a unique haid-string key.
The haid-string is the haId used to uniquely identify the appliance for the Home Connect API. It is usually comprised of the manufacturer's name, the appliance model number (E-Nr), and a twelve-digit hexadecimal number, each separated by hyphens (e.g. SIEMENS-HB678GBS6B-0123456789AB). However, some appliances use an eighteen-digit decimal number instead. This can be found within HomeKit apps as the appliance's Serial Number. It is also written to the Homebridge log file after using the HomeKit Identify method on the accessory (and as part of the Home Connect request URLs when debug is enabled by starting Homebridge with the -D option). By default the haId values are partially redacted in the log; set the Log Appliance IDs debug option to reveal the full values.
The names-member controls the names used for the HomeKit services created for the appliance. This currently affects whether the appliance name is used as a prefix for the other service name, which helps to disambiguate the controls for different appliances when using the "Show as Separate Tiles" option in the Apple Home app.
The prefix-programs-member controls whether the appliance name is used as a prefix for the Switch services that control individual appliance programs.
The prefix-other-member controls whether the appliance name is used as a prefix for all services, excludning those for individual appliance programs.
Set the value for the enabled key to false to prevent the appliance from being exposed to HomeKit.
A single features key can be optionally included for each appliance to specify whether HomeKit services should be created for some optional features.
Each features-option-member specifies whether a particular optional feature should be enabled. The feature-name key is the name of the feature to control, and the value is a boolean (true to create the HomeKit associated services, or false to remove them).
The currently supported feature-name values are:
- HomeKit
Lightbulbservices used to control appliance lighting:Ambient LightExternal LightFunctional LightInternal Light
- HomeKit
Stateless Programmable Switchservices used to trigger HomeKit automations from Home Connect appliance events:Event Buttons
- HomeKit
Doorservice used to indicate the state of the appliance door:Door
- HomeKit
Switchservices used to control appliance mode settings:Cup WarmerSabbath ModeFreezer Super ModeIce DispenserRefrigerator Super ModeVacation ModeFresh ModeEco ModeSabbath Mode
The features supported by each appliance are written to the Homebridge log file during plugin initialisation.
The value for the addprograms key is not currently used by this plugin. It is only included in the configuration schema (config.schema.json) as workaround for homebridge-config-ui-x limitations. The possible values are:
-
"none": Set programs-list-member to"programs": []. -
"auto": Removes programs-list-member from the configuration. -
"custom": Manual configuration of programs-list-member.
A single programs key can be optionally included for each appliance to specify which programs should have HomeKit Switch services created. See HomeKit Services and Characteristics for more details.
If this key is omitted the plugin automatically creates a Switch for each program that the appliance supports. No options are specified for these programs, so the appliance will use its current or default options.
When included the value must be an array of program-object values, each of which specifies the program associated with a single Switch service. The array can be empty to prevent any Switch services being added for the appliance's programs.
Each program-object includes a program-name-string to provide a short human-readable description of the program. This is used to identify the HomeKit Switch. For a particular appliance each program-name-string must be unique (but the same value can be used for programs on different appliances).
HomeKit has restrictions on the characters that can be included in the names of characteristics. It is safest to only use alphanumeric characters (letters and numbers), although hyphens (-) and apostrophes (') can be included as long as they are not the first or last character of the string.
The program-key-string of each program-object is the identifier used by the Home Connect API to select the program. The same key value can be used in multiple program objects, e.g. combined with different options.
The supported program key values can be found in the Homebridge log file when the plugin first starts or after using the HomeKit Identify method on the accessory. Descriptions of the available programs and their options can also be found in the Home Connect API documentation (see below).
If the value for the selectonly key is true then the Switch only selects the program and its options. This allows the program to be customised and started on the appliance itself.
Omitting this member (or setting its value to false) causes the Switch to start or stop the program.
In both cases the switch indicates when the program is active.
A single options key can be optionally included for each program-object to specify options that are used when selecting or starting the program.
It is not necessary to specify all of the program's possible options. For any options that are omitted the appliance will use its current or default values. If this key is omitted (or is an empty object) then no options are overridden.
The options are not checked when indicating to HomeKit which program is running.
Each program-option-member specifies a single option for a program, such as a temperature or duration. Alternatively, if the first character of the program-option-key-string is an underscore (_) then the value is treated as a comment and ignored (i.e. not passed to the Home Connect API).
The program-option-key-string must either be an option key supported by the program, or it must start with an underscore character (_) in which case it is treated as a comment and ignored (i.e. not passed to the Home Connect API).
The program-option-value must be a valid value for the option. This can be:
- a simple number, for numeric types
- a string within quotation marks (
”), typically for enumerated types -
trueorfalse, for boolean types
When the HomeKit Identify method is used on an accessory this plugin writes details of the options supported by each program to the Homebridge log file. It attempts to provide a valid example value for each option. It also adds a comment (a second program-option-member with the program-option-key-string prefixed by an underscore) listing the allowed values for enumerated types, or the range of allowed values for numeric types.
Descriptions of the available program options can also be found in the Home Connect API documentation (see below).
The BSH.Common.Option.StartInRelative and BSH.Common.Option.FinishInRelative program options expect a delay value in seconds. However, it is usually more convenient to specify the time of day that the program should start or finish. Hence, as a special case, this plugin allows the value for these options to be specified as an absolute time in "HH:MM" format (e.g. "12:00" for noon). This time is automatically converted to a delay in seconds when the program is started (using the Homebridge server's timezone).
A simple example is included in the README file.
Controlling Programs provides a more complete example.
Errors in the config.json file will stop Homebridge from starting.
Use JSONLint to check that the modified config.json file is valid JSON.
Descriptions of the available programs and their options can be found in the Home Connect API documentation:
