HomeKit Bridge Mode Config Changes and Optimizations

I would like to suggest a couple of process improvement changes to the HomeKit integration when acting in Bridge mode. Back when the primary way of configuring HomeKit was done in the YAML configuration, it was easy to exclude all entity types (Domains) and then simply manually include each of the individual entity ID’s that I wanted to pass on to HomeKit. Now that this is done via the GUI these days, I’ve found the process to be a bit buggy and I think that this “might” be a result (at least partially) of the simplified options when configuring in the GUI.

A Small Bit of Background:

First, for the last couple of years, I’ve had the HomeKit integration configuration set to Bridge mode (of course), Inclusion Mode=Include, with the following Domains selected:

  1. Button
  2. Binary Sensor
  3. Climate, Light
  4. Switch
  5. Fan
  6. Sensor

…Then I would select each of the individual entities within those domains I wanted to pass onto HomeKit. This worked well when I had only a handful of Z-Wave, Zigbee, and Tuya devices to pass onto HomeKit but as my entity count grew in number, I found that randomly, entities I had NOT selected on the entities to include page would appear in HomeKit anyways. If I removed them manually in HomeKit, they would reappear the next time I reloaded Home Assistant. I know this has to be a bug in the current iteration of the HomeKit controller because the “phantom appearing” entities would normally only be of one type, say binary_sensor, and only a handful of the entities I had not “included” would appear in HomeKit. It wasn’t passing through all of the known binary_sensor(s), and boy are their a lot of them. :smiley:

Therefore, for one the inclusion and exclusion of domains and entities is a bit buggy with larger setups.

Currently, the inclusion/exclusion mode via the HomeKit Bridge GUI only effects the 2nd step (IE: including/excluding individual entities). If I set the exclusion mode to exclude, each of those Domains are still included but the 2nd step of the HomeKit Bridge config allows me to then select each of the entities I DON’T want to pass onto HomeKit.

This 2nd step is also quite difficult as it literally lists out each of the entities known to HomeKit, however long, and there’s no way to search through them or type-to-filter to aid in quickly selecting them. I have several hundred entities in my primary Home Assistant deployment which makes this very difficult. Furthermore, since I am using iBeacon monitoring, I have a bunch of useless entities that make the list long and burdensome to scroll through.

My Suggestions:
To keep the HomeKit Bridge config simple but to enhance the usability, I would suggest the following process improvements.

  1. Change the inclusion/exclusion mode setting in the GUI’s first step to only impact the selected domains on the first step of the HomeKit integration config. AKA, a Domain Inclusion/Exclusion mode

    • For example: If set to include, and only the domains light and climate are selected immediately afterwards, then when selecting the individual entities in the 2nd step, only entities of those two domain types are shown in the drop-down menu for selection.
    • This means that when set to include, and no domains are selected, all domains are actually excluded by default. The inclusion/exclusion mode selected is understood quite literally this way, with the domain selection being dependent upon the inclusion mode selection.
    • Likewise, if the same setting is set to exclude, then all domains are automatically included, except those that are selected for exclusion.
  2. The 2nd step, (Entity selection) should always be dependent upon the domain inclusion/exclusion mode setting I suggested in number 1 above. In other words, show only the entities that have NOT been filtered out by the domain inclusion/exclusion in step 1 of the HomeKit bridge GUI config.

    • Keeping my first example from number 1 above: If the domain inclusion mode is set to include only the domains light and climate, then step 2 of the HomeKit bridge GUI config will only list the entities that are classified as those two domains.
    • I would suggest that all entities be included by default in step 2. However, users could select any of the individual entities that they want to exclude.

So basically, to sum this first bit up: I suggest changing the inclusion mode that currently only impacts the entity selection, to only impact the domain selection. Then make the entities available for selection in step 2 dependent upon the filters from step 1. This logic would be a lot simpler to configure and manage.

  1. Step 2 needs a better method of selecting individual entities. If you have only a handful of devices in HA, it’s pretty easy, but as I mentioned earlier, I’ve been running HA for years and I’ve a lot of devices in HA that are all pruned and active.
    • At a minimum, add a type to search filter in the step 2 drop-down menu, so that individual entity IDs can be selected quicker.
    • However, entities are already mapped “Areas” their associated devices are placed into. Why not provide a way to filter and browse through the available entities based on this information?

I like what you suggest.
In addition I would like to see the possibility to include/exclude all entities of a certain Integration so that all entities belonging to that integration will be passed/not passed to Homekit


Yeah. That would make a lot of sense. It would be nice to automatically exclude the entities created from the BLE monitor and iBeacon integrations (others too) globally via the HomeKit configure wizard. Great idea!

You’re completely right — the HomeKit Bridge configuration flow is difficult and confusing — but in my opinion your suggested fixes don’t go far enough.

Seems to me the GUI flow is trying to (sort of) replicate the “Filter” section of the HomeKit YAML. This is counterintuitive for anyone who isn’t well-versed in the YAML underpinnings of filters, and would have been better implemented as you suggest, with a series of checkboxes and search fields to help downselect the sea of entities available to bridge.

However the GUI flow is still missing some key features, such as entity-specific configuration changes, or selecting devices with triggers — all of which can currently only be done via YAML — not to mention it’s very difficult to go back and review your selections to understand why a device is missing or mistakenly appears.

So, if we’re making changes to the flow, let’s go all the way. Give me an entire tabbed screen for HomeKit bridge configuration, similar to what I get when I click CONFIGURE for my Z-wave JS integrations. The screen should be two tabs: the first, in addition to basics like name and port number, should have three selection lists: (1) INCLUDED entities: either globs (wildcards) which can be manually entered (and removed) including domain globs like alarmpanel.* or individual entities names entered via a searchable drop-down similar to the one in automations; (2) EXCLUDED entities: a list of exclusion globs or entity names to remove items matching from above, and (3) DEVICE TRIGGERS list of devices with triggers to expose. Like the voice assistant config, this screen could show a count at the bottom, “85 ENTITIES EXPOSED” (and warn me of the 150-entity limit). The other main tab should be a dynamically-updated but read-only list of all the “exposed” entities that are matched to the selections. I should be able to click an entity on this list to configure entity-specific parameters like a linked battery/sensor, or change the switch type for valves/showers. After being customized, there should be an icon in the list-row indicating the entity has customizations.

Improving the “Bridge” configuration flow would finally eliminate the majority of my remaining configuration.yaml. It would also be help if HA decides to someday support bridging to an external Matter Controller, which could use the exact same config flow to select what should be bridged. I would argue a similar selection flow would simplify the Voice Assistant “expose” settings with improved filtering.