第 12 章

Domain 控制圖鑑

HA 把所有東西按「類別（Domain）」歸類：燈是 light、冷氣是 climate、窗簾是 cover。同一 domain 的所有裝置接受同一套動作（Action，舊版叫「服務 Service」），學會一個就會全部。這一章是每個常用 domain 的速查表。

Domain 是什麼？為什麼要理解它

每個 entity_id 都長成 domain.name，前面那半就是 domain：

  • light.livingroom_main → domain 是 light
  • climate.bedroom_ac → domain 是 climate
  • sensor.outdoor_temperature → domain 是 sensor

為什麼重要？因為 HA 的「執行動作」（舊版叫「呼叫服務」）是以 domain 為單位。light.turn_on 可以打開任何品牌任何協定的燈—飛利浦 Hue、宜家 Tradfri、小米 Yeelight、Zigbee 通用燈、DIY WLED 燈條—都吃同一個動作。這是 HA 抽象化的強大之處。

心法：買新設備前先查它會被 HA 認成哪個 domain。如果認成 light，你就知道所有現有燈的自動化都可以直接吃它，不用重寫。認成 switch 就沒亮度、色溫可調。

light · 燈

可調亮度、色溫、顏色的照明設備。開關型（只有開/關）也可能被歸類到 light，端看整合。

常用動作

  • light.turn_on — 支援參數：brightness_pct: 60、color_temp_kelvin: 3000、rgb_color: [255, 100, 50]、transition: 5（漸變秒數）、effect: "colorloop"
  • light.turn_off — 也支援 transition（漸暗）
  • light.toggle — 開關切換

常用 UI 卡片

  • Light card：內建，滑動調亮度、按住開色板
  • Tile card：小圖磚，適合排一整片
  • Mushroom Light card（HACS）：更漂亮，滑條 + 色板整合

常見坑

  • 燈被實體開關斷電：Zigbee 燈斷電就離線，開燈自動化跑不到。解法：裝不斷電的智慧開關，或把牆壁開關綁死開。
  • 色溫單位：新版用 color_temp_kelvin（3000K 暖白 / 6500K 冷白）；舊版用 color_temp（mired，數字越小越冷）。UI 選哪個看整合，寫 YAML 時 kelvin 比較直覺。
  • 轉場（transition）小心：transition: 30 讓燈從當前 30 秒淡到目標亮度，如果同時來另一個 turn_on 會打斷，用 restart 模式的腳本包起來比較穩。

switch · 開關 / 智慧插座

純粹的通斷電。插座、繼電器、簡單牆壁開關都是這一類。

常用動作

  • switch.turn_on / switch.turn_off / switch.toggle — 沒別的參數，就是這麼單純。

常見用途

  • 控制非智慧家電：飲水機、除濕機、風扇（老式）、聖誕燈
  • 控制電磁閥：熱水器、灑水系統、瓦斯
  • 控制電動窗簾馬達（但更建議認成 cover）

常見坑

  • 斷電記憶：很多插座沒設「上電後恢復先前狀態」，跳電後全關。優先在 App 或 HA 設「Power on state = Last / On」。
  • 能耗實體：許多智慧插座同時有 sensor.*_power、sensor.*_energy，可以拿去做能源儀表板，或當「洗衣機洗完了」的訊號（見範例）。
神奇範例：偵測洗衣機/烘衣機完成。用智慧插座量功率，寫自動化「當 sensor.washer_power 從 >10W 掉到 <5W 持續 3 分鐘 → 推播」。比原廠 App 還好用。

climate · 冷暖氣 / 空調 / 恆溫器

常用動作

  • climate.turn_on / climate.turn_off
  • climate.set_temperature — 參數：temperature: 26（單一目標溫度），或 target_temp_high / target_temp_low（區間，恆溫器）
  • climate.set_hvac_mode — 參數 hvac_mode: cool / heat / auto / dry / fan_only / off
  • climate.set_fan_mode — fan_mode: auto / low / medium / high / on / off（值依廠牌）
  • climate.set_preset_mode — 廠商預設模式（節能、睡眠、離家）
  • climate.set_swing_mode — 掃風方向

