第 9 章

裝置映射一：控制設備

看懂 Stable 2.0.55 如何把 Home Assistant 的燈、插座、門鎖、窗簾、空調、風扇與濕度設備轉成 Matter 裝置，並在改用 override 或 workaround 前先判斷能力與 Controller 支援。

映射不是改個圖示而已

Home Assistant Matter Hub 不是 Matter Controller；它讀取 Home Assistant 實體的 domain、device_class、supported_features 與屬性，建立 Matter endpoint，再由 Apple Home、Google Home、Alexa、Aqara 或 SmartThings 等外部 Controller 決定是否顯示控制介面。相同的實體若映射成不同 Matter device type，Controller 可能給你完全不同的磁磚、滑桿與語音能力。

以牆面繼電器為例：on_off_plugin_unit 表示可切換的負載；名稱容易誤導的 on_off_switch 在 v2.0.55 實作成 Matter On/Off Light（0x0100），Controller 會以燈呈現，不是牆面控制器；mounted_on_off_control 才是實驗性的 Matter 1.4 牆面控制類型。on_off_light 同樣表示燈。三者都能帶 On/Off，卻不保證 Controller 用相同方式呈現。正確做法是先保留自動映射，確認 Home Assistant 能力，再針對明確的 Controller 缺口使用 Matter override。

三個事實要分開：本章項目都存在於 Stable 2.0.55 release channel；多數映射成熟度為 stable，但 mounted_on_off_control 是 Stable 內的實驗性類型；Controller 支援則逐類型不同，不能把「在 Stable」推論成「每個家庭平台都會顯示」。

完成本章後，你應能回答三件事：原始 domain 預設會走哪一條路、實體能力會加入哪些 Matter 功能，以及某個 Controller 不顯示時應改類型、啟用 workaround，還是維持現況等待平台支援。

控制類 domain 與 override 矩陣

Stable 2.0.55 的完整 HomeAssistantDomain 清單共有 27 項，本章負責其中七項控制 domain。下表同時列出這七項的預設類型候選與本章全部 Matter override；候選不是保證結果，實際 endpoint 還會依能力位元與屬性選擇。

Home Assistant domain預設或可選 Matter 類型判斷重點
lighton_off_light、dimmable_light、color_temperature_light、extended_color_light依 supported_color_modes 判斷亮度、色溫與彩色能力。
switchon_off_plugin_unit；可 override 為 on_off_switch、dimmable_plugin_unit、mounted_on_off_control一般開關預設像可切換插座；負載語意應由你核對。
lockdoor_lockOPEN feature 決定是否帶 unlatch；電池可附加 Power Source。
coverwindow_covering升降、位置感知、傾斜能力來自 supported features。
climatethermostatheat、cool、heat_cool、auto、fan_only、dry 至少要有一種可用模式。
fanfan；可 override 為 air_purifier速度、預設、方向、擺動與自然風模式由能力與名稱決定。
humidifierhumidifier_dehumidifierAuto 名稱與 current_humidity 決定模式與量測能力。
本章 Matter override用途成熟度／重要相容性
on_off_light只有開關的燈stable；Apple、Google、Alexa、Aqara 為 yes。
dimmable_light可調光、不帶色彩的燈stable；四個主要 Controller 為 yes。
color_temperature_light色溫燈的 override 名稱stable；實作以可安全初始化的 Extended Color Light 能力組合呈現。
extended_color_light亮度、色溫與色彩燈stable；四個主要 Controller 為 yes。
on_off_plugin_unit可切換插座或一般負載stable；四個主要 Controller 為 yes。
dimmable_plugin_unit可調輸出的插接負載stable；Google 為 no，其餘列出的主要平台為 yes。
on_off_switch名稱雖是 switch，實作輸出 Matter On/Off Light 0x0100stable；Controller 以燈呈現，不是可暴露的牆面控制裝置。
mounted_on_off_controlMatter 1.4 牆面控制類型Stable 內實驗性；Apple、Google、Alexa 為 no，Aqara 為 yes；不可當通用替代品。
door_lock門鎖stable；Google partial，Apple、Alexa、Aqara yes。
window_covering窗簾、捲簾、百葉、門或車庫門stable；四個主要 Controller 為 yes，但位置方向仍需驗證。
thermostat空調、暖氣、恆溫與通風設備stable；四個主要 Controller 為 yes，細部模式仍依平台。
fan獨立風扇stable；Apple no，Google、Alexa、Aqara yes。
air_purifier空氣清淨機，可關聯濾網、溫濕度stable；Apple no，Google、Alexa、Aqara yes。
humidifier_dehumidifier加濕／除濕控制stable；Google no、Alexa yes、Apple 與 Aqara unknown。

SmartThings 未出現在 pinned 原始碼的四欄 picker 矩陣中；feature manifest 對上述項目多標為 unknown。unknown 代表這份固定版本沒有足夠證據，不代表 yes 或 no。不要用一次成功的個案改寫成全面支援聲明。

燈、開關與插座如何決定能力

