第 10 章

裝置映射二：感測與能源

用 Stable 2.0.55 的完整矩陣判讀 sensor、binary_sensor 與 weather，涵蓋溫濕度、壓力、空氣品質、安全偵測、電力、能源、電池、utility meter 與 EVSE，並辨認 Controller 不顯示和資料本身錯誤的差別。

感測值能建立，不代表 Controller 會呈現

感測實體不像燈具只有幾個明顯控制。Home Assistant 的 sensor 可能是溫度、壓力、照度、流量、污染物、即時功率、累積能源或電池百分比；binary_sensor 可能是門窗、移動、佔用、煙霧、漏水或一般布林狀態。Matter Hub 先依 device_class 選 endpoint，再由 Controller 決定是否顯示該 device type 與 cluster。

這會產生三種不同結果：一是 Matter Hub 根本略過不支援的 device class；二是 endpoint 健康，但 Controller 不支援該類型；三是 Controller 有磁磚，卻因來源單位、狀態或關聯實體錯誤而顯示不合理數值。排錯前先辨別是哪一層。

版本界線：本章所有 domain 與 override 都在 Stable 2.0.55 release channel。electrical_utility_meter 是 Stable 內 opt-in Matter 1.4 override，固定來源未標為 experimental；Controller 支援另列，不能由 release channel 或規格版本推導。

安全感測器只提供通知與自動化訊號，不能取代法規要求的煙霧、瓦斯、漏水或凍結保護設備。能源與 EVSE 類型也只是橋接 Home Assistant 狀態與命令，不是計費認證或充電安全控制器。

sensor、binary_sensor、weather 的入口

domain自動判斷不符合時
sensor依 device_class 對應量測或能源 endpoint；部分能力再看 mapping。有未知 device_class 時記錄 entity warning 並略過；沒有 class 也不猜測。
binary_sensor依 device_class 選 Contact、Motion、Occupancy、Smoke/CO 或一般 OnOff Sensor。未知 class 回退 OnOff Sensor，不會自動當安全警報。
weatherWeatherDevice 組合目前溫度、濕度、壓力等可用屬性。Controller 可能只顯示其中一部分；weather 不是預報資料的通用 Matter 畫面。

sensor 的 temperature 會建立 Temperature Sensor；humidity 與 moisture 都可映射 Relative Humidity，後者適合 0–100% 的土壤濕度語意；illuminance 對應 Light Sensor；pressure 與 atmospheric_pressure 對應 Pressure；volume_flow_rate 對應 Flow。PM2.5、PM10、CO2 雖然不是 Entity Mapping picker 的 override 名稱，v2.0.55 自動路徑仍有對應 endpoint 實作；本章矩陣列的是 manifest 規定的完整 override 集合，不應把自動支援與 override 選項混為一談。

binary_sensor 的 door、garage_door、opening、window 等會成為 Contact；motion／moving 成為 Motion；occupancy／presence 成為 Occupancy；smoke 成為 Smoke Alarm；carbon_monoxide／gas 成為 CO Alarm。cold 與 moisture 使用 detector contact 變體。battery_charging、light、plug、power、running 使用 OnOff Sensor；其他 battery、connectivity、heat、lock、problem、safety、sound、tamper、update、vibration 等使用 Contact。

電池：binary sensor 若有 battery／battery_level 屬性或關聯 batteryEntity，在有對應變體時加入 Power Source。對市電設備錯誤自報電池時，可用 disableBatteryMapping，避免 Controller 長期顯示假低電量。

溫度、濕度、壓力、照度與流量

Temperature Sensor 可透過 humidityEntity、pressureEntity 與 batteryEntity 組成平面多量測 endpoint。v2.0.55 會把 Temperature、Humidity、Pressure 的 device type 都放入 descriptor，讓 SmartThings 等 Controller 更有機會辨認每一項。可用組合包括溫濕、溫壓、溫濕壓，以及各自加電池。

Bridge flags autoHumidityMapping、autoPressureMapping、autoBatteryMapping 可從同一 HA device 找關聯實體；autoComposedDevices 則可能建立組合裝置結構。這些 flag 在 Stable 且成熟度 stable，但自動關聯是否正確取決於 HA device registry。名稱相近不代表同一顆硬體，儲存前應核對實體所屬裝置與單位。

override量測語意固定矩陣的 Controller 重點
temperature_sensor溫度Apple、Google、Alexa、Aqara yes。
humidity_sensor相對濕度或百分比 moisture四個主要 Controller yes。
pressure_sensor壓力／大氣壓Google、Aqara yes；Apple、Alexa no。
light_sensor照度Apple、Google、Alexa yes；Aqara unknown。
flow_sensor體積流率Google yes；Apple、Alexa no；Aqara unknown。

