From 915a15dd21b477a87c508bba78b7f8908524c88d Mon Sep 17 00:00:00 2001 From: cdce8p <30130371+cdce8p@users.noreply.github.com> Date: Fri, 19 Oct 2018 01:54:50 +0200 Subject: [PATCH 1/3] Refactor HomeKit doc, add troubleshooting section --- source/_components/homekit.markdown | 93 +++++++++++++++++------------ 1 file changed, 56 insertions(+), 37 deletions(-) diff --git a/source/_components/homekit.markdown b/source/_components/homekit.markdown index 77ec79577f6..5c694d4add6 100644 --- a/source/_components/homekit.markdown +++ b/source/_components/homekit.markdown @@ -12,17 +12,13 @@ ha_release: 0.64 logo: apple-homekit.png --- -The `HomeKit` component allows you to forward entities from Home Assistant to 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. +The `HomeKit` component allows you to forward entities from Home Assistant to 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, checkout the [troubleshooting](#troubleshooting) section.

It might be necessary to install an additional package: `$ sudo apt-get install libavahi-compat-libdnssd-dev`

-

- If you are upgrading Home Assistant from `0.65.x` and have used the HomeKit component, some accessories may not respond or may behave unusually. To fix these problems, you will need to remove the Home Assistant Bridge from your Home, stop Home Assistant and delete the `.homekit.state` file in your configuration folder and follow the Homekit [setup](#setup) steps again. -

- ```yaml # Example configuration.yaml entry configuring HomeKit homekit: @@ -129,9 +125,6 @@ homekit: default: '`switch`' {% endconfiguration %} -

- If you use Z-Wave, or `discovery:` you'll need to disable auto-start, see the [section below](#disable-auto-start) for details on how to do this. You'll then need to start the HomeKit component once Z-Wave is ready, or an appropriate delay to allow your entities to be discovered. -

## {% linkable_title Setup %} @@ -145,17 +138,17 @@ 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: 1. Open the Home Assistant frontend. A new card will display the `pin code`. 1. Open the `Home` app. -2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`. -4. Confirm the you are adding an `Uncertified Accessory` by clicking on `Add Anyway`. -5. Follow the setup be clicking on `Next` and lastly `Done` in the top right hand corner. -6. The `Home Assistant` Bridge and the Accessories should now be listed in the `Home` app. +2. Click `Add Accessory`, than 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. +6. Follow the setup be 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. After the setup is completed you should be able to control your Home Assistant components through `Home` and `Siri`. ## {% linkable_title Considerations %} - ### {% linkable_title Accessory ID %} 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. @@ -280,36 +273,62 @@ The following components are currently supported: | switch | Switch | Represented as a switch by default but can be changed by using `type` within `entity_config`. | -## {% linkable_title Error reporting %} +## {% linkable_title Troubleshooting %} -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. +### {% linkable_title Deleting the `.homekit.state` file %} + +The `.homekit.state` file can be found in the configurations directory. You might need to enable `view hidden files` to see it. + 1. **Stop** Home Assistant + 2. Delete the `.homekit.state` file + 3. **Start** Home Assistant + +### {% linkable_title Errors during pairing %} + +If you encounter any issues during pairing, make sure to + 1. **Stop** Home Assistant + 2. Delete the `.homekit.state` file + 3. Edit your configuration (see below) + 4. **Start** Home Assistant -1. Enable debugging mode: ```yaml logger: default: warning logs: - homeassistant.components.homekit: debug - pyhap: debug -``` -2. Reproduce the bug / problem you have encountered. -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. -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. -5. Fill out all fields and especially include the following information: - - The configuration entries for `homekit` and the `component` that is causing the issue. - - The log / traceback you have generated before. - - Screenshots of the failing entity in the `states` panel. + homeassistant.components.homekit: debug + pyhap: debug -## {% linkable_title Troubleshooting PIN not appearing %} - -In some instances, the PIN will not appear as a persistent status or in the log files despite deleting `.homekit.state`, enabling logging, and reboot. The log files will include the error ```Duplicate AID found when attempting to add accessory```. - -In such cases, modifying your configuration.yaml to add a filter limiting the included entities similar to the following: - -```yaml -filter: - include_domains: - - light +homekit: + filter: + include_entities: + - demo.demo ``` -Restart Home Assistant and re-attempt pairing - a persistent status should now correctly appear. +**PIN doesn't appear as persistent status**
+You might have paired the `Home Assistant Bridge` already. If not, delete the `.homekit.state` file ([guide](#deleting-the-homekitstate-file)). + +**`Home Assistant Bridge` doesn't appear in the Home App (for pairing)**
+For `Docker` users: make sure to set `network_mode: host`. Other reasons could be network related. Make sure to check your router configuration. For some it helped when the Home Assistant device was using WIFI, not LAN. Remember that the iOS device needs to be in the same local network as the Home Assistant device for paring. + +**Pairing hangs - zeroconf error**
+Paining eventually fails, you might see and an error message `NoneUniqueNameException`. To resolve this, you need to replace a specific file. See the following git issues for more details: [home-assistant#14567](https://github.com/home-assistant/home-assistant/issues/14567) and [home-assistant#17181](https://github.com/home-assistant/home-assistant/issues/17181) + +**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. + + +### {% linkable_title Issues during normal use %} + +**Pairing hangs - no error**
+Make sure that you don't try to add more then 100 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` repo, so we can resolve it. + +**Some of my devices don't show up - Z-Wave / Discovery**
+See [disable auto start](#disable-auto-start) + +**Accessory not responding - after restart or update**
+See [device limit](#device-limit) + +**Accessory not responding - randomly**
+Unfortunately that sometimes happens at the moment. It might help to close the `Home` App and delete it from the cache. Usually the accessory should get back to responding after a few minutes at most. + +**Accessories not responding / behaving unusual - Upgrade from `0.65.x`**
+To fix this, you need to unpair the `Home Assistant Bridge`, delete the `.homekit.state` file ([guide](#deleting-the-homekitstate-file)) and pair it again. This should only be an issue if you're upgrading from `0.65.x` or below. From f7d10d3c93ba7d791b2fa4fdc2b8ac34459abaec Mon Sep 17 00:00:00 2001 From: cdce8p <30130371+cdce8p@users.noreply.github.com> Date: Fri, 19 Oct 2018 10:38:48 +0200 Subject: [PATCH 2/3] Fix speeling error --- source/_components/homekit.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_components/homekit.markdown b/source/_components/homekit.markdown index 5c694d4add6..1063a4f38ba 100644 --- a/source/_components/homekit.markdown +++ b/source/_components/homekit.markdown @@ -310,7 +310,7 @@ You might have paired the `Home Assistant Bridge` already. If not, delete the `. For `Docker` users: make sure to set `network_mode: host`. Other reasons could be network related. Make sure to check your router configuration. For some it helped when the Home Assistant device was using WIFI, not LAN. Remember that the iOS device needs to be in the same local network as the Home Assistant device for paring. **Pairing hangs - zeroconf error**
-Paining eventually fails, you might see and an error message `NoneUniqueNameException`. To resolve this, you need to replace a specific file. See the following git issues for more details: [home-assistant#14567](https://github.com/home-assistant/home-assistant/issues/14567) and [home-assistant#17181](https://github.com/home-assistant/home-assistant/issues/17181) +Paining eventually fails, you might see and an error message `NonUniqueNameException`. To resolve this, you need to replace a specific file. See the following git issues for more details: [home-assistant#14567](https://github.com/home-assistant/home-assistant/issues/14567) and [home-assistant#17181](https://github.com/home-assistant/home-assistant/issues/17181) **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. From 8c074f6eea85f5aae420b972d0210422ebcee1ae Mon Sep 17 00:00:00 2001 From: cdce8p <30130371+cdce8p@users.noreply.github.com> Date: Fri, 19 Oct 2018 20:50:30 +0200 Subject: [PATCH 3/3] Added linkable_titles --- source/_components/homekit.markdown | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/_components/homekit.markdown b/source/_components/homekit.markdown index 1063a4f38ba..129463a3b47 100644 --- a/source/_components/homekit.markdown +++ b/source/_components/homekit.markdown @@ -303,32 +303,32 @@ homekit: - demo.demo ``` -**PIN doesn't appear as persistent status**
+#### {% linkable_title PIN doesn't appear as persistent status %} You might have paired the `Home Assistant Bridge` already. If not, delete the `.homekit.state` file ([guide](#deleting-the-homekitstate-file)). -**`Home Assistant Bridge` doesn't appear in the Home App (for pairing)**
+#### {% linkable_title `Home Assistant Bridge` doesn't appear in the Home App (for pairing) %} For `Docker` users: make sure to set `network_mode: host`. Other reasons could be network related. Make sure to check your router configuration. For some it helped when the Home Assistant device was using WIFI, not LAN. Remember that the iOS device needs to be in the same local network as the Home Assistant device for paring. -**Pairing hangs - zeroconf error**
+#### {% linkable_title Pairing hangs - zeroconf error %} Paining eventually fails, you might see and an error message `NonUniqueNameException`. To resolve this, you need to replace a specific file. See the following git issues for more details: [home-assistant#14567](https://github.com/home-assistant/home-assistant/issues/14567) and [home-assistant#17181](https://github.com/home-assistant/home-assistant/issues/17181) -**Duplicate AID found when attempting to add accessory**
+#### {% linkable_title 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. ### {% linkable_title Issues during normal use %} -**Pairing hangs - no error**
+#### {% linkable_title Pairing hangs - no error %} Make sure that you don't try to add more then 100 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` repo, so we can resolve it. -**Some of my devices don't show up - Z-Wave / Discovery**
+#### {% linkable_title Some of my devices don't show up - Z-Wave / Discovery %} See [disable auto start](#disable-auto-start) -**Accessory not responding - after restart or update**
+#### {% linkable_title Accessory not responding - after restart or update %} See [device limit](#device-limit) -**Accessory not responding - randomly**
+#### {% linkable_title Accessory not responding - randomly %} Unfortunately that sometimes happens at the moment. It might help to close the `Home` App and delete it from the cache. Usually the accessory should get back to responding after a few minutes at most. -**Accessories not responding / behaving unusual - Upgrade from `0.65.x`**
+#### {% linkable_title Accessories not responding / behaving unusual - Upgrade from `0.65.x` %} To fix this, you need to unpair the `Home Assistant Bridge`, delete the `.homekit.state` file ([guide](#deleting-the-homekitstate-file)) and pair it again. This should only be an issue if you're upgrading from `0.65.x` or below.