UI 卡片

  • Thermostat card：內建圓形溫度盤，最直觀
  • Tile card：緊湊，適合多台空調並列
  • simple-thermostat（HACS）：更多控制細節

常見坑

  • 紅外冷氣的狀態不準：走 IR blaster 的冷氣（Broadlink、SwitchBot Hub）HA 只知道「發射過什麼指令」，不知道冷氣真的收到沒。加一顆溫度感測器對比實際溫度變化才靠譜。
  • Preset 覆寫溫度：切到 preset「eco」通常會強制設定溫度，回 none preset 才能自由設。
  • 單位：確認第 2 章的單位系統設「攝氏」，否則 temperature: 26 會被當成華氏（很冷 XD）。

cover · 窗簾 / 車庫門 / 百葉窗

常用動作

  • cover.open_cover / cover.close_cover / cover.stop_cover / cover.toggle
  • cover.set_cover_position — 參數 position: 50（0 全關、100 全開）
  • cover.set_cover_tilt_position — 百葉窗葉片角度
  • cover.open_cover_tilt / cover.close_cover_tilt

常見坑

  • 方向反了：有些馬達的「開」跟你的直覺相反。到裝置頁「Reconfigure」或直接在設備 App 校準，不要在 HA 用 position: 100 - x 反著寫。
  • 沒 position 支援：便宜的窗簾馬達只有 open/close/stop 三段，設 set_cover_position 會直接失敗。查裝置頁看 supported_features。
  • 車庫門要 lock 保險：cover.open_cover 沒防呆，自動化寫錯可能半夜開車庫。用 input_boolean 當開關 + 條件檢查。

media_player · 電視 / 音響 / 串流盒

常用動作

  • media_player.turn_on / turn_off / toggle
  • media_player.volume_set（volume_level: 0.3，0-1）、volume_up / volume_down / volume_mute
  • media_player.media_play / media_pause / media_stop / media_next_track / media_previous_track
  • media_player.play_media — 播特定內容（media_content_id + media_content_type）
  • media_player.select_source — 換輸入源（HDMI1、Netflix、Spotify）
  • media_player.select_sound_mode — 音場模式

整合差異大

  • Google Cast：可推 URL 到 Nest Hub / Chromecast，適合廣播「洗衣機洗完了」的 TTS 語音
  • Apple TV / Sonos / HEOS：支援豐富，含歌單、群組
  • Samsung / LG TV：關機通常 OK，開機常常需要 Wake-on-LAN 額外設定
  • Spotify / Plex：可以 play_media 指定歌單 / 影片

常見坑

  • 電視開機後 3-5 秒才接受指令，自動化寫「開機 + 換源」要中間加 delay。
  • Cast 群組（好幾支喇叭群播）是額外的 media_player 實體，不是任一支喇叭的屬性。

lock · 智慧門鎖

常用動作

  • lock.lock / lock.unlock
  • lock.open（如果是可電控門把，會實際打開）

常見坑

  • 安全第一：門鎖自動化務必雙重保險。例：「離家自動上鎖」加條件「沒有人在家 + 過去 5 分鐘沒開門」。不要單純用時間觸發。
  • 雲端延遲：品牌雲端整合（Yale、August、Aqara 雲端）常有 5-15 秒延遲。想低延遲用 Matter over Thread 或 Z-Wave。
  • Unavailable 時不能鎖：如果門鎖跟主機斷線就無法遠端操作，走本地協定（Matter、Zigbee、Z-Wave）比純雲端可靠。
提醒：如果沒手機、沒鑰匙備份就自動鎖門，你會被鎖在門外。永遠準備一個機械鑰匙或 PIN 碼備援。

vacuum · 掃地機器人

常用動作

  • vacuum.start / vacuum.pause / vacuum.stop
  • vacuum.return_to_base — 回充電座
  • vacuum.locate — 響鈴找位置
  • vacuum.set_fan_speed — 吸力等級
  • vacuum.send_command — 傳自訂指令（各品牌不一，如 Roborock 的房間指定清掃）