資料進入 Matter 前仍應符合 HA device class 的單位語意。若溫度看似差一個數量級、濕度超出 0–100 或壓力顯示不合理，先修正來源 integration 或 template sensor；不要只靠 override 變更標籤。

空氣品質與稀有污染物完整表

空氣品質不是單一 cluster。AQI、CO、CO2、TVOC、NO₂、O₃、甲醛、氡、PM1、PM2.5、PM10 各有不同量測語意。Matter override picker 的完整空氣相關集合如下；即使 Controller 不顯示，endpoint 仍可能健康。

override來源建議Controller 支援快照
air_quality_sensorAQI device classApple no；Google、Alexa、Aqara yes。
carbon_monoxide_sensorCO 數值量測，不是二元警報Apple partial（警報而非讀值）、Google no、Alexa partial、Aqara yes。
tvoc_sensorvolatile_organic_compounds 或 partsApple、Google no；Alexa partial；Aqara yes。
nitrogen_dioxide_sensorNO₂Apple、Google no；Alexa partial；Aqara yes。
ozone_sensorO₃Apple、Google no；Alexa partial；Aqara yes。
formaldehyde_sensor甲醛 HCHO；通常需明確 overrideApple、Google no；Alexa partial；Aqara yes。
radon_sensor氡Apple、Google no；Alexa partial；Aqara yes。
pm1_sensorPM1Apple、Google no；Alexa partial；Aqara yes。

CO 數值的 carbon_monoxide_sensor 與偵測危險狀態的 smoke_co_alarm 不同。前者報濃度；後者報警報事件。把濃度 sensor 強制改成 alarm 可能造成錯誤警報語意，把二元煙霧偵測改成讀值也會失去告警呈現。

健康資訊界線：橋接數值只忠實反映 Home Assistant。校正、感測器壽命、安裝位置與警報器法規認證都在 Matter Hub 範圍之外。

接觸、移動、佔用、煙霧、漏水與天候偵測

override適合狀態Controller 支援重點
contact_sensor開／關、接觸／分離Apple、Google、Alexa、Aqara yes。
motion_sensor瞬時移動／PIR四個主要 Controller yes。
occupancy_sensor空間佔用／presenceApple partial；Google、Alexa、Aqara yes。
smoke_co_alarm煙霧或 CO 二元警報Apple、Alexa、Aqara yes；Google no。
water_leak_detector漏水Apple、Alexa、Aqara yes；Google no。
water_freeze_detector結凍風險Aqara yes；Apple、Google、Alexa no。
rain_sensor降雨Aqara yes；Apple、Google、Alexa no，Alexa 可能拒絕此較新類型。

Smoke/CO Alarm 可用 mapping 的 faultEntity 讓同裝置 problem／safety binary sensor 驅動 hardware fault alert；該 fault entity 本身不一定被吞併，仍可保留原本 endpoint。這是設備故障訊號，不是 alarm active。選擇錯誤會讓 Controller 把維護問題當成火警，或反之。

門窗與移動感測器不需要控制命令，驗證時只做唯讀狀態變化即可。不要為了測試漏水或煙霧 endpoint 而製造真實危險；可在 Home Assistant 的開發或測試環境使用文件化的測試實體，但本章不提供 live 環境資料。

電力、能源、電池、utility 與 EVSE

power、energy、voltage、current device class 預設映射為 electrical_meter，因固定來源指出 Google 與 SmartThings 能呈現 Electrical Meter。electrical_sensor 是 legacy SolarPower alias；solar_power 用於發電。選擇 consumption 或 generation 必須符合正負方向與來源語意。

override用途成熟度／Controller 注意
electrical_meter功率、能源、電壓、電流的消耗量裝置stable；Google yes、Apple/Alexa no、Aqara unknown；SmartThings 在 source note 為可呈現。
electrical_sensorlegacy SolarPower 類型stable；Apple/Google no，Alexa/Aqara unknown。
solar_power發電stable；Apple/Google no，Alexa/Aqara unknown；source note 指 SmartThings 可獨立呈現。
electrical_utility_meterMatter 1.4 Meter Identification 加量測 clustersStable opt-in、非來源指定 experimental；Apple/Google/Alexa no、Aqara unknown、SmartThings yes。
battery_storage有充放電功率／能源的儲能；單純百分比則是較輕量電池來源stable；Aqara yes，其餘三個主要平台 no。
evse電動車供電設備stable；Aqara yes，Apple/Google/Alexa no；bridged EVSE 可能破壞 Alexa 辨識，應排除 Alexa Bridge。

