HomeKit Mapping
HomeKit does not define services and characteristics that are appropriate for most home appliances, other than for switching their power on/off. Only Hood appliances can be properly supported by HomeKit currently. Hence, this plugin adds extra characteristics to the main power `Switch service.
The following HomeKit services and characteristic are used by this plugin.
| Service | Characteristic | Used for |
|---|---|---|
Accessory Information |
Identify |
Log information about the appliance |
Accessory Information |
Manufacturer |
Appliance manufacturer |
Accessory Information |
Model |
Appliance model number (E-Nr) |
Accessory Information |
Serial Number |
Appliance haID (Home Appliance ID) |
Switch (power)
|
Configured Name |
Switch name (Power) |
Switch (power)
|
On |
Power on/off |
Switch (power)
|
Lock Physical Controls |
Child lock |
Switch (power)
|
Program Mode |
Remote control enable / local control status |
Switch (power)
|
Set Duration |
Alarm clock |
Switch (active program)
|
Configured Name |
Switch name (Active Program) |
Switch (active program)
|
On |
Operation state program running |
Switch (active program)
|
Status Active |
Operation state normal operation |
Switch (active program)
|
Status Fault |
Operation state error |
Switch (active program)
|
Remaining Duration |
Program progress |
Switch (specific program)
|
Configured Name |
Switch name (program to select/start/stop) |
Switch (specific program)
|
On |
Program select/start/stop (or monitor) |
Switch (mode)
|
Configured Name |
Switch name (mode) |
Switch (mode)
|
On |
Modes |
Door |
Current Position |
Door open/closed |
Door |
Target Position |
Open or partly open door |
Door |
Position State |
Door being opened/stopped |
Door |
Lock Current State |
Door locked/unlocked |
Stateless Programmable Switch |
Configured Name |
Switch name (event) |
Stateless Programmable Switch |
Programmable Switch Event |
Events |
Fan (v2)
|
Active |
Hood fan on/off control |
Fan (v2)
|
Current Fan State |
Hood fan on/off indication |
Fan (v2)
|
Target Fan State |
Hood fan manual/automatic |
Fan (v2)
|
Rotation Speed |
Hood fan speed |
Fan (v2)
|
Remaining Duration |
Program progress |
Lightbulb |
Configured Name |
Light (Ambient Light, External Light, Functional Light or Internal Light) |
Lightbulb |
On |
Light (ambient, external, functional, or internal) on/off |
Lightbulb |
Brightness |
Light (ambient, external, functional, or internal) brightness |
Lightbulb |
Color Temperature |
Light (functional) colour temperature |
Lightbulb |
Hue |
Light (ambient) colour |
Lightbulb |
Saturation |
Light (ambient) colour |
Battery Service |
Battery Level |
CleaningRobot battery charge level |
Battery Service |
Status Low Battery |
CleaningRobot battery charge level |
Battery Service |
Charging State |
CleaningRobot docked and charging status |
All HomeKit accessories support an Accessory Information service. This plugin uses its Manufacturer, Model, and Serial Number characteristics to report information about the appliance. It also uses the Identify routine to trigger reading information from the appliance, such as details of its supported programs, which are then written to the Homebridge log file.
This plugin creates a Switch for each appliance's power state.
For appliances that do not support being switched off via the Home Connect API (which surprisingly includes Dryer, Washer, and WasherDryer appliances) this Switch is read-only, i.e. it just indicates the state of the appliance.
For other appliances the Switch allows the appliance to be switched on or off. (CleaningRobot, CoffeeMaker, CookProcessor, Oven, and WarmingDrawer appliances actually switch to standby rather than off.)
This plugin creates additional characteristics on the main power Switch service to indicate the current status of the appliance.
For appliances that have a child lock, the Lock Physical Controls characteristic allows the child lock to be enabled or disabled.
For appliances that support an alarm clock, the Set Duration characteristic allows this to be set and monitored.
The Program Mode characteristic indicates the remote or local control status:
- If the appliance is being manually controlled locally then it is set to
Program Scheduled, currently overriden to manual mode(displayed as OVERRIDE in Elgato Eve, or Manual Mode in Home+). - Else, if either remote control or remote start is disabled on the appliance then it is set to
No Programs Scheduled(displayed as MANUAL in Elgato Eve, or Program not Scheduled in Home+). - Otherwise it is set to
Program Scheduled(displayed as SCHEDULE in Elgato Eve, or Program Scheduled in Home+).
These characteristics are not part of the standard Switch service as defined by Apple, and are not supported by Apple's Home app. See the recommended HomeKit Apps that should be used instead.
For most appliances that support programs a Switch service indicates when a program is currently running (including delayed start and in the process of aborting). It also allows the currently selected program to be started, or the active program to be stopped. For appliances that support pause and resume this also controls that functionality.
Turning the switch on while the active program is paused attempts to resume it if supported by the appliance. Otherwise, it attempts to start the selected program. For this to work most appliances require:
- Connection to the Home Connect servers
- Powered on
- No active program
- Remote control enabled
- Remote program start enabled
- No recent local (manual) control
Turning a switch off attempts to pause the active program if supported by the appliance and the appliance is not in an error state. Otherwise it stops the active program.
The Status Active and Status Fault characteristics are used to indicate the operation state of the appliance:
-
Status Activeis cleared if a program is active but not running normally (e.g. when it is paused, requires user interaction, has an error, or is in the process of aborting). (Elgato Eve only shows this status when it is active.) -
Status Errorindicates when the appliance actually reports an error. (Elgato Eve only shows this status when it is active.)
For appliances that provide a countdown of the remaining program time this is reported in the Remaining Duration characteristic.
These characteristics are not part of the standard Switch service as defined by Apple, and are not supported by Apple's Home app. See the recommended HomeKit Apps that should be used instead.
For most appliances that support programs additional Switch services may be created to allow programs to be selected, started, or stopped. This is not done for Hood appliances, for which a more appropriate Fan service is used instead.
By default a Switch is automatically created for each program that the appliance supports. However, this can be customised via the Homebridge config.json file.
Turning a switch on attempts to either start (or just select) the corresponding program (with any configured options). For this to work most appliances require:
- Connection to the Home Connect servers
- Powered on
- No active program
- Remote control enabled
- Remote program start enabled (not required if just selecting the program)
- No recent local (manual) control
Turning a switch off stops the active program.
Some appliances support special modes, such as cooling modes on refrigeration appliances or sabbath mode. A Switch service is created for each supported mode allowing it to be switched on or off, and the current status viewed.
This plugin creates a Door for each appliance's door. The Current Position characteristic is set to the last state reported by the appliance.
FridgeFreezer appliances have multiple doors, but the Home Connect API does not distinguish between them and just reports whether the action was to open or close a door. However, for those appliances the separate door alarm events can be used to trigger automations.
For appliances that can lock their door during operation, the Lock Current State characteristic indicates when the door is locked.
For appliances that support opening their door remotely, the Target Position characteristic can be set to 100% to fully open the door, or (if supported) 50% to partly open the door.
Most appliance types can generate events, e.g. indicating when a program has finished, when a Freezer/Refrigerator door has been left open, or when a CoffeeMaker drip tray is full. This plugin creates a Stateless Programmable Switch service for each possible event (plus a single Service Label service) so that they can be used to trigger HomeKit automations.
Apple's Home app only shows numeric labels for these services instead of their names. This makes it difficult to construct HomeKit automations from these triggers. See the recommended HomeKit Apps that should be used instead.
This plugin treats Hood appliances specially because HomeKit does support appropriate services and characteristics natively.
A Fan (v2) service provides control over the Hood's fan programs (instead of using Switch services). This allows the fan to be switched on or off, selection of manual or automatic mode, and (in manual mode) selection of the fan speed. If the fan supports intensive modes then these are treated as the highest fan speeds. (No control is provided over fan run-on.)
The remaining program time (for fan run-on) is reported in the Remaining Duration characteristic.
This characteristic is not part of the standard Fan service as defined by Apple, and is not supported by Apple's Home app. See the recommended HomeKit Apps that should be used instead.
If a Hood appliance incorporates a functional light then a Lightbulb service allows it to be switched on and off, its brightness adjusted, and its colour temperature selected.
If a Dishwasher or Hood incorporates an ambient light then a Lightbulb service allows it to be switched on and off, its brightness adjusted, and a custom colour selected. (Non-custom colours cannot be mapped to HomeKit characteristics.)
If a Freezer, Fridge, or FridgeFreezer, appliance incorporates an external light and/or internal light then a Lightbulb service allows it to be switched on and off, and its brightness adjusted.
For CleaningRobot appliances this plugin creates a Battery Service to indicate the current battery status. Low battery status is indicated when the charge level falls to 15%.
The Charging State characteristic is used to indicate both whether the appliance is connected to the docking station, and whether the battery is charging:
-
Not Chargingis reported if the battery is currently charging. -
Chargingis reported if the appliance is connected to the docking station, but is not currently charging. -
Not Chargeableis reported if the appliance is not connected to the docking station.