light 的自動路徑會檢查 supported_color_modes。只有 onoff 時建立 On/Off Light；任何非 unknown、非 onoff 模式可帶亮度；HS、RGB、XY、RGBW、RGBWW 代表彩色能力；color_temp 代表色溫能力。色彩或色溫燈在此版本以 Extended Color Light 組合必要 feature，避免 Color Temperature Light 初始化問題。這不表示沒有色溫，而是 endpoint 基底的實作選擇。

switch 預設為 On/Off Plug-in Unit，附有 Groups 與 Scenes Management。若有 battery／battery_level 屬性或 Entity Mapping 指定 batteryEntity，可加入 Power Source。燈與開關也可關聯 powerEntity、energyEntity、voltageEntity、currentEntity；電壓或電流即使沒有獨立 power entity，仍會啟用 Electrical Power Measurement。

選型原則：會長期保持 on／off 的繼電器適合 plug unit；若要燈磁磚可用 on_off_switch，真正牆面控制才評估實驗性 mounted_on_off_control；由第 11 章處理的按鈕、場景與腳本是瞬時動作，不應只因 Controller 喜歡插座磁磚，就假裝成持續供電設備。

若 Alexa 在「開燈」時把先前亮度改掉，Bridge feature flag alexaPreserveBrightnessOnTurnOn 是 Alexa 專用 workaround：Stable、成熟度 stable，manifest 標示 Alexa yes、Apple no。它不增加燈具原本沒有的亮度能力，也不該為其他 Controller 預先啟用。Google 房間關閉與燈狀態同步在此版有原始碼修正，但你仍應以 Home Assistant 狀態回報是否正確作為成功標準。

門鎖、窗簾與安全邊界

lock 映射為 Door Lock。HA 的 locked／locking 對應 Locked，unlocked／unlocking 對應 Unlocked，open／opening 對應 Unlatched，其他狀態保守地呈現 Not Fully Locked。若 supported features 含 OPEN，endpoint 加入 Unbolting，Apple Home 等支援平台可顯示 unlatch。這是「開閂」能力，不等於每把鎖都能物理開門。

Entity Mapping 另有 disableLockPin、鎖碼服務、slot 與長度上下限等設定，但本指南不提供任何實際門鎖碼。Controller 可能快取固定屬性，變更長度界線後不一定立即更新。會寫入實體門鎖使用者碼的服務屬高風險整合，除非你已備份門鎖與整合設定並確認回復方式，否則維持未設定。

cover 只要可建立就會帶 Lift 與 PositionAwareLift；即使 HA 沒宣告 open feature，程式也會以警告方式補上有效 descriptor。open_tilt 或 set_tilt_position 可帶 Tilt，只有 set_tilt_position 才帶 PositionAwareTilt。二元門與車庫門則依狀態回報完全開／關，不會憑空製造中間位置。

設定何時考慮風險與驗證
coverDoNotInvertPercentageController 百分比語意與預期相反時Stable/stable；每次只改一項，對照 HA 與 Controller 的全開、半開、全關。
coverUseHomeAssistantPercentage希望直接採 HA 百分比時Stable/stable；不可與其他方向修正一起盲試。
coverSwapOpenClose開／關指令對調時Stable/stable；先在可目視、無夾傷風險處測試。
coverSliderDebounceMsController 連續送大量滑桿更新時Stable/stable；0 表示未設全域值，entity override 優先。
coverExposeAsDimmableLightAlexa 不再送 Window Covering 位置指令的特定 workaround會把窗簾呈現成可調光燈，語意失真；只用於該 Controller 專用 Bridge。
注意：移動門、車庫門、窗簾與門鎖都可能有實體安全影響。遠端測試前先清空行程範圍並保留本地停止方式；Matter 回報成功不等於機構安全。

空調、風扇、清淨機與加濕器

climate 至少要宣告 heat、cool、heat_cool、auto、fan_only 或 dry 之一，否則 endpoint 會以不支援設備失敗。程式依 hvac_modes 分別加入 Heating、Cooling；只有真正支援雙 setpoint 的 heat_cool 組合才安全啟用 Matter AutoMode。單一 setpoint 的 HA auto 會動態映射，不宣告 AutoMode，以避免某些 Controller 把 auto 寫成 heat 或 cool。

current_humidity 存在或 TARGET_HUMIDITY feature 可加入濕度量測；同時支援 TURN_ON 與 TURN_OFF 才加入 OnOff。disableClimateOnOff 可避免房間「全部關閉」連帶關掉恆溫器。FAN_MODE 會讓 endpoint 使用 Room Air Conditioner 與 Fan Control；若 Aqara 等平台不認得該 device type，可用 disableClimateFanControl 回退 Thermostat。climateExposeFan 是 Bridge 模式的 companion fan 組合；Server Mode 不支援 composed shape，會回退平面 endpoint。

風扇沒有速度與可用速度 preset 時，映射成 On/Off Plug-in Unit，避免 Controller 顯示假的速度滑桿。有 SET_SPEED 或非 Auto preset 時才加入 MultiSpeed 與 Step；preset 中真的有「auto」才加入 Auto；DIRECTION、OSCILLATE 分別加入方向與擺動。natural、nature、sleep 或 fanWindPresets 指定的在地化名稱可加入 Wind。fanSliderDebounceMs 可處理連續滑桿更新，不會擴增硬體速度級數。

