Domain reference

What is a domain, and why does it matter?

Every entity ID follows domain.name. The part before the period is its domain:

• light.livingroom_main → the domain is light
• climate.bedroom_ac → the domain is climate
• sensor.outdoor_temperature → the domain is sensor

Why does it matter? Home Assistant’s actions—formerly called service calls—are organized by domain. light.turn_on can turn on any supported light, regardless of brand or protocol: Philips Hue, IKEA TRÅDFRI, Xiaomi Yeelight, generic Zigbee lights, and DIY WLED strips all use the same action. That abstraction is one of Home Assistant’s greatest strengths.

light · Lights

Lighting devices may support brightness, color temperature, and color. On/off-only devices may also be classified as lights, depending on the integration.

Common actions

• light.turn_on — Common parameters include brightness_pct: 60, color_temp_kelvin: 3000, rgb_color: [255, 100, 50], transition: 5 (fade time in seconds), and effect: "colorloop"
• light.turn_off — Also supports transition for a gradual fade-out
• light.toggle — Switch between on and off

Common dashboard cards

• Light card: Built in, with a brightness slider and color controls
• Tile card: A compact tile that works well in a grid
• Mushroom Light card (HACS): A polished community card that combines sliders and color controls

Common pitfalls

• Cutting power at the wall: A Zigbee bulb goes offline when a physical switch cuts its power, so an automation cannot turn it back on. Use a smart switch that keeps the bulb powered, or prevent the wall switch from being turned off.
• Color-temperature units: Current Home Assistant actions use color_temp_kelvin (3000 K for warm white / 6500 K for cool white). Older examples use color_temp in mireds, where a lower number is cooler. Kelvin is generally more intuitive in YAML; use the parameter supported by your integration.
• Transitions can be interrupted: transition: 30 fades from the current state to the target brightness over 30 seconds. Another turn_on call during that period interrupts the transition. Wrapping the sequence in a script set to restart mode can make the behavior more predictable.

switch · Switches and smart plugs

This domain provides simple power control. Smart plugs, relays, and basic wall switches all commonly appear as switches.

Common actions

• switch.turn_on / switch.turn_off / switch.toggle — No extra parameters; switch control is that simple.

Common uses

• Control non-smart appliances such as water dispensers, dehumidifiers, traditional fans, and holiday lights
• Control solenoid valves for water heaters, irrigation systems, or gas—using appropriately rated, fail-safe equipment
• Control a curtain motor, although exposing it as a cover is preferable

Common pitfalls

• Power-loss recovery: Many plugs remain off after an outage unless “Power-on state” is set to “Last” or “On” in the manufacturer’s app or Home Assistant. Choose this setting carefully; restoring power automatically may be unsafe for some appliances.
• Energy entities: Many smart plugs also expose sensor.*_power and sensor.*_energy. You can use them in the Energy dashboard or as a signal that a washing machine has finished its cycle.

climate · Heating, cooling, and thermostats

Common actions

• climate.turn_on / climate.turn_off
• climate.set_temperature — Use temperature: 26 for a single target temperature, or target_temp_high / target_temp_low for a thermostat range
• climate.set_hvac_mode — Set hvac_mode: cool / heat / auto / dry / fan_only / off
• climate.set_fan_mode — fan_mode: auto / low / medium / high / on / off (values depend on the device)
• climate.set_preset_mode — Select a manufacturer-defined preset such as energy-saving, sleep, or away
• climate.set_swing_mode — Set the louver swing mode

Dashboard cards

• Thermostat card: A built-in circular temperature control
• Tile card: A compact option for displaying several climate devices side by side
• simple-thermostat (HACS): A community card with additional controls

Common pitfalls

• Infrared air-conditioner state may be inaccurate: With an IR blaster such as BroadLink or SwitchBot Hub, Home Assistant knows only which command it sent—not whether the air conditioner received it. Add a separate temperature sensor to confirm that the room temperature is actually changing.
• Presets can override the temperature: A manufacturer’s “eco” preset will often force its own target temperature. Return the preset to none before setting the temperature manually.
• Units: Confirm that the unit system described in Chapter 2 is set to Celsius. Otherwise, temperature: 26 may be interpreted as Fahrenheit—which would be extremely cold.

