Components Home Assistant (Apple) "HomeKit"

8 minutes of reading
Proconductor: Home Assistant Community
Availability: included in thepersonale HUB Home Assistant
Category: software
Type: components Home Assistant
Implementation difficulties: low
Card revision: 1.1

The "HomeKit" component (understood as Appthe HomeKit) of Home Assistant serves to expose the entity present in configuration Home Assistant towards'app"House" indication of Appthe iOS /macOS.Appthe Logo

In practice, users Apple and no want use theapp mobile of Home Assistant and want to use it instead (or side by side, why not) 'sapp "House of Apple to check the profirst home automation based on Home Assistant others must not do that configure this component.

Practically, it is like Home Assistant become a BRIDGE/Gateway compatible with Appthe HomeKits.

Automatically - after an initial, simple procedura - theapp "Home" will inherit all entities (lights, switches, climate systems, etc.) configured at Home Assistant. Any action carried out by others (or by automatisms in being) to the states of these entities will be reflected on the states at theapp "Home", and vice versa.
If for example we turned on a light means Home Assistant, that element appit will light up immediately also onapp "Home", and vice versa.

The exportable entities towards Appthe "House" they are different: can be integers of (eg "all lights") or entities single (eg "kitchen light"). It is also possible to selectively configure what to exhibit and what not.

Questo componente it is particularly useful to those who own a smart speaker Appthe HomePod and want to check the profirst home automation based on Home Assistant with the voice assistant Siri (or device that still has this assistant, see iPhone / iPad or macOS latest versions). Once the entities have been exposed Home Assistant to Appthe HomeKits, in fact, Siri will automatically be able to "see" them and govern them.
We have dedicated this specific theme un FOCUS specific.

