mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-14 12:56:54 +00:00
HomeKit doc improvements (#7515)
* HomeKit improvements
* Bugfix
* Added move install section
* Added additional troubleshooting notes
* ✏️ Spelling & grammar
This commit is contained in:
cdce8p
Franck Nijhof
parent
c0573af717
commit
78c11cf7bf
@ -105,7 +105,7 @@ homekit:
|
||||
type: map
|
||||
keys:
|
||||
name:
|
||||
description: Name of entity to show in HomeKit. HomeKit will cache the name on the first run so a device must be removed and then re-added 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 a device must be removed and then re-added for any change to take effect.
|
||||
required: false
|
||||
type: string
|
||||
code:
|
||||
@ -142,20 +142,25 @@ 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. Click `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and choose the `Home Assistant Bridge`.
|
||||
2. Click `Add Accessory`, then 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.
|
||||
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.
|
||||
|
||||
After the setup is completed you should be able to control your Home Assistant components through `Home` and `Siri`.
|
||||
After the setup is completed, you should be able to control your Home Assistant components through `Home` and `Siri`.
|
||||
|
||||
## {% linkable_title 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 `.homekit.state` file inside your configurations directory. Keep in mind though that the file 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.
|
||||
|
||||
## {% 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.
|
||||
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.
|
||||
|
||||
### {% linkable_title Device Limit %}
|
||||
|
||||
@ -163,19 +168,18 @@ The HomeKit guidelines only allow a maximum of 100 unique accessories (`aid`) pe
|
||||
|
||||
### {% linkable_title Persistence Storage %}
|
||||
|
||||
Unfortunately `HomeKit` doesn't support any kind of persistent 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.)
|
||||
Unfortunately `HomeKit` doesn't support any persistent 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 set up, their config will be deleted. (State unknown or similar will not cause any issues.)
|
||||
|
||||
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).
|
||||
|
||||
|
||||
## {% linkable_title Disable Auto Start %}
|
||||
|
||||
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`.
|
||||
Depending on your setup, it might be necessary to disable `Auto Start` for all accessories to be available for `HomeKit`. Only those entities that are fully set up when the `HomeKit` component is started, can be added. To start `HomeKit` when `auto_start: False`, you can call the service `homekit.start`.
|
||||
|
||||
If you have Z-Wave entities you want exposed to HomeKit then you'll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won't be fully set up until then. This can be automated using an automation.
|
||||
If you have Z-Wave entities you want to be exposed to HomeKit, then you'll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won't be fully set up until then. This can be automated using an automation.
|
||||
|
||||
<p class='note'
|
||||
Please remember that [as explained here][devices] you can only have a single `automation:` entry. Add the automation to your existing automations, or use `automation homekit:`
|
||||
<p class='note'>
|
||||
Please remember that you can only have a single `automation` entry. Add the automation to your existing automations.
|
||||
</p>
|
||||
|
||||
{% raw %}
|
||||
@ -202,7 +206,7 @@ For a general delay where your component doesn't generate an event, you can also
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
# Example using a delay after start of Home Assistant
|
||||
# Example using a delay after the start of Home Assistant
|
||||
homekit:
|
||||
auto_start: False
|
||||
|
||||
@ -217,10 +221,9 @@ automation:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
## {% linkable_title Configure Filter %}
|
||||
|
||||
By default no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added.
|
||||
By default, no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added.
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
@ -252,7 +255,6 @@ Filters are applied as follows:
|
||||
- if entity is included, pass (as #2 above)
|
||||
- if entity include and exclude, the entity exclude is ignored
|
||||
|
||||
|
||||
## {% linkable_title Supported Components %}
|
||||
|
||||
The following components are currently supported:
|
||||
@ -281,7 +283,6 @@ The following components are currently supported:
|
||||
| switch | Switch | Represented as a switch by default but can be changed by using `type` within `entity_config`. |
|
||||
| water_heater | WaterHeater | All water_heater devices. |
|
||||
|
||||
|
||||
## {% linkable_title Troubleshooting %}
|
||||
|
||||
### {% linkable_title Deleting the `.homekit.state` file %}
|
||||
@ -313,48 +314,72 @@ homekit:
|
||||
```
|
||||
|
||||
#### {% 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)).
|
||||
|
||||
#### {% 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.
|
||||
|
||||
This is often setup and network related. Make sure to check the other issues below as well, but things that might work include:
|
||||
- Check your router configuration
|
||||
- Try with WIFI **and** LAN
|
||||
- Change the default [port](#port)
|
||||
|
||||
Remember that the iOS device needs to be in the same local network as the Home Assistant device for paring.
|
||||
|
||||
#### {% linkable_title `Home Assistant Bridge` doesn't appear in the Home App (for pairing) - Docker %}
|
||||
|
||||
Set `network_mode: host`. If you have further problems this [issue](https://github.com/home-assistant/home-assistant/issues/15692) might help.
|
||||
|
||||
#### {% linkable_title `Home Assistant Bridge` doesn't appear in the Home App (for pairing) - VirtualBox %}
|
||||
|
||||
Configure the network mode as `networkbridge`. Otherwise the Home Assistant Bridge won't be exposed to the network.
|
||||
|
||||
#### {% 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)
|
||||
|
||||
#### {% linkable_title Pairing hangs - only works with debug config %}
|
||||
|
||||
Pairing works fine when the filter is set to only include `demo.demo`, but fails with normal config. See [specific entity doesn't work](#specific-entity-doesnt-work)
|
||||
|
||||
#### {% 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 Pairing hangs - no error %}
|
||||
|
||||
Make sure that you don't try to add more than 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.
|
||||
|
||||
#### {% 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 %}
|
||||
|
||||
#### {% 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.
|
||||
|
||||
#### {% linkable_title Some of my devices don't show up - Z-Wave / Discovery %}
|
||||
|
||||
See [disable auto start](#disable-auto-start)
|
||||
|
||||
#### {% linkable_title My entity doesn't show up %}
|
||||
|
||||
Check if the domain of your entity is [supported](#supported-components). If it is, check your [filter](#configure-filter) settings. Make sure the spelling is correct, especially if you use `include_entities`.
|
||||
|
||||
#### {% linkable_title HomeKit doesn't work on second Home Assistant instance %}
|
||||
|
||||
To use the HomeKit component with to 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)
|
||||
|
||||
#### {% linkable_title Specific entity doesn't work %}
|
||||
|
||||
Although we try our best, some entities don't work with the HomeKit component 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: homekit)
|
||||
|
||||
#### {% linkable_title Accessories are all listed as not responding %}
|
||||
|
||||
See [specific entity doesn't work](#specific-entity-doesnt-work)
|
||||
|
||||
#### {% linkable_title Accessory not responding - after restart or update %}
|
||||
|
||||
See [device limit](#device-limit)
|
||||
|
||||
#### {% 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.
|
||||
|
||||
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.
|
||||
|
||||
#### {% 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.
|
||||
|
||||
[devices]: https://www.home-assistant.io/docs/configuration/devices/
|
||||
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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user