配對 Apple Home
從配對前的 Apple 家庭中樞與本機網路檢查開始，完成家庭 App 納管、房間與名稱整理，再用分層方法診斷「無回應」而不破壞既有 Fabric。
先定義 Apple Home 在架構中的角色
Matter Hub 把 Home Assistant 實體以 Matter Bridge 暴露；Apple Home 是接收這座 Bridge 的 Matter Controller 生態系統。配對完成後，你可以在家庭 App 中看見 Controller 能理解的 Endpoint，並用 Siri、場景或自動化操作。Home Assistant 仍是原始實體的狀態來源，Matter Hub 仍負責映射與協定轉接。
這個流程不會把 Home Assistant 區域、名稱、Dashboard 或自動化完整搬到 Apple 家庭。Apple 的家庭、房間、顯示名稱、成員與自動化是另一套管理資料。你要先讓小量裝置穩定納管，再於家庭 App 整理，而不是一開始橋接所有實體。
Apple Home 配對前檢查表
| 項目 | 你要確認的事 | 未成立時的現象 |
|---|---|---|
| Apple 裝置與帳號 | iPhone 或 iPad 已登入預計使用的 Apple 帳號，家庭 App 可正常開啟目標家庭。 | 加入錯誤家庭、沒有新增配件權限。 |
| 家庭中樞 | 目標家庭有 Apple 官方支援的家庭中樞，軟體已更新且在線。 | 遠端控制、自動化或長期連線不穩。 |
| 本機網路 | 手機、家庭中樞與 Matter Hub 之間可進行 IPv6 本機通訊與 mDNS 發現。 | 找不到配件、加入到最後逾時、間歇無回應。 |
| Matter Hub | Stable 2.0.55 Bridge 正在執行，持久化資料已備份，基本 Endpoint 映射正確。 | 掃碼後沒有裝置或重啟後身分改變。 |
| 變更凍結 | 配對期間不改埠、網路介面、篩選、Bridge 名稱或大量映射。 | 無法判斷問題來自納管還是結構變更。 |
Apple 官方會隨系統版本擴充 Matter 類型；「Apple Home 支援 Matter」不等於 Matter Hub 映射的每一種 device type 都會出現完整控制項。先選一個基本燈或開關建立基線，再測窗簾、風扇、感測器、吸塵器等型別。
三種支援事實不可混在一起
| 面向 | 本章結論 | 限制 |
|---|---|---|
| Release channel | Matter Hub Stable v2.0.55，來源固定至 exact commit。 | 不引用 Alpha、Testing 或後續 UI 行為。 |
| 產品成熟度 | 一般 Bridge 與 commissioning 流程按 Stable 功能使用。 | Server Mode 多實體、Camera／Security Plugins 與部分 Matter 1.4 類型即使出現在 Stable，仍是實驗性。 |
| Apple Controller 支援 | Apple 官方列出家庭 App 可加入 Matter 配件，且支援類型依 Apple 平台版本。 | 上游 manifest 對多數逐型別 Apple 支援仍標 unknown；不能宣稱全部映射獲 Apple 認證。 |
若某個 Endpoint 在 Apple Home 缺少按鈕或狀態，不代表 Matter Hub 整體故障。先查它的 Matter device type 與 cluster，再對照 Apple 當前支援；若是實驗性類型，要明確把結果當試驗，不當保證。
在家庭 App 完成納管
準備最小 Bridge
在 Matter Hub 的 Bridges 頁開啟目標 Bridge，確認正在執行；用 Devices 核對只包含預期實體。先保留一個低風險燈或開關作驗證，不在此時新增特殊類型。
開啟 commissioning window
在 Bridge 配對區顯示當次 QR。不要下載、截圖、轉傳或把畫面放入支援工單；若相機無法掃描，才準備使用家庭 App 的手動輸入入口。
從家庭 App 新增配件
在 iPhone 開啟「家庭」，選擇新增配件，掃描 Matter Hub 本機畫面上的 QR。遇到「未認證配件」或安全提示時，先確認你連的是自己的 Bridge 與正確家庭，不要盲目略過。
選擇家庭並等待納管完成
依家庭 App 畫面選擇目標家庭與房間，保持 App 在前景、手機網路穩定；不要同時重啟 Matter Hub、家庭中樞或路由器。
先完成基本命名
為 Bridge 與代表性配件使用簡短、可口述且不重複的名稱。避免房間名稱與配件名稱完全相同，也避免一開始逐一改動所有 Endpoint。
驗證兩個方向
由家庭 App 切換測試燈，確認 Home Assistant 狀態改變；再由 Home Assistant 切換，確認家庭 App 卡片更新。等待狀態回報，不以連點掩蓋延遲。
重啟後再驗證
在維護時段正常重啟 Matter Hub，確認相同配件恢復而不是新增一份。若重複出現，先停止變更並檢查 Bridge 身分與持久化資料。
名稱、房間與 Siri 語句的整理順序
納管後先在家庭 App 逐房整理。Apple Home 的顯示名稱是 Controller 端資料；它不必與 Home Assistant entity_id 相同，也不應靠修改 entity_id 來整理語音體驗。先固定 Home Assistant 實體及 Matter Hub 映射，再改 Apple 端顯示名稱，能降低 Bridge 結構變動。
| 層級 | 建議 | 例子原則 |
|---|---|---|
| Bridge 名稱 | 用區域或用途辨識，不把版本、埠或秘密資料放進名稱。 | 「一樓核心橋接器」這類角色名稱。 |
| 房間 | 在家庭 App 指派實際空間；一次整理一個房間並測試。 | 客廳、廚房、會議室。 |
| 配件名稱 | 短、唯一、容易口述；房間資訊可交給房間欄位。 | 「立燈」優於重複冗長的全路徑名稱。 |
| 服務／子配件 | 組合裝置出現多卡片時先辨識功能，再命名。 | 不要因卡片多就刪除原始 HA 實體。 |
名稱變更後用家庭 App 與 Siri 各測一次。若 Siri 誤判，先處理同音、重複或房間衝突；不要 reset Bridge。多 Fabric 環境中，Apple 端名稱不會同步至 Google 或 Alexa。
Apple-specific Matter 支援怎麼判讀
Apple 官方支援頁列出的 Matter 類別可作生態系統上限，但實際呈現還取決於 Apple 平台版本、家庭中樞版本、Bridge 宣告的 device type／cluster，以及該 Endpoint 的映射品質。本章不把「Matter 規格有定義」寫成「家庭 App 一定有完整 UI」。
- 燈、插座、開關：適合作為第一批基線；仍需分別驗證開關、亮度、色溫與顏色。
- 窗簾、鎖、恆溫器：涉及位置、方向、安全或模式語意；先小量驗證，不只看卡片是否出現。
- 感測器：可能能在配件詳細資料中看到，卻不一定有主頁卡片、通知或自動化觸發入口。
- 吸塵器及較新類型：支援與 UI 對 Apple 系統版本敏感；Matter Hub 端若為部分 Matter 1.4 映射，還要標示 Stable 內實驗性。
- Camera／Security Plugins：屬 Stable channel 中的實驗性 Plugin，不應因 Apple Home 有相似配件類別就宣稱完整支援。
No Response 要從範圍與時間切入
| 範圍 | 較可能層級 | 優先動作 |
|---|---|---|
| 整座 Bridge 全部無回應 | Matter Hub 程序、主機網路、IPv6／mDNS、家庭中樞路徑或 Bridge 身分。 | 看 Bridges、Health 與已遮蔽 log；確認程序及持久化掛載。 |
| 只有一個 Endpoint | HA 實體 unavailable、映射、型別或 Controller UI。 | 在 Home Assistant 核對原始狀態及 Matter Hub Devices。 |
| 只有離家時失效 | Apple 家庭中樞或帳號家庭狀態。 | 在家庭 App 查看家庭中樞，不改 Matter Fabric。 |
| 控制有效、卡片停舊值 | subscription 或狀態映射。 | 比較雙向狀態、等待訂閱恢復，避免反覆配對。 |
| 重啟後短暫出現 | session 恢復、啟動順序或 HA 尚未就緒。 | 觀察穩定時間與啟動紀錄，不在恢復期連續重啟。 |
Apple 裝置與 Matter Hub 分 VLAN 時，單純能上網不代表本機 Matter 可達。Matter 需要 IPv6 路徑與服務發現；不要用公開網路位址、port forwarding 或把 QR 貼到遠端機器作替代。網路修正後先讓 session 自行恢復，再評估移除配件。
Apple Home 常見卡關
家庭 App 找不到配件
確認 commissioning window 有效、Bridge 正在執行、手機與 Matter Hub 可進行 IPv6／mDNS 本機發現。關閉會改變路徑的 VPN 後重試，但不要 reset。
加入流程最後逾時
保持家庭 App 前景，確認家庭中樞在線及目標家庭正確；停止同時重啟或改 Bridge。回 Matter Hub 查看是否已新增 Apple Fabric，避免建立重複項目。
只看到 Bridge，沒有預期配件
查看 Devices 與 Filter，確認實體成功映射；再以 Apple 官方支援類型核對。先加入基本燈作對照，不用刪除 Fabric 測型別。
卡片顯示「無回應」
按整座、單一 Endpoint、僅遠端或僅狀態回報分類；先修 Home Assistant unavailable、網路、session 或 subscription，保留仍正常的 Fabric。
名稱或房間又變回去
釐清是 Apple 顯示名稱、Matter Hub Node Label 還是 HA 名稱；只在一層修改並驗證。不要同時重命名 HA entity_id 與 Bridge。
移除後出現重複灰色卡片
先在家庭 App 清理舊配件與自動化引用；Matter Hub reset 會影響其他 Fabric，不是清 App 快取的首選。