Programs
This plugin can start and stop programs on CoffeeMaker, Dishwasher, Dryer, Washer, and WasherDryer appliances. It is also capable of monitoring (but not controlling) the active program on Oven appliances; see Home Connect Authorisation Scopes.
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. for a CoffeeMaker it is possible to specify the temperature, strength, and amount of water).
The easiest way to customise the list of programs for an appliance is to use HomeKit's Identify mechanism, which triggers this plugin to read details of available programs from the appliance and write a template configuration to the Homebridge log file. This can then be edited as required before being pasted into the config.json file.
Unfortunately, Apple's Home app in iOS 13 does not appear to provide an Identify feature, so use one of the recommended third-party HomeKit Apps instead.
The format of the config.json file is:
"platforms":
[{
"platform": "HomeConnect",
"clientid": <Client ID>,
<Home Appliance ID #1>: {
"programs": [{
"name": <Program name #1>,
"key": <Program key #1>,
"options": {
<Option key #1>: <Option value #1>,
<Option key #2>: <Option value #2>,
...
<Option key #n>: <Option value #n>
}
},{
"name": <Program name #2>,
"key": <Program key #2>,
"options": {
...
}
},{
...
},{
"name": <Program name #n>,
"key": <Program key #n>,
"options": {
...
}
}]
},
<Home Appliance ID #2>: {
"programs": [
....
]
},
....
<Home Appliance ID #n>: {
"programs": [
....
]
},
}]
}
The Home Appliance ID (haID) is a string used by the Home Connect API to uniquely identify each appliance. It is 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). 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).
Each appliance to be customised should have an object with a single program key. Its value should be an array of objects, each describing a single program. The program array can be empty to prevent Switch services being added for any programs.
Each program object must include a name that is used to identify the HomeKit Switch. This 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 key. This 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 Identify log output or the Home Connect API documentation.
Each program object may also include an options object to modify behaviour of the program. This contains 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.)
Descriptions of the available programs and their options can be found in the Home Connect API documentation:
Use JSONLint to validate the modified config.json file before restarting Homebridge.
As an example, running Identify against the simulated CoffeeMaker results in the following output in the Homebridge log file:
[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
[HomeConnect] [CoffeeMaker Simulator] 6 of 6 programs available
{
"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",
"_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": 60,
"_ConsumerProducts.CoffeeMaker.Option.FillQuantity": "Int [60 .. 250] step 10 ml"
}
},
... 84 lines omitted ...
]
}
}
Ignore the first few lines which report the appliance's current state. The relevant portion is after the 6 of 6 programs available line.
The section between (but not including) the outer-most braces ({ and }) can be pasted into the HomeConnect platform section of the config.json file. However, it makes more sense to remove unwanted programs, customise the options, and remove the comments.
For example, to reduce the six CoffeeMaker programs to two:
-
My Espresso(95°C, very strong, small) -
Coffee(using the program's default options)
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"
}]
}
}]
}