cover · Curtains, garage doors, and blinds

Common actions

• cover.open_cover / cover.close_cover / cover.stop_cover / cover.toggle
• cover.set_cover_position — Use position: 50 (0 is fully closed; 100 is fully open)
• cover.set_cover_tilt_position — Set the angle of blind slats
• cover.open_cover_tilt / cover.close_cover_tilt

Common pitfalls

• Direction is reversed: Some motors interpret “open” in the opposite direction from what you expect. Use “Reconfigure” on the device page or calibrate the motor in its manufacturer’s app. Do not work around it in Home Assistant by writing position: 100 - x.
• No position support: Inexpensive curtain motors may support only open, close, and stop. Calling set_cover_position will fail. Check supported_features on the device’s entity page first.
• Add lock safeguards for garage doors: cover.open_cover has no built-in confirmation, so a faulty automation could open the garage in the middle of the night. Use an input_boolean as an enable switch and add explicit conditions.

media_player · TVs, speakers, and streamers

Common actions

• 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 — Play specific content using media_content_id and media_content_type
• media_player.select_source — Select an input or source such as HDMI1, Netflix, or Spotify
• media_player.select_sound_mode — Select a supported sound mode

Capabilities vary by integration

• Google Cast: Can cast a URL to a Nest Hub or Chromecast, making it useful for text-to-speech announcements such as “The washing machine has finished.”
• Apple TV / Sonos / HEOS: Offer extensive support, including playlists and speaker groups
• Samsung / LG TVs: Usually turn off reliably, but turning them on may require additional Wake-on-LAN configuration
• Spotify / Plex: Can use play_media to start a specific playlist or video

Common pitfalls

• A TV may need 3–5 seconds after turning on before it accepts another command. Add a delay between “turn on” and “select source.”
• A Cast speaker group is a separate media-player entity, not an attribute of one of its speakers.

lock · Smart locks

Common actions

• lock.lock / lock.unlock
• lock.open — Physically unlatch or open the door when the hardware supports it

Common pitfalls

• Safety first: Always give lock automations two safeguards. For example, an “auto-lock when leaving” automation should verify both that nobody is home and that the door has not opened in the past 5 minutes. Do not rely on a time trigger alone.
• Cloud latency: Cloud integrations for brands such as Yale, August, and Aqara often have a 5–15-second delay. For lower latency, use a supported local protocol such as Matter over Thread or Z-Wave.
• You cannot control an unavailable lock: If the lock loses its connection to Home Assistant, remote control will not work. Local protocols such as Matter, Zigbee, and Z-Wave are generally more resilient than cloud-only connections.

vacuum · Robot vacuums

Common actions

• vacuum.start / vacuum.pause / vacuum.stop
• vacuum.return_to_base — Return to the charging dock
• vacuum.locate — Play a sound so you can find the vacuum
• vacuum.set_fan_speed — Set the suction level
• vacuum.send_command — Send a vendor-specific command, such as cleaning a particular Roborock room

Common uses

• Everyone has been away for 30 minutes → start cleaning
• All Zigbee motion sensors have reported no motion for 15 minutes on a weekday afternoon → start cleaning
• A Google Calendar event says guests are coming → clean the living room 30 minutes beforehand

Common pitfalls

• Cloud API rate limits: Some brands limit the number of daily API calls. Do not write an automation that polls the vacuum’s state every minute.
• Room IDs are hidden: To clean only the living room, first divide the map into rooms in the manufacturer’s app, then pass the room ID through send_command. The ID is usually available in the device attributes or integration logs.

fan · Fans and air purifiers

Common actions

• fan.turn_on / fan.turn_off / fan.toggle
• fan.set_percentage — Set the speed from 0–100%
• fan.set_preset_mode — Select auto / sleep / turbo, depending on the device
• fan.oscillate — Enable or disable side-to-side oscillation
• fan.set_direction — Set a ceiling fan to rotate clockwise or counterclockwise

Common pitfalls

