From 9c20af02fac6aa5cf795507d80a2b6ae60efbfe9 Mon Sep 17 00:00:00 2001 From: cdce8p <30130371+cdce8p@users.noreply.github.com> Date: Thu, 15 Mar 2018 03:16:30 +0100 Subject: [PATCH] Homekit: Updated docs for Restructure PR (#4915) * Homekit: Updated docs for Restructure PR * Added considerations * Removed QR Code --- source/_components/homekit.markdown | 147 +++++++++++++++++++++++++--- 1 file changed, 131 insertions(+), 16 deletions(-) diff --git a/source/_components/homekit.markdown b/source/_components/homekit.markdown index ebb4b6ccd44..4ed321f4bb5 100644 --- a/source/_components/homekit.markdown +++ b/source/_components/homekit.markdown @@ -12,7 +12,7 @@ ha_release: 0.64 logo: apple-homekit.png --- -The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. +The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later. {% configuration %} homekit: @@ -20,18 +20,55 @@ The `HomeKit` component allows you to forward entities from Home Assistant to Ap required: true type: map keys: - pincode: - description: Pin code required during setup of HomeKit Home Assistant accessory. The format needs to be 'XXX-XX-XXX' where X is a number between 0 and 9. + 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: string - default: '"123-45-678"' + type: boolean + default: true port: description: Port for the HomeKit extension. required: false type: int - default: 51826 + default: 51827 + filter: + description: Filter entities to available in the `Home` app. ([Configure Filter](#configure-filter)) + required: false + type: map + keys: + include_domains: + description: Domains to be included. + 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_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: + alarm_control_panel: + description: Additional options for `alarm_control_panel` entities. + required: false + type: map + keys: + code: + description: Code to arm or disarm the alarm in the frontend. + required: false + type: string + default: '' {% endconfiguration %} + ## {% linkable_title Setup %} To enable the `HomeKit` component in Home Assistant, add the following to your configuration file: @@ -39,18 +76,78 @@ To enable the `HomeKit` component in Home Assistant, add the following to your c ```yaml # Example for HomeKit setup homekit: - pincode: '123-45-678' ``` -
It is not recommended to choose '123-45-678' as your pin code!
- -After Home Assistant has started, all supported entities (see the [list](#supported-components) below which components are already integrated) will be exposed to `HomeKit`. To add them: -1. Open the `Home` App. -2. Choose `Add Accessory` and then `Don't Have a Code or Can't Scan?`. -3. The `Home Assistant` Bridge should be listed there. Select it and follow the instructions to complete setup. +After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if the 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. 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. + +### {% linkable_title Persistence Storage %} + +Unfortunately `HomeKit` doesn't support any kind of persistence 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.) + +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`. + +This can be automated using an `automation`. + +{% raw %} +```yaml +# Example for Z-Wave +homekit: + auto_start: False + +automation: + - alias: 'Start HomeKit' + trigger: + - platform: event + event_type: zwave.network_ready + action: + - service: homekit.start +``` +{% endraw %} + +{% raw %} +```yaml +# Example using a delay after start of Home Assistant +homekit: + auto_start: False + +automation: + - alias: 'Start HomeKit' + trigger: + - platform: homeassistant + event: start + action: + - delay: 00:05 # Waits 5 minutes + - service: homekit.start +``` +{% endraw %} + + +## {% linkable_title Configure Filter %} + +To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. By default no entity will be excluded. Keep in mind though that only supported components can be added. + + ## {% linkable_title Supported Components %} The following components are currently supported: @@ -59,8 +156,26 @@ The following components are currently supported: | --------- | --------- | ----------- | | alarm_control_panel | SecuritySystem | All security systems. | | climate | Thermostat | All climate devices. | -| cover | Window | All covers that support `set_cover_position`. | +| cover | WindowCovering | All covers that support `set_cover_position`. | | sensor | TemperatureSensor | All sensors that have `Celsius` and `Fahrenheit` as their `unit_of_measurement`. | -| switch/remote | Switch | All switches or remotes (represented as switches). | +| switch / remote | Switch | All switches or remotes (represented as switches). | -Currently only devices that are setup when Home Assistant is starting can be exposed to `HomeKit`. This means that especially `Z-Wave` components are currently not supported, since they will be setup afterwards. We are working on a solution for this problem.
+ +## {% linkable_title Error reporting %} + +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. + +1. Enable debugging mode: +```yaml +logger: + default: warning + logs: + homeassistant.components.homekit: 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.