組合裝置與關聯實體

HA 的多個實體不一定要變成多張 Controller 卡片

許多整合把一台實體裝置拆成主控制 entity、電池、溫濕度、功率、累積能源、模式 select 與動作 button。若每個 entity 都各自成為 Matter endpoint，Controller 可能顯示大量碎片，或無法把輔助數值放到正確 cluster。Entity Mapping 的 linked fields 讓你指定「哪個 entity 是哪一種資料來源」；composedEntities 則把額外 entities 建成同一 BridgedNodeEndpoint 下的 sub-endpoints。

組合前要先確認 unit、device_class、state 語意與更新頻率。把 current sensor 填進 voltage 欄位不會因為欄位名稱而自動轉換正確；把不同實體設備的電池 sensor 接到主 entity 也會造成錯誤警告。每次只建立一組 link，回到 Devices card 檢查 mapping 與 cluster。

自動映射、明確連結與 Composed Sub-Endpoint

autoComposedDevices 是自動組合 master toggle：開啟後同時允許 battery、humidity、pressure、power、energy 自動合併。autoBatteryMapping 預設 false；autoHumidityMapping 與 autoPressureMapping 預設 true。手動填 batteryEntity 等欄位是明確映射，不應在文件中說成由 flag 自動找到。

Devices card 會列出 mapping 中 battery、humidity、pressure、power、energy、voltage、current、battery power／energy、charging switch、current limit 等關聯，並據此標記對應 clusters。這個卡片資訊同時可能來自 runtime auto mapping 與保存 mapping；判讀時回到 Bridge flags 與 entity mapping 交叉確認。

Battery、溫濕壓、濾網與 Fault

Battery Storage 另有 batteryPowerEntity 與 batteryEnergyEntity，不要與一般裝置的 battery percent 混淆。前者描述家庭儲能的充放電功率與 lifetime throughput；batteryEntity 描述裝置本身電量來源。

Power、Energy、Voltage、Current、Utility Meter 與 EVSE

一般 switch/light/plugin unit 可連 power 與 energy；on_off_switch 被呈現為 plain On/Off Light，UI 不提供電力欄位。electrical_meter、solar_power、electrical_sensor、electrical_utility_meter 會顯示完整 power/energy/voltage/current 群組。EVSE 顯示 charging switch、current limit 與可選 power/energy，避免與一般群組重複。

Lock、Vacuum、Fan、Cover、Select 與 Climate 完整 Helpers

Lock

• disableLockPin：單一 lock 不要求 credential 驗證；若系統有設定 credential，預設仍要求。不得在文件填實際 lock code。
• lockUsercodeService：選配 HA service，把 Controller 設定／清除的 credential 同步到實體 lock；未設定時只保存在 Matter Hub。這是 opt-in 寫入外部裝置的行為，先確認整合服務語意。
• lockUsercodeSlot：實體 lock 的 code slot，預設 1；UI 只接受 1 以上整數。
• lockPinMinLength／lockPinMaxLength：廣告給 Controller 的長度 1–20，預設 4／8；固定 attributes 可能被 Controller 快取到重新配對。只記錄長度，不記錄實際 credential。

Vacuum 與區域

• cleaningModeEntity：清潔模式 select；未指定時 backend 可由 vacuum entity ID 推導慣例名稱。
• suctionLevelEntity、mopIntensityEntity：吸力與拖地水量 select，為 cleaning modes 增加 intensity variants。
• roomEntities：room／scene button 陣列；Matter 選房後按對應 button。UI 可讀相關 buttons，也允許輸入 entity ID。
• currentRoomEntity：目前房間 sensor；cleanedAreaEntity：累積清掃面積 sensor，搭配每區 sizeSqm 推進 progress。
• vacuumAscendingRoomOrder：依 area ID 升冪 dispatch，不依 Controller 選取順序；同時影響 current 與 progress 歸屬。
• vacuumRoomSwitches：每區建立 momentary sibling switch，供不能發 array command 的平台例行程序使用。
• disableCustomAreaRoomModes：不把 custom areas 建成 per-room RvcRunMode，讓 Apple Home 使用多房 area picker；Google／Alexa 依賴 modes 時應保持關閉。
• valetudoIdentifier：保留 Valetudo MQTT identifier 的精確大小寫；未設時由小寫 entity ID 推導。
• customFanSpeedTags：HA option 字串到 Matter ModeTag number 的 map，覆蓋預設 speed tags。
• cleanAreaRooms：runtime 在 vacuum 支援 HA 2026.3 CLEAN_AREA 時自動填入，用 HA area 到 Matter ServiceArea ID 的 mapping；不是 dialog 的人工欄位。

customServiceAreas 每區含必填 name、service，可選 target、plain-object data、batchDispatch 與 sizeSqm。batchDispatch 會以第一個匹配區的 service／target 當模板，能合併 arrays、以逗號串 primitive 並注入選取 metadata；預設逐區 dispatch。data 必須是 JSON object，array 或 primitive 會被 UI 判無效。服務會造成真實裝置動作，先在 HA 以最小範圍驗證。

Fan、Cover、Select、Climate 與 Momentary