• An air purifier may expose separate entities in three domains: fan for fan speed, sensor for PM2.5, and switch for features such as ionization.
• set_percentage: 0 usually turns the fan off. Call turn_on before restoring its speed.

camera · Cameras

Common actions

• camera.snapshot — Save a still image using filename: /media/snap_{{ now().timestamp() }}.jpg
• camera.turn_on / turn_off — Supported by some cameras
• camera.enable_motion_detection / disable_motion_detection
• camera.record — Record a video clip

Dashboard cards

• Picture entity: The simplest built-in option
• Picture glance: Shows a camera image with small icons for related entities such as locks and lights
• WebRTC card (HACS): Provides low-latency streaming suitable for doorbells

Common pitfalls

• Cloud cameras such as Ring, Wyze, and TP-Link Kasa: A 5–30-second video delay is common. For real-time video, use a local ONVIF or RTSP stream.
• Snapshot file location: Files in /config/www/ can be served to a dashboard by default. Files saved under /media/ require additional media_source configuration.

sensor / binary_sensor · Sensors

A sensor reports a numeric or textual value, such as a temperature of 25.3 or a battery level of 87%. A binary_sensor reports one of two states, such as open/closed, occupied/clear, or raining/not raining.

They do not accept control actions

Sensors are read-only: you cannot “turn on” a temperature sensor. Their value lies in serving as triggers and conditions:

• Trigger: when binary_sensor.motion_livingroom changes to on → turn on the light
• Condition: at sunset, proceed only if binary_sensor.someone_home is on
• Numeric trigger: when sensor.pm25 exceeds 35 → turn on the air purifier

Common device classes, which determine icons and behavior

• sensor: temperature / humidity / pressure / illuminance / power / energy / battery / co2 / pm25
• binary_sensor: motion / occupancy / door / window / smoke / moisture / opening / battery / connectivity

Common pitfalls

• Binary-sensor chatter: A motion sensor may rapidly switch “on → off → on.” If your automations turn lights on for on and off for off, the lights will flicker. Require the state to remain stable with a “for: 5 minutes” condition before acting.
• Battery level is a sensor, not a binary sensor: To send a warning below 20%, use sensor.*_battery with a numeric-state trigger.

notify · Notifications

Chapter 7 covers the basics; this section provides more detail about notification parameters.

Full Companion App push-notification payload

action: notify.mobile_app_iphone
data:
  title: Washing cycle complete
  message: Remember to collect the laundry
  data:
    push:
      sound: US-EN-Alexa-Laundry-Ready.wav  # iOS sound
      badge: 1
    actions:                                # Tappable actions
      - action: LAUNDRY_DONE
        title: OK, I will get it
      - action: LAUNDRY_SNOOZE
        title: Remind me in 10 minutes
    image: /api/camera_proxy/camera.laundry # Show a camera snapshot
    tag: laundry                            # Replaces the previous notification with the same tag
    channel: laundry                        # Android notification channel
    ttl: 0                                  # Android high priority

Other commonly used notify.* actions

• notify.persistent_notification — Create an internal Home Assistant notification, shown under the bell icon; this does not send a phone notification
• notify.notify — Send to the default notification group across all configured channels
• tts.* — Read text aloud through a media_player; see the voice appendix to this chapter

input_* · Helper entities

Helpers are built-in Home Assistant “virtual entities” that give automations a value you can change or “flip.” See Appendix B for details. The table below maps each helper to its domain:

Each domain has corresponding actions, including input_boolean.turn_on, input_number.set_value, and timer.start. Appendix B provides a complete tutorial.

Tools and best practices

Use Tools to test actions

Open the sidebar and select Settings → Tools → Actions. Choose any action, enter its parameters, and select Perform action. This is the fastest way to learn a new domain because you can test it directly without creating an automation.

Use States to inspect entity attributes

Go to Settings → Tools → States, enter an entity ID, and inspect its attributes. For example, light.livingroom may report supported_color_modes, min_color_temp_kelvin, and max_color_temp_kelvin. These attributes determine which parameters you can set.

Key takeaway

FAQ