|
|
做完這一篇，你的 iPhone「家庭」App 裡會多出一台叫 Home Assistant Bridge 的配件，
底下掛著你挑選過的燈、開關、窗簾、感測器；攝影機和門鎖會以獨立配件的形式各自出現。
先說三條會咬人的規則，不先知道的話你會在第四步或第七步整個重來：
- 一座橋最多 150 個配件，這是 HomeKit 協定（HAP）的硬限制，不是建議值
- 攝影機、門鎖、支援「活動」的遙控器、電視型媒體播放器，不能放進橋裡，
必須各自開一個 accessory 模式的實例
- 在介面上建立的橋，就只能在介面上改。拿 configuration.yaml 去改它，
結果不是改到，而是「多開一座在別的埠上的橋」
步驟 1：確認網路條件
HomeKit 靠 mDNS（區域網路的裝置探索）找到你的橋，這一關不過的話後面全部免談。
要做的事：
- iPhone 和 Home Assistant 必須在同一個子網路。有分 VLAN 或訪客網路的話，兩邊要放在一起，或是設定 mDNS 轉發
- Home Assistant 主機如果有防火牆，開 UDP 5353（mDNS）與 TCP 21063（HomeKit 預設埠）
- 用 Docker 跑 Home Assistant 的話，要用 host 網路模式
Docker Compose 的寫法：
- services:
- homeassistant:
- container_name: homeassistant
- image: ghcr.io/home-assistant/home-assistant:stable
- volumes:
- - /opt/homeassistant/config:/config
- - /etc/localtime:/etc/localtime:ro
- restart: unless-stopped
- privileged: true
- network_mode: host
你會看到什麼：在 Mac 或 Linux 上執行下面這行，Home Assistant 一啟動 HomeKit 就會出現在清單裡。
- # macOS
- dns-sd -B _hap._tcp
- # Linux（要先裝 avahi-utils）
- avahi-browse -rt _hap._tcp
正常會看到類似這樣的一行：
- Timestamp A/R Flags if Domain Service Type Instance Name
- 12:01:33.412 Add 3 6 local. _hap._tcp. Home Assistant Bridge XXXX
這裡什麼都沒出現，代表 mDNS 沒通，通常是 VLAN 或 Docker bridge 網路造成的，
先把這關解決，不要往下走。
非 host 網路又非改不可的情況：在 Docker 主機上跑 avahi-daemon 的 reflector 模式，
然後在 Home Assistant 的設定裡指定要對外宣告哪個 IP：
- # configuration.yaml
- homekit:
- - name: HA Bridge
- advertise_ip: "192.168.1.50" # 換成 Docker 主機的實體 IP
步驟 2：建立第一座橋
這一步有兩條路，選一條，之後就一直走那條。
路 A：介面（適合只想挑實體、不需要細調的人）
設定 → 裝置與服務 → 新增整合 → 搜尋 HomeKit Bridge。
接著會問你要用「包含」還是「排除」模式，以及要選哪些網域。
第一次建議這樣選：
- 模式選 包含（include）
- 網域勾 light、switch、cover、climate、fan
- 感測器先不要勾，第五步再用清單一個一個加
路 B：YAML（需要 entity_config 的人只能走這條）
只要你想幫某個實體改顯示名稱、改配件型別、綁電池感測器，
就一定要用 YAML 建立這座橋 —— 介面建的橋沒有這些選項。
在 configuration.yaml 的最外層（不要縮排在任何東西底下）加：
- # configuration.yaml
- homekit:
- - name: HA Bridge
- port: 21063
- filter:
- include_domains:
- - light
- - switch
- - cover
- - climate
- - fan
存檔後「開發者工具 → YAML → 重新啟動」。
你會看到什麼：重啟完成後，Home Assistant 首頁左上角會跳出一則通知，
標題是 HomeKit Bridge Setup，裡面有一個 QR code 和一組八位數配對碼（格式像 123-45-678）。
沒有看到這則通知，去「設定 → 系統 → 日誌」看有沒有 homekit 相關的錯誤；
最常見的是 YAML 縮排錯誤，這種情況下整個 homekit: 區塊會被忽略，
而且首頁不會有任何提示。
步驟 3：配對
在 iPhone 上：
- 打開「家庭」App
- 右上角加號 → 加入配件
- 掃描步驟 2 那個 QR code（或選「更多選項」手動輸入配對碼）
- 會跳出「這是未認證的配件」的警告，選「仍要加入」 —— 自製橋一定會跳，是正常的
- 接下來它會一個一個問你每個配件要放哪個房間、叫什麼名字
你會看到什麼：配對成功後，Home Assistant 那則通知會自動消失，
「家庭」App 裡出現一堆新配件。
卡在「正在加入配件」轉圈超過兩分鐘，九成是步驟 1 的 mDNS 沒通，
或是 iPhone 連到了不同的 Wi-Fi 頻段而被路由器隔離（很多路由器的訪客網路或
「AP 隔離」設定會擋掉 mDNS）。
跳出「找不到配件」，代表 QR code 是舊的 —— 重啟過 Home Assistant 之後
配對碼不會變，但如果你曾經刪過 .storage/homekit.* 就會換一組，回步驟 2 重新看通知。
步驟 4：算出你現在有幾個配件
這是整件事最容易誤判的地方。一個「裝置」通常不只一個「配件」。
一顆 Zigbee 溫濕度感測器在 Home Assistant 裡會產生溫度、濕度、電池三個實體，
橋過去就是兩個配件（電池會被當成配件的電量屬性，不佔獨立的配件編號）；
一個有計量功能的智慧插座會產生開關、功率、電壓、電流四個實體。
所以「我只有 30 個裝置」很可能是 70 個以上的配件。
實際去數的方法：
- # configuration.yaml
- logger:
- default: warning
- logs:
- homeassistant.components.homekit: debug
- pyhap: info
存檔、重啟，然後到「設定 → 系統 → 日誌 → 載入完整日誌」，搜尋 homekit。
你會看到什麼：每一個被加進橋的實體都會有一行 debug 記錄，
把這些行數加起來就是配件數。同時要特別找這一行：
- The bridge HA Bridge has entity camera.front_door. For best performance,
- and to prevent unexpected unavailability, create and pair a separate
- HomeKit instance in accessory mode for this entity
看到這一行，代表你把不該放進橋的東西放進去了（攝影機、門鎖、活動遙控器、
電視型媒體播放器），到步驟 6 處理。放著不管的症狀不是「不能用」，
而是整座橋會間歇性變成「無回應」，而且時好時壞，非常難查。
另外一個判斷點：在「家庭」App 裡點那個 Home Assistant Bridge 配件 →
往下捲到「配件詳細資料」，Apple 會列出它底下掛了哪些東西。
步驟 5：收斂實體數量
先講一個很多教學搞錯的前提：Home Assistant 的 HomeKit 整合
預設就會跳過隱藏實體，以及被歸類為「設定」「診斷」「系統」的實體。
也就是說，linkquality、rssi、韌體版本、更新實體這些東西，
現在的 Home Assistant 已經自動幫你排掉了，你不需要再寫 exclude 去排。
（舊教學花很多篇幅在排這些，是因為那是好幾年前的行為。）
真正需要你動手排的是這一類：正常的、不是診斷類的、但你不會在「家庭」App 看的實體。
最典型的是計量插座的功率／電壓／電流，以及一堆自動化和腳本。
完整的 configuration.yaml 寫法：
|
|
加入惟家 LINE 群
窺視卡
雷達卡
發表於 2026-9-21 11:06:57
提升卡
置頂卡
沉默卡
喧囂卡
變色卡
千斤頂
照妖鏡