From 5184b418bf97336bccd5074849160917e867da9e Mon Sep 17 00:00:00 2001 From: Lindsay Ward Date: Mon, 1 Nov 2021 17:29:45 +1000 Subject: [PATCH] Improve wording for HomeKit (#20096) Co-authored-by: Franck Nijhof --- source/_integrations/homekit.markdown | 70 +++++++++++++-------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index 6e8497908bb..94229cdc5f7 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -14,17 +14,17 @@ 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. +so they can be controlled from Apple's Home app and Siri; even if those devices do not natively support HomeKit. 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 +some trouble later. However, if you do encounter issues, check out the [troubleshooting](#troubleshooting) section.
- 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. + If you want to control HomeKit-only devices with Home Assistant, + check out the [HomeKit controller](/integrations/homekit_controller/) integration, + which provides the possibility to pull HomeKit-enabled devices into Home Assistant.
@@ -34,8 +34,8 @@ some trouble later. However if you do encounter issues, check out the 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. +IP address the HomeKit uses to advertise itself to the network, then you will need to configure the +HomeKit integration using an entry in your `configuration.yaml` file. This is an example entry of how that would look: @@ -90,7 +90,7 @@ homekit: type: integer default: 21063 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: Needs to be unique 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`' @@ -137,7 +137,7 @@ homekit: 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`. + description: Configuration for specific entities. All subordinate keys are the corresponding entity ids of the domains, e.g., `alarm_control_panel.alarm`. required: false type: map keys: @@ -191,7 +191,7 @@ homekit: type: string default: '`switch`' 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 streams the camera can support. required: false type: integer default: 3 @@ -221,7 +221,7 @@ homekit: type: integer default: 1080 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 (frames per second) supported by camera. Used when generating advertised video resolutions. required: false type: integer default: 30 @@ -272,15 +272,15 @@ To enable the HomeKit integration in Home Assistant, add the following to your c homekit: ``` -After Home Assistant has started, the entities specified by the filter are exposed to HomeKit if they are [supported](#supported-components). To add them: +After Home Assistant has started, the entities (depending on the filter) are exposed to HomeKit if they are [supported](#supported-components). To add them: 1. Open the Home Assistant frontend. A new card will display the pairing QR code and the `pin code` as seen in the example below. Note: If pin code is not displayed, check "Notifications" (the bell icon) in the lower-left of the Home Assistant UI. -2. Open the `Home` app. +2. Open the Apple `Home` app. 3. Click `Add Accessory`, then scan the QR code or select `Don't Have a Code or Can't Scan?` and choose the `Home Assistant Bridge`. 4. Confirm that you are adding an `Uncertified Accessory` by clicking on `Add Anyway`. 5. Enter the `PIN` code (skip this step if you scanned the QR code). 6. Follow the setup by clicking on `Next` and lastly `Done` in the top right-hand corner. -7. The `Home Assistant` Bridge and the Accessories should now be listed in the `Home` app. +7. The `Home Assistant Bridge` and the Accessories should now be listed in the `Home` app. After the setup is completed, you should be able to control your Home Assistant integrations through Apple's Home and Siri. @@ -290,7 +290,7 @@ After the setup is completed, you should be able to control your Home Assistant ## Move Home Assistant install -If you like to retain your HomeKit pairing through a move to a new Home Assistant device or installation, besides copying the configurations files you need to copy the `.storage/homekit.*` file inside your configurations directory. Keep in mind though that the file is usually hidden by default, depending on your operating system. +If you would like to retain your HomeKit pairing when moving to a new Home Assistant device or installation, besides copying the configuration files you also need to copy the `.storage/homekit.*` file inside your configuration directory. Keep in mind that the folder is usually hidden by default, depending on your operating system. Before you copy it, make sure to stop the old and new Home Assistant instances first entirely, otherwise it won't work. @@ -312,9 +312,9 @@ It is recommended to only edit a HomeKit instance in the UI that was created in ### Accessory mode -When exposing a Camera, Activity based remote (a `remote` that supports activities), Lock, 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, Activity based remote (a `remote` that supports activities), Lock, or Television media player (a `media_player` with device class `tv`) to HomeKit, `mode` must be set to `accessory`, and the relevant `include` filter should be setup to only include a single entity. -To quickly add all accessory modes entities in the UI: +To quickly add all accessory mode 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`, `remote`, `lock`, and `camera` domains. @@ -371,7 +371,7 @@ Filters are applied as follows: The `advertise_ip` option can be used to run this integration even inside an ephemeral Docker container with network isolation enabled, e.g., not using the host network. -You may also need to set `default_interface` to `true` in the `zeroconf` integration. +You may need to set the default network interfaces Home Assistant uses, in its [network configuration](/integrations/network). To use `advertise_ip`, add the option to your `homekit` configuration: @@ -427,17 +427,17 @@ The following integrations are currently supported: Devices that support triggers can be added to the bridge by accessing options for the bridge in **{% my integrations title="Configuration >> Integrations" %}**. -Bridged device triggers are represented as a single press button on stateless programmable switches. This allows a HomeKit automation to run when a device trigger fires. Because the iOS Home app currently only shows the number of the button and not the name, users may find it easier to identify the name of the button in the `Eve for HomeKit` app. +Bridged device triggers are represented as a single press button on stateless programmable switches. This allows a HomeKit automation to run when a device trigger fires. Because the Apple Home app currently only shows the number of the button and not the name, users may find it easier to identify the name of the button in the `Eve for HomeKit` app. ## iOS Remote Widget Entities exposed as `TelevisionMediaPlayer` are controllable within the Apple Remote widget in Control Center. Play, pause, volume up and volume down should work out of the box depending on the `supported_features` -of the entity. However, if your television can be controlled in other ways outside of the `media_player` entity, (i.e. +of the entity. However, if your television can be controlled in other ways outside of the `media_player` entity, (e.g., service calls to an IR blaster), it is possible to build an automation to take advantage of these events. When a key is pressed within the Control Center Remote widget, the event `homekit_tv_remote_key_pressed` will be fired. -The key name will be available in the event data in the `key_name` field: +The key name will be available in the event data in the `key_name` field. Example: ```yaml automation: @@ -466,11 +466,11 @@ The following home hubs showed strong results when testing with 400 accessories: - HomePod - HomePod Mini -- Apple TV 4k Gen 2 (best results when using ethernet instead of WiFi) +- Apple TV 4k Gen 2 (best results when using Ethernet instead of Wi-Fi) The following home hubs showed strong results when testing with 300 accessories: -- Apple TV 4k Gen 1 (best results when using ethernet instead of WiFi) +- Apple TV 4k Gen 1 (best results when using ethernet instead of Wi-Fi) The following home hubs have been reported to have trouble with a large number of accessories: @@ -492,7 +492,7 @@ The following home hubs have been reported to have trouble with a large number o ### Errors during pairing -If you encounter any issues during pairing, make sure to add the following to your `configuration.yaml` +If you encounter any issues during pairing, make sure to add the following to your `configuration.yaml` to try and identify the issue(s). ```yaml logger: @@ -502,11 +502,11 @@ logger: pyhap: debug ``` -Follow the above instructions for `Resetting` +Follow the above instructions for resetting. ### Minimal Configuration -If pairing still fails after trying the steps in ([Errors during pairing](#errors-during-pairing)), it may be caused by a specific entity. Try resetting with a minimal configuration: +If pairing still fails after trying the steps in ([Errors during pairing](#errors-during-pairing)), it may be caused by a specific entity. Try resetting with a minimal configuration like: ```yaml homekit: @@ -517,7 +517,7 @@ homekit: #### PIN doesn't appear as persistent status -You might have paired the `Home Assistant Bridge` already. If not, follow the above instructions for `Resetting` +You might have paired the `Home Assistant Bridge` already. If not, follow the above instructions for resetting. #### `Home Assistant Bridge` doesn't appear in the Home App (for pairing) @@ -541,7 +541,7 @@ Configure the network mode as `networkbridge`. Otherwise the Home Assistant Brid #### Pairing hangs - zeroconf error -Pairing eventually fails, you might see and an error message `NonUniqueNameException`, you likely need to enable `default_interface: true` in the `zeroconf` integration configuration and set a unique name such as `name: MyHASS42`. +Pairing eventually fails, you might see the error message, `NonUniqueNameException`, you likely need to enable `default_interface: true` in the `zeroconf` integration configuration and set a unique name such as `name: MyHASS42`. If you had previously paired (even unsuccessfully), you may need to delete your `.homekit.state` file in order to able to successfully pair again. See [Errors during pairing](#errors-during-pairing). @@ -552,7 +552,7 @@ Pairing works fine when the filter is set to only include `demo.demo`, but fails #### Pairing hangs - no error 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 connected to a correct interface. If it did not, explicitly set `homekit.ip_address` configuration variable. ### Issues during normal use @@ -562,17 +562,17 @@ Check if the domain of your entity is [supported](#supported-components). If it #### HomeKit doesn't work on second Home Assistant instance -To use the HomeKit integration with two different Home Assistant instances on the same local network, you need to set a custom name for at least one of them. [config/name](#name) +To use the HomeKit integration with multiple different Home Assistant instances on the same local network, you need to set a custom name for at least one of them. [config/name](#name) #### Specific entity doesn't work -Although we try our best, some entities don't work with the HomeKit integration yet. The result will be that either pairing fails completely or all Home Assistant accessories will stop working. Use the filter to identify which entity is causing the issue. It's best to try pairing and step by step including more entities. If it works unpair and repeat until you find the one that is causing the issues. To help others and the developers, please open a new issue here: [home-assistant/issues/new](https://github.com/home-assistant/home-assistant/issues/new?labels=component:%20homekit) +Although we try our best, some entities don't work with the HomeKit integration yet. The result will be that either pairing fails completely or all Home Assistant accessories will stop working. Use the filter to identify which entity is causing the issue. It's best to try pairing and step by step including more entities. If it works, unpair and repeat until you find the one that is causing the issues. To help others and the developers, please open a new issue here: [home-assistant/issues/new](https://github.com/home-assistant/home-assistant/issues/new?labels=component:%20homekit) If you have any iOS 12.x devices signed into your iCloud account, media player entities with `device_class: tv` may trigger this condition. Filtering the entity or signing the iOS 12.x device out of iCloud should resolve the issue after restarting other devices. #### Accessories are all listed as not responding -There are reports where the IGMP settings in a router were causing issues with HomeKit. This resulted in a situation where all of the Home Assistant HomeKit accessories stopped responding a few minutes after Home Assistant (re)started. Double check your router's IGMP settings if you experiencing this issue. The default IGMP settings typically work best. +There were reports where the IGMP settings in a router were causing issues with HomeKit. This resulted in a situation where all of the Home Assistant HomeKit accessories stopped responding a few minutes after Home Assistant (re)started. Double check your router's IGMP settings if you experience this issue. The default IGMP settings typically work best. See [specific entity doesn't work](#specific-entity-doesnt-work) @@ -598,9 +598,9 @@ The volume and play/pause controls will show up on the Remote app or Control Cen Ensure that the [`ffmpeg`](/integrations/ffmpeg) integration is configured correctly. Verify that your stream is directly playable with `ffplay ` or [VLC Media Player](https://www.videolan.org/). If you have changed your camera's entity configuration, you may need to [reset the accessory](#resetting-accessories). -#### Cameras streaming is unstable or slow +#### Camera streaming is unstable or slow -If your camera supports native H.264 streams, Home Assistant can avoid converting the video stream, which is an expensive operation. To enable native H.264 streaming when configured via YAML, change the `video_codec` to `copy`. To allow native H.264 streaming when via the UI, go to **Configuration** >> **Integrations** in the UI, click **Options** for your HomeKit Bridge, and check the box for your camera on the `Cameras that support native H.264 streams` screen. +If your camera supports native H.264 streams, Home Assistant can avoid converting the video stream, which is an expensive operation. To enable native H.264 streaming when configured via YAML, change the `video_codec` to `copy`. To allow native H.264 streaming when setting up HomeKit via the UI, go to **Configuration** >> **Integrations** in the UI, click **Options** for your HomeKit Bridge, and check the box for your camera on the `Cameras that support native H.264 streams` screen. #### Multiple camera streams @@ -624,7 +624,7 @@ HomeKit camera snapshots tie up the HomeKit connection during snapshots. To avoi #### Resetting accessories -You may use the service `homekit.reset_accessory` with one or more entity_ids to reset accessories whose configuration may have changed. This can be useful when changing a media_player's device class to `tv`, linking a battery, or whenever Home Assistant adds support for new HomeKit features to existing entities. +You may use the service `homekit.reset_accessory` with one or more entity IDs to reset accessories whose configuration may have changed. This can be useful when changing a media player's device class to `tv`, linking a battery, or whenever Home Assistant adds support for new HomeKit features to existing entities. On earlier versions of Home Assistant, you can reset accessories by removing the entity from HomeKit (via [filter](#configure-filter)) and then re-adding the accessory.