fan override 成 air_purifier 後，可使用 filterLifeEntity、temperatureEntity、humidityEntity 關聯濾網與環境量測。這個映射在 Stable、成熟度 stable；Google、Alexa、Aqara yes，Apple no。加濕器會依 available_modes 中是否有 Auto、是否有 current_humidity，建立四種能力組合；humidifier_dehumidifier 的 Controller 支援明顯較薄，尤其 Google 為 no。

Controller caveat：Apple 不顯示獨立 Matter fan 與 air purifier，不表示 endpoint 建立失敗；Google 不顯示 humidifier_dehumidifier 也不是 Home Assistant 服務錯誤。先區分 endpoint health 與平台 UI 支援。

以最小變更驗證控制映射

  1. 在 Home Assistant 先核對能力

    到「設定 → 裝置與服務 → 實體」查看目標實體的 domain、device class、目前狀態與可用控制。以文件 placeholder 如 light.example_lamp 記錄，不複製任何 live 環境資料。

  2. 在 Matter Hub 開啟 Devices

    搜尋該實體，查看目前映射與失敗原因。先保留自動類型；確認顯示的能力與本章矩陣一致，再決定是否開啟 Entity Mapping 編輯。

  3. 只改一個 override 或 workaround

    需要時選擇精確 Matter device type；cover 方向、climate fan、Alexa 亮度等 workaround 一次只改一項。不要同時重命名、改類型及重排 Bridge，否則無法定位差異。

  4. 儲存後查看 Bridge 狀態

    回到該 Bridge 的 Details 或 Devices，確認 endpoint 沒有 failed entity。若類型不支援，還原上一個已知可用設定，而不是直接重設或刪除 Fabric。

  5. 在 Controller 做低風險驗證

    先比對狀態，再測一次 on/off；滑桿只移到容易辨識的位置。鎖與移動設備需有人在現場，並保留本地停止手段。

  6. 分開記錄三項結論

    記下 Stable 2.0.55 是否成功建立、該功能成熟度、以及目標 Controller 是否顯示。unknown 就保留 unknown，不用單一觀察推廣成正式支援。

控制設備卡關與返回點

  1. 燈只有開關，沒有亮度或顏色

    先查 HA 的 supported_color_modes。若來源只宣告 onoff，Matter Hub 不會製造亮度；若能力完整但 override 錯選 on_off_light，移除 override 回到自動判斷。

  2. 窗簾百分比或方向相反

    依序測全開、半開、全關，分清數值反轉與指令對調。一次只試一個 cover flag；完成後把不需要的 workaround 關掉。

  3. 空調 endpoint 建立失敗

    檢查 hvac_modes 是否至少含 heat、cool、heat_cool、auto、fan_only、dry 之一，以及 min_temp／max_temp 單位是否合理。不要用 thermostat override 掩蓋來源實體沒有可用模式。

  4. Apple Home 看不到風扇或清淨機

    固定矩陣對獨立 fan 與 air_purifier 都是 Apple no。保留 HA 控制，或依需求建立其他 Controller 專用 Bridge；不要反覆刪除重配。

  5. Aqara 遺漏帶 fan mode 的空調

    先確認純 Thermostat 可否顯示；若是 Room Air Conditioner 類型相容問題，再考慮 disableClimateFanControl。代價是 Controller 端不再有 Fan Control。

  6. Alexa 不接受窗簾位置或燈亮度異常

    使用 Controller 專用 workaround 前先分拆 Bridge，避免影響其他 Fabric。窗簾偽裝成 dimmable light 會失去正確設備語意，應清楚命名並留下回復紀錄。

常見問題

override 會改變 Home Assistant 實體嗎？
不會改變 domain 或硬體能力；它改變 Matter Hub 對外建立的 device type。控制仍會呼叫相應 HA action，因此錯誤類型可能得到不合適的 Controller UI，而不是新增功能。
switch 應選 plug unit 還是 on/off switch？
先看負載語意與 Controller 呈現。一般可切換電器預設 plug unit 最保守；真正牆面控制器才考慮 switch。Stable 內實驗性的 mounted control 不適合跨平台 Bridge。
為什麼色溫燈看起來使用 Extended Color Light？
v2.0.55 原始碼為避免 Color Temperature Light 初始化問題，以 Extended Color Light 基底只啟用實際支援的 feature。它不會憑空宣告彩色能力。
門鎖可以不要求 Controller 驗證嗎？
disableLockPin 可在特定映射停用 Matter Hub 的 PIN requirement，但是否允許、平台如何呈現及實體鎖安全政策是不同問題。本章不提供任何實際碼值，也不建議為了方便降低門鎖保護。
Controller 矩陣中的 partial 與 unknown 是什麼？
partial 表示只呈現部分能力或特定 UI；unknown 表示固定來源沒有足夠證據。兩者都不能寫成完整支援。

Stable 2.0.55 固定來源

以上連結都固定到指定 commit，不引用 branch HEAD。Controller 支援是固定版本內的 point-in-time 矩陣；平台後續變動應另行驗證。