Electrical Meter 可把 powerEntity、energyEntity、voltageEntity、currentEntity 摺入同 endpoint。Utility Meter 另可有 meter serial 與 point of delivery 欄位；本站只使用文字 placeholder，不放任何實際識別資料。Battery Storage 使用 batteryPowerEntity 與 batteryEnergyEntity 後成為較完整 ESS；充電與放電方向要依來源定義核對。

EVSE 可以帶狀態與控制，但 Controller 支援是明顯限制。不要把 Matter tile 當作電氣保護、負載管理或計費依據；任何遠端啟停都必須服從充電設備與安裝現場的安全規範。

建立可驗證的感測映射

  1. 在 HA 實體頁確認 device class 與單位

    到「設定 → 裝置與服務 → 實體」，確認來源是 sensor、binary_sensor 或 weather，並記下 device class、單位與正常範圍。文件只用 sensor.example_temperature 之類 placeholder。

  2. 在 Devices 查看自動結果

    搜尋該實體，先確認是否已被自動映射、組合或略過。若顯示 unsupported device class，先修正 HA 來源，不急著套用語意不符的 override。

  3. 核對關聯實體

    若加入濕度、壓力、電池或電力量測，確認它們屬於同一實體設備且單位相容。一次只新增一個關聯，避免無法判斷是哪個值造成錯誤。

  4. 選擇 override 並讀 Controller caveat

    只有在自動類型不符合且語意明確時才 override。對 utility meter、freeze、rain、EVSE 等稀有類型，先接受 Controller 可能完全不呈現。

  5. 在 Bridge 詳情驗證 endpoint

    確認沒有 failed entity，並比較 Matter Hub 所見值與 Home Assistant。安全偵測採唯讀觀察，不製造煙霧、漏水或其他真實危險。

  6. 最後驗證 Controller UI

    Controller 不顯示時回查本章支援矩陣。若是 no 或 unknown，保留 HA 為主要檢視面，不反覆重新 commissioning。

感測與能源排錯

  1. sensor 被略過

    查看 entity warning 與 device class。v2.0.55 對未知 sensor class 會略過，不會猜測；建立有正確 device class 與單位的 HA template sensor，比強制錯誤 Matter 類型安全。

  2. 二元感測器變成一般 On/Off

    未知或未設定 binary_sensor class 會回退 OnOff Sensor。若它真的是門、移動、佔用或煙霧，先在 HA 修正 device class，再重新查看 endpoint。

  3. 溫濕壓只顯示一項

    確認 mapping 的 humidityEntity／pressureEntity 有值且可用，descriptor 是否列出多個 device type；再查 Controller 是否支援該量測。Apple、Alexa 對 pressure 為 no。

  4. Controller 顯示假低電量

    來源若是市電設備卻自報錯誤 battery，可對該實體使用 disableBatteryMapping。先確認不是實際電池感測器故障。

  5. 功率與能源數值混在一起

    檢查 W 與累積能源單位的 device class，並確認 powerEntity 與 energyEntity 沒有對調。不要用名稱猜測；以 HA attribute 與統計語意為準。

  6. Alexa 配對後因 EVSE 或新型 detector 異常

    把 EVSE、rain、freeze 等薄支援類型排除於 Alexa 專用 Bridge，再觀察是否恢復。不要因此刪除其他正常 Fabric；先用最小 filter 變更定位。

常見問題

weather 會把完整預報送到 Matter Controller 嗎？
不要這樣假設。v2.0.55 的 WeatherDevice 使用可取得的目前量測組合；Controller 是否顯示每個 cluster 與預報 UI 是另一件事。
moisture sensor 為何映射成 humidity？
對 0–100% 的 HA moisture device class，程式採用 Relative Humidity 相同百分比語意，避免被略過。它不代表空氣相對濕度；命名應清楚標成土壤或材料濕度。
CO sensor 與 Smoke/CO Alarm 可以互換嗎？
不應互換。前者是濃度讀值，後者是二元安全警報。來源 device class 與實際設備能力必須匹配。
electrical_utility_meter 為何不能推成普遍支援？
它是 Stable 內 opt-in Matter 1.4 override，固定來源沒有標為 experimental；但 Apple、Google、Alexa no，Aqara unknown，只有 SmartThings yes。release channel、規格版本與 Controller 支援要分開看。
可以把 Controller 不支援的感測器改成 contact sensor 嗎？
只有來源本來就是二元接觸語意時才合理。把壓力、AQI 或能源硬改成 contact 會丟失數值與正確語意，應保留在 HA 或選支援的平台。

Stable 2.0.55 固定來源

來源均固定到 exact commit。平台呈現可能隨 Controller 韌體與 App 更新變化；本章只陳述 pinned v2.0.55 內可核對的支援快照。