常見用法

  • 「大家都離家 30 分鐘 → 開始打掃」— 出門自動化
  • 「Zigbee 動作感應器全部無動作 15 分鐘 + 平日下午」— 條件觸發
  • 「客廳有訪客要來（Google Calendar 事件）→ 30 分鐘前打掃客廳」— 事件驅動

常見坑

  • 雲端 API 限流：某些品牌雲端 API 每天呼叫次數有限制，別把自動化寫成每 1 分鐘查狀態。
  • 房間 ID 是隱藏的：想「只掃客廳」得先在原廠 App 分區，然後從 HA 用 send_command 傳房間 ID。ID 通常在裝置屬性或整合日誌找。

fan · 電風扇 / 天花板吊扇 / 空氣清淨機

常用動作

  • fan.turn_on / fan.turn_off / fan.toggle
  • fan.set_percentage（0-100 風速）
  • fan.set_preset_mode（auto / sleep / turbo，依裝置）
  • fan.oscillate（左右擺頭）
  • fan.set_direction（吊扇順逆時針）

常見坑

  • 空氣清淨機常同時屬 fan（風量）+ sensor（PM2.5）+ switch（負離子）三個 domain 分開的實體。
  • set_percentage: 0 通常等於關機，要開回來記得先 turn_on。

camera · 攝影機

常用動作

  • camera.snapshot — 拍一張存檔（參數 filename: /media/snap_{{ now().timestamp() }}.jpg）
  • camera.turn_on / turn_off（有些相機支援）
  • camera.enable_motion_detection / disable_motion_detection
  • camera.record — 錄一段影片

UI 卡片

  • Picture entity：內建，最單純
  • Picture glance：影像 + 上方小 icon 顯示相關實體（門鎖、燈）
  • WebRTC card（HACS）：低延遲串流，適合門鈴

常見坑

  • 雲端相機（Ring、Wyze、TP-Link Kasa）：畫面延遲 5-30 秒是常態，想即時要走 ONVIF / RTSP 本地流。
  • Snapshot 檔案位置：預設 /config/www/ 才能被儀表板讀到；存 /media/ 要另外配 media_source。

sensor / binary_sensor · 感測器

sensor 是有數值的感測器（溫度 25.3、電量 87%），binary_sensor 是只有兩態的（門開/關、有人/沒人、下雨/沒雨）。

它們不接受控制動作

感測器是唯讀。你不能「turn_on」一顆溫度感測器。感測器的價值在當觸發或條件：

  • 觸發：「當 binary_sensor.motion_livingroom 變 on → 開燈」
  • 條件：「當日落時，如果 binary_sensor.someone_home 是 on 才做事」
  • 數值：「當 sensor.pm25 > 35 → 開清淨機」

常用 device_class（決定圖示與行為）

  • sensor：temperature / humidity / pressure / illuminance / power / energy / battery / co2 / pm25
  • binary_sensor：motion / occupancy / door / window / smoke / moisture / opening / battery / connectivity
技巧：如果一顆感測器判斷 device_class 錯了（例如 opening 判成 door），實體齒輪頁可覆寫 device_class，儀表板圖示會跟著換。

常見坑

  • Binary sensor 抖動：動作感應器常「亮 → 秒關 → 亮」，自動化寫「on → 開燈」跟「off → 關燈」會抖到頭暈。改用「for: 5 minutes」條件，狀態穩定 5 分鐘才動作。
  • battery 是 sensor 不是 binary_sensor：想「電量低於 20% 提醒」用 sensor.*_battery + numeric_state 觸發器。

notify · 通知

第 7 章講過，這裡補充參數細節。

Companion App 推播完整參數

action: notify.mobile_app_iphone
data:
  title: 洗衣機洗完了
  message: 記得拿出來
  data:
    push:
      sound: US-EN-Alexa-Laundry-Ready.wav  # iOS 音效
      badge: 1
    actions:                                # 可點按動作
      - action: LAUNDRY_DONE
        title: 好，我來拿
      - action: LAUNDRY_SNOOZE
        title: 10 分鐘後提醒
    image: /api/camera_proxy/camera.laundry # 直接顯示相機截圖
    tag: laundry                            # 相同 tag 會覆蓋前一則
    channel: laundry                        # Android 通知通道
    ttl: 0                                  # Android 高優先

