裝置映射三：特殊設備

特殊設備最容易出現「建立成功但不能用」

這一組 domain 跨越完全不同的語意：media_player 有音量與播放，select 有選項，valve 有開關狀態，event 只有事件，script 則是觸發動作。Matter 沒有一對一 device type 時，Matter Hub 會選最接近的 Mode Select、Generic Switch、On/Off Plug-in Unit 或 Robotic Vacuum Cleaner。

因此你不能只看 Controller 出現一個磁磚就判定完整支援。磁磚是否持續維持 on、是否只能按一下、off 是否真的呼叫 HA action、Controller 是否能顯示 Mode Select，以及設備是否需要 Server Mode，都是不同問題。

警報、警笛、閥門、熱水與自走設備會造成真實環境動作。先以唯讀狀態與低風險命令確認，再決定是否暴露給語音或多人家庭；Matter Hub 不是安全聯鎖或人身監護系統。

本章 17 個 HomeAssistantDomain

Stable 2.0.55 的完整 HomeAssistantDomain 共 27 個；第 9 章涵蓋 7 個，第 10 章涵蓋 3 個，本章涵蓋餘下 17 個，合計不遺漏 rare domain。

domainToDefaultMatterTypes 是 picker 候選矩陣，不是所有 domain 最終 endpoint 的逐字名稱。例如 automation、scene、script 的候選寫 on_off_switch，legacy 實作採 On/Off Plug-in Unit device 基底並保持瞬時 off 語意。文件應描述可觀察行為，不把型別候選與底層 class 混為同一層。

媒體播放器、speaker、valve、pump 與熱水

media_player 若 device_class 為 TV，自動使用 basic_video_player；明確 override speaker 可繞過 TV 偵測。Speaker 只有同時支援 TURN_ON 與 TURN_OFF 時才以電源控制 OnOff，否則有 mute 能力時以靜音代替；VOLUME_SET 加入 0–254 相容音量控制，SELECT_SOURCE 加入輸入來源，PLAY 或 PAUSE 加入播放控制。

Valve 可依電池屬性或 batteryEntity 加入 Power Source；open／close 分別呼叫 HA valve action，opening／closing 呈現 Transitioning。Pump 從 switch override 而來時仍需以來源整合的 turn_on／turn_off 行為為準。熱水器的 boost 涉及能源與燙傷風險，不應只用 Controller 是否顯示按鈕判斷安全。

select、alarm、event、doorbell 與 siren

select 與 input_select 會把非空 options 建成 Mode Select，大小寫不敏感地找到目前選項；沒有選項則不建立 endpoint。固定矩陣對 mode_select 是 Apple、Google、Alexa no、Aqara unknown。若 Controller 無法呈現，可設 selectExposeAsSwitch 並明確指定 selectSwitchOnOption 與 selectSwitchOffOption，把兩個選項折成持續 On/Off；超過兩個模式就不適合此 workaround。

alarm_control_panel 沒有專用 Matter security panel type，因此用 Mode Select 保留 Disarmed、Armed Home、Away、Night、Vacation、Custom 等 HA 支援位元。轉換中的 arming、pending、triggered 不對應固定模式。對不支援 Mode Select 的平台，可使用 On/Off fallback：on 依 Away、Home、Night 優先序布防，off 解除。這會丟失多模式，而且實際整合若需要額外驗證，Controller 命令可能失敗。

event 預設 Generic Switch，會從 event_types 名稱偵測 double／triple／multi press；generic_switch 固定矩陣為 Apple partial、Google no、Alexa yes、Aqara unknown。override doorbell 是 Stable 內 experimental Matter 1.4 類型，Apple、Google、Alexa、Aqara 都是 no；source note 只有 SmartThings 目前呈現，其他平台至多 fallback plain Switch。它不是 Camera Plugin，也不會提供影像。

siren 是持續狀態，on／off 會呼叫 siren.turn_on／siren.turn_off，不要與瞬時事件混淆。警笛測試可能擾民或造成恐慌；先在 HA 確認靜音測試能力，若沒有就只核對 endpoint，不遠端啟動。

dishwasher、vacuum、lawn_mower 與 Service Area

dishwasher 是 switch 可選的 Matter override，maturity stable，但 Apple、Google 為 no，Alexa、Aqara unknown；固定 source note 指家電類平台支援很薄。把任意開關標成洗碗機不會新增行程、門鎖或完成時間，只會改 device type。

vacuum 建立 Robotic Vacuum Cleaner，包含 operational state、run mode、Power Source、Service Area 與永遠存在的 clean mode。OnOff 不屬於標準 RVC device type，預設不加入，因為非 conformant endpoint 會讓 Alexa 拒絕；只有 vacuumOnOff feature flag 明確啟用時加入。robot_vacuum_cleaner 在 Apple、Google、Alexa、Aqara 都為 yes，但 Apple 語音與 Alexa discovery 適合使用第 12 章 Server Mode。

