Programs - thoukydides/homebridge-homeconnect GitHub Wiki
Controlling Programs
This plugin can select, start, and stop programs on CleaningRobot, CoffeeMaker, Dishwasher, Dryer, Oven, Washer, and WasherDryer appliances.
By default this plugin creates a Switch for each program that the appliance supports, as described under HomeKit Mapping. However, it is possible to use the config.json file to select which programs should be presented (including none), and to provide options (e.g. setting the temperature, strength, and amount of water for a CoffeeMaker).
Customising Programs
The easiest way to configure this plugin is via the homebridge-config-ui-x (version 4.8.1 or later) graphical settings editor. This plugin dynamically updates its configuration schema with details of the programs and options supported by each connected appliance.
Otherwise, use HomeKit's Identify mechanism to trigger this plugin to write a template configuration to the Homebridge log file. Unfortunately, Apple's Home app in iOS/iPadOS 17 does not appear to provide a way to trigger the Identify routine, so use one of the recommended third-party HomeKit Apps instead.
Also invoke the Identify routine if programs or their options appear to be missing. This should be done when the appliance does not have an active program, and with remote control enabled on the appliance. The plugin will then switch the appliance on (if necessary), select each program in turn to read their options, and then restore the previously selected program and power state.
The format of the config.json file is:
"platforms":
[{
"platform": "HomeConnect",
"name": "HomeConnect",
"clientid": <clientid-string>,
"simulator": false,
"language": {
"api": "en-GB",
},
"debug": []
<haid-string #1>: {
"enabled": true,
"names": {
prefix: { programs: false, other: true }
},
"features": {},
"programs": [{
"name": <program-name-string #1>,
"key": <program-key-string #1>,
"selectonly": true|false,
"options": {
<program-option-key-string #1>: <program-option-value #1>,
<program-option-key-string #2>: <program-option-value #2>,
...
<program-option-key-string #n>: <program-option-value #n>
}
},{
"name": <program-name-string #2>,
"key": <program-key-string #2>,
"selectonly": true|false,
"options": {
...
}
},{
...
},{
"name": <program-name-string #n>,
"key": <program-key-string #n>,
"selectonly": true|false,
"options": {
...
}
}]
},
<haid-string #2>: {
"enabled": true,
"names": {},
"features": {},
"programs": [
....
]
},
....
<haid-string #n>: {
"enabled": true,
"names": {},
"features": {},
"programs": [
....
]
},
}]
}
The haid-string (haID) is a string used by the Home Connect API to uniquely identify each appliance. 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. BOSCH-HCS06COM1-846D1E984F70). However, some appliances use an eighteen-digit decimal number instead. This value can be found from the Identify log output (or from almost any part of this plugin's log when debug is enabled by starting Homebridge with the -D option). It is also shown by this plugin as the accessory's Serial Number within HomeKit apps.
Each appliance to be customised should have an object with a single programs key. Its value should be an array of program-object objects, each describing a single program. The programs array can be left empty to prevent Switch services being added for any programs.
Each program-object must include a program-name-member that is used to identify the HomeKit Switch. The value of the name key should be a short human-readable description of the program. It must be unique (within the programs for that appliance), and should not contain any special characters.
Each program-object must also include a program-key-member. The value of the key key specifies the identifier used by the Home Connect API to select the program. The same value can be used in multiple program objects, e.g. combined with different options. The supported values can be found in the Identify log output or the Home Connect API documentation.
Each program-object may include a program-selectonly-member. If the value of the selectonly key is true then the HomeKit Switch only selects the program and its options, otherwise it start and stops the program.
Each program-object may also include a program-options-list-member to modify behaviour of the program. The value of the options key is an object with key-value pairs for the options that should be changed from their defaults. It is not necessary to include all supported options. The Identify output attempts to list a valid value for each option. This is followed by a second key prefixed with an underscore (_) that provides details of the allowed values; either a list of supported enum values, or a description of the range and units for numeric values. (The option keys prefixed by an underscore are ignored when this plugin processes the config.json file so can be left as comments.)
Example Identify Output for a CoffeeMaker
Running Identify against the simulated CoffeeMaker results in the following being written to the Homebridge log file. The first line provides the haID of the appliance (which should be used as the haid-string in the config.json file). This is followed by a dump of the appliance's complete current state and settings. Ignore this initial output:
[HomeConnect] [CoffeeMaker Simulator] Identify: BOSCH-HCS06COM1-846D1E984F70
[HomeConnect] [CoffeeMaker Simulator] BSH.Common.Root.SelectedProgram=ConsumerProducts.CoffeeMaker.Program.Beverage.Coffee
[HomeConnect] [CoffeeMaker Simulator] BSH.Common.Setting.PowerState=BSH.Common.EnumType.PowerState.On
[HomeConnect] [CoffeeMaker Simulator] BSH.Common.Status.DoorState=BSH.Common.EnumType.DoorState.Closed
[HomeConnect] [CoffeeMaker Simulator] BSH.Common.Status.OperationState=BSH.Common.EnumType.OperationState.Ready
[HomeConnect] [CoffeeMaker Simulator] BSH.Common.Status.RemoteControlStartAllowed=true
[HomeConnect] [CoffeeMaker Simulator] connected=true
The plugin then updates its cache of programs that the appliance supports. When it has collated the results it writes a line to the log summarising how many programs the appliance supports:
[HomeConnect] [CoffeeMaker Simulator] 6 programs supported
This is immediately followed by a JSON structure that describes all of the appliance's programs and their options:
{
"BOSCH-HCS06COM1-846D1E984F70": {
"programs": [
{
"name": "Espresso",
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
"options": {
"ConsumerProducts.CoffeeMaker.Option.CoffeeTemperature": "ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.88C",
"_ConsumerProducts.CoffeeMaker.Option.CoffeeTemperature": [
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.88C",
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.90C",
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.92C",
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.94C",
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.95C",
"ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.96C"
],
"ConsumerProducts.CoffeeMaker.Option.BeanAmount": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.VeryMild",
"_ConsumerProducts.CoffeeMaker.Option.BeanAmount": [
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.VeryMild",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Mild",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Normal",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.Strong",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.VeryStrong",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.DoubleShot",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.DoubleShotPlus",
"ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.DoubleShotPlusPlus"
],
"ConsumerProducts.CoffeeMaker.Option.FillQuantity": 35,
"_ConsumerProducts.CoffeeMaker.Option.FillQuantity": "Int [35 .. 60] step 5 ml"
}
},
... 28 lines omitted ...
{
"name": "Coffee",
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Coffee",
"options": {
"ConsumerProducts.CoffeeMaker.Option.CoffeeTemperature": "ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.88C",
... 8 lines omitted ...
"ConsumerProducts.CoffeeMaker.Option.BeanAmount": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.VeryMild",
... 10 lines omitted ...
"ConsumerProducts.CoffeeMaker.Option.FillQuantity": 60,
"_ConsumerProducts.CoffeeMaker.Option.FillQuantity": "Int [60 .. 250] step 10 ml"
}
},
... 84 lines omitted ...
]
}
}
The section between (but not including) the outer-most braces ({ and }) can be copied unmodified as an appliance-member into the HomeConnect platform section of the config.json file. However, it is better to customise and simplify it first:
- Remove any program-object for programs that are not required.
- Remove the program-options-list-member (the
optionskey and its value object) for any programs that should use its current or default values. Alternatively, remove any individual program-option-member for options that are not required. - Remove the program-option-member comments (those where the program-option-key-string begins with an underscore character).
- Add a program-selectonly-member (
"selectonly": true) to each program that should only be selected (rather than started or stopped). - Modify the remaining program-option-value values to customise the program options as required.
It is also possible to duplicate a program-object to add variants of the program that specify different options. If this is done then the program-name-member must be modified to give each program a unique name.
Example config.json with CoffeeMaker Programs
As an example, to only create Switch services for two CoffeeMaker programs (instead of for all six programs that are supported by the simulator):
My Espresso(95°C, very strong, small)Coffee(select but do not start the program, allowing its options to be adjusted on the appliance)
then the following configuration could be used:
{
"platforms":
[{
"platform": "HomeConnect",
"clientid": "0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF",
"BOSCH-HCS06COM1-846D1E984F70": {
"programs": [{
"name": "My Espresso",
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Espresso",
"options": {
"ConsumerProducts.CoffeeMaker.Option.CoffeeTemperature": "ConsumerProducts.CoffeeMaker.EnumType.CoffeeTemperature.95C",
"ConsumerProducts.CoffeeMaker.Option.BeanAmount": "ConsumerProducts.CoffeeMaker.EnumType.BeanAmount.VeryStrong",
"ConsumerProducts.CoffeeMaker.Option.FillQuantity": 40
}
},{
"name": "Coffee",
"key": "ConsumerProducts.CoffeeMaker.Program.Beverage.Coffee",
"selectonly": true
}]
}
}]
}