其他常用 notify.*

  • notify.persistent_notification — HA 內部通知（右上鈴鐺），不推手機
  • notify.notify — 預設通知群組（發送到所有已設定的通道）
  • tts.* — 語音朗讀（配合 media_player），詳見第 12 章附錄語音章節

input_* · 輔助元件 Helpers

Helpers 是 HA 內建的「假實體」，讓你在自動化裡有東西可以「翻」— 詳見附錄 B。這裡列 domain 對照：

Domain 是什麼 常用場景
input_boolean開/關「訪客模式」「渡假模式」開關
input_number可調數字「自動開燈的照度門檻」用滑桿調
input_select下拉選單「家庭模式」= 在家/離家/睡覺
input_text字串記錄事件、當標籤
input_datetime日期/時間「起床時間」讓家人自己在儀表板改
timer倒數計時器「亮燈 5 分鐘後自動關」
counter整數計數器「今日開門次數」
schedule週排程「上班時段」以週為單位畫時間表

每個都有對應動作，例：input_boolean.turn_on、input_number.set_value、timer.start。附錄 B 有完整教學。

共通工具與心法

觀念：這個工具改過兩次名字。它以前是側欄的獨立項目「開發者工具（Developer Tools）」，2026.2 起被收進設定（Settings）裡面，2026.8 又把名字簡化成工具（Tools）——現在的路徑是設定 → 工具。裡面的「服務（Services）」頁籤也在 2024.8 跟著改名叫動作（Actions）。所以本章寫「設定 → 工具 → 動作」的地方，如果你的 HA 還是舊版，請去側欄「開發者工具 → 服務」，東西完全一樣。

用「工具」試動作

側邊選單「設定」→「工具」→「動作」頁籤。可以選任何動作、填參數、按執行。這是你學新 domain 最快的方式：不用寫自動化，直接試。

開發者工具 服務
圖 12-1「設定 → 工具 → 動作」— 學新 domain 就在這裡玩。（截圖為舊版介面「開發者工具 → 服務」，位置與名稱已如上改過）

用「狀態」看實體屬性

設定 → 工具 → 「狀態」頁籤 → 貼實體 ID → 看它有哪些 attributes。例如 light.livingroom 的屬性會有 supported_color_modes、min_color_temp_kelvin、max_color_temp_kelvin，這些決定你能設什麼參數。

心法總結

買設備 → 先查 domain：能被認成 light / switch / cover / climate 這種「有名有姓」的 domain 通常後續體驗最好；如果只能認成一堆 sensor + switch（例如某些山寨 Tuya 電動窗簾），寫自動化會很痛。這一點在買設備前 Google「品牌 Home Assistant integration」就能查到。

常見問題

我家的燈明明是燈，為什麼 HA 把它認成 switch？可以改成 light 嗎？

因為那顆裝置回報給 HA 的能力就只有「通電／斷電」——常見於智慧插座接檯燈、繼電器型的牆壁開關、Tuya 的一開一切模組。整合只知道它會通斷電，不知道後面接的是燈還是飲水機，所以歸到 switch。

HA 內建一個輔助元件可以幫它換一張臉：設定 → 裝置與服務 → 輔助元件 → 建立輔助元件，選「Change device type of a switch」（英文舊名 Switch as X，中文介面會顯示對應的「變更開關裝置類型」字樣）。挑一顆 switch 實體，就能把它變成 light、cover、fan、lock、siren 或 valve 其中一種。轉換後會多一顆新實體（例如 light.desk_lamp），原本那顆 switch 會被自動隱藏起來，免得儀表板上出現兩個一樣的東西。

注意：這只是換分類，不會變出硬體沒有的能力。轉成 light 之後你可以用 light.turn_on，但還是不能調亮度和色溫——它本來就沒有。想要調光就要換成真的可調光的燈具或調光模組。
我的燈只有亮度、沒有色溫和顏色選項，是 HA 的問題嗎？

八成不是 HA 的問題，是燈本身就沒有。到設定 → 工具 → 狀態貼上實體 ID，看 supported_color_modes 這個屬性，它會誠實告訴你這顆燈支援哪些顏色模式：