Service Area 可來自 cleanAreaRooms、customServiceAreas、解析到的房間或 roomEntities；沒有任何房間時仍建立預設單一區域。vacuumIncludeUnnamedRooms 控制是否納入無名房；vacuumRoomSwitches 可為不會渲染陣列命令的平台建立每區瞬時 switch。cleaningModeEntity、suctionLevelEntity、mopIntensityEntity 等關聯選項決定清潔模式，不該用名稱相近就自動假設正確。

lawn_mower 沒有原生 Matter mower type，v2.0.55 以 Robotic Vacuum Cleaner 表示，並使用割草機 run／operational state；robotic_lawn_mower 固定矩陣為 Apple、Alexa yes，Google、Aqara unknown，且 UI 會像掃地機器人。只有存在電池屬性或 mapping 時才加 Power Source。

momentary、auto-reset 與 disableMomentaryFlip

持續狀態（persistent）會一直反映設備目前值，例如 input_boolean、remote、siren、valve、select。on 與 off 通常各有 HA action，Controller 改變後應等來源狀態回報。

瞬時動作（momentary）只有「觸發」：automation 呼叫 trigger，scene 與 script 只接受 turn on，button 與 input_button 只 press。它們正常保持 off；收到 on 時動作一次，Controller 不應把它視為持續運轉。

script、scene、automation 與 input_button 的 momentary 行為會樂觀回報 on，再約一秒回 off，避免 Controller 看起來卡住；button 不同，永遠回報 off，從不設為 true。部分 Echo 裝置會因未請求的 on→off report pair 卡住；entity mapping 的 disableMomentaryFlip 對前四者可實質略過翻轉，但對 button 只略過原本就不改狀態的 timer。底層 HA action 仍會觸發。這是特定 Controller workaround，不是把瞬時動作改成 persistent，也不應全域盲開。

映射特殊設備的最小流程

1. 分類為狀態、模式或動作

   先在 HA 確認實體是 persistent state、Mode Select 還是 momentary action。用 script.example_action 等 placeholder 記錄，避免把 live 環境資料帶入文件。

2. 查看 Devices 的預設映射

   在 Matter Hub 的 Devices 搜尋目標，核對 domain 與自動類型；media player 要額外看 device_class 與 supported features，vacuum 要看房間與模式屬性。

3. 對照目標 Controller

   Mode Select、speaker、TV、valve、water heater 與 appliance 支援差異很大。先查矩陣，再決定是否需要 fallback 或 Server Mode。

4. 一次只調一個 mapping

   必要時設定 speaker、pump、water valve 或 select-as-switch；momentary 只有確認 Echo 卡住時才啟用 disableMomentaryFlip。儲存前記下原值。

5. 先做唯讀或低風險驗證

   比較模式、音量、區域與狀態；按鈕用無危險的測試動作。警笛、熱水、泵、閥門、吸塵器與割草機要有人在場並保留停止方式。

6. 確認 Controller 命令與 HA 回報

   persistent 類型測 on 與 off；momentary 只測一次 on 並確認 action 僅觸發一次。失敗時回復 mapping，不先 reset Fabric。

特殊設備卡關與返回點

1. Mode Select 完全不出現

   Apple、Google、Alexa 對固定矩陣皆為 no。只有兩個明確選項時可用 select-as-switch；多選項應保留在 HA，不要犧牲語意硬折成開關。

2. script／scene／automation／input_button 在 Controller 卡在 on

   先確認 action 是否只觸發一次及稍後是否回 off。若是特定 Echo 對 on→off report 卡住，再針對該 entity 啟用 disableMomentaryFlip。一般 button 永遠回報 off，不應以翻轉排錯。

3. automation 的 off 沒有停用自動化

   這是預期行為：此映射是 momentary trigger，不是 automation enable switch。若要持續啟停，應在 HA 建立明確、安全的 input_boolean 流程。

4. TV 或 speaker 只顯示部分控制

   核對 TURN_ON/OFF、VOLUME_MUTE、VOLUME_SET、SELECT_SOURCE、PLAY、PAUSE feature bits，再查 Controller 是否顯示該 cluster。override 不會新增來源設備未提供的能力。

5. Alexa 拒絕 vacuum

   確認沒有不必要的 vacuumOnOff，因 OnOff 不屬於 RVC spec；再考慮以第 12 章 Server Mode 建立專用節點，避免和其他不支援類型混在同 Bridge。

6. 割草機顯示成掃地機器人

   這是 v2.0.55 的相容設計，因 Matter 尚無 mower type。若名稱與遠端啟動風險不可接受，就不要暴露給該 Controller，保留 HA 操作。

常見問題

Stable 2.0.55 固定來源

• 完整 HomeAssistantDomain enum
• 特殊 override、momentary 設定與 Controller 矩陣
• 所有 legacy domain endpoint 實作
• RVC、Service Area、Clean Mode 與 OnOff 限制
• Mode Select 與 switch fallback
• Pinned Add-on mirror

以上皆固定至指定 commit。實驗性 doorbell／water heater management 與 Controller support 已分開陳述，不把 Stable channel 誤寫成全面正式支援。