Tweaks to HomeKit documentation (#16875)

This commit is contained in:
Franck Nijhof 2021-03-05 21:09:28 +01:00 committed by GitHub
parent 0c31682313
commit 0d3924de79
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -12,241 +12,255 @@ ha_codeowners:
ha_zeroconf: true
---
The HomeKit integration allows you to make your Home Assistant entities available in Apple HomeKit, so they can be controlled from Apple's Home app and Siri. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later. However if you do encounter issues, check out the [troubleshooting](#troubleshooting) section.
The HomeKit integration allows you to make your Home Assistant entities available in Apple HomeKit,
so they can be controlled from Apple's Home app and Siri.
Please make sure that you have read the [considerations](#considerations) listed below to save you
some trouble later. However if you do encounter issues, check out the
[troubleshooting](#troubleshooting) section.
<div class="note">
If you want to control `HomeKit` only devices with Home Assistant, check out the [HomeKit controller](/integrations/homekit_controller/) component.
If you want to control HomeKit only devices with Home Assistant,
check out the [HomeKit controller](/integrations/homekit_controller/) integration.
That one provides the possibility to pull HomeKit enabled devices into Home Assistant.
</div>
{% include integrations/config_flow.md %}
If you need to use the `entity_config`, `ip_address`, or `advertise_ip` configuration options, HomeKit Bridge must be configured via your `configuration.yaml` file:
## Manual configuration
```yaml
If you want make specific changes to the way entities are published to HomeKit, override the
IP address the HomeKit integration uses to communicate with your network or change the
IP address the HomeKit uses to advertise itself to the network, you'll need to configure the
HomeKit integration using a manual YAML entry to your `configuration.yaml` file.
This is an example entry of how that would look:
```yaml test
# Example configuration.yaml entry configuring HomeKit
homekit:
- filter:
include_domains:
- alarm_control_panel
- light
- media_player
include_entity_globs:
- binary_sensor.*_occupancy
include_entities:
- binary_sensor.living_room_motion
entity_config:
alarm_control_panel.home:
code: 1234
binary_sensor.living_room_motion:
linked_battery_sensor: sensor.living_room_motion_battery
low_battery_threshold: 31
light.kitchen_table:
name: Kitchen Table Light
lock.front_door:
code: 1234
media_player.living_room:
feature_list:
- feature: on_off
- feature: play_pause
- feature: play_stop
- feature: toggle_mute
switch.bedroom_outlet:
type: outlet
camera.back_porch:
support_audio: True
- name: HASS Bridge 2
port: 56332
filter:
include_domains:
- light
- filter:
include_domains:
- alarm_control_panel
- light
- media_player
include_entity_globs:
- binary_sensor.*_occupancy
include_entities:
- binary_sensor.living_room_motion
entity_config:
alarm_control_panel.home:
code: 1234
binary_sensor.living_room_motion:
linked_battery_sensor: sensor.living_room_motion_battery
low_battery_threshold: 31
light.kitchen_table:
name: "Kitchen Table Light"
lock.front_door:
code: 1234
media_player.living_room:
feature_list:
- feature: on_off
- feature: play_pause
- feature: play_stop
- feature: toggle_mute
switch.bedroom_outlet:
type: outlet
camera.back_porch:
support_audio: true
- name: "HASS Bridge 2"
port: 56332
filter:
include_domains:
- light
```
{% configuration %}
homekit:
description: HomeKit configuration.
required: true
type: map
keys:
auto_start:
description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start))
required: false
type: boolean
default: true
port:
description: Port for the HomeKit extension. If you are adding more than one instance they need to have different values for port.
required: false
type: integer
default: 51827
name:
description: Need to be individual for each instance of Home Assistant using the integration on the same local network. Between `3` and `25` characters. Alphanumeric and spaces allowed.
required: false
type: string
default: '`Home Assistant Bridge`'
ip_address:
description: The local network IP address. Only necessary if the default from Home Assistant does not work.
required: false
type: string
mode:
description: HomeKit can expose an entity via a bridge, or a single entity as an accessory which is needed for Television Media Players. ([Accessory mode](#accessory-mode))
required: false
type: string
default: '`bridge`'
advertise_ip:
description: If you need to override the IP address used for mDNS advertisement. (For example, using network isolation in Docker and together with an mDNS forwarder like `avahi-daemon` in reflector mode)
required: false
type: string
filter:
description: Filters for entities to be included/excluded from HomeKit. ([Configure Filter](#configure-filter))
required: false
type: map
keys:
include_domains:
description: Domains to be included.
required: false
type: list
include_entity_globs:
description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`).
required: false
type: list
include_entities:
description: Entities to be included.
required: false
type: list
exclude_domains:
description: Domains to be excluded.
required: false
type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`).
required: false
type: list
exclude_entities:
description: Entities to be excluded.
required: false
type: list
entity_config:
description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g., `alarm_control_panel.alarm`.
required: false
type: map
keys:
'`ENTITY_ID`':
description: Additional options for specific entities.
required: false
type: map
keys:
name:
description: Name of the entity to show in HomeKit. HomeKit will cache the name on the first run so the accessory must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_battery_sensor:
description: The `entity_id` of a `sensor` entity to use as the battery of the accessory. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_doorbell_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the doorbell sensor of the camera accessory to enable doorbell notifications. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_motion_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the motion sensor of the camera accessory to enable motion notifications. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_obstruction_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the obstruction sensor of the garage door (cover) accessory to enable obstruction state tracking. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
low_battery_threshold:
description: Minimum battery level before the accessory starts reporting a low battery.
required: false
type: integer
default: 20
code:
description: Code to `arm / disarm` an alarm or `lock / unlock` a lock. Only applicable for `alarm_control_panel` or `lock` entities.
required: false
type: string
default: '`<No code>`'
feature_list:
description: Only for `media_player` entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema.
required: false
type: list
keys:
feature:
description: Name of the feature to add to the entity representation. Valid features are `on_off`, `play_pause`, `play_stop` and `toggle_mute`. The media_player entity must support the feature to be valid.
required: true
type: string
type:
description: Only for `switch` entities. Type of accessory to be created within HomeKit. Valid types are `faucet`, `outlet`, `shower`, `sprinkler`, `switch` and `valve`. HomeKit will cache the type on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
default: '`switch`'
stream_count:
description: Only for `camera` entities. The number of simultaneous stream the camera can support.
required: false
type: integer
default: 3
stream_address:
description: Only for `camera` entities. The source IP address to use when streaming to RTP clients. If your Home Assistant host has multiple interfaces, selecting a specific IP may be necessary.
required: false
type: string
default: local IP from Home Assistant
stream_source:
description: Only for `camera` entities. A URL, file or other valid FFmpeg input string to use as the stream source, rather than the default camera source. Required for camera entities that do not natively support streaming (MJPEG). If `-i` is not found in the stream source, it is prepended to construct the FFmpeg input.
required: false
type: string
default: stream source from camera entity
support_audio:
description: Only for `camera` entities. Whether the camera supports audio. Audio is disabled unless this flag is set to `True`.
required: false
type: boolean
default: '`False`'
max_width:
description: Only for `camera` entities. Maximum width supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 1920
max_height:
description: Only for `camera` entities. Maximum height supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 1080
max_fps:
description: Only for `camera` entities. Maximum fps supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 30
audio_map:
description: Only for `camera` entities. FFmpeg [stream selection mapping](https://ffmpeg.org/ffmpeg.html#Stream-selection) for the audio-only stream. Selects the first audio stream in the input stream by default. If your input stream has multiple audio streams, this may need to be adjusted.
required: false
type: string
default: '`0:a:0`'
video_map:
description: Only for `camera` entities. FFmpeg [stream selection mapping](https://ffmpeg.org/ffmpeg.html#Stream-selection) for the video-only stream. Selects the first video stream in the input stream by default. If your input stream has multiple video streams, this may need to be adjusted.
required: false
type: string
default: '`0:v:0`'
audio_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming audio to HomeKit clients.
required: false
type: integer
default: 188
video_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming video to HomeKit clients.
required: false
type: integer
default: 1316
video_codec:
description: Only for `camera` entities. FFmpeg video codec for transcoding. `copy` option reduces CPU load when video source already encoded with `H264` (MPEG4). `h264_omx` option is only available with custom FFmpeg builds and enables GPU Hardware acceleration on Raspberry Pi.
required: false
type: string
default: libx264
available options: copy, libx264, h264_omx
audio_codec:
description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source already encoded with `libopus`.
required: false
type: string
default: libopus
available options: copy, libopus
homekit:
description: HomeKit configuration.
required: true
type: map
keys:
auto_start:
description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start))
required: false
type: boolean
default: true
port:
description: Port for the HomeKit extension. If you are adding more than one instance they need to have different values for port.
required: false
type: integer
default: 51827
name:
description: Need to be individual for each instance of Home Assistant using the integration on the same local network. Between `3` and `25` characters. Alphanumeric and spaces allowed.
required: false
type: string
default: '`Home Assistant Bridge`'
ip_address:
description: The local network IP address. Only necessary if the default from Home Assistant does not work.
required: false
type: string
mode:
description: HomeKit can expose an entity via a bridge, or a single entity as an accessory which is needed for Television Media Players. ([Accessory mode](#accessory-mode))
required: false
type: string
default: '`bridge`'
advertise_ip:
description: If you need to override the IP address used for mDNS advertisement. (For example, using network isolation in Docker and together with an mDNS forwarder like `avahi-daemon` in reflector mode)
required: false
type: string
filter:
description: Filters for entities to be included/excluded from HomeKit. ([Configure Filter](#configure-filter))
required: false
type: map
keys:
include_domains:
description: Domains to be included.
required: false
type: list
include_entity_globs:
description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`).
required: false
type: list
include_entities:
description: Entities to be included.
required: false
type: list
exclude_domains:
description: Domains to be excluded.
required: false
type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`).
required: false
type: list
exclude_entities:
description: Entities to be excluded.
required: false
type: list
entity_config:
description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g., `alarm_control_panel.alarm`.
required: false
type: map
keys:
'`ENTITY_ID`':
description: Additional options for specific entities.
required: false
type: map
keys:
name:
description: Name of the entity to show in HomeKit. HomeKit will cache the name on the first run so the accessory must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_battery_sensor:
description: The `entity_id` of a `sensor` entity to use as the battery of the accessory. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_doorbell_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the doorbell sensor of the camera accessory to enable doorbell notifications. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_motion_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the motion sensor of the camera accessory to enable motion notifications. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
linked_obstruction_sensor:
description: The `entity_id` of a `binary_sensor` entity to use as the obstruction sensor of the garage door (cover) accessory to enable obstruction state tracking. HomeKit will cache an accessory's feature set on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
low_battery_threshold:
description: Minimum battery level before the accessory starts reporting a low battery.
required: false
type: integer
default: 20
code:
description: Code to `arm / disarm` an alarm or `lock / unlock` a lock. Only applicable for `alarm_control_panel` or `lock` entities.
required: false
type: string
default: '`<No code>`'
feature_list:
description: Only for `media_player` entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema.
required: false
type: list
keys:
feature:
description: Name of the feature to add to the entity representation. Valid features are `on_off`, `play_pause`, `play_stop` and `toggle_mute`. The media_player entity must support the feature to be valid.
required: true
type: string
type:
description: Only for `switch` entities. Type of accessory to be created within HomeKit. Valid types are `faucet`, `outlet`, `shower`, `sprinkler`, `switch` and `valve`. HomeKit will cache the type on the first run so a device must be [reset](#resetting-accessories) for any change to take effect.
required: false
type: string
default: '`switch`'
stream_count:
description: Only for `camera` entities. The number of simultaneous stream the camera can support.
required: false
type: integer
default: 3
stream_address:
description: Only for `camera` entities. The source IP address to use when streaming to RTP clients. If your Home Assistant host has multiple interfaces, selecting a specific IP may be necessary.
required: false
type: string
default: local IP from Home Assistant
stream_source:
description: Only for `camera` entities. A URL, file or other valid FFmpeg input string to use as the stream source, rather than the default camera source. Required for camera entities that do not natively support streaming (MJPEG). If `-i` is not found in the stream source, it is prepended to construct the FFmpeg input.
required: false
type: string
default: stream source from camera entity
support_audio:
description: Only for `camera` entities. Whether the camera supports audio. Audio is disabled unless this flag is set to `True`.
required: false
type: boolean
default: '`False`'
max_width:
description: Only for `camera` entities. Maximum width supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 1920
max_height:
description: Only for `camera` entities. Maximum height supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 1080
max_fps:
description: Only for `camera` entities. Maximum fps supported by camera. Used when generating advertised video resolutions.
required: false
type: integer
default: 30
audio_map:
description: Only for `camera` entities. FFmpeg [stream selection mapping](https://ffmpeg.org/ffmpeg.html#Stream-selection) for the audio-only stream. Selects the first audio stream in the input stream by default. If your input stream has multiple audio streams, this may need to be adjusted.
required: false
type: string
default: '`0:a:0`'
video_map:
description: Only for `camera` entities. FFmpeg [stream selection mapping](https://ffmpeg.org/ffmpeg.html#Stream-selection) for the video-only stream. Selects the first video stream in the input stream by default. If your input stream has multiple video streams, this may need to be adjusted.
required: false
type: string
default: '`0:v:0`'
audio_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming audio to HomeKit clients.
required: false
type: integer
default: 188
video_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming video to HomeKit clients.
required: false
type: integer
default: 1316
video_codec:
description: Only for `camera` entities. FFmpeg video codec for transcoding. `copy` option reduces CPU load when video source already encoded with `H264` (MPEG4). `h264_omx` option is only available with custom FFmpeg builds and enables GPU Hardware acceleration on Raspberry Pi.
required: false
type: string
default: libx264
available options: copy, libx264, h264_omx
audio_codec:
description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source already encoded with `libopus`.
required: false
type: string
default: libopus
available options: copy, libopus
{% endconfiguration %}
## Setup
@ -304,14 +318,14 @@ It is recommended to only edit a HomeKit instance in the UI that was created in
### Accessory mode
When exposing a Camera or Television media player (a `media_player` with device class `tv`) to HomeKit, `mode` must be set to `accessory`, and the include filter should be setup to only include a single entity.
When exposing a Camera or Television media player (a `media_player` with device class `tv`) to HomeKit, `mode` must be set to `accessory`, and the include filter should be setup to only include a single entity.
To quickly add all accessory modes entities in the UI:
1. Create a new bridge via the UI (i.e., **{% my config_flow_start title="Configuration >> Integrations" domain=page.ha_domain %}**).
2. Select `media_player` and `camera` domains.
3. Complete the flow as normal.
4. Additional HomeKit entries for each entity that must operate in accessory mode will be created for each entity that does not already have one.
4. Additional HomeKit entries for each entity that must operate in accessory mode will be created for each entity that does not already have one.
5. If you have already created another HomeKit bridge for the non-accessory mode entities, the new bridge can safely be removed.
6. [Pair each bridge or accessory](#setup).
@ -521,10 +535,6 @@ Pairing works fine when the filter is set to only include `demo.demo`, but fails
1. Make sure that you don't try to add more than 150 accessories, see [device limit](#device-limit). In rare cases, one of your entities doesn't work with the HomeKit component. Use the [filter](#configure-filter) to find out which one. Feel free to open a new issue in the `home-assistant` repository, so we can resolve it.
2. Check logs, and search for `Starting accessory Home Assistant Bridge on address`. Make sure Home Assistant Bridge hook up to a correct interface. If it did not, explicitly set `homekit.ip_address` configuration variable.
#### Duplicate AID found when attempting to add accessory
Two of your entities share the same `entity_id`. Either resolve this or configure the [filter](#configure-filter) to exclude them.
### Issues during normal use
#### Some of my devices don't show up - Z-Wave / Discovery
@ -569,7 +579,6 @@ Media Player entities with `device_class: tv` will show up as Television accesso
The [Universal Media Player](/integrations/universal/#harmony-remote-example) has an example of how it can be used to wrap existing entities to enable them to be used as a Television accessory in HomeKit.
#### Can't control volume of your TV media player?
The volume and play/pause controls will show up on the Remote app or Control Center. If your TV supports volume control through Home Assistant, you will be able to control the volume using the side volume buttons on the device while having the remote selected on screen.