HomeKit 桥接集成允许您将 Home Assistant 实体提供给 Apple HomeKit， 因此它们可以从 Apple 的 Home 应用和 Siri 控制；即使这些设备本身不支持 HomeKit。

请确保您已阅读下面列出的 注意事项，以免今后遇到麻烦。但是，如果您遇到问题，请查看 故障排除 部分。

配置

要将 HomeKit 桥接 集成 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

HomeKit 桥接 可以被 Home Assistant 自动发现。如果发现了实例， 它将显示为 已发现。您可以立即进行设置。

手动配置

如果您希望对实体发布到 HomeKit 的方式进行具体更改，覆盖 HomeKit 集成用于与您的网络通信的 IP 地址，或更改 HomeKit 用于向网络通告自身的 IP 地址，那么您需要在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件中配置 HomeKit 集成。

下面是一个示例条目，展示了这将如何看起来：

# 配置 HomeKit 的示例 configuration.yaml 条目
homekit:
  - filter:
      include_domains:
        - alarm_control_panel
        - light
        - media_player
      include_entity_globs:
        - binary_sensor.*_occupancy
      include_entities:
        - binary_sensor.living_room_motion
    entity_config:
      alarm_control_panel.home:
        code: 1234
      binary_sensor.living_room_motion:
        linked_battery_sensor: sensor.living_room_motion_battery
        low_battery_threshold: 31
      light.kitchen_table:
        name: 厨房餐桌灯
      lock.front_door:
        code: 1234
      media_player.living_room:
        feature_list:
          - feature: on_off
          - feature: play_pause
          - feature: play_stop
          - feature: toggle_mute
      switch.bedroom_outlet:
        type: outlet
      camera.back_porch:
        support_audio: True
      sensor.some_co_sensor:
        co_threshold: 1000
      sensor.some_co2_sensor:
        co2_threshold: 1000
  - name: HASS 桥接 2
    port: 21065
    filter:
      include_domains:
        - light

设置

要在 Home Assistant 中启用 HomeKit 桥接集成，请在您的配置文件中添加以下内容：

# HomeKit 设置示例
homekit:

在 Home Assistant 启动后，实体（根据过滤器）会被暴露给 HomeKit，如果它们是 支持的。要添加它们：

1. 打开 Home Assistant 前端。一个新卡片将显示配对二维码和示例中的 pin code。注意：如果未显示 pin code，请检查 Home Assistant UI 左下角的“通知”（铃铛图标）。
2. 打开 Apple Home 应用。
3. 点击 添加配件，然后扫描二维码或选择 没有代码或无法扫描？ 并选择 Home Assistant Bridge。
4. 确认您正在添加一个 未认证的配件，点击 继续添加。
5. 输入 PIN 代码（如果扫描了二维码，跳过此步骤）。
6. 按照设置点击 下一步，最后点击右上角的 完成。
7. Home Assistant Bridge 和配件现在应该列在 Home 应用中。

完成设置后，您应该能够通过 Apple 的 Home 和 Siri 控制您的 Home Assistant 集成。

移动 Home Assistant 安装

如果您希望在迁移到新的 Home Assistant 设备或安装时保留 HomeKit 配对，除了复制配置文件外，您还需要复制配置目录中的 .storage/homekit.* 文件。请记住，该文件夹通常默认是隐藏的，具体取决于您的操作系统。

在复制之前，请确保首先完全停止旧的和新的 Home Assistant 实例，否则将无法工作。

注意事项

配件 ID

当前，此集成使用 entity_id 来生成唯一的 配件 ID (aid) 用于 HomeKit。aid 用于标识设备并保存为其所做的所有配置。因此，这意味着如果您决定更改没有 unique_id 的 entity_id，则在 Home 应用中对该配件所做的所有配置将丢失。

设备限制

HomeKit 配件协议规范每个桥接仅允许最大 150 个唯一配件 (aid)。在配置过滤器时请留意这一点。如果您计划超过 150 个设备的限制，可以创建多个桥接。如果您需要通过 entity_config 为某些实体提供特定配置，请确保将它们添加到通过 YAML 配置的桥接中。

