HomeKit Services and Characteristics

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

Accessory Information Service

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.

Switch Service for Power

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.)

Extra Power Switch Characteristics

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.

Switch Service for Active Program

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.

Extra Active Program Switch Characteristics

The Status Active and Status Fault characteristics are used to indicate the operation state of the appliance:

• Status Active is 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 Error indicates 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.

Switch Services for Programs

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.

Switch Services for Modes

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.

Door Service for Appliance Doors

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.

Extra Door Characteristics

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.

Stateless Programmable Switch Services for Events

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.

Fan Service for Hood Appliances

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.)

Extra Fan Characteristic

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.

Lightbulb Service for Ambient, External, Functional, and Internal Lights

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.

Battery Service Service for CleaningRobot Appliances

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 Charging is reported if the battery is currently charging.
• Charging is reported if the appliance is connected to the docking station, but is not currently charging.
• Not Chargeable is reported if the appliance is not connected to the docking station.