• fanWindPresets.natural／.sleep：本地化 HA preset 名稱陣列映射 Matter wind modes；UI 以逗號分隔輸入。
• fanRestoreSpeedOnPowerOn：fan 從 off 開啟時忽略 Controller 注入的 100%／High，恢復上次速度；較低速度仍可在 off 時指定。
• coverSwapOpenClose：單一 cover 交換開關並覆蓋 Bridge flag；coverExposeAsDimmableLight：Alexa workaround，以 level 當 position、on/off 當開關，沒有 stop，且不應放進 Alexa room 的 lights 群組。
• selectExposeAsSwitch 搭配 selectSwitchOnOption／selectSwitchOffOption：把 select/input_select 轉成開關，兩個 option 必須精確符合；變更後需要重新配對該裝置。
• disableClimateOnOff：略過 climate OnOff，避免房間關閉語音呼叫 climate.turn_off。
• disableClimateFanControl：略過 FanControl，改為 ThermostatDevice，以相容不認 RoomAirConditioner 的 Controller；HA 仍可控制 fan modes。
• climateKeepModeOnIdle：HA off＋hvac_action idle 時仍回報上次模式，讓內部清潔週期可取消；HA 與 Matter 暫時刻意不同。
• climateExposeFan：同 HA climate 建立 companion Fan tile；需 entity 回報 FAN_MODE，會把該 AC 重新註冊為 composed device並造成此 AC 一次性重新配對。
• climateAutoMode：只可 heat 或 cool，固定 single-setpoint auto climate 的 Matter 方向。
• disableMomentaryFlip：script、scene、automation、input_button、button 不送 optimistic on→off report，底層 HA action 仍執行；針對部分 Echo 被此 report pair 卡住的 workaround。

Throttle 與 Debounce 不可互換

Debounce 等「最後一次」輸入後才執行，會增加控制延遲；Throttle 限制輸出報告頻率，可能略過中間狀態。你不應用 updateThrottleMs 解決窗簾多次移動，也不應用 fan debounce 解決功率 sensor 報告過密。先從單一 entity、小數值測試，再依 log 與操作體感調整。

profile v1 會攜帶 cover/fan debounce，但不包含 updateThrottleMs。若以 profile 搬設定，匯入後必須手動核對 throttle；也不要假設 Bridge 的全域 debounce 被 mapping profile 搬走。

建立一個可回復的 Linked Mapping

1. 確認主 entity 與同裝置來源

   在 Home Assistant 唯讀確認主 entity、device 關聯、各 sensor 的 device_class、unit 與有效 state。記錄為本地清單，不在文件貼 live entity ID 或供電識別。

2. 確認 Bridge 自動 flags

   檢查 autoComposedDevices、auto battery/humidity/pressure。若自動結果已正確，不再重複手動連結；若只一台例外，優先使用 Entity Mapping。

3. 開啟主 entity Mapping

   在 Devices card 按 Edit Mapping，保持正確主 Matter type。依欄位 autocomplete 選 battery、humidity、power 等來源；只有相符 type/domain 才會顯示專用群組。

4. 設定一組 helper

   一次只填同一目的的欄位，例如 power＋energy，或 humidity＋pressure。需要額外 sub-endpoint 才加入 composed entity，並確認 Bridge 已開 autoComposedDevices。

5. 儲存並檢查 endpoint

   回 Devices card 展開 clusters，確認關聯 entity labels 與數值。若 endpoint failed，先刪除剛加入的 mapping 回到基準，不要 reset Bridge。

6. 做 Controller 特定驗證

   依 support chips 與 maturity 檢查目標 Controller。電力／utility／EVSE 先確認是否顯示，再測讀值；lock、vacuum service area 等會下命令的功能只做經授權的最小測試。

組合與關聯實體排錯

1. 手動 link 儲存後沒有數值

   檢查 linked entity state 是否可用、device_class 與 unit 是否符合欄位。autocomplete 選得到不代表數值語意正確；先清除該 link，確認主 endpoint 恢復。

2. Composed Entities 沒有成為 sub-endpoint

   確認 Bridge 已開 autoComposedDevices，每筆 composed entityId 非空且 type 可支援。再看 failed entities；不要把一般 linked field 誤當 composed sub-endpoint。

3. 市電裝置在 Controller 顯示低電量

   檢查是否由 auto battery、手動 batteryEntity 或 entity 自身 battery attribute 加入。對該主 entity 開 disableBatteryMapping，不要全域關閉所有裝置的 battery。

4. Utility Meter／EVSE endpoint 不顯示

   先讀固定矩陣：Utility Meter 為 Stable opt-in override，只有 SmartThings yes；EVSE 只有 Aqara yes，且不得加入 Alexa Bridge。其他 no／unknown 平台應還原為 Controller 支援的 type，不要反覆改 identity 或 commissioning。

5. Vacuum room progress 錯位

   確認 currentRoomEntity、cleanedAreaEntity、每區 sizeSqm 與實際 dispatch 順序。若機器按 area ID 排序，才開 vacuumAscendingRoomOrder；否則維持 Controller 選取順序。

6. Slider 操作延遲或裝置連續動作

   分辨方向：連續 command 用 cover/fan debounce；過密 state report 用 update throttle。逐步調小／清空 per-entity 值回退 Bridge 預設，不要同時改全域與單體。

7. 找得到 faultEntity 說明但 UI 沒欄位

   這是 v2.0.55 型別與 request/dialog 的落差。不要手改 storage 或杜撰操作；保留預設 smoke/CO mapping，等待有正式 API/UI 支援的版本。

Composed／Linked Entity 常見問題

Stable 2.0.55 固定版本來源

• entity-mapping.ts：全部 composed／linked fields 與 Matter types
• bridge-data.ts：自動 mapping feature flags
• EntityMappingDialog.tsx：欄位顯示、解析、範圍與儲存
• EndpointCard.tsx：關聯 mapping 與 cluster 顯示
• bridge-registry.ts：自動組合判定
• 官方 v2.0.55 Release