ATTENTION. This component it is not to be confused with the component "iOS", Which serves a completely different purpose, namely to ensure that theapp "Home Assistant" for Appthe iOS manage to connect properly to our Home Assistant and offer him the proyour functionality (define a "Device Tracker, notifications push etc).

ATTENTION. This component it is not to be confused not even with the component "HomeKit controller support", Which serves to ensure that Home Assistant automatically recognize any compatible devices Appthe HomeKits and “get them propri ”, thus allowing them to register and check them.


Basic requirements

For users of Home Assistant installed on Raspberry in mode Raspbian +Home Assistant o HASSBIAN additional library installation may be required Avahi for compatibility with the service Apple Bonjour.

For installation, execute the command:

sudo apt-get install libavahi-compat-libdnssd-dev

Distribution users HASSIO they do not need any additional installation.


To enable the functions of the component "HomeKit"It is sufficient to add, in the configuration di Home Assistant, the following minimal block:


After restarting Home Assistant, at the web frontend appa box containing the PIN dedicated to Appthe HomeKits:

Home Assistant - HomeKit Code

Now open theapp"Home" iOS and press "Add accessory"
Then press on “I don't have a code" and subsequently "Enter code"

You will be asked to enter the code above; insert it, then wait: at the end of the procedura, le entity (at least, those eligible) of Home Assistant appthey will be listed and controlled at “Houses"

Component customization

The component provides various fields to customize the exposure (as well as filtering) of the entities to HomeKit.

autostart(Boolean, optional) Set up integration with HomeKit as automatic when starting Home Assistant (default: true)
port(integer, optional) Defines the port tcp/ip on which to operate the BRIDGE to HomeKit (default: 51827)
name(string, optional) Defines the name of the BRIDGE at theapp Appthe "House" (default: "Home Assistant Bridge"). The minimum number of characters is 3, the maximum 25.
ip_address(string, optional) Specifies which IP to use (in case the device it hosts Home Assistant have multiple interfaces / IPs) for integration
safe_mode(boolean, optional) Set to "true" in case of proproblems during pairing con theapp Appthe "House" (default: false)
filter(mappa, optional) Defines which entities and / or domains to include / exclude from exposure to HomeKit. In the absence of this block, Home Assistant exposes all that is eligible.

include_domains(list, optional) Lists the domains to be included
include_entities(list, optional) Lists the entities to be included
exclude_domains(list, optional) Lists the domains to be excluded
excude_entites(list, optional) Lists the entities to be excluded
entity_config(mappa, optional) Defines customizations of individual entities towards HomeKit. Every nome_entità allows one propria personalization (eg light.cucina)

name(string, optional) The name of the entity at theapp Appthe "House"
code(string, optional) The code to arm / disarm an alarm or open / close a lock. Apponly eligible for "Alarm Control Panel" and "Lock" type entities (default: no code)
feature_list(list, optional) Valid only for type entities "Media Player". The list may contain only elements provided in the platform in use (eg. "Broalink IR Media Player"Used for domotizing TV, Hi-Fi systems etc.)

feature(string, request) Name of the feature available for the entity being customized. Valid examples are "on_off","play_pause" etc.
type(string, optional) Specifies the type of accessory to be submitted to Appthe "Casa" in case the starting entity is type "Switch". Valid types are "faucet", "outlet", "shower", "sprinkler", "switch" and "valve".

HomeKit caches this proproperty, so if this configuration is changed, so that it takes effect at Appthe "Houses" it is necessary to remove the integration (the BRIDGE) and put it back.

Various considerations


The component uses the ID entity presso Home Assistant to generate a corresponding accessory ID at HomeKit to which all customizations can be associated. It goes without saying that a change in the entity ID will make you lose to Home Assistant the customizations previously assigned to him by appto go to HomeKit.


HomeKit accepts up to 100 accessories for BRIDGE. Important thing to keep in mind when you do prosee to configure the inclusions and exclusions of the domains / entities in configuration.


Unfortunately HomeKit does not present persistent storage, which means that if at start up Home Assistant certain entities are not yet proto use (perhaps a given integration is still starting / taking stock of the components), the corresponding entities at Appthe "House" disappear.

To avoid this it is advised to disable the auto-start and configure the automations to start the "HomeKit" component only when it is actually the time.

Turn off auto-start

As explained, it could be useful to disable the auto-start of this component:

  auto_start: False

To start the component later you can use the service "homekit.start"

Let's take the example of having some entity based on integration Z-Wave which, as long as the integration is not actually working, require us not to start "HomeKit".

A useful automation for this purpose could be the following:

  - alias: 'Avvio HomeKit al momento giusto'
      - platform: event
        event_type: zwave.network_ready
      - platform: event
        event_type: zwave.network_complete
      - platform: event
        event_type: zwave.network_complete_some_dead
      - service: homekit.start

As can be seen, it is expected that all events related to the launch of Z-Ware will be completed to start, subsequently, “HomeKit”.

It could also simply be useful to start it after a set time:

  - alias: 'Avvio temporizzato di HomeKit'
      - platform: homeassistant
        event: start
      - delay: 00:05  # Attende cinque minuti
      - service: homekit.start

Filter configuration

As anticipated, in the absence of filters Home Assistant (in case of activation of this component) it does not set any limits and exposes any entity towards HomeKit.

An example of a configuration type:

      - alarm_control_panel
      - light
      - light.cucina

In this case are included all the possible "Alarm Control Panel" (alarm systems) and all the lights; it is excluded instead a single light, that of the kitchen.

Supported domains / entities are the following:

alarm_control_panelSecurity systemsAll security systems.
automation / input_boolean / remote / scene / scriptSwitchesAll components rappmade as on / off switches.
binary_sensorSensoriSupports type devices "co2","door","garage_door","gas","moisture","motion","occupancy","opening","smoke" and "window". Anything else falls into the type "occupancy"
climateThermostatsAll climate type entities.
coverGarage door openingAll closures that support "open" and "close"And have"garage"That"device_class"Associated.
Darks finestraAll the axes that support "set_cover_position"
All the axes that support "open_cover" and "close_cover”Through mapping of values ​​(open> = 50, closed <50).
All the axes that support "open_cover","stop_cover" and "close_cover”Through mapping of values ​​(open> 70, closed <30, stop any value in the interval).
device_trackerSensoriSupport for i device of type "occupancy"
fanFans / fansSupport for "on/off","direction" and "oscillating"
lightLuciSupport for "on/off","brightness" and "rgb_color"
lockLocksSupport for "lock" and "unlock"
media_playerMediaPlayerRappshown as a series of switches which support "on/off","play/pause","play/stop","mute"Based on"supported_features"And the lists"mode”Provided for the specific entity.
sensorSensori of temperatureAll the thermal sensors they have Celsius and / or Fahrenheit as a unit of measurement.
Sensori of humidityAll humidity sensors that have the percentage as a unit of measurement.
Sensori of air qualityAll the sensors that have "pm25”Which element of the procharacteristics.
Sensori of carbon monoxideAll the sensors that have "co”Which element of the procharacteristics.
Sensori of carbon dioxideAll the sensors that have "co2”Which element of the procharacteristics.
Sensori lumiof brillianceAll the sensors that have "lm"Or"lx”Which elements of the procharacteristics.
switchSwitchesRappmade as switches. They can be changed as type using the personalization field "type"
water_heaterWater heatersAll water heaters.

Resolution of proproblems

Deleting the .HOMEKIT.STATE file

In case of proproblems with integration it is possible to return to the zero point simply:

  1. then stopping Home Assistant
  2. deleting the .HOMEKIT.STATE file
  3. restarting Home Assistant

Errors during pairing

In case of proproblems during pairing between Home Assistant and l 'applished here Appthe "House", prosee as follows:

  1. stop Home Assistant
  2. delete the file .HOMEKIT.STATE
  3. change the configuration of Home Assistant (see below)
  4. restart Home Assistant

Proto be modified the configuration as follows:

  default: warning
    homeassistant.components.homekit: debug
    pyhap: debug

      - demo.demo
The PIN for the pairing no appare

You may already have used the pairing. Delete the file .homekit.state.

Home Assistant no appare like BRIDGE su Apple Casa

It is usually a pronetwork problem. Verify that you are on the same local network as Home Assistant.
Provare also changing the default_port.

Home Assistant (on Docker) not appare like BRIDGE su Apple Casa

Setting up network_mode: host

Home Assistant (on VirtualBox) not appare like BRIDGE su Apple Casa

Configure the network mode as networkbridge. Otherwise, the BRIDGE will not be exposed to the network (and therefore will not work).

Il pairing fails - zeroconf error

If the pairing fails should appmake a mistake NonUniqueNameException. Set the mode "safe_mode"

Il pairing fails - works only with debug configuration

It only works if you include the demo.demo entity, but fails under the actual configuration conditions.
Unfortunately, some (rare) entities simply don't work. To solve it is necessary to discriminate the entities one at a time until you understand which one it creates proproblems, perhaps using domains to simplify the task.

Il pairing fails but without errors

Check that you have not exceeded the 100 accessories limit.

Duplicate IDs found when adding an accessory

Two entities share the same ID. Solve the proproblem or to exclude one of the two.

Errors in ordinary use

Some accessories not appaiono, for example i Z-Wave

See above under "disable auto-start"

A new entity Home Assistant no appare up Appthe "House"

Check that you have not excluded in the configuration the domain to which appartiene. Verify that, if explicitly included, it is well written.

An entity is present but does not work

Unfortunately, some (rare) entities simply don't work. To solve it is necessary to discriminate the entities one at a time until you understand which one it creates proproblems, perhaps using domains to simplify the task.

All accessories at Appthe "Houses" are "not responding"

Check that you have not exceeded the 100 accessories limit.

Accessory not responding - after restart or update

Check that you have not exceeded the 100 accessories limit.

Some accessories do not work from time to time

Unfortunately it happens. There is little to do. Usually they start working by themselves.

Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.


Stay up to date through ours Telegram channel!