色彩模式你在 UI 上會看到什麼
onoff只有開／關，連亮度滑桿都沒有
brightness只有亮度滑桿（單色調光燈）
color_temp亮度 + 色溫（暖白到冷白）
hs / rgb / rgbw / rgbww亮度 + 彩色色盤（rgbww 這種還另外有白光通道）

清單裡有 color_temp 的燈，屬性裡才會同時出現 min_color_temp_kelvin 和 max_color_temp_kelvin，也就是這顆燈色溫能調到多暖、多冷。硬體不支援的話，任何輔助元件、任何 HACS 卡片都變不出色溫來。

如果 supported_color_modes 明顯少於商品規格寫的（例如買了彩色燈泡卻只有 brightness），那才是整合的鍋：先更新燈泡韌體、重新配對，或到該整合的 GitHub 看有沒有同型號的回報。

窗簾的開關方向是反的，按「開」它去關，位置 0 跟 100 也顛倒，怎麼修？

先記住 HA 這邊的定義是死的：position: 0 是全關、position: 100 是全開。這條規則不會因為你的馬達裝反而改變。

正確做法是去裝置那一端把它調正，不要在 HA 的自動化裡寫 100 - x 這種數學題——你會在半年後完全忘記為什麼有這行，而且儀表板上的滑桿還是反的。依你的接法：

  1. Zigbee2MQTT 的馬達

    到裝置頁面的設定區找 motor_reversal（把馬達轉向反過來）或 invert_cover（把位置數值反過來，false 是 open=100 / close=0）。以 Tuya TS130F 這類常見窗簾模組為例，這兩個選項都在裝置的可設定項裡。

  2. 原廠 App 配對的馬達

    多數電動窗簾在原廠 App 裡有「馬達方向」或「行程校準」，把上下限重新走一次通常就正了。校準完 HA 這邊不用改任何東西。

  3. 裝置頁的重新設定

    有些整合在裝置頁提供「Reconfigure（重新設定）」，能重跑一次校準流程。

  4. 真的都沒得選，最後手段

    才考慮用 template cover 包一層把數值反過來。這是最難維護的做法，能避就避。

我用 climate.set_temperature 設了 26 度，冷氣完全沒反應？

照這個順序檢查，九成是前兩項：

  • 冷氣是關的。設目標溫度不等於開機。climate.set_temperature 本身就吃 hvac_mode 這個欄位，所以一次寫完最保險：hvac_mode: cool 加 temperature: 26。
  • 被 preset 綁住了。切在「eco」「sleep」這類廠商預設模式時，目標溫度常常是廠商說了算。先 climate.set_preset_mode 設回 none，再設溫度。
  • 超出可設定範圍。每台機器有自己的 min_temp / max_temp（HA 端的預設值是 7 到 35 度），還有 target_temp_step（有的機器只能調整數度，你送 25.5 會被忽略）。設定 → 工具 → 狀態看得到這幾個屬性。
  • 它其實是區間型恆溫器。這種要用 target_temp_high / target_temp_low，送單一 temperature 會被吃掉。
  • 紅外線冷氣。本文前面講過，HA 只是發指令，發出去有沒有中沒人知道——冷氣正對著遙控器沒？中間有沒有擋到？

想確定到底發生什麼事，最快的方法是到設定 → 工具 → 動作直接執行一次，看它回報成功還是跳錯誤訊息。

電視的 select_source 找不到我要的來源，或者選了沒反應？

media_player.select_source 只認裝置自己回報的字串，而且大小寫、空格都要一模一樣。到設定 → 工具 → 狀態查那顆 media_player 的 source_list 屬性，裡面有什麼你就只能填什麼；填 HDMI 1 但清單裡寫的是 HDMI1，動作就會失敗。

兩個常見狀況：

  • 清單是空的或只有一兩項。很多電視要開機、連上網之後才會把完整來源清單回報給 HA。自動化寫「開機 → 換源」時，中間要留幾秒 delay，不然指令送出去時清單根本還沒生出來。
  • 整合根本不支援換源。不是每個 media_player 都有這個能力（純喇叭、部分串流盒就沒有）。裝置頁看不到來源下拉選單、狀態裡也沒有 source_list，那就是沒有，改用該品牌的 App 巨集或紅外線／HDMI-CEC 繞路。
