Devices 與 Entity Mapping
從 Devices 總覽找到 endpoint，安全調整名稱、識別、disable 與 Matter type，讀懂 Controller support chips，並使用 mapping profile 與 device image 工作流。
Filter 決定候選，Mapping 決定如何呈現
Devices 頁面聚合所有 Bridge 的 leaf endpoints，讓你從 Matter 實際產物反查 Home Assistant entity。Entity Mapping（實體映射）則是每座 Bridge、每個 entity 的明確覆寫：可改名稱、Matter device type、識別資訊、disabled 狀態與關聯 helper。它不會改 Home Assistant entity registry，也不會把 Matter Hub 變成 Controller。
操作順序應是：先用 Filter Preview 控制候選，再從 Devices 確認 endpoint，最後只對例外實體加 mapping。若一開始就為每個實體覆寫 type 與 identity，你會失去自動偵測的優點，也更容易遇到 Controller 不支援的類型或 commissioning 後身份變更。
搜尋、篩選、排序、失敗與分頁
| 控制 | 實際範圍 | 使用方式 |
|---|---|---|
| Search | endpoint 顯示名稱、Bridge 名稱、device type 名稱 | 不直接搜尋 entity_id；若名稱找不到，可先依 Bridge／type 縮小後展開 card 查看。 |
| Bridge filter | 所有已載入 Bridge | 只顯示選定 Bridge 的 leaf endpoints，適合避免在同名裝置間改錯 mapping。 |
| Type filter | 目前 endpoints 出現的 type name | 清單由實際裝置類型去重並排序，不是所有可覆寫 Matter type 的完整目錄。 |
| Sort | name、type、bridge；升冪／降冪 | type 與 bridge 相同時再以名稱排序。 |
| Page size | 預設 12；可選 10、25、50、100、自訂或 All | 選擇寫入瀏覽器 local storage；All 以 0 表示並取消分頁切片。 |
| Refresh | 重新載入 Bridge metadata | 裝置 state 會按 bridges 載入；它不是 Force Sync，也不會變更 Controller。 |
?showFailed=true | 所有 Bridge 的 failed entity 摘要 | Dashboard 可導向此焦點檢視，列出 entity_id、Bridge、reason 與可選 failed time；v2.0.55 仍會在下方顯示一般 cards，並非把 cards 真正過濾成失敗項目。 |
Devices 只收集 endpoint tree 中 endpoint number 不為 0 的 leaf；root node 與 aggregator 不會當一般 device card。卡片可顯示 reachable、HA state、clusters、battery percent、自動／明確 mapping 關聯，以及對應狀態 chips。Controller 裡看不到時，Devices 是比 Controller UI 更靠近 Bridge 的第一個檢查點。
從裝置卡片完成最小映射
鎖定正確 Bridge
進入側欄 Devices，先用 Bridge filter 選目標 Bridge，再以名稱或 type 搜尋。展開 card，確認它對應的文件用 entity 佔位符
<ENTITY_ID>。開啟 Edit Mapping
按卡片右上角的 mapping 編輯按鈕。頁面會先讀取該 Bridge 的 mappings，找到相同 entityId 的既有設定；讀取失敗時 dialog 會以無現有 mapping 開啟，這時不要急著覆寫。
保留 Auto Detect 作基準
Matter Device Type 沒有明確問題就維持 Auto Detect。若要覆寫，先讀 suggested types 與每列 Controller support chips，再查看選擇後的支援警告。
只填必要欄位
名稱問題只填 Custom Name；單一 Controller 顯示 productName 才填 Custom Product Name；錯誤 endpoint 才改 type；暫停暴露才開 Disabled。空欄位會送成 undefined。
儲存並查看回饋
按 Save。成功會顯示已儲存訊息；失敗則保留錯誤。回到 card 檢查 mapping 與 clusters，不要立刻同時 Force Sync、改 filter 與重配對。
驗證 Controller
先確認該 type 的支援狀態，再在目標 Controller 觀察。若 type／cluster 拓撲改變需要重新探索或重配，只處理這個例外裝置並先保留回復路徑。
你也可以在單一 Bridge 詳細頁的 Entity Mapping section 新增、編輯或刪除 mapping。新增時可搜尋或輸入 entity ID；刪除 mapping 是回到自動偵測與預設值，不等於從 Filter 排除實體。
名稱、完整身份覆寫、Disable 與 Type Override
| 欄位 | 優先序／限制 | 何時使用 |
|---|---|---|
entityId | mapping 的主鍵之一，另以 bridgeId 隔離 | 新增 mapping 時使用實際 HA entity ID；文件只寫 <ENTITY_ID>，不要公開 live environment 值。 |
matterDeviceType | 省略為 Auto Detect | 自動偵測錯誤或需要明確替代呈現時才覆寫。type 變更可能改 endpoint clusters。 |
customName | nodeLabel 名稱解析的最高優先 | 只改 Matter Controller 顯示名稱，不改 HA entity_id。適合局部 rename。 |
customProductName | 高於 HA device model／model_id，也高於 bridge 的 productNameFromNodeLabel | Controller 以 productName 顯示名稱時使用。 |
customVendorName | 高於 HA device manufacturer | 修正或明確指定文字 vendorName；它不等於 numeric vendorId。 |
customSerialNumber | 高於 HA registry serial 與預設 hash | 只在你理解 Controller 快取風險時設定；不得把實際序號貼進教學或診斷分享。 |
customVendorId | 整數 1–0xFFFE，可輸入十進位或 0x 格式 | Bridge Mode 可覆寫數字 Vendor ID。Server Mode root vendorId 在 commissioning 固定，不能靠此欄位安全改動已配對 Controller。 |
disabled | boolean | 保留 mapping 但停用該實體。這與 Filter Exclude 不同，也不會在 HA 停用實體。 |
兩種 rename：Custom Name 是 Matter 側覆寫，HA entity_id 不變；在 HA 真正改 entity_id 則可能牽涉 endpoint identity。Bridge feature flag stableIdentity 會以 HA registry unique_id 錨定身份，使 rename 不重新 mint 裝置。若沒開 stable identity，不要在已配對環境把 HA rename、custom serial 與 suffix 變更綁在同一批。
<CUSTOM_SERIAL> 等純文件占位符。讀懂 A／G／X／Q 支援 chips
type picker 每列可顯示四個圓形 chips：A 是 Apple Home、G 是 Google Home、X 是 Alexa、Q 是 Aqara Home。綠色代表 works，橘色代表 partly works；no 與 unknown 都使用灰色與較低透明度，必須把游標停在 chip 上讀 tooltip 才能分辨「not supported」或「unverified」。
選定 type 後，如果任一 Controller 明確為 no，dialog 會顯示資訊警告；某些 type 還有自己的 note，例如 standalone fan 在 Apple Home 的呈現限制。這是 v2.0.55 來源內的時間點快照，不是 Controller 廠商永久保證。SmartThings 不在這組 UI chips 中，不能因為沒 chip 就推導支援或不支援。
| 狀態 | UI | 你的判斷 |
|---|---|---|
| yes | 綠色 | 此快照標為可用，仍要用你實際 Controller 版本驗證功能細節。 |
| partial | 橘色 | 可能只呈現部分 cluster／操作；閱讀 type note 並規劃降級。 |
| no | 灰色、tooltip not supported | 可能不顯示。不要用反覆重配對取代 type 相容性檢查。 |
| unknown | 灰色、tooltip unverified | 沒有驗證資料，不能寫成支援或不支援。 |
匯出、預覽與選擇性匯入
Mapping Profile 是 JSON 格式 version: 1，含 name、createdAt、domains、entryCount 與 entries。它搬運的是一組 mapping 規則，不是 Bridge identity、Fabric、配對資料或完整備份。匯出 dialog 預選現有 mappings，你可以全選／取消全選、逐筆勾選並指定 profile name。
選擇匯出範圍
在 Bridge 詳細頁的 Entity Mapping 按 Export，只勾選你要分享或移轉的 entity mappings，使用不含環境機密的 profile name。
保存 JSON
確認下載檔名與內容。分享前人工檢查 entityIdPattern、custom names、service names、area data 與識別欄位，移除能辨識 live environment 的內容；profile 不是自動去識別化工具。
選取 Import 檔案
按 Import 選
.json。前端先要求 version 與 entries，backend preview 再驗證 entries 與可用 entity IDs。審核預覽
確認 profile name、總筆數、matched、unmatched、matchType（exact 或 domain）及 existing mapping。預設會勾選所有 matches，你應取消不想覆寫的項目。
選擇性套用
按套用後看 applied、skipped、errors。v2.0.55 apply 以 profile entry 的
entityIdPattern對 selected IDs，因此跨環境使用時以 exact entity ID 相符最可靠；domain fallback 預覽不要視為一定成功。重新載入與逐筆驗證
匯入後 mappings 會重新載入。先查看少量裝置，再擴大使用；若結果不符，刪除該 mapping 回到自動偵測，而不是重設整座 Bridge。
v2.0.55 profile 並非 EntityMappingConfig 全量備份。它包含 type、customName、disabled，以及多數 battery／sensor／energy／vacuum／lock／cover／fan／climate helper；但 profile 型別與 export 轉換沒有 customProductName、customVendorName、customSerialNumber、customVendorId、composedEntities、chargingStateEntity、currentRoomEntity、cleanedAreaEntity、coverExposeAsDimmableLight、select switch helpers、updateThrottleMs、disableCustomAreaRoomModes 等欄位。需要完整災難復原時使用正式 Backup，而不是把 profile 當完整映射快照。
上傳、移除與自動解析
Devices card 的圖片來源優先序是：自訂檔案（custom）→ Zigbee2MQTT model URL（z2m）→ none。backend 先以 entity_id 安全化後在持久化 storage 的 device-images 目錄找同名檔案；沒有自訂檔時，若 HA device registry 有 model，組成 Zigbee2MQTT 官方圖片 URL。圖片只影響 Matter Hub UI 卡片，不會把圖片同步到 Controller。
| 動作 | 限制 | 結果 |
|---|---|---|
| Upload | PNG、JPG／JPEG、GIF、WebP、SVG；最大 5 MB | 以 entity_id 對應檔名保存；新副檔名會刪除同 entity 的舊副檔名檔案。 |
| Remove | 只在 source 是 custom 時顯示 | 刪除自訂檔；重新 resolve 後可能退回 z2m 圖，而不是一定變成圖示。 |
| Auto resolve | 需要 device registry model | 組成 z2m image URL；遠端不存在時圖片載入失敗，卡片退回裝置圖示。 |
| No image | 沒有 custom 且無 model | 顯示按 Matter device type 選擇的內建 icon。 |
上傳時按 card 的相機按鈕；成功後頁面增加 cache version 並重新 batch resolve。刪除亦重新 resolve。請只使用你有權使用的圖片，不要上傳含住家影像、標籤序號或其他個資的檔案；備份與遷移時要把持久化 device-images 納入資產規劃。
Devices 與 Mapping 排錯
Search 找不到已知 entity_id
Search 只看顯示名稱、Bridge name 與 type。先選 Bridge 與 type，再展開 cards 找 HA entity；或到該 Bridge 的 Entity Mapping section 以 Entity Autocomplete 搜尋。
Failed focus 還顯示正常裝置
這是 v2.0.55 的實際行為：
showFailed=true顯示 failure summary，但不過濾下方 cards。依摘要中的 Bridge 與 entity_id 返回 Filter、mapping 與 failed reason 排查。覆寫 type 後 Controller 不顯示
回到 picker 讀 support chips、tooltip 與 warning，確認 type 成熟度。先還原 Auto Detect；不要先改 identity 或重配整座 Bridge。
匯入預覽 matched、套用卻 skipped
檢查 profile 的 entityIdPattern 是否與目標完全相同。v2.0.55 apply 依 entry pattern 配對 selected IDs，domain fallback preview 在 entity ID 不同時不可靠；採 exact match 或手動建立 mapping。
刪除圖片後仍有圖片
自訂圖片刪除後會重新解析。若 HA device 有 model，來源會退回 z2m；這不是刪除失敗。若遠端 URL 無圖，載入錯誤後才顯示內建 icon。
HA rename 後 Controller 出現新裝置
確認 Bridge 是否使用 stableIdentity，並檢查是否同時改過 serial／unique suffix 或 custom serial。還原非必要身份變更；對已配對環境先從備份與 Controller 影響評估，不直接反覆 rename。