jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-12 20:06:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Tweaks to HomeKit documentation (#16875)

Browse Source
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
1 changed files with 237 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

461
source/_integrations/homekit.markdown
View File

@ -12,241 +12,255 @@ ha_codeowners:
ha_zeroconf: true 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"> <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> </div>
{% include integrations/config_flow.md %} {% 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 # Example configuration.yaml entry configuring HomeKit
homekit: homekit:
- filter: - filter:
include_domains: include_domains:
- alarm_control_panel - alarm_control_panel
- light - light
- media_player - media_player
include_entity_globs: include_entity_globs:
- binary_sensor.*_occupancy - binary_sensor.*_occupancy
include_entities: include_entities:
- binary_sensor.living_room_motion - binary_sensor.living_room_motion
entity_config: entity_config:
alarm_control_panel.home: alarm_control_panel.home:
code: 1234 code: 1234
binary_sensor.living_room_motion: binary_sensor.living_room_motion:
linked_battery_sensor: sensor.living_room_motion_battery linked_battery_sensor: sensor.living_room_motion_battery
low_battery_threshold: 31 low_battery_threshold: 31
light.kitchen_table: light.kitchen_table:
name: Kitchen Table Light name: "Kitchen Table Light"
lock.front_door: lock.front_door:
code: 1234 code: 1234
media_player.living_room: media_player.living_room:
feature_list: feature_list:
- feature: on_off - feature: on_off
- feature: play_pause - feature: play_pause
- feature: play_stop - feature: play_stop
- feature: toggle_mute - feature: toggle_mute
switch.bedroom_outlet: switch.bedroom_outlet:
type: outlet type: outlet
camera.back_porch: camera.back_porch:
support_audio: True support_audio: true
- name: HASS Bridge 2 - name: "HASS Bridge 2"
port: 56332 port: 56332
filter: filter:
include_domains: include_domains:
- light - light
``` ```
{% configuration %} {% configuration %}
homekit: homekit:
description: HomeKit configuration. description: HomeKit configuration.
required: true required: true
type: map type: map
keys: keys:
auto_start: 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)) 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 required: false
type: boolean type: boolean
default: true default: true
port: port:
description: Port for the HomeKit extension. If you are adding more than one instance they need to have different values for 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 required: false
type: integer type: integer
default: 51827 default: 51827
name: 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. 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 required: false
type: string type: string
default: '`Home Assistant Bridge`' default: '`Home Assistant Bridge`'
ip_address: ip_address:
description: The local network IP address. Only necessary if the default from Home Assistant does not work. description: The local network IP address. Only necessary if the default from Home Assistant does not work.
required: false required: false
type: string type: string
mode: 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)) 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 required: false
type: string type: string
default: '`bridge`' default: '`bridge`'
advertise_ip: 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) 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 required: false
type: string type: string
filter: filter:
description: Filters for entities to be included/excluded from HomeKit. ([Configure Filter](#configure-filter)) description: Filters for entities to be included/excluded from HomeKit. ([Configure Filter](#configure-filter))
required: false required: false
type: map type: map
keys: keys:
include_domains: include_domains:
description: Domains to be included. description: Domains to be included.
required: false required: false
type: list type: list
include_entity_globs: include_entity_globs:
description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`). description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`).
required: false required: false
type: list type: list
include_entities: include_entities:
description: Entities to be included. description: Entities to be included.
required: false required: false
type: list type: list
exclude_domains: exclude_domains:
description: Domains to be excluded. description: Domains to be excluded.
required: false required: false
type: list type: list
exclude_entity_globs: exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`). description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`).
required: false required: false
type: list type: list
exclude_entities: exclude_entities:
description: Entities to be excluded. description: Entities to be excluded.
required: false required: false
type: list type: list
entity_config: entity_config:
description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g., `alarm_control_panel.alarm`. description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g., `alarm_control_panel.alarm`.
required: false required: false
type: map type: map
keys: keys:
'`ENTITY_ID`': '`ENTITY_ID`':
description: Additional options for specific entities. description: Additional options for specific entities.
required: false required: false
type: map type: map
keys: keys:
name: 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. 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 required: false
type: string type: string
linked_battery_sensor: 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. 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 required: false
type: string type: string
linked_doorbell_sensor: 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. 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 required: false
type: string type: string
linked_motion_sensor: 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. 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 required: false
type: string type: string
linked_obstruction_sensor: 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. 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 required: false
type: string type: string
low_battery_threshold: low_battery_threshold:
description: Minimum battery level before the accessory starts reporting a low battery. description: Minimum battery level before the accessory starts reporting a low battery.
required: false required: false
type: integer type: integer
default: 20 default: 20
code: code:
description: Code to `arm / disarm` an alarm or `lock / unlock` a lock. Only applicable for `alarm_control_panel` or `lock` entities. description: Code to `arm / disarm` an alarm or `lock / unlock` a lock. Only applicable for `alarm_control_panel` or `lock` entities.
required: false required: false
type: string type: string
default: '`<No code>`' default: '`<No code>`'
feature_list: feature_list:
description: Only for `media_player` entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema. description: Only for `media_player` entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema.
required: false required: false
type: list type: list
keys: keys:
feature: 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. 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 required: true
type: string type: string
type: 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. 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 required: false
type: string type: string
default: '`switch`' default: '`switch`'
stream_count: stream_count:
description: Only for `camera` entities. The number of simultaneous stream the camera can support. description: Only for `camera` entities. The number of simultaneous stream the camera can support.
required: false required: false
type: integer type: integer
default: 3 default: 3
stream_address: 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. 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 required: false
type: string type: string
default: local IP from Home Assistant default: local IP from Home Assistant
stream_source: 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. 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 required: false
type: string type: string
default: stream source from camera entity default: stream source from camera entity
support_audio: support_audio:
description: Only for `camera` entities. Whether the camera supports audio. Audio is disabled unless this flag is set to `True`. description: Only for `camera` entities. Whether the camera supports audio. Audio is disabled unless this flag is set to `True`.
required: false required: false
type: boolean type: boolean
default: '`False`' default: '`False`'
max_width: max_width:
description: Only for `camera` entities. Maximum width supported by camera. Used when generating advertised video resolutions. description: Only for `camera` entities. Maximum width supported by camera. Used when generating advertised video resolutions.
required: false required: false
type: integer type: integer
default: 1920 default: 1920
max_height: max_height:
description: Only for `camera` entities. Maximum height supported by camera. Used when generating advertised video resolutions. description: Only for `camera` entities. Maximum height supported by camera. Used when generating advertised video resolutions.
required: false required: false
type: integer type: integer
default: 1080 default: 1080
max_fps: max_fps:
description: Only for `camera` entities. Maximum fps supported by camera. Used when generating advertised video resolutions. description: Only for `camera` entities. Maximum fps supported by camera. Used when generating advertised video resolutions.
required: false required: false
type: integer type: integer
default: 30 default: 30
audio_map: 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. 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 required: false
type: string type: string
default: '`0:a:0`' default: '`0:a:0`'
video_map: 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. 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 required: false
type: string type: string
default: '`0:v:0`' default: '`0:v:0`'
audio_packet_size: audio_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming audio to HomeKit clients. description: Only for `camera` entities. RTP packet size used for streaming audio to HomeKit clients.
required: false required: false
type: integer type: integer
default: 188 default: 188
video_packet_size: video_packet_size:
description: Only for `camera` entities. RTP packet size used for streaming video to HomeKit clients. description: Only for `camera` entities. RTP packet size used for streaming video to HomeKit clients.
required: false required: false
type: integer type: integer
default: 1316 default: 1316
video_codec: 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. 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 required: false
type: string type: string
default: libx264 default: libx264
available options: copy, libx264, h264_omx available options: copy, libx264, h264_omx
audio_codec: audio_codec:
description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source already encoded with `libopus`. description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source already encoded with `libopus`.
required: false required: false
type: string type: string
default: libopus default: libopus
available options: copy, libopus available options: copy, libopus
{% endconfiguration %} {% endconfiguration %}
## Setup ## 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. 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. 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 ### Issues during normal use
#### Some of my devices don't show up - Z-Wave / Discovery #### 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. 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? #### 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. 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.