多个 HomeKit 实例

如果您通过 UI 创建 HomeKit 集成（即 设置 > 设备与服务），则必须仅通过 UI 进行配置。虽然 UI 当前提供的配置选项有限，但任何尝试通过 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 文件配置在 UI 中创建的 HomeKit 实例的尝试，将导致在不同端口上运行另一个 HomeKit 实例。

建议仅在在 UI 中创建的 HomeKit 实例中进行编辑，类似地，仅在 YAML 中创建的 HomeKit 实例中进行编辑。

配件模式

在将相机、基于活动的遥控器（支持活动的 remote）、锁或电视媒体播放器（具有 tv 或 receiver 设备类别的 media_player）暴露给 HomeKit 时，必须将 mode 设置为 accessory，并且相关的 include 过滤器应仅包含单个实体。

要快速在 UI 中添加所有配件模式实体：

1. 通过 UI 创建一个新桥接（即 设置 > 设备与服务）。
2. 选择 media_player、remote、lock 和 camera 域。
3. 像正常一样完成流程。
4. 将为每个必须以配件模式操作的实体创建其他 HomeKit 条目，前提是它们尚未拥有一个。
5. 如果您已经为非配件模式实体创建了另一个 HomeKit 桥接，则可以安全删除新桥接。
6. 为每个桥接或配件配对。

要在配件模式下添加单个实体：

1. 通过 UI 创建一个新桥接（即 设置 > 设备与服务）。
2. 在配对桥接之前，访问该桥接的选项。
3. 将模式更改为 accessory。
4. 选择实体。
5. 完成选项流程。
6. 配对配件。

配置过滤器

默认情况下，所有实体（除了隐藏的实体和分类的实体 [config]、[diagnostic] 和 [system] 实体）都被包含在内。要限制暴露给 HomeKit 的实体，您可以使用 filter 参数。请记住，只有 支持的集成 可以添加。

# 示例过滤器以包含指定域并排除指定实体
homekit:
  filter:
    include_domains:
      - alarm_control_panel
      - light
    include_entity_globs:
      - binary_sensor.*_occupancy
    exclude_entities:
      - light.kitchen_light

Filters are applied as follows:

1. 不使用过滤器
   • 包含所有实体
2. 仅包含
   • 实体列表中的实体包含：include
   • 否则，实体匹配域包含：include
   • 否则，实体匹配通配符包含：include
   • 否则：排除
3. 仅排除
   • 实体列表中的实体排除：exclude
   • 否则，实体匹配域排除：exclude
   • 否则，实体匹配通配符排除：exclude
   • 否则：包含
4. 域和/或通配符包含（还可能有排除）
   • 实体列表中的实体包含：include
   • 否则，实体列表中的排除：exclude
   • 否则，实体匹配通配符包含：include
   • 否则，实体匹配通配符排除：exclude
   • 否则，实体匹配域包含：include
   • 否则：排除
5. 域和/或通配符排除（没有域和/或通配符包含）
   • 实体列表中的实体包含：include
   • 否则，实体列表中的排除：exclude
   • 否则，实体匹配通配符排除：exclude
   • 否则，实体匹配域排除：exclude
   • 否则：包含
6. 没有域和/或通配符的包含或排除
   • 实体列表中的实体包含：include
   • 否则：排除

以下字符可用于实体通配符：

* - 星号表示零个、一个或多个字符
? - 问号表示零个或一个字符

隐藏实体和分类实体（[config]、[diagnostic] 和 [system] 实体）不被包括在内，除非它们被 include_entity_globs 或 include_entities 明确匹配，或在 UI 中选择的包含模式。

Docker 网络隔离

advertise_ip 选项可用于在启用网络隔离的临时 Docker 容器中运行此集成，例如，不使用主机网络。

您可能需要设置 Home Assistant 使用的默认网络接口，在其 网络配置 中。

要使用 advertise_ip，请将此选项添加到您的 homekit 配置中：

homekit:
  advertise_ip: "YOUR_DOCKER_HOST_STATIC_IP"