攝影機在儀表板上又慢又卡，有辦法救嗎？

先分清楚卡在哪一段：

  1. 先確認不是雲端整合的天生延遲

    走品牌雲端的相機（本文前面提過的那幾類）延遲好幾秒是結構性的，改設定救不了，只能改走 ONVIF / RTSP 本地串流。

  2. 確認你在用 WebRTC

    Home Assistant 從 2024.11 起內建了 go2rtc，替相機提供 WebRTC 串流，比舊的 HLS 明顯即時。如果你跑的是 Home Assistant OS 或官方容器，更新後預設就會啟用；不支援 WebRTC 的相機會自動退回舊方式。

  3. 用子碼流（substream）

    大部分 IP 攝影機同時提供一條高畫質主碼流和一條低解析度子碼流。儀表板上的小格子用子碼流，點開放大才用主碼流，機器負擔差很多。

  4. 不要一頁塞八台相機

    每一路即時串流都吃 CPU 和頻寬。把相機集中在單獨一個分頁，平常那頁不要打開，就不會拖累整個儀表板。

  5. 「預先載入串流」要斟酌

    相機實體設定裡有「Preload stream（預先載入串流）」選項，開了會一直保持連線，點開時比較快，但會持續消耗資源。低階主機（像老 Raspberry Pi）不建議全開。

感測器顯示 unknown 和 unavailable，這兩個差在哪？

官方開發文件對這兩個狀態的分工講得很清楚：

狀態意思典型情境
unavailable整合抓不到資料——連線斷了、裝置沒電、雲端服務掛了Zigbee 感測器沒電池、Wi-Fi 插座斷線、主機剛重開還沒連上
unknown連得上，但這個值目前是空的剛重開機還沒收到第一筆回報、某個欄位這次沒回傳、輔助元件建立後還沒被設過值

白話版：unavailable 是「人不在」，unknown 是「人在，但答不出來」。

寫自動化時兩個都要防：數值型觸發器（numeric_state）碰到這兩種狀態不會觸發，但如果你在條件或範本裡拿它做運算，就會噴錯讓整條自動化中斷。習慣加一道條件擋掉，例如判斷狀態不是 unknown 也不是 unavailable 才往下走。

提示：如果某顆感測器經常變 unavailable，那是訊號或電池問題，不是寫程式能解決的——去看第 11 章的裝置頁排查，或幫它加個 Zigbee 路由器（有插電的裝置）中繼。
我要一次控制客廳五盞燈，該做一個群組還是在自動化裡逐一列出來？

四種做法都可行，選擇標準是「這組東西之後還會不會一起出現」：

做法怎麼做什麼時候用
指定區域動作的目標選「區域」，客廳裡所有燈一起吃最推薦的預設做法。以後客廳多買一盞燈，掛進區域就自動被包含，自動化一個字都不用改
群組輔助元件設定 → 裝置與服務 → 輔助元件 → 建立輔助元件 → 群組（Group），可以做燈、開關、窗簾、風扇、感測器等多種群組這組燈需要在儀表板上當成一顆來顯示和操作時。做出來是一顆真的實體，可以放卡片、可以當條件
標籤（Label）幫實體貼上「夜燈」之類的標籤，動作目標選標籤這組東西跨區域（全家的夜燈、全家的窗簾），區域包不住的時候
逐一列出實體目標一顆一顆點組合是一次性的、而且刻意排除某幾顆（例如「客廳除了魚缸燈以外全關」）

群組輔助元件還有一個好處：燈群組的狀態規則是只要有一顆是開的，群組就是開的，所以「客廳還有燈沒關嗎」這種條件寫起來特別直覺。建群組時也可以選擇把成員實體隱藏起來，儀表板才不會一堆重複的東西。

不要犯的錯：不要為了「一次控制」而做一堆群組。群組是給需要被當成一個東西看待的場合用的；只是要一起開關，用區域或標籤更省事，也不會在實體清單裡養出一堆你半年後看不懂的 light.group_xxx。