You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`.
15
+
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
16
16
17
17
{% configuration %}
18
18
homekit:
19
19
description: HomeKit configuration.
20
20
required: true
21
21
type: map
22
22
keys:
23
-
pincode:
24
-
description: Pin code required during setup of HomeKit Home Assistant accessory. The format needs to be 'XXX-XX-XXX' where X is a number between 0 and 9.
23
+
auto_start:
24
+
description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start))
25
25
required: false
26
-
type: string
27
-
default: '"123-45-678"'
26
+
type: boolean
27
+
default: true
28
28
port:
29
29
description: Port for the HomeKit extension.
30
30
required: false
31
31
type: int
32
-
default: 51826
32
+
default: 51827
33
+
filter:
34
+
description: Filter entities to available in the `Home` app. ([Configure Filter](#configure-filter))
35
+
required: false
36
+
type: map
37
+
keys:
38
+
include_domains:
39
+
description: Domains to be included.
40
+
required: false
41
+
type: list
42
+
include_entities:
43
+
description: Entities to be included.
44
+
required: false
45
+
type: list
46
+
exclude_domains:
47
+
description: Domains to be excluded.
48
+
required: false
49
+
type: list
50
+
exclude_entities:
51
+
description: Entities to be excluded.
52
+
required: false
53
+
type: list
54
+
entity_config:
55
+
description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g. `alarm_control_panel.alarm`.
56
+
required: false
57
+
type: map
58
+
keys:
59
+
alarm_control_panel:
60
+
description: Additional options for `alarm_control_panel` entities.
61
+
required: false
62
+
type: map
63
+
keys:
64
+
code:
65
+
description: Code to arm or disarm the alarm in the frontend.
66
+
required: false
67
+
type: string
68
+
default: ''
33
69
{% endconfiguration %}
34
70
71
+
35
72
## {% linkable_title Setup %}
36
73
37
74
To enable the `HomeKit` component in Home Assistant, add the following to your configuration file:
38
75
39
76
```yaml
40
77
# Example for HomeKit setup
41
78
homekit:
42
-
pincode: '123-45-678'
43
79
```
44
80
45
-
<p class='note'>It is not recommended to choose '123-45-678' as your pin code!</p>
46
-
47
-
After Home Assistant has started, all supported entities (see the [list](#supported-components) below which components are already integrated) will be exposed to `HomeKit`. To add them:
48
-
1. Open the `Home` App.
49
-
2. Choose `Add Accessory` and then `Don't Have a Code or Can't Scan?`.
50
-
3. The `Home Assistant` Bridge should be listed there. Select it and follow the instructions to complete setup.
81
+
After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if the are [supported](#supported-components). To add them:
82
+
1. Open the Home Assistant frontend. A new card will display the `pin code`.
83
+
1. Open the `Home` app.
84
+
2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`.
85
+
4. Confirm the you are adding an `Uncertified Accessory` by clicking on `Add Anyway`.
86
+
5. Follow the setup be clicking on `Next` and lastly `Done` in the top right hand corner.
87
+
6. The `Home Assistant` Bridge and the Accessories should now be listed in the `Home` app.
51
88
52
89
After the setup is completed you should be able to control your Home Assistant components through `Home` and `Siri`.
53
90
91
+
92
+
## {% linkable_title Considerations %}
93
+
94
+
95
+
### {% linkable_title Accessory ID %}
96
+
97
+
Currently this component uses the `entity_id` to generate a unique `accessory id (aid)` for `HomeKit`. The `aid` is used to identify a device and save all configurations made for it. This however means that if you decide to change an `entity_id` all configurations for this accessory made in the `Home` app will be lost.
98
+
99
+
### {% linkable_title Persistence Storage %}
100
+
101
+
Unfortunately `HomeKit` doesn't support any kind of persistence storage, only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
102
+
103
+
A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one).
104
+
105
+
106
+
## {% linkable_title Disable Auto Start %}
107
+
108
+
Depending on your individual setup, it might be necessary to disable `Auto Start` for all accessories to be available for `HomeKit`. Only those entities that are fully setup when the `HomeKit` component is started, can be added. To start `HomeKit` when `auto_start: False`, you can call the service `homekit.start`.
109
+
110
+
This can be automated using an `automation`.
111
+
112
+
{% raw %}
113
+
```yaml
114
+
# Example for Z-Wave
115
+
homekit:
116
+
auto_start: False
117
+
118
+
automation:
119
+
- alias: 'Start HomeKit'
120
+
trigger:
121
+
- platform: event
122
+
event_type: zwave.network_ready
123
+
action:
124
+
- service: homekit.start
125
+
```
126
+
{% endraw %}
127
+
128
+
{% raw %}
129
+
```yaml
130
+
# Example using a delay after start of Home Assistant
131
+
homekit:
132
+
auto_start: False
133
+
134
+
automation:
135
+
- alias: 'Start HomeKit'
136
+
trigger:
137
+
- platform: homeassistant
138
+
event: start
139
+
action:
140
+
- delay: 00:05 # Waits 5 minutes
141
+
- service: homekit.start
142
+
```
143
+
{% endraw %}
144
+
145
+
146
+
## {% linkable_title Configure Filter %}
147
+
148
+
To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. By default no entity will be excluded. Keep in mind though that only supported components can be added.
149
+
150
+
54
151
## {% linkable_title Supported Components %}
55
152
56
153
The following components are currently supported:
@@ -59,8 +156,26 @@ The following components are currently supported:
59
156
| --------- | --------- | ----------- |
60
157
| alarm_control_panel | SecuritySystem | All security systems. |
61
158
| climate | Thermostat | All climate devices. |
62
-
| cover | Window | All covers that support `set_cover_position`. |
159
+
| cover | WindowCovering | All covers that support `set_cover_position`. |
63
160
| sensor | TemperatureSensor | All sensors that have `Celsius` and `Fahrenheit` as their `unit_of_measurement`. |
64
-
| switch/remote | Switch | All switches or remotes (represented as switches). |
161
+
| switch / remote | Switch | All switches or remotes (represented as switches). |
162
+
65
163
66
-
<p class='note'>Currently only devices that are setup when Home Assistant is starting can be exposed to `HomeKit`. This means that especially `Z-Wave` components are currently not supported, since they will be setup afterwards. We are working on a solution for this problem.</p>
164
+
## {% linkable_title Error reporting %}
165
+
166
+
If you encounter any issues or bug and want to report them on `GitHub`, please follow these steps to make it easier for others to help and get your issue solved.
167
+
168
+
1. Enable debugging mode:
169
+
```yaml
170
+
logger:
171
+
default: warning
172
+
logs:
173
+
homeassistant.components.homekit: debug
174
+
```
175
+
2. Reproduce the bug / problem you have encountered.
176
+
3. Stop Home Assistant and copy the log from the log file. That is necessary since some errors only get logged, when Home Assistant is being shutdown.
177
+
4. Follow this link: [home-assistant/issues/new](https://github.com/home-assistant/home-assistant/issues/new?labels=component: homekit) and open a new issue.
178
+
5. Fill out all fields and especially include the following information:
179
+
- The configuration entries for `homekit` and the `component` that is causing the issue.
180
+
- The log / traceback you have generated before.
181
+
- Screenshots of the failing entity in the `states` panel.
0 commit comments