重启您的 Home Assistant 实例。此功能需要在您的 Docker 主机上运行 mDNS 转发器，例如 avahi-daemon 以反射模式。

防火墙

如果您的 Home Assistant 系统上配置了防火墙，请确保您打开以下端口：

• UDP: 5353
• TCP: 21063（或配置/使用的 port 在集成设置中）。

支持的集成

目前支持以下集成：

设备触发器

支持触发器的设备可以通过访问 设置 > 设备与服务 中桥接的选项添加。要使用此功能，必须在您的用户配置文件中启用高级模式。

桥接的设备触发器被表示为无状态可编程开关上的单个按键。这允许 HomeKit 自动化在设备触发时运行。由于 Apple Home 应用当前只显示按钮的编号而不显示名称，用户可能会发现更容易在 Eve for HomeKit 应用中识别按钮的名称。

iOS 遥控小部件

作为 TelevisionMediaPlayer 和 ReceiverMediaPlayer 暴露的实体可以在控制中心的 Apple 遥控小部件中控制。根据实体的 supported_features，播放、暂停、调高音量和调低音量应开箱即用。但如果您的电视可以通过其他方式控制，例如通过红外发射器执行操作，则可以构建自动化来利用这些事件。

当在控制中心遥控小部件中按下按键时，将触发事件 homekit_tv_remote_key_pressed。 按键名称将在事件数据中的 key_name 字段中可用。示例：

automation:
  triggers:
    - trigger: event
      event_type: homekit_tv_remote_key_pressed
      event_data:
        key_name: arrow_right

  # 通过 broadlink IR 发射器发送箭头右键
  actions:
    - action: broadlink.send
      host: 192.168.1.55
      packet: XXXXXXXX

事件

HomeKit 集成会发出 homekit_state_change 事件。这些事件可以用于自动化，以了解实体的状态何时从 HomeKit 更改。

# 处理 HomeKit 事件的示例
automation:
  triggers:
    - trigger: event
      event_type: homekit_state_change
      event_data:
        entity_id: cover.garage_door
        action: open_cover
  actions:
    - action: persistent_notification.create
      data:
        message: "车库门通过 HomeKit 打开"

故障排除

所有或某些设备间歇性无响应

HomeKit 在很大程度上依赖于您的家庭中心来跟踪蓝牙设备。此外，每个家庭中心必须跟踪每个您桥接的 HomeKit 配件。如果您有许多配件，特别是摄像头或蓝牙设备，请 考虑禁用旧家庭中心上的 HomeKit。

以下测试在 Home Assistant 2021.6（HAP-python 3.5.0）和 iOS/tvOS 14.6 中进行

以下家庭中心在测试 400 个配件时表现良好：

• HomePod
• HomePod Mini
• Apple TV 4k 第二代（使用以太网而不是 Wi-Fi 时效果最佳）

以下家庭中心在测试 300 个配件时表现良好：

• Apple TV 4k 第一代（使用以太网而不是 Wi-Fi 时效果最佳）

以下家庭中心已经报告在大量配件时存在问题：

• Apple TV HD
• 各种 iPad 型号

通过 YAML 创建时重置

1. 在 Devices & services 面板中删除 HomeKit 集成。
2. 重启 Home Assistant。
3. 配置将从 YAML 自动重新导入。
4. 为桥接或配件配对。

通过 集成 面板创建时重置

1. 在 集成 面板中删除 HomeKit 集成。
2. 在 集成 面板中重新创建 HomeKit 集成。
3. 为桥接或配件配对。

配对过程中出现错误

如果您在配对过程中遇到任何问题，请确保在您的 configuration.yamlconfiguration.yaml 文件是 Home Assistant 的主要配置文件。它列出了要加载的集成及其特定配置。在某些情况下，需要直接在 configuration.yaml 文件中手动编辑配置。大多数集成可以在 UI 中配置。 [Learn more] 中添加以下内容，以尝试识别问题。

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

按上述说明进行重置。

最小配置

如果在尝试(配对期间出现错误)中的步骤后配对仍然失败，可能是由于特定实体。尝试使用最小配置进行重置，例如：

homekit:
  filter:
    include_entities:
      - demo.demo

PIN 作为持续状态未显示

您可能已经配对了 Home Assistant Bridge。如果没有，请遵循上述重置说明。

Home Assistant Bridge 未在 Home 应用中出现（以进行配对）

这通常是设置和网络相关的问题。确保检查下面的其他问题，但可能有效的事情包括：

• 检查您的路由器配置
• 尝试使用 Wi-Fi 和 LAN
• 更改默认 端口

请记住，iOS 设备需要与 Home Assistant 设备在同一局域网中才能进行配对。

Home Assistant Bridge 未在 Home 应用中出现（以进行配对） - Docker

在您的 docker-compose.yaml 中设置 network_mode: host。如果您还有其他问题，这个 问题 可能会有所帮助。

您还可以尝试将 avahi-daemon 与 advertise_ip 选项一起使用，见上文。

Home Assistant Bridge 未在 Home 应用中出现（以进行配对） - VirtualBox

将网络模式配置为 networkbridge。否则 Home Assistant Bridge 不会向网络公开。

配件未在 Home 应用中出现（以进行配对） - Libvirt QEMU/KVM 虚拟机与 macvtap 适配器

有关更多详细信息，请参阅 零配置网络 集成。

配对挂起 - zeroconf 错误

配对最终失败，您可能会看到错误消息 NonUniqueNameException，您可能需要在 zeroconf 集成配置中启用 default_interface: true，并设置唯一名称，例如 name: MyHASS42。

如果您之前已经配对过（即使不成功），可能需要删除 .homekit.state 文件，以便能够成功配对。参见 配对期间出现错误。

配对挂起 - 仅在调试配置下工作

当过滤器仅设置为包含 demo.demo 时，配对工作良好，但在正常配置下失败。查阅 特定实体不工作。

配对挂起 - 无错误

1. 确保您没有尝试添加超过 150 个配件，参见 设备限制。在极少数情况下，您的某些实体可能无法与 HomeKit 集成配合使用。使用 过滤器 查找是哪一个。请随意在 home-assistant 仓库中打开一个新问题，以便我们可以解决它。
2. 检查日志，搜索 Starting accessory Home Assistant Bridge on address。确保 Home Assistant Bridge 连接到正确的接口。如果没有，请明确设置 homekit.ip_address 配置变量。

正常使用中的问题

桥接自发解除配对

多名用户报告说，iOS 12 及早期设备会自发删除配对。确保所有拥有家庭管理员访问权的 iOS 设备都运行 iOS 13 或更高版本。如果您无法将设备升级到 iOS 13，请在设备的 iCloud 设置中禁用 Home。

我的实体未显示

检查您的实体的域是否 支持。如果支持，请检查您的 过滤器 设置。确保拼写正确，特别是如果您使用 include_entities 的话。

HomeKit 在第二个 Home Assistant 实例中不工作

要在同一局域网中使用多个不同的 Home Assistant 实例与 HomeKit 集成，您需要为至少一个实例设置自定义名称。config/name

特定实体不工作

尽管我们尽力而为，但某些实体尚未与 HomeKit 集成配合使用。结果将导致配对完全失败或所有 Home Assistant 配件停止工作。使用过滤器识别导致问题的实体。最好逐步尝试配对，逐步包括更多实体。如果工作正常，请取消配对并重复，直到找到导致问题的实体。为帮助他人和开发人员，请在此处打开一个新问题：core/issues/new

如果您在 iCloud 帐户中登录的任何设备都是 iOS 12.x，则 device_class: tv 或 device_class: receiver 的媒体播放器实体可能会触发此条件。过滤该实体或将 iOS 12.x 设备从 iCloud 中注销应该在重启其他设备后解决该问题。

配件均显示为无响应

有报告指出，路由器中的 IGMP 设置导致 HomeKit 出现问题。这导致所有 Home Assistant HomeKit 配件在 Home Assistant（重新）启动几分钟后停止响应。如果您遇到此问题，请仔细检查路由器的 IGMP 设置。默认 IGMP 设置通常效果最好。

请参见 特定实体不工作。

配件未响应 - 重启或更新后

请参见 重置配件 和 取消配对与重新配对。

未识别的链接电池传感器

尝试从 HomeKit 中移除实体，然后重新添加。如果您将此配置选项添加到 HomeKit 中的现有实体，任何更改都不会在配件从 HomeKit 移除并重新添加之前显示。请参见 重置配件。

我的媒体播放器未显示为电视或接收器配件

device_class: tv 或 device_class: receiver 的媒体播放器实体将在运行 iOS 12.2/macOS 10.14.4 或更高版本的设备上显示为电视或接收器配件。如果需要，请尝试从 HomeKit 中移除该实体，然后重新添加，特别是如果 media_player 之前作为一系列开关暴露。对现有配件所做的所有更改，包括更改支持的功能，在配件从 HomeKit 移除并重新添加之前不会显示。参见 重置配件。

通用媒体播放器 有示例展示如何将现有实体封装以使其能够作为 HomeKit 中的电视配件使用。

不能控制电视媒体播放器的音量？

音量和播放/暂停控制将显示在遥控器应用或控制中心中。如果您的电视通过 Home Assistant 支持音量控制，您将能够使用设备上的侧面音量按钮控制音量，同时在屏幕上选择遥控器。

相机视频未流式传输

确保 ffmpeg 集成配置正确。验证您的流是否可以直接使用 ffplay <stream_source> 或 VLC 媒体播放器 播放。如果您更改了相机的实体配置，则可能需要 重置配件。

相机流式传输不稳定或缓慢

如果您的相机支持原生 H.264 流，Home Assistant 可以避免转换视频流，这是一个昂贵的操作。要在通过 YAML 配置时启用原生 H.264 流，需将 video_codec 更改为 copy。要在通过 UI 设置 HomeKit 时允许原生 H.264 流，请在 UI 中转到 设置 > 设备与服务，点击您的 HomeKit 桥接的 选项，并在 Cameras that support native H.264 streams 屏幕上选中您的相机。

多个相机流

可以使用 stream_count 配置选项配置多个流。

相机音频未流式传输

确保相机的实体配置中 support_audio 为 True。

相机运动通知

可以通过 linked_motion_sensor 配置设置链接运动传感器，以启用运动通知。

门铃按钮通知

可以通过 linked_doorbell_sensor 配置设置链接门铃传感器，以启用运动通知。

有许多相机时 HomeKit 停顿或设备响应缓慢

HomeKit 相机快照会在快照期间占用 HomeKit 连接。为避免此问题，请为每个相机在 配件模式 中创建一个单独的 HomeKit 实例。

重置配件

您可以使用 homekit.reset_accessory 操作，配合一个或多个实体 ID，重置配置可能发生变化的配件。这在将媒体播放器的设备类别更改为 tv、链接电池或每当 Home Assistant 为现有实体添加对新 HomeKit 功能的支持时非常有用。

在早期版本的 Home Assistant 中，您可以通过从 HomeKit 中移除该实体（通过 filter）然后重新添加配件来重置配件。

无论哪种策略，配件的行为将如同第一次配置该配件，因此您需要恢复名称、组、房间、场景和/或自动化设置。

取消配对与重新配对

HomeKit 集成会记住每个配对设备的公钥。偶尔，设备配对的公钥可能会因为配对失败而缺失。如果一个或多个设备显示配件不可用，则可能需要取消配对并重新配对设备，以确保集成有每个配对客户端的公钥。homekit.unpair 操作会强制移除所有配对，并允许与配件重新配对。在通过 UI 设置 HomeKit 时，这避免了删除并创建新实例的有时耗时的过程。

配件的行为将如同第一次配置该配件，因此您需要恢复名称、组、房间、场景和/或自动化设置。

空气质量传感器实体

HomeKit 提供五个值来表示空气质量：优秀、良好、中等、差以及糟糕。对于 Home Assistant 中的 PM2.5 传感器实体，将使用原始密度值（µg/m3）来根据 2024 美国 AQI 标准确定相应的值。映射如下：