public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[homekit] add support for complex accessories (#12346)

Browse Source 
* Add complex accessories

Signed-off-by: Eugen Freiter <freiter@gmx.de>
This commit is contained in:
eugen
2022-03-28 00:11:44 +02:00
committed by GitHub
parent 53bb6f48ad
commit f1176a062b
12 changed files with 174 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
bundles/org.openhab.io.homekit/README.md
View File

@@ -457,7 +457,73 @@ or using UI
![sensor_ui_config.png](doc/sensor_ui_config.png)
### Complex accessory
Multiple HomeKit accessories can be combined to one accessory in order to group several functions provided by one or multiple physical devices.
For example, ceiling fans often include lighting functionality. Such fans can be modeled as:
- two separate HomeKit accessories - fan **and** light.
iOS home app would show them as **two tiles** that can be controlled directly from home screen.
![ios_fan_and_light_home_screen.png](doc/ios_fan_and_light_home_screen.png)
- one complex accessory - fan **with** light.
iOS home app would show them as **one tile** that opens view with two controls
![ios_fan_with_light_home_screen.png](doc/ios_fan_with_light_home_screen.png)
![ios_fan_with_light_details.png](doc/ios_fan_with_light_details.png)
The provided functionality is in both cases identical.
In order to combine multiple accessories to one HomeKit accessory you need:
- add corresponding openHAB items to one openHAB group
- configure HomeKit metadata of both HomeKit accessories at that group.
e.g. configuration for a fan with light would look as follows
```xtend
Group FanWithLight "Fan with Light" {homekit = "Fan,Light"}
Switch FanActiveStatus "Fan Active Status" (FanWithLight) {homekit = "Fan.ActiveStatus"}
Number FanRotationSpeed "Fan Rotation Speed" (FanWithLight) {homekit = "Fan.RotationSpeed"}
Switch Light "Light" (FanWithLight) {homekit = "Lighting.OnState"}
```
or in mainUI
![ui_fan_with_light_group_view.png](doc/ui_fan_with_light_group_view.png)
![ui_fan_with_light_group_code.png](doc/ui_fan_with_light_group_code.png)
![ui_fan_with_light_group_config.png](doc/ui_fan_with_light_group_config.png)
iOS home app uses by default the type of the first accessory on the list for the tile on home screen.
e.g. an accessory defined as homekit = "Fan,Light" will be shown as a fan and an accessory defined as homekit = "Light,Fan" as a light in iOS home app.
if you want to change the tile you can either change the order of types in homekit metadata or add "primary=<type>" to HomeKit metadata configuration.
e.g. following configuration will force "fan" to be used as tile
```xtend
Group FanWithLight "Fan with Light" {homekit = "Light,Fan" [primary = "Fan"]}
```
![ui_fan_with_light_primary.png](doc/ui_fan_with_light_primary.png)
However, home app does not support changing of tiles for already added accessory.
If you want to change the tile after the accessory was added, you need either to rename the group, if you use textual item configuration, or to delete and to create a new group with a different name, if you use UI for configuration.
You can combine more than two accessories as well as accessories linked to different physical devices.
You can also do unusually combinations, e.g. you can combine temperature sensor with blinds and light.
It will be represented by home app as follows
![ios_complex_accessory_detail_screen.png](doc/ios_complex_accessory_detail_screen.png)
#### Limitations
Currently, it is not possible to combine multiple accessories of the same type, e.g. 2 lights.
Support for this is planned for the future release of openHAB HomeKit binding.
## Supported accessory type
| Accessory Tag | Mandatory Characteristics | Optional Characteristics | Supported OH items | Description |