Home Assistant Naming Guide

Version: 2.1 Last Updated: 2026-03-12 Status: Comprehensive Specification

Consistent, predictable naming makes your Home Assistant configuration maintainable, discoverable, and intuitive. This guide provides a deterministic naming system that scales from simple setups to complex smart homes.

Quick Start Guide

5-Minute Overview

The Core Pattern:

<domain>.<area>_<optional_location>_<optional_function>

The 4 Rules (apply in order, stop at first match):

Uniqueness: If domain + area is unique → use neither location nor function
- Example: light.office (only one light in office)
Physicality: If multiple entities differ by physical location → add location
- Example: light.bedroom_ceiling, light.bedroom_bedside
Purpose: If multiple entities differ by function/measurement → add function
- Example: sensor.kitchen_temperature, sensor.kitchen_humidity
Combination: If need both physical and functional distinction → use both
- Example: sensor.entryway_lock_battery (location: lock, function: battery)

Most Common Patterns:

Type	Pattern	Example
Entity	`<domain>.<area>_<location>_<function>`	`light.bedroom_ceiling`
Automation	`automation.<area>_<trigger>_<action>`	`automation.bedroom_motion_light_on`
Script	`script.<area>_<action>_<qualifier>`	`script.bedroom_wake_routine`
Scene	`scene.<area>_<mood_or_activity>`	`scene.living_room_movie`

Quick Decision:

START: Name my entity

1. Is domain + area unique?
   YES → Done! (e.g., light.office)
   NO → Continue

2. Multiple entities differ by location?
   YES → Add location (e.g., light.bedroom_ceiling)
   NO → Continue

3. Multiple entities differ by function?
   YES → Add function (e.g., sensor.kitchen_temperature)
   NO → Continue

4. Need both?
   YES → Add both (e.g., sensor.door_lock_battery)

When to Use Which Pattern

Use Rule 1 (Neither) when:

Only one entity of that type in the area
Domain + area is self-explanatory
Example: light.office, media_player.living_room

Use Rule 2 (Location) when:

Multiple entities of same type in area
Distinguished by physical location
Example: light.bedroom_ceiling, light.bedroom_bedside

Use Rule 3 (Function) when:

Multiple entities of same type in area
Distinguished by what they measure/do
Example: sensor.kitchen_temperature, sensor.kitchen_humidity

Use Rule 4 (Both) when:

Need to specify both location AND function
Multiple components each with multiple functions
Example: sensor.entryway_lock_battery, sensor.back_door_lock_battery

The 4-Rule Naming System

The deterministic naming system uses four rules applied in order. Stop at the first rule that applies.

Pattern Template

<domain>.<area>_<optional_location>_<optional_function>

Components:

domain – The entity domain (light, sensor, binary_sensor, etc.)
area – The physical room or zone (should match Home Assistant areas)
optional_location – The physical place or component (the "Which")
optional_function – What it does or measures (the "What")

Key Distinction:

Location (noun) = "Which one?" → ceiling, window, desk, paddle
Function (verb/attribute) = "What does it do?" → motion, temperature, power, single_tap

Rule 1: The Rule of Uniqueness

IF the domain and area are enough to uniquely and clearly identify the entity, THEN do not add a location or function.

Examples:

✅ light.office - Only one light switch in office
✅ media_player.living_room - Only one TV/media player
✅ cover.bedroom - Only one window covering
✅ climate.home - Only one thermostat system

When to Apply:

Single entity of that domain in the area
No ambiguity about which entity
Domain + area is self-documenting

When NOT to Apply:

Multiple entities of same domain in area
Ambiguity about which entity
Need to distinguish by location or function

Future-Proofing: If you expect to add more entities of the same type to an area, consider using Rule 2 or 3 from the start. Renaming light.office to light.office_ceiling later will require updating all automations, scripts, dashboards, and scenes that reference it. When in doubt, add a location or function token proactively.

Rule 2: The Rule of Physicality

IF Rule 1 does not apply because there are multiple entities of the same domain in the same area, AND they can be distinguished by their physical location or the component they belong to, THEN you must add a location.

Examples:

✅ light.bedroom_ceiling and light.bedroom_bedside
✅ switch.kitchen_island and switch.kitchen_countertop
✅ cover.living_room_north and cover.living_room_south
✅ binary_sensor.bedroom_window and binary_sensor.bedroom_door

Common Location Tokens:

Furniture: desk, table, bedside, nightstand
Architectural: ceiling, wall, floor, window, door
Fixtures: chandelier, sconce, pendant, recessed
Appliances: island, countertop, stove, sink
Directions: north, south, east, west, left, right
Components: paddle, button1, button2, relay1

When to Apply:

Multiple entities differ by physical location
Location is the primary distinguishing factor
Physical placement is meaningful

Rule 3: The Rule of Purpose

IF Rule 1 does not apply, AND the entities are not distinguished by a physical location but by their purpose, measurement, or attribute, THEN you must add a function.

Examples:

✅ sensor.guest_room_temperature and sensor.guest_room_humidity
✅ input_boolean.guest_mode and input_boolean.away_mode
✅ binary_sensor.hallway_motion and binary_sensor.hallway_occupancy
✅ light.bedroom_group - Virtual group of lights

Common Function Tokens:

Measurements: temperature, humidity, pressure, illuminance, power
Detection: motion, occupancy, presence, contact, leak
Status: battery, status, state, connection, signal
Control: mode, preset, scene, profile, level
Actions: restart, reboot, identify, ping, update

When to Apply:

Multiple entities differ by what they measure/do
Function is the primary distinguishing factor
Purpose is more meaningful than location

Rule 4: The Rule of Combination

IF you must first distinguish entities by their physical component (Rule 2), AND then you must further distinguish them by their purpose or action (Rule 3), THEN you must use both location and function, in that order.

Examples:

✅ select.entryway_paddle_single_tap and select.entryway_paddle_double_tap
✅ sensor.entryway_lock_battery and sensor.entryway_lock_status
✅ binary_sensor.bedroom_window_contact and binary_sensor.bedroom_door_contact
✅ switch.entryway_button1_indication and switch.entryway_button2_indication

When to Apply:

Need both physical AND functional distinction
Multiple components each with multiple functions
Location alone isn't sufficient
Function alone isn't sufficient

Order Matters:

Always: <area>_<location>_<function>
Never: <area>_<function>_<location>

Examples of the Rules in Action

Rule 1: Uniqueness (Neither)

light.bedroom          # Only one light control in bedroom
cover.living_room      # Only one window covering
climate.home           # Only one HVAC system
media_player.kitchen   # Only one speaker

Rule 2: Physicality (Location Only)

light.bedroom_ceiling      # Ceiling light
light.bedroom_bedside      # Bedside lamp
light.bedroom_closet       # Closet light

cover.kitchen_window       # Window covering
cover.kitchen_door         # Door covering

Rule 3: Purpose (Function Only)

sensor.kitchen_temperature     # Temperature measurement
sensor.kitchen_humidity        # Humidity measurement
sensor.kitchen_pressure        # Pressure measurement

binary_sensor.hallway_motion   # Motion detection
binary_sensor.hallway_occupancy # Occupancy detection

Rule 4: Combination (Both)

binary_sensor.bedroom_window_contact   # Window contact sensor
binary_sensor.bedroom_door_contact     # Door contact sensor

sensor.entryway_lock_battery           # Entryway lock battery
sensor.back_door_lock_battery          # Back door lock battery

select.entryway_paddle_single_tap      # Paddle single tap action
select.entryway_paddle_double_tap      # Paddle double tap action

Complex Functions

Multi-word functions are common for helpers and template sensors. Parse them according to the rules:

Entity ID	Location	Function
`binary_sensor.bedroom_contact`	(none)	`contact`
`input_boolean.bedroom_shade_automation_enabled`	`shade`	`automation_enabled`
`input_number.bedroom_shade_night_position`	`shade`	`night_position`
`sensor.bedroom_shade_reported_position`	`shade`	`reported_position`

Decision Tree for Entity Naming

START: Name my entity

1. Is domain + area unique and clear?
   ├─ YES → DONE: Use neither location nor function
   │  Example: light.office
   └─ NO → Continue to step 2

2. Are multiple entities distinguished by physical location?
   ├─ YES → Add location token
   │  ├─ Is function also needed?
   │  │  ├─ YES → Add both (Rule 4)
   │  │  │  Example: sensor.door_lock_battery
   │  │  └─ NO → Location only (Rule 2)
   │  │     Example: light.bedroom_ceiling
   │  └─ Continue
   └─ NO → Continue to step 3

3. Are multiple entities distinguished by function/measurement?
   ├─ YES → Add function token (Rule 3)
   │  Example: sensor.kitchen_temperature
   └─ NO → Review: You may need both (Rule 4)

4. VERIFY:
   ├─ Is it unique? ✓
   ├─ Is it clear? ✓
   ├─ Does it follow pattern? ✓
   └─ Is it under 50 characters? ✓ (see note below)

DONE: <domain>.<area>_<location>_<function>

Common Entity Types

These are the most frequently used entity types in Home Assistant.

Lights

Pattern: light.<area>_<location>_<function>

Examples:

# Rule 1: Single light in area
light.office
light.bathroom
light.closet

# Rule 2: Multiple lights by location
light.bedroom_ceiling
light.bedroom_bedside
light.bedroom_closet

light.kitchen_island
light.kitchen_countertop
light.kitchen_under_cabinet

# Rule 3: Multiple lights by function
light.living_room_main
light.living_room_accent
light.living_room_reading

# Rule 4: Both location and function
light.bedroom_ceiling_main
light.bedroom_ceiling_accent

Common Patterns:

Ceiling lights: light.<area>_ceiling
Table/desk lamps: light.<area>_<furniture>
Accent lighting: light.<area>_accent
Under-cabinet: light.<area>_under_cabinet
Outdoor: light.front_yard_sconces, light.backyard_floods

See detailed guide: Entity Types Reference

Switches

Pattern: switch.<area>_<location>_<function>

Examples:

# Rule 1: Single switch in area
switch.garage
switch.porch

# Rule 2: Multiple switches by location
switch.kitchen_island
switch.kitchen_countertop
switch.bedroom_outlet

# Rule 3: Multiple switches by function
switch.backyard_lights
switch.backyard_fountain
switch.backyard_christmas_lights

# Rule 4: Both location and function
switch.kitchen_island_outlet
switch.kitchen_countertop_outlet

Common Patterns:

Outlets: switch.<area>_outlet or switch.<area>_<location>_outlet
Lights: switch.<area>_lights (when not using light domain)
Appliances: switch.<area>_<appliance>
Seasonal: switch.<area>_christmas_lights

See detailed guide: Entity Types Reference

Sensors

Pattern: sensor.<area>_<location>_<measurement>

Examples:

# Rule 1: Single sensor type in area
sensor.bedroom_temperature
sensor.kitchen_humidity
sensor.garage_co2

# Rule 2: Multiple sensors by location
sensor.bedroom_window_temperature
sensor.bedroom_door_temperature
sensor.bedroom_closet_temperature

# Rule 3: Multiple measurements (most common)
sensor.bedroom_temperature
sensor.bedroom_humidity
sensor.bedroom_pressure
sensor.bedroom_illuminance

# Rule 4: Both location and measurement
sensor.bedroom_window_temperature
sensor.bedroom_door_temperature

Common Measurements:

Environmental: temperature, humidity, pressure, co2, voc
Light: illuminance, lux, uv_index
Energy: power, energy, voltage, current
Status: battery, signal, rssi, uptime

Multi-Sensor Devices: When a single device provides multiple measurements, use function tokens:

sensor.bedroom_temperature    # From multi-sensor
sensor.bedroom_humidity       # From same device
sensor.bedroom_pressure       # From same device
sensor.bedroom_illuminance    # From same device

See detailed guide: Entity Types Reference

Binary Sensors

Pattern: binary_sensor.<area>_<location>_<detection_type>

Examples:

# Rule 1: Single binary sensor in area
binary_sensor.garage_motion
binary_sensor.basement_leak

# Rule 2: Multiple sensors by location
binary_sensor.bedroom_window
binary_sensor.bedroom_door
binary_sensor.bedroom_closet_door

# Rule 3: Multiple detection types
binary_sensor.hallway_motion
binary_sensor.hallway_occupancy
binary_sensor.hallway_presence

# Rule 4: Both location and detection
binary_sensor.bedroom_window_contact
binary_sensor.bedroom_door_contact

# Rule 4: Camera AI detection
binary_sensor.entryway_doorbell_person    # AI person detection
binary_sensor.entryway_doorbell_visitor   # AI visitor detection
binary_sensor.entryway_doorbell_vehicle   # AI vehicle detection
binary_sensor.entryway_doorbell_pet       # AI pet detection

Common Detection Types:

Movement: motion, occupancy, presence
Contact: contact, door, window
Safety: smoke, co, leak, gas
Status: connectivity, problem, tamper, battery_low
Camera/AI Detection: person, visitor, vehicle, pet, package, animal

Motion vs. Occupancy vs. Presence:

motion - Detects movement (PIR sensor)
occupancy - Detects if area is occupied (may use multiple sensors)
presence - Detects if specific person is present (mmWave, AI)

Camera AI Detection Types:

person - Generic person detected by AI camera
visitor - Visitor/stranger at doorbell (vs known person)
vehicle - Vehicle detected in camera view
pet - Pet/animal detected (doorbell cameras)
animal - Wildlife/animal detected (outdoor cameras)
package - Package delivery detected

For new detection types, use the detection category as the function token (e.g., _face, _license_plate).

See detailed guide: Entity Types Reference

Covers

Pattern: cover.<area>_<location>

Examples:

# Rule 1: Single cover in area
cover.bedroom

# Rule 2: Multiple covers by location
cover.living_room_left_shade
cover.living_room_right_shade
cover.living_room_north_window

# Rule 3: Multiple covers by function (rare)
cover.garage_door
cover.garage_window

See detailed guide: Entity Types Reference

Less Common Entity Types

Media & Entertainment

media_player

Pattern: media_player.<area>_<device>

Examples:

media_player.living_room       # Single media player
media_player.bedroom_tv        # TV
media_player.kitchen_speaker   # Smart speaker
media_player.portable_speaker  # Portable device (no area)

camera

Pattern: camera.<area>_<location>_<view>

Examples:

camera.front_yard              # Outdoor camera
camera.doorbell_main           # Main doorbell view
camera.doorbell_package_view   # Package view
camera.backyard_clear          # High-quality stream
camera.backyard_fluent         # Low-bandwidth stream

remote

Pattern: remote.<area>_<device>

Examples:

remote.living_room_tv          # TV remote
remote.bedroom_ir              # IR blaster
remote.basement_universal      # Universal remote

See detailed guide: Entity Types Reference

Climate & Environment

climate

Pattern: climate.<area>_<location>

Examples:

climate.home                   # Whole-home system
climate.upstairs               # Upstairs zone
climate.upstairs_hallway       # Zone thermostat
climate.bedroom_ac             # Room AC unit

fan

Pattern: fan.<area>_<type>

Examples:

fan.bedroom_ceiling            # Ceiling fan
fan.bathroom_exhaust           # Exhaust fan
fan.office_desk                # Desk fan

weather

Pattern: weather.<location>

Examples:

weather.home                   # Home location
weather.cabin                  # Vacation home
weather.kbfi                   # Weather station

valve

Pattern: valve.<area>_<type>

Examples:

valve.backyard_irrigation      # Irrigation valve
valve.kitchen_water_shutoff    # Water shutoff
valve.utility_room_gas         # Gas shutoff

humidifier

Pattern: humidifier.<area>

Examples:

humidifier.bedroom             # Bedroom humidifier
humidifier.nursery             # Nursery humidifier
humidifier.whole_home          # Whole-home unit

water_heater

Pattern: water_heater.<area>

Examples:

water_heater.home              # Main water heater
water_heater.garage            # Garage water heater
water_heater.cabin             # Vacation home

See detailed guide: Entity Types Reference

Security & Safety

lock

Pattern: lock.<area>

Examples:

lock.entryway                  # Main entry
lock.garage                    # Garage entry
lock.back_door                 # Rear entry
lock.gate                      # Property gate

alarm_control_panel

Pattern: alarm_control_panel.<area>

Examples:

alarm_control_panel.home       # Main security system
alarm_control_panel.garage     # Garage alarm

siren

Pattern: siren.<area>_<location>

Examples:

siren.indoor                   # Indoor siren
siren.outdoor                  # Outdoor siren
siren.garage                   # Garage siren

See detailed guide: Entity Types Reference

Cleaning & Maintenance

vacuum

Pattern: vacuum.<area> or vacuum.<name>

Examples:

vacuum.upstairs                # Upstairs robot
vacuum.downstairs              # Downstairs robot
vacuum.rosie                   # Named robot

lawn_mower

Pattern: lawn_mower.<area>

Examples:

lawn_mower.front_yard          # Front yard mower
lawn_mower.back_yard           # Back yard mower
lawn_mower.mowbot              # Named mower

See detailed guide: Entity Types Reference

Configuration & Control

button

Pattern: button.<device>_<action>

Examples:

button.doorbell_restart        # Restart doorbell
button.router_reboot           # Reboot router
button.garage_door_open        # Open garage

select

Pattern: select.<device>_<setting>

Examples:

select.thermostat_mode         # HVAC mode
select.tv_input                # TV input
select.washer_cycle            # Washer cycle

number

Pattern: number.<device>_<value>

Examples:

number.thermostat_setpoint     # Temperature setpoint
number.motion_delay            # Motion delay
number.brightness_threshold    # Brightness threshold

See detailed guide: Entity Types Reference

Helper Entities

Helper entities (input_* entities) are virtual entities used for automation logic and user input.

When to Include an Area

Helper entities follow the same 4-rule system, but many helpers are area-less because they represent whole-home concepts:

No area needed: Mode toggles, global thresholds, system flags
- input_boolean.guest_mode, input_boolean.away_mode
Area prefix needed: Helpers scoped to a specific room or device
- input_number.rec_room_grow_light_duration, timer.backyard_floodlight_auto_off

Rule of thumb: If the helper controls or tracks something in a specific area, include the area prefix. If it's a global concept, omit it.

Input Booleans

Pattern: input_boolean.<purpose>_<state>

Examples:

input_boolean.guest_mode       # Guest mode toggle
input_boolean.vacation_mode    # Vacation mode
input_boolean.quiet_hours      # Quiet hours flag
input_boolean.notify_when_away # Away notification toggle

Common Patterns:

Mode toggles: input_boolean.<mode>_mode
Feature flags: input_boolean.<feature>_enabled
Status flags: input_boolean.<system>_active

Input Numbers

Pattern: input_number.<purpose>_<value>

Examples:

input_number.temperature_threshold  # Temperature threshold
input_number.motion_timeout         # Motion timeout
input_number.brightness_level       # Brightness setting

Common Patterns:

Thresholds: input_number.<sensor>_threshold
Setpoints: input_number.<device>_setpoint
Delays: input_number.<automation>_delay

Input Selects

Pattern: input_select.<purpose>_<options>

Examples:

input_select.house_mode            # House mode selection
input_select.lighting_scene        # Lighting scene
input_select.notification_priority # Notification priority

Common Patterns:

Mode selections: input_select.<system>_mode
Scene selections: input_select.<area>_scene
Profile selections: input_select.<user>_profile

Input Text

Pattern: input_text.<purpose>_<content>

Examples:

input_text.alarm_message       # Alarm message
input_text.notification_text   # Notification content
input_text.guest_name          # Guest name entry

Input DateTime

Pattern: input_datetime.<event>_<time_aspect>

Examples:

input_datetime.alarm_time      # Alarm time
input_datetime.vacation_start  # Vacation start date
input_datetime.reminder_datetime # Reminder timestamp

Timers

Pattern: timer.<area>_<purpose>

Do not add a _timer suffix — the domain already indicates it's a timer.

Examples:

timer.backyard_floodlight_auto_off    # Floodlight auto-off countdown
timer.living_room_right_shade_movement # Shade movement tracking
timer.laundry_cycle                   # Laundry cycle countdown
timer.kitchen_cooking                 # Kitchen cooking timer

Counters

Pattern: counter.<item>

Do not add a _count suffix — the domain already indicates it's a counter.

Examples:

counter.doorbell_rings         # Doorbell ring counter
counter.coffee_cups            # Coffee consumption
counter.package_deliveries     # Delivery counter

See detailed guide: Entity Types Reference

Automation Naming

Automations connect triggers to actions. The naming pattern reflects this trigger-action relationship.

Core Pattern

automation.<area>_<trigger>_<action>

Components:

area: Where the automation is triggered or primarily operates
trigger: What initiates the automation (event, time, state change)
action: What the automation does (turn on, notify, set scene)

Pattern Categories

Time-Based Automations

Pattern: automation.<area>_<time_event>_<action>

Examples:

automation.bedroom_sunrise_lights_on
automation.exterior_sunset_lights_on
automation.home_midnight_lights_off
automation.living_room_evening_scene_cozy

Common Time Triggers:

sunrise, sunset, dawn, dusk
morning, evening, night, midnight
<time> (e.g., 8pm, 7am, or 24hr: 0700, 2200)

Event-Based Automations

Pattern: automation.<area>_<event>_<action>

Examples:

automation.bedroom_motion_light_on
automation.front_door_opened_notify
automation.garage_door_closed_lock
automation.doorbell_pressed_notify

Common Event Triggers:

Motion: motion, motion_detected, motion_cleared
Contact: opened, closed, door_opened, window_opened
Button: pressed, double_pressed, held
State: on, off, home, away

Button/Controller Automations

Pattern: automation.<area>_<button>_<gesture>_<action>

Examples:

automation.entryway_btn1_pressed_scene_evening
automation.entryway_btn2_pressed_scene_tv
automation.entryway_btn12_double_scene_bright
automation.living_room_pico_on_pressed_lights_on

Gesture Tokens:

pressed - Single tap/press
double - Double tap
triple - Triple tap
held - Long press
released - Button released

Multi-Area Automations

Pattern: automation.<scope>_<trigger>_<action>

Examples:

automation.home_away_mode_lights_off
automation.exterior_sunset_lights_on
automation.upstairs_bedtime_lights_dim

Scope Tokens:

home - Whole home
upstairs/downstairs - Floor level
exterior - All outdoor areas
interior - All indoor areas

Notification Automations

Pattern: automation.notify_<event>

Notification automations send alerts in response to events. Because the "action" is always notification, the entity ID focuses on the triggering event.

Examples:

automation.notify_doorbell_ring
automation.notify_person_detected_at_front_door
automation.notify_backyard_door_opened_while_away
automation.notify_device_offline_daily_digest

Alias Pattern: Notify: <Description>

automation.notify_doorbell_ring:
  alias: "Notify: Doorbell Ring"

automation.notify_device_offline_daily_digest:
  alias: "Notify: Device Offline Daily Digest"

Configuration Automations

Pattern: automation.<area>_<device_function>

Some automations configure device behavior rather than responding to a single trigger-action pair. These include scene controller setups, multi-trigger responders, and device state sync automations.

Examples:

automation.entryway_scene_controller
automation.office_paddle_config
automation.home_presence_sync

These use the Area: Purpose alias pattern (no arrow) since there's no single trigger→action relationship.

Automation Naming Examples

✅ Good Examples:

automation.bedroom_motion_light_on
automation.kitchen_sunset_lights_on
automation.front_door_opened_notify
automation.entryway_btn1_pressed_scene_evening
automation.home_away_mode_all_off
automation.notify_doorbell_ring
automation.entryway_scene_controller

❌ Anti-Patterns:

automation.turn_on_bedroom_light_when_motion  # Too verbose
automation.automation1                         # Not descriptive
automation.bedroom_light                       # Missing trigger
automation.motion_detected                     # Missing area and action

Singular vs. Plural Actions:

Use singular (light_on, light_off) when the automation controls a single light
Use plural (lights_on, lights_off) when controlling multiple lights or a group
Example: automation.office_motion_light_on (one light) vs automation.exterior_sunset_lights_on (all exterior lights)

Decision Tree for Automation Naming

START: Name my automation

1. IDENTIFY TRIGGER AREA
   ├─ Single room? → Use room name
   ├─ Whole home? → Use "home"
   ├─ Floor/level? → Use floor name
   └─ Exterior? → Use "exterior"

2. IDENTIFY TRIGGER TYPE
   ├─ Time-based? → Use time event (sunset, 0700, etc.)
   ├─ Motion? → Use "motion"
   ├─ Button? → Use button identifier (btn1, pico_on, etc.)
   ├─ State change? → Use state (opened, closed, home, away)
   └─ Other event? → Use descriptive trigger

3. IDENTIFY ACTION
   ├─ Control lights? → lights_on, lights_off, lights_dim
   ├─ Activate scene? → scene_<scene_name>
   ├─ Send notification? → notify
   ├─ Run script? → script_<script_name>
   └─ Other? → Use descriptive action

4. COMBINE
   automation.<area>_<trigger>_<action>

5. VERIFY
   ├─ Under 60 characters? ✓ (see note below)
   ├─ Clear trigger? ✓
   ├─ Clear action? ✓
   └─ Follows pattern? ✓

DONE: automation.bedroom_motion_light_on

Character limits: Entity IDs should stay under 50 characters; automation IDs have a 60-character guideline. (Automation IDs include trigger and action components, so they tend to be longer.)

See detailed guide: Automation Naming Reference

Script Naming

Scripts are reusable sequences of actions. The naming pattern emphasizes the action being performed.

Core Pattern

script.<area>_<action>_<qualifier>

Components:

area: Where the script operates (or home for multi-area)
action: What the script does (verb-based)
qualifier: Optional additional context

Pattern Categories

Reusable Scripts

Pattern: script.<area>_<action>

Examples:

script.bedroom_wake_routine
script.kitchen_cleanup_lights
script.home_goodnight_sequence
script.exterior_security_check

One-Off Scripts

Pattern: script.<area>_<specific_action>

Examples:

script.living_room_movie_mode
script.bedroom_reading_light
script.kitchen_dinner_prep

Timed Scripts

Pattern: script.<area>_<action>_<duration>

Examples:

script.bathroom_fan_15min
script.garage_light_5min
script.porch_light_30min

Data Management Scripts

Pattern: script.<system>_<action>_<data>

Examples:

script.system_backup_config
script.system_cleanup_logs
script.system_export_data

Scripts vs. Automations

Use Script When:

Action sequence is reusable
Called by multiple automations
Manual execution needed
Complex logic or sequences
Parameterized actions

Use Automation When:

Triggered by specific event
One-time use case
Simple trigger-action pair
No reusability needed

Example:

# Script: Reusable wake routine
script.bedroom_wake_routine:
  sequence:
    - action: light.turn_on
      target:
        entity_id: light.bedroom_ceiling
      data:
        brightness: 255
    - action: cover.open_cover
      target:
        entity_id: cover.bedroom
    - delay: 00:00:30
    - action: media_player.play_media
      # ...

# Automation: Triggers the script
automation.bedroom_alarm_wake_routine:
  trigger:
    - platform: time
      at: input_datetime.alarm_time
  action:
    - action: script.turn_on
      target:
        entity_id: script.bedroom_wake_routine

Script Naming Examples

✅ Good Examples:

script.bedroom_wake_routine
script.home_goodnight_sequence
script.kitchen_cleanup_lights
script.bathroom_fan_15min
script.system_backup_config

❌ Anti-Patterns:

script.script1                 # Not descriptive
script.do_bedroom_stuff        # Too vague
script.turn_on_lights          # Missing area
script.bedroom                 # Missing action

See detailed guide: Script Naming Reference

Scene Naming

Scenes capture a desired state for multiple entities, optimized for a specific purpose, mood, or time of day.

Core Pattern

scene.<area>_<mood_or_activity>

Components:

area: The scope of the scene (room, floor, or home)
mood_or_activity: The purpose, mood, or activity

Scope Selection

Single-Area Scenes:

scene.bedroom_bright
scene.bedroom_reading
scene.living_room_movie
scene.kitchen_cooking

Multi-Area Scenes:

scene.upstairs_bright          # Entire floor
scene.exterior_evening         # All outdoor
scene.home_away                # Whole home

Purpose Types

Mood-Based (Brightness)

scene.bedroom_bright           # Maximum brightness
scene.bedroom_medium           # Medium brightness
scene.bedroom_dim              # Low brightness
scene.bedroom_night            # Very low/night light

Activity-Based

scene.living_room_movie        # Movie watching
scene.living_room_tv           # TV watching
scene.bedroom_reading          # Reading
scene.kitchen_cooking          # Cooking
scene.office_work              # Working

Time-Based

scene.home_morning             # Morning routine
scene.home_evening             # Evening ambiance
scene.bedroom_bedtime          # Before sleep
scene.kitchen_morning          # Morning kitchen

State-Based

scene.home_away                # Leaving home
scene.home_sleep               # Sleeping
scene.home_all_off             # Everything off
scene.home_all_on              # Everything on

Scene Naming Examples

✅ Good Examples:

scene.bedroom_bright
scene.living_room_movie
scene.home_evening
scene.exterior_night
scene.upstairs_dim

❌ Anti-Patterns:

scene.bright                   # Missing area
scene.tvnew_scene              # Poor naming, redundant "scene"
scene.bedroom_scene_1          # Not descriptive

Important: Verify Scope

Critical: Ensure the area name accurately reflects which entities are affected.

scene.upstairs_bright          # Verify scope! (if it also affects downstairs, use "home_bright")

❌ Bad: scene.upstairs_bright (but affects downstairs too)
✅ Good: scene.home_bright (accurately reflects whole-home scope)

See detailed guide: Scene Naming Reference

Dashboard Naming

Dashboards have multiple naming components: slug (URL), title (display), icon, and filename.

Dashboard Slug

Pattern: <purpose>-dashboard (kebab-case)

Examples:

humidity-dashboard:
  title: "Humidity"
  icon: mdi:water-percent
  filename: dashboards/humidity_dashboard.yaml

security-overview:
  title: "Security"
  icon: mdi:shield-home
  filename: dashboards/security_overview.yaml

Dashboard File Naming

Pattern: dashboards/<purpose>_dashboard.yaml (snake_case)

Examples:

dashboards/humidity_dashboard.yaml
dashboards/security_overview.yaml
dashboards/energy_monitoring.yaml
dashboards/bedroom_controls.yaml

See detailed guide: Configuration Objects Reference

Blueprint Naming

Blueprints are reusable automation/script/template patterns.

Blueprint File Path

Pattern: blueprints/<type>/<source>/<name>.yaml

Examples:

blueprints/automation/homeassistant/motion_light.yaml
blueprints/automation/custom/bedroom_wake_routine.yaml
blueprints/script/homeassistant/confirmable_notification.yaml
blueprints/template/homeassistant/inverted_binary_sensor.yaml

See detailed guide: Configuration Objects Reference

Package Naming

Packages allow modular organization of configuration.

Package File Naming

Pattern: packages/<scope>.yaml

Examples:

packages/climate.yaml          # Climate control
packages/security.yaml         # Security system
packages/living_room.yaml      # Living room config
packages/lutron.yaml           # Lutron integration

See detailed guide: Configuration Objects Reference

Template File Naming

Template files contain template entity definitions.

Template File Naming

Pattern: templates/<purpose>.yaml

Examples:

templates/sensor_templates.yaml
templates/calculations.yaml
templates/climate_templates.yaml
templates/examples.yaml

See detailed guide: Configuration Objects Reference

ESPHome Config Naming

ESPHome device configurations define individual ESP devices.

ESPHome File Naming

Pattern: esphome/<device-type>-<identifier>.yaml (kebab-case)

Examples:

esphome/apollo-msr-2-173d74.yaml    # Device + MAC suffix
esphome/atom-s3-lite-0.yaml         # Device + number
esphome/plug-12.yaml                # Type + number
esphome/sonoff-s31-12.yaml          # Brand + model + number

ESPHome Internal Naming

esphome:
  name: plug12                   # Hostname: no underscores, stable
  friendly_name: "Bedroom Plug"  # Display name: changeable

See detailed guide: Configuration Objects Reference

Multi-Area Entities

Entities that span multiple rooms or the entire home require special area designation.

Whole-Home Entities

Use home when: Entity affects or represents the entire house.

Examples:

climate.home                    # Whole-home HVAC
alarm_control_panel.home        # Security system
weather.home                    # Home weather
sensor.home_average_temperature # Calculated across all rooms
sensor.home_total_power         # Whole-home power

Floor/Level Entities

Use floor names when: Entity affects an entire floor.

Examples:

light.upstairs_all              # All upstairs lights
vacuum.upstairs                 # Upstairs robot vacuum
sensor.downstairs_temperature   # Downstairs zone sensor

Exterior Entities

Use exterior or specific outdoor area:

Examples:

light.front_yard_sconces        # Front yard lights
camera.backyard_clear           # Backyard camera
sensor.exterior_temperature     # General outdoor temp
automation.exterior_sunset_lights_on # All exterior lights

See detailed guide: Edge Cases Reference

Temporary and Seasonal Entities

Lifecycle Prefixes

Use these prefixes to indicate an item's lifecycle status. These are global prefixes that go at the start of the name (after the domain).

temp_ — Truly temporary, safe to delete anytime

Throwaway tests, one-off experiments
No need to save or document
Clean up periodically by searching for temp_

dev_ — In development, not ready for deployment

Work in progress, being actively developed
Keep the work, but don't rely on it yet
Rename to proper name when finished

Examples:

# Temporary - delete whenever
script.temp_test_plug_timer
automation.temp_debug_motion
scene.temp_lighting_experiment

# In development - keep but not production-ready
automation.dev_presence_detection
script.dev_morning_routine
sensor.dev_energy_calculation

Alias pattern: Include status in alias for visibility

automation.dev_garage_presence:
  alias: "[DEV] Garage: Presence Detection"

script.temp_test_delay:
  alias: "[TEMP] Test Delay Script"

Seasonal Decorations

Pattern: <domain>.<area>_<season>_<device>

Examples:

switch.front_yard_christmas_lights
switch.backyard_halloween_lights
light.porch_holiday_lights
automation.exterior_sunset_christmas_lights_on

Guest/Visitor Devices

Pattern: <domain>.<area>_guest_<device> or <domain>.guest_<device>

Examples:

device_tracker.guest_phone_1    # Guest's phone
light.bedroom_guest_lamp        # Temporary guest lamp

See detailed guide: Edge Cases Reference

Disabled Entities

Deprecated Entities

Pattern: Keep original name, disable via the UI

DO NOT modify entity ID:

# ❌ Bad
switch.old_bedroom_light
switch.deprecated_kitchen_fan

Disable deprecated entities through the HA UI (Settings → Devices & services → entity → Disable). Document the deprecation in a code comment or commit message.

# ✅ Good: Disable via the entity registry UI, and document in a comment
# switch.bedroom_light — Deprecated 2025-10-29: Replaced by light.bedroom_ceiling
#   Disabled in entity registry, will be removed after confirming no dependencies

Rationale: Entity ID describes what it IS, not its current state. The entity registry (not YAML) controls the enabled/disabled state.

See detailed guide: Edge Cases Reference

Integration-Specific Patterns

ESPHome Entities

Rename device-generated names to match location:

# Device-generated
sensor.apollo_msr_2_co2
sensor.apollo_msr_2_temperature

# Renamed to location
sensor.kitchen_co2
sensor.kitchen_temperature

Z-Wave/Zigbee Entities

Rename all entities with area prefix, including diagnostics:

# Functional (rename)
light.2_1_dimmer → light.rec_room
sensor.z_wave_thermostat_temperature → sensor.living_temperature

# Diagnostic (also rename with area prefix)
sensor.node_8_rssi       → sensor.rec_room_dimmer_rssi
sensor.node_8_last_seen  → sensor.rec_room_dimmer_last_seen

Area-prefixed diagnostics are easier to find when troubleshooting than opaque node numbers.

Template Entities

Use standard naming, indicate calculation in function:

sensor.indoor_average_humidity  # ✅ Calculated average
binary_sensor.hvac_fan_status   # ✅ Derived status
sensor.home_total_power         # ✅ Sum of all power

DO NOT use template_ prefix:

# ❌ Bad
sensor.template_average_humidity

# ✅ Good
sensor.indoor_average_humidity

See detailed guide: Edge Cases Reference

Learned RF/IR Commands (Broadlink)

Broadlink remotes store learned commands in a two-level structure: device (the physical thing being controlled) and command (the action).

Device naming pattern: <area>_<location>_<device_type>

Follow the same 4-rule system as entities:

Rule 1 (Uniqueness): main_bedroom_fan - only one fan
Rule 2 (Physicality): living_room_left_shade - distinguished by position
Rule 4 (Combination): living_room_north_window_shade - if both location and qualifier needed

Command naming pattern: Simple snake_case action verbs

# Device: living_room_left_shade
up                    # Simple action
down
stop

# Device: living_room_shades (group)
all_up                # Prefixed for group commands
all_down
all_stop

# Device: main_bedroom_fan
off
light_toggle          # Compound action
speed_low
speed_high

Complete structure example:

{
  "living_room_left_shade": {
    "up": "...", "down": "...", "stop": "..."
  },
  "living_room_center_shade": {
    "up": "...", "down": "...", "stop": "..."
  },
  "living_room_shades": {
    "all_up": "...", "all_down": "...", "all_stop": "..."
  },
  "main_bedroom_fan": {
    "off": "...", "light_toggle": "..."
  }
}

Why this structure:

Device name is fully self-documenting (no context needed)
Commands are simple and consistent across devices
Scales cleanly when adding new rooms or device types
Reads naturally in automations: device: living_room_left_shade, command: up

Avoid:

# Bad: Generic device, location in command
"shades": { "left_up": "...", "center_down": "..." }

# Bad: Numbered devices
"shade_1": { "up": "..." }

# Bad: Inconsistent command style
"living_room_shade": { "goUp": "...", "go-down": "..." }

Entity Classification and Rename Priority

Integrations create many entities that serve different purposes. Not all need renaming.

Tier 1: Always Rename (Functional Entities)

Entities you directly control or regularly monitor:

# Lights, physical switches, primary sensors
light.ceiling_501 → light.kitchen_island
switch.wave_1_mini → switch.entryway_exterior
sensor.apollo_msr_2_temperature → sensor.guest_room_temperature

Rename these because:

They appear on dashboards and in voice commands
They're referenced in automations
Clear names improve daily usability

Tier 2: Rename If Needed (Configuration Entities)

Device settings and feature toggles:

# Already has area - KEEP
switch.living_room_crossfade          # Sonos setting, area clear
switch.living_room_night_sound        # Sonos setting, area clear

# Cryptic or used in automations - RENAME
switch.ll_bath_motion_sensor_led_trigger_indicator
  → switch.downstairs_bathroom_motion_led

# Set-and-forget, not in automations - KEEP
switch.doorbell_record_audio          # Configure once, never touch
switch.thermostat_mute                # Rarely changed

Rename if ANY apply:

Used in automations
Appears on user-facing dashboards
Name is cryptic or uses abbreviations
Controlled by voice

Leave as-is if ALL apply:

Set-and-forget setting
Already has area in name
Not used in automations
Integration may recreate on update

Tier 3: Rename with Area Prefix (Diagnostic Entities)

Technical and debug information — rename with area prefix for discoverability:

# Rename diagnostics with area prefix
sensor.node_8_rssi       → sensor.rec_room_dimmer_rssi
sensor.node_8_last_seen  → sensor.rec_room_dimmer_last_seen
update.dimmer_firmware    → update.rec_room_dimmer_firmware
button.node_8_ping       → button.rec_room_dimmer_ping

Rename these because:

Area-prefixed names are easier to find when troubleshooting
Node numbers are opaque and meaningless after device swaps
Consistency with Tier 1/2 entities improves the overall system

Decision Flowchart:

Is it a light, switch, or sensor you directly use?
  → YES: Rename (Tier 1)
  → NO: Continue...

Is it diagnostic/debug info (RSSI, firmware, node ID)?
  → YES: Rename with area prefix (Tier 3)
  → NO: Continue...

Is it used in automations OR has cryptic name?
  → YES: Rename (Tier 2)
  → NO: Keep as-is (Tier 2)

Migration Safety Checklist

CRITICAL: Before renaming ANY entity, complete this checklist:

Pre-Rename Steps

Find all references to the entity being renamed:

# From tools/ directory on HA instance:
make refcheck

# Or locally:
grep -r "old_entity_id" *.yaml dashboards/ .storage/

Update references FIRST in these files (before renaming):
- automations.yaml - automation triggers, conditions, actions
- scenes.yaml - scene entity definitions
- scripts.yaml - script sequences
- dashboards/*.yaml - dashboard cards
- .storage/lovelace.* - UI-managed dashboards
- templates/*.yaml - template sensors/binaries
- customize.yaml - entity customizations

Deploy updated config files to HA:

scp <file>.yaml root@homeassistant.local:/config/

Reload the domains that were updated:

hass-cli service call automation.reload
hass-cli service call scene.reload
hass-cli service call script.reload
hass-cli service call template.reload
hass-cli service call input_boolean.reload
hass-cli service call input_number.reload
hass-cli service call timer.reload

Rename Step

Now rename the entity:

hass-cli entity rename old_entity_id new_entity_id

Update friendly name if needed:

hass-cli raw ws config/entity_registry/update --json='{"entity_id": "new_entity_id", "name": "New Friendly Name"}'

Post-Rename Verification

Test affected automations/scenes to confirm they work

Commit changes to git:

git add -A && git commit -m "rename: old_entity_id → new_entity_id"

If Something Goes Wrong

Restore from snapshot — Take an HA snapshot before starting any batch renames
Re-rename — Use the same rename tool to rename back to the old ID
Check statistics — Developer Tools → Statistics shows orphaned statistic IDs that need cleanup

Common Mistakes to Avoid

Mistake	Consequence	Prevention
Rename entity before updating references	Automations/scenes break immediately	Always update references FIRST
Forget to reload after config changes	HA still uses cached old config	Reload each domain after scp
Miss references in .storage/ files	UI dashboards break	Include .storage/ in grep search
Batch many renames without testing	Hard to identify which broke	Test after each rename or small batch
Rename without migrating statistics	Historical data orphaned under old entity ID	Use Developer Tools → Statistics to update statistic IDs after rename

Virtual and Calculated Entities

Template Sensors

Pattern: Use standard naming, indicate calculation in function token

Examples:

sensor.indoor_average_humidity  # Average across sensors
sensor.home_total_power         # Sum of power sensors
sensor.open_window_count        # Count of open windows
binary_sensor.anyone_home       # Presence aggregation

Function Tokens for Calculations:

average_<measurement> - Mean value
total_<measurement> - Sum
min_<measurement> - Minimum
max_<measurement> - Maximum
<measurement>_count - Count
<measurement>_rate - Rate of change

See detailed guide: Edge Cases Reference

Friendly Names

Friendly names (aliases) are shown in the UI and should use natural language with visual separators.

General Rules:

Use Title Case for proper nouns
Use natural language with spaces
Add qualifiers for duplicates in parentheses
Can differ from entity ID

Area Prefix Rule

Core principle: Use a colon after the area/subject when it applies to everything that follows. Omit the colon and state areas explicitly when they differ.

This applies across all alias types:

Area: ... — area applies to everything (colon groups it)
Area Device: ... — "Area Device" is the subject (no colon between area and device)
Source-Area Thing → Dest-Area Thing — different areas stated explicitly (no colon prefix)

Automation Aliases

Pattern: Trigger → Result with area prefix when areas match

Arrow character: Always use the Unicode arrow → (U+2192), not the ASCII ->. This keeps aliases visually consistent and easy to scan.

Same area (trigger and result in same location):

# Area prefix with colon - applies to both trigger and result
automation.downstairs_bathroom_motion_light_on:
  alias: "Downstairs Bathroom: Motion → Light On"

automation.exterior_sunset_minus_30m_lights_on:
  alias: "Exterior: Sunset Minus 30m → Lights On"

Different areas (trigger in one location, result in another):

# No colon prefix - state each area explicitly
automation.driveway_motion_entryway_lights_on:
  alias: "Driveway Motion → Entryway Lights On"

automation.front_door_open_living_room_alert:
  alias: "Front Door Open → Living Room Alert"

Locationless trigger (time-based, etc.):

# Area prefix refers to result location
automation.exterior_sunrise_plus_20m_lights_off:
  alias: "Exterior: Sunrise Plus 20m → Lights Off"

automation.downstairs_bathroom_8pm_light_dim:
  alias: "Downstairs Bathroom: 8pm → Light Dim"

Configuration Automations

Some automations don't follow the trigger→action pattern because they configure device behavior or handle multiple triggers/actions. These include:

Scene controller setups - Configure button mappings for multi-button devices
Device configuration - Set LED colors, sync states, manage device modes
Multi-trigger responders - React to many inputs with conditional logic

Entity ID Pattern: <area>_<device_function>

Alias Pattern: Area: Purpose (no arrow - no single trigger→action relationship)

Examples:

automation.entryway_scene_controller:
  alias: "Entryway: Scene Controller"

automation.office_paddle_config:
  alias: "Office: Paddle Config"

automation.home_presence_sync:
  alias: "Home: Presence Sync"

automation.system_device_monitor:
  alias: "System: Device Monitor"

When to use:

Blueprint-based automations that configure device behavior
Automations with multiple unrelated triggers
Automations where the "action" is complex conditional logic

Script Aliases

Pattern: Subject: Action where Subject is Area or Area Device

Standard scripts (action in one area):

script.bedroom_wake_routine:
  alias: "Bedroom: Wake Routine"

script.home_goodnight:
  alias: "Home: Goodnight"

script.front_yard_maple_watered:
  alias: "Front Yard: Maple Watered"

Transfer scripts (source → destination, rare):

script.office_music_to_living_room:
  alias: "Office Music → Living Room"

Scene Aliases

Pattern: Subject: State where Subject is Area or Area Device

When the scene controls a specific device type, include it in the subject (no colon between area and device since "Area Device" is a logical unit):

Area only (mood/activity for whole area):

scene.home_dark:
  alias: "Home: Dark"

scene.upstairs_tv:
  alias: "Upstairs: TV"

scene.living_room_movie:
  alias: "Living Room: Movie"

Area + device type (when specifying what's controlled):

scene.upstairs_lights_bright:
  alias: "Upstairs Lights: Bright"

scene.upstairs_lights_medium:
  alias: "Upstairs Lights: Medium"

scene.home_nightlights:
  alias: "Home: Nightlights"  # "nightlights" is the subject, not a device type

Entity Friendly Names

Friendly names are the human-readable labels shown in the Home Assistant UI. Unlike entity IDs (which use underscores and lowercase), friendly names use Title Case with spaces.

Core Principles

Mirror the entity ID structure - The friendly name should be a human-readable version of the entity ID
Use Title Case - Capitalize each word: "Guest Room Temperature" not "guest room temperature"
Use spaces, not underscores - "Backyard Door Contact" not "Backyard_Door_Contact"
Omit the domain - Never include "Sensor", "Binary Sensor", "Light" etc. in the friendly name
Omit redundant words - "Motion" not "Motion Detected", "Person" not "Person Detected"
Be consistent - All entities from the same device should follow the same pattern

The Mapping Rule

Transform entity IDs to friendly names by:

Removing the domain prefix (sensor., binary_sensor., etc.)
Replacing underscores with spaces
Capitalizing each word (Title Case)
Optionally adding context words for clarity

Entity ID                                    → Friendly Name
─────────────────────────────────────────────────────────────────
sensor.guest_room_temperature                → "Guest Room Temperature"
binary_sensor.downstairs_bathroom_motion     → "Downstairs Bathroom Motion"
light.kitchen_island                         → "Kitchen Island"
binary_sensor.entryway_doorbell_person       → "Entryway Doorbell Person"
sensor.upstairs_hallway_thermostat_humidity  → "Upstairs Hallway Thermostat Humidity"

Domain-Specific Patterns

Sensors:

# Environmental measurements
sensor.guest_room_temperature:        "Guest Room Temperature"
sensor.guest_room_humidity:           "Guest Room Humidity"
sensor.guest_room_co2:                "Guest Room CO2"
sensor.guest_room_pressure:           "Guest Room Pressure"

# Battery sensors
sensor.backyard_door_battery:         "Backyard Door Battery"
sensor.attic_switchbot_battery:       "Attic SwitchBot Battery"

# Energy sensors
sensor.guest_room_fan_energy:         "Guest Room Fan Energy"
sensor.downstairs_bathroom_power:     "Downstairs Bathroom Power"

Binary Sensors:

# Motion and occupancy
binary_sensor.garage_motion:                      "Garage Motion"
binary_sensor.rec_room_occupancy:                 "Rec Room Occupancy"
binary_sensor.downstairs_bathroom_motion:         "Downstairs Bathroom Motion"

# Contact sensors
binary_sensor.backyard_door_contact:              "Backyard Door Contact"
binary_sensor.garage_door_contact:                "Garage Door Contact"

# AI camera detection (no "Detected" suffix!)
binary_sensor.entryway_doorbell_person:           "Entryway Doorbell Person"
binary_sensor.entryway_doorbell_vehicle:          "Entryway Doorbell Vehicle"
binary_sensor.backyard_camera_animal:             "Backyard Camera Animal"

# Template/alert sensors
binary_sensor.indoor_humidity_alert:              "Indoor Humidity Alert"

Lights:

# Room lights (location describes physical position)
light.bedroom_ceiling:                "Bedroom Ceiling"
light.kitchen_island:                 "Kitchen Island"
light.living_room_lamp:               "Living Room Lamp"

# Status indicator lights (different from room illumination)
light.guest_room_status:              "Guest Room Status"

Switches:

switch.backyard_christmas_lights:     "Backyard Christmas Lights"
switch.guest_room_fan:                "Guest Room Fan"
switch.entryway_exterior:             "Entryway Exterior"

Device Context Patterns

Multi-Sensor Devices (one device, multiple measurements):

# Apollo MSR-2 in guest room - all share area, differ by function
sensor.guest_room_co2:                "Guest Room CO2"
sensor.guest_room_temperature:        "Guest Room Temperature"
sensor.guest_room_pressure:           "Guest Room Pressure"
sensor.guest_room_light_level:        "Guest Room Light Level"
sensor.guest_room_uv_index:           "Guest Room UV Index"

Embedded Sensors (sensors inside another device like a thermostat):

# Sensors embedded in thermostat - include device as location
sensor.upstairs_hallway_thermostat_temperature:       "Upstairs Hallway Thermostat Temperature"
sensor.upstairs_hallway_thermostat_humidity:          "Upstairs Hallway Thermostat Humidity"
binary_sensor.upstairs_hallway_thermostat_motion:     "Upstairs Hallway Thermostat Motion"
binary_sensor.upstairs_hallway_thermostat_occupancy:  "Upstairs Hallway Thermostat Occupancy"

Camera AI Detection (smart cameras with object detection):

# Doorbell camera - area + device + detection type
binary_sensor.entryway_doorbell_motion:   "Entryway Doorbell Motion"
binary_sensor.entryway_doorbell_person:   "Entryway Doorbell Person"
binary_sensor.entryway_doorbell_visitor:  "Entryway Doorbell Visitor"
binary_sensor.entryway_doorbell_vehicle:  "Entryway Doorbell Vehicle"
binary_sensor.entryway_doorbell_pet:      "Entryway Doorbell Pet"

# Outdoor camera - area + device + detection type
binary_sensor.backyard_camera_motion:     "Backyard Camera Motion"
binary_sensor.backyard_camera_person:     "Backyard Camera Person"
binary_sensor.backyard_camera_vehicle:    "Backyard Camera Vehicle"
binary_sensor.backyard_camera_animal:     "Backyard Camera Animal"

Door/Window Sensors with Measurements:

# Contact sensor with temperature and battery
binary_sensor.backyard_door_contact:      "Backyard Door Contact"
sensor.backyard_door_temperature:         "Backyard Door Temperature"
sensor.backyard_door_battery:             "Backyard Door Battery"

# Window sensor with humidity and temperature
sensor.downstairs_bathroom_window_humidity:            "Downstairs Bathroom Window Humidity"
sensor.downstairs_bathroom_window_temperature:         "Downstairs Bathroom Window Temperature"
sensor.downstairs_bathroom_window_switchbot_battery:   "Downstairs Bathroom Window SwitchBot Battery"

Complex Locations (device at specific location within area):

# Sensor mounted at whole house fan inlet
sensor.upstairs_hallway_whole_house_fan_temperature:  "Upstairs Hallway Whole House Fan Temperature"
sensor.upstairs_hallway_whole_house_fan_humidity:     "Upstairs Hallway Whole House Fan Humidity"
sensor.upstairs_hallway_whole_house_fan_pressure:     "Upstairs Hallway Whole House Fan Pressure"
sensor.upstairs_hallway_whole_house_fan_battery:      "Upstairs Hallway Whole House Fan Battery"

Occupancy Zones (radar with multiple detection zones):

# Zone numbers without underscore in entity ID, with space in friendly name
binary_sensor.guest_room_zone1_occupancy:  "Guest Room Zone 1 Occupancy"
binary_sensor.guest_room_zone2_occupancy:  "Guest Room Zone 2 Occupancy"
binary_sensor.guest_room_zone3_occupancy:  "Guest Room Zone 3 Occupancy"

Anti-Patterns (What NOT to Do)

Don't include "Detected" or "Sensor" suffixes:

# BAD
binary_sensor.backyard_camera_motion:  "Backyard Camera Motion Detected"  ❌
binary_sensor.garage_motion:           "Garage Motion Sensor"             ❌
sensor.kitchen_temperature:            "Kitchen Temperature Sensor"       ❌

# GOOD
binary_sensor.backyard_camera_motion:  "Backyard Camera Motion"           ✓
binary_sensor.garage_motion:           "Garage Motion"                    ✓
sensor.kitchen_temperature:            "Kitchen Temperature"              ✓

Don't include domain in friendly name:

# BAD
binary_sensor.backyard_door_contact:   "Backyard Door Contact Binary Sensor"  ❌
light.bedroom_ceiling:                 "Bedroom Ceiling Light Entity"         ❌

# GOOD
binary_sensor.backyard_door_contact:   "Backyard Door Contact"                ✓
light.bedroom_ceiling:                 "Bedroom Ceiling"                      ✓

Don't include device model or MAC address:

# BAD
sensor.guest_room_co2:                 "Apollo MSR-2 CO2"                     ❌
sensor.guest_room_co2:                 "Guest Room CO2 (173d74)"              ❌

# GOOD
sensor.guest_room_co2:                 "Guest Room CO2"                       ✓

Don't use abbreviations (except well-known ones like CO2, UV):

# BAD
sensor.downstairs_bathroom_temperature:  "DS Bath Temp"                       ❌
binary_sensor.upstairs_hallway_motion:   "UL Hall Motion"                     ❌

# GOOD
sensor.downstairs_bathroom_temperature:  "Downstairs Bathroom Temperature"    ✓
binary_sensor.upstairs_hallway_motion:   "Upstairs Hallway Motion"            ✓

Qualifiers in Parentheses

Use parentheses when you need to add disambiguation or context that doesn't fit the standard pattern:

# Disambiguating similar entities
light.bedroom_lamp:           "Bedroom Lamp (Bedside)"      # Which lamp?
light.bedroom_floor_lamp:     "Bedroom Lamp (Floor)"

# Clarifying purpose
light.guest_room_status:      "Guest Room Status (RGB)"     # Not for illumination

# Brand identification when needed for battery sensors
sensor.attic_switchbot_battery:  "Attic SwitchBot Battery"  # vs other batteries

See also: naming_examples.md for comprehensive real-world examples from 106 entity migrations.

Devices

Device names can include brand, model, and location information.

Pattern: <Brand> <Model> or <Brand> <Model> – <Location>

Examples:

Hue Bulb                       # Brand + model
Hue Bulb – Office              # With location
Sonos Roam                     # Portable device
Apollo MSR-2                   # Sensor device
Zooz ZEN32 Scene Controller    # Controller device

Device vs. Entity Naming:

Devices can have technical names
Entities should be user-friendly
Entities inherit from device but can be renamed

See detailed guide: Edge Cases Reference

Quick Reference Tables

Entity Type Patterns

Entity Type	Pattern	Example
light	`light.<area>_<location>`	`light.bedroom_ceiling`
switch	`switch.<area>_<location>_<function>`	`switch.kitchen_island_outlet`
sensor	`sensor.<area>_<location>_<measurement>`	`sensor.bedroom_temperature`
binary_sensor	`binary_sensor.<area>_<location>_<detection>`	`binary_sensor.hallway_motion`
media_player	`media_player.<area>_<device>`	`media_player.living_room_tv`
camera	`camera.<area>_<location>`	`camera.front_yard`
climate	`climate.<area>`	`climate.home`
fan	`fan.<area>_<type>`	`fan.bedroom_ceiling`
lock	`lock.<area>`	`lock.entryway`
cover	`cover.<area>_<location>`	`cover.living_room_left_shade`
vacuum	`vacuum.<area>`	`vacuum.upstairs`
valve	`valve.<area>_<type>`	`valve.backyard_irrigation`
humidifier	`humidifier.<area>`	`humidifier.bedroom`
water_heater	`water_heater.<area>`	`water_heater.home`
automation	`automation.<area>_<trigger>_<action>`	`automation.bedroom_motion_light_on`
script	`script.<area>_<action>`	`script.bedroom_wake_routine`
scene	`scene.<area>_<mood>`	`scene.living_room_movie`

Helper Entity Patterns

Helper Type	Pattern	Example
input_boolean	`input_boolean.<mode>_mode`	`input_boolean.guest_mode`
input_number	`input_number.<purpose>_<value>`	`input_number.temperature_threshold`
input_select	`input_select.<purpose>_<options>`	`input_select.house_mode`
input_text	`input_text.<purpose>_<content>`	`input_text.alarm_message`
input_datetime	`input_datetime.<event>_<aspect>`	`input_datetime.alarm_time`
timer	`timer.<area>_<purpose>`	`timer.backyard_floodlight_auto_off`
counter	`counter.<item>`	`counter.doorbell_rings`

Common Location Tokens

Furniture and Fixtures

Token	Meaning	Example
`ceiling`	Ceiling-mounted	`light.bedroom_ceiling`
`wall`	Wall-mounted	`switch.kitchen_wall`
`floor`	Floor-level	`light.bedroom_floor`
`desk`	Desk/table	`light.office_desk`
`bedside`	Beside bed	`light.bedroom_bedside`
`nightstand`	Nightstand	`light.bedroom_nightstand`
`table`	Table	`light.living_room_table`

Architectural Elements

Token	Meaning	Example
`window`	Window	`binary_sensor.bedroom_window`
`door`	Door	`binary_sensor.front_door`
`chandelier`	Chandelier	`light.entryway_chandelier`
`sconce`	Wall sconce	`light.front_yard_sconces`
`pendant`	Pendant light	`light.kitchen_pendant`
`recessed`	Recessed light	`light.living_room_recessed`

Appliances and Features

Token	Meaning	Example
`island`	Kitchen island	`switch.kitchen_island`
`countertop`	Countertop	`switch.kitchen_countertop`
`under_cabinet`	Under cabinet	`light.kitchen_under_cabinet`
`stove`	Stove/range	`sensor.kitchen_stove`
`sink`	Sink	`sensor.kitchen_sink`
`exhaust`	Exhaust fan	`fan.bathroom_exhaust`

Directions and Positions

Token	Meaning	Example
`north`	North side	`cover.living_room_north`
`south`	South side	`cover.living_room_south`
`east`	East side	`cover.bedroom_east`
`west`	West side	`cover.bedroom_west`
`left`	Left side	`light.bedroom_left`
`right`	Right side	`light.bedroom_right`
`front`	Front	`camera.front`
`back`	Back	`camera.back`

Device Components

Token	Meaning	Example
`paddle`	Main paddle/rocker	`select.entryway_paddle_single_tap`
`button1`	Button 1	`switch.entryway_button1_indication`
`button2`	Button 2	`switch.entryway_button2_indication`
`relay1`	Relay 1	`switch.garage_relay1`
`zone1`	Zone 1	`binary_sensor.kitchen_zone1_occupancy`

Common Function Tokens

Measurements

Token	Meaning	Unit	Example
`temperature`	Temperature	°F/°C	`sensor.bedroom_temperature`
`humidity`	Relative humidity	%	`sensor.kitchen_humidity`
`pressure`	Barometric pressure	hPa/inHg	`sensor.office_pressure`
`illuminance`	Light level	lux	`sensor.hallway_illuminance`
`co2`	CO2 level	ppm	`sensor.bedroom_co2`
`voc`	Volatile organic compounds	ppb	`sensor.living_room_voc`
`pm25`	Particulate matter 2.5	µg/m³	`sensor.bedroom_pm25`

Energy and Power

Token	Meaning	Unit	Example
`power`	Current power	W	`sensor.kitchen_power`
`energy`	Energy consumption	kWh	`sensor.home_energy`
`voltage`	Voltage	V	`sensor.outlet_voltage`
`current`	Current	A	`sensor.outlet_current`

Detection and Status

Token	Meaning	Type	Example
`motion`	Motion detected	binary	`binary_sensor.hallway_motion`
`occupancy`	Area occupied	binary	`binary_sensor.bedroom_occupancy`
`presence`	Person present	binary	`binary_sensor.office_presence`
`contact`	Contact sensor	binary	`binary_sensor.door_contact`
`leak`	Water leak	binary	`binary_sensor.bathroom_leak`
`smoke`	Smoke detected	binary	`binary_sensor.kitchen_smoke`
`battery`	Battery level	%	`sensor.sensor_battery`
`signal`	Signal strength	dBm	`sensor.device_signal`

Actions and Controls

Token	Meaning	Example
`restart`	Restart device	`button.doorbell_restart`
`reboot`	Reboot device	`button.router_reboot`
`identify`	Identify device	`button.switch_identify`
`ping`	Ping device	`button.node_ping`
`mode`	Mode selection	`select.thermostat_mode`
`preset`	Preset selection	`select.fan_preset`
`scene`	Scene selection	`select.lighting_scene`

Calculations

Token	Meaning	Example
`average`	Mean value	`sensor.indoor_average_temperature`
`total`	Sum	`sensor.home_total_power`
`min`	Minimum	`sensor.home_min_temperature`
`max`	Maximum	`sensor.home_max_temperature`
`count`	Count	`sensor.open_window_count`
`rate`	Rate of change	`sensor.temperature_rate`

Pattern Summary

Entity ID Patterns

# Basic pattern
<domain>.<area>_<optional_location>_<optional_function>

# Automation pattern
automation.<area>_<trigger>_<action>

# Script pattern
script.<area>_<action>_<qualifier>

# Scene pattern
scene.<area>_<mood_or_activity>

# Helper pattern
input_<type>.<purpose>_<descriptor>

File Naming Patterns

# Dashboard files (snake_case)
dashboards/<purpose>_dashboard.yaml

# Blueprint files (snake_case)
blueprints/<type>/<source>/<name>.yaml

# Package files (snake_case)
packages/<scope>.yaml

# Template files (snake_case)
templates/<purpose>.yaml

# ESPHome files (kebab-case)
esphome/<device-type>-<id>.yaml

# Theme files (snake_case)
themes/<theme_name>.yaml

Slug Patterns

# Dashboard slugs (kebab-case)
<purpose>-dashboard

# Examples
humidity-dashboard
security-overview
bedroom-controls

Example: Scene Controller (Zooz ZEN32)

This comprehensive example demonstrates how the 4-rule system applies to a complex, real-world device with multiple entity types.

Device Overview

Device: Zooz ZEN32 Scene Controller
Location: Entryway
Function: Controls chandelier + 4 scene buttons

Load (Wired Chandelier)

Rule 2: Physicality (Location Only)

light.entryway_chandelier

domain: light
area: entryway
location: chandelier (The "Which" - distinguishes from other lights)
function: (none - the domain implies it's a light)

Rationale: Multiple lights could exist in entryway, so location distinguishes this specific fixture.

Controller Settings

The ZEN32 exposes many configuration entities for the paddle and buttons.

Paddle Configuration

Rule 4: Combination (Both Location and Function)

select.entryway_paddle_single_tap

domain: select
area: entryway
location: paddle (The "Which" component)
function: single_tap (The "What" action being configured)

select.entryway_paddle_double_tap

domain: select
area: entryway
location: paddle
function: double_tap

Rationale: Must specify which component (paddle vs. buttons) AND which action (single vs. double tap).

Button Configuration

Rule 4: Combination (Both Location and Function)

switch.entryway_button1_indication

domain: switch
area: entryway
location: button1 (The "Which" button)
function: indication (The "What" attribute - LED indication)

select.entryway_button1_led_color

domain: select
area: entryway
location: button1
function: led_color

switch.entryway_button2_indication

domain: switch
area: entryway
location: button2
function: indication

Rationale: Must specify which button (1-4) AND which attribute (indication, LED color, etc.).

Device-Wide Settings

Rule 3: Purpose (Function Only)

number.entryway_local_dimming_speed

domain: number
area: entryway
location: (none - applies to whole device)
function: local_dimming_speed (The "What" setting)

Rationale: Setting applies to entire device, not specific component, so only function is needed.

Device Identity

Rule 2: Physicality (Location Only)

update.entryway_scene_controller

domain: update
area: entryway
location: scene_controller (The "Which" device)
function: (none - update domain implies firmware/software)

button.entryway_scene_controller_identify

domain: button
area: entryway
location: scene_controller
function: identify (The "What" action)

Automations (Binding Gestures to Actions)

Automations connect the scene controller buttons to actions.

Pattern: automation.<area>_<button>_<gesture>_<action>

automation.entryway_btn1_pressed_scene_evening

area: entryway (where controller is located)
trigger: btn1_pressed (button 1 single press)
action: scene_evening (activates evening scene)

Alternative (more concise): automation.entryway_btn1_press_set_home_evening

More Examples:

automation.entryway_btn2_pressed_scene_tv
automation.entryway_btn3_pressed_scene_night
automation.entryway_btn4_pressed_scene_all_off
automation.entryway_btn12_double_scene_bright
automation.entryway_paddle_double_chandelier_30pct

Gesture Tokens

Recommended gesture tokens for button automations:

Gesture	Token	Example
Single press	`pressed`	`automation.entryway_btn1_pressed_scene_evening`
Double press	`double`	`automation.entryway_btn12_double_scene_bright`
Triple press	`triple`	`automation.bedroom_btn1_triple_scene_bright`
Quadruple press	`quad`	`automation.living_btn1_quad_scene_party`
Quintuple press	`quint`	`automation.office_btn1_quint_scene_focus`
Long press	`held`	`automation.bedroom_btn1_held_lights_dim`
Release	`released`	`automation.bedroom_btn1_released_lights_stop`

Complete Entity List

Summary of all ZEN32 entities following the 4-rule system:

# Load
light.entryway_chandelier                    # Rule 2

# Paddle configuration
select.entryway_paddle_single_tap            # Rule 4
select.entryway_paddle_double_tap            # Rule 4
select.entryway_paddle_held                  # Rule 4
select.entryway_paddle_released              # Rule 4

# Button 1 configuration
switch.entryway_button1_indication           # Rule 4
select.entryway_button1_led_color            # Rule 4
number.entryway_button1_led_brightness       # Rule 4

# Button 2-4 configuration (similar pattern)
switch.entryway_button2_indication           # Rule 4
switch.entryway_button3_indication           # Rule 4
switch.entryway_button4_indication           # Rule 4

# Device-wide settings
number.entryway_local_dimming_speed          # Rule 3
number.entryway_remote_dimming_speed         # Rule 3
select.entryway_switch_type                  # Rule 3

# Device identity
update.entryway_scene_controller             # Rule 2
button.entryway_scene_controller_identify    # Rule 4

# Automations
automation.entryway_btn1_pressed_scene_evening
automation.entryway_btn2_pressed_scene_tv
automation.entryway_btn3_pressed_scene_night
automation.entryway_btn4_pressed_scene_all_off
automation.entryway_btn12_double_scene_bright
automation.entryway_paddle_double_chandelier_30pct

Detailed Documentation

For comprehensive coverage of all patterns, examples, and edge cases, see the detailed reference documentation:

Core References

Automation Naming Reference (1,826 lines)
- Complete automation patterns with trigger-action structure
- Analysis of existing automations with proposed improvements
- Decision trees and comprehensive examples
- Button/controller automation patterns
- Multi-area automation handling
Script Naming Reference (2,627 lines)
- Complete script patterns using action-oriented approach
- Analysis of existing scripts
- Scripts vs. automations decision guidance
- Reusable vs. one-off script patterns
- Parameterized script naming
Scene Naming Reference (2,483 lines)
- Complete scene patterns with area and mood/activity structure
- Analysis of existing scenes with proposed improvements
- Mood-based, activity-based, and time-based patterns
- Multi-area scene handling
- Scene-automation integration
Entity Types Reference (884 lines)
- Patterns for 35+ entity types
- Integration-specific patterns (ESPHome, Z-Wave, Zigbee, MQTT)
- Helper entity patterns
- System entity patterns
- Migration examples from real inventory
Configuration Objects Reference (1,545 lines)
- Dashboard naming (slug, title, icon, file)
- Blueprint naming and organization
- Package, template, and ESPHome config naming
- File organization strategies
- Version control considerations
Edge Cases Reference (2,445 lines)
- Multi-area entity patterns
- Temporary and seasonal entity handling
- Disabled entity documentation
- Integration-specific edge cases
- Virtual and calculated entity patterns
- Migration and legacy entity handling
- Conflict resolution strategies

Quick Navigation

By Topic:

Need automation patterns? → Automation Reference
Need script patterns? → Script Reference
Need scene patterns? → Scene Reference
Need entity type patterns? → Entity Types Reference
Need configuration object patterns? → Configuration Objects Reference
Need edge case guidance? → Edge Cases Reference

By Entity Type:

Lights, switches, sensors → Entity Types Reference
Media players, cameras → Entity Types Reference
Climate, fans, weather → Entity Types Reference
Locks, alarms, sirens → Entity Types Reference
Helpers (input_*) → Entity Types Reference

By Situation:

Multi-area entities → Edge Cases Reference
Temporary/seasonal → Edge Cases Reference
Disabled/deprecated → Edge Cases Reference
ESPHome/Z-Wave/MQTT → Edge Cases Reference
Virtual/calculated → Edge Cases Reference

Best Practices

General Guidelines

Be Consistent: Use the same patterns across similar entities
Be Clear: Names should be immediately understandable
Be Concise: Keep entity IDs under 50 characters when possible
Be Specific: Use descriptive tokens, avoid generic names
Be Systematic: Follow the 4-rule system deterministically

Naming Checklist

Before finalizing an entity name, verify:

Common Mistakes to Avoid

❌ Don't:

Use brand names as primary identifier: sensor.aqara_temperature
Include model numbers: light.hue_bulb_gen3
Use spaces or hyphens: sensor.bedroom-temperature
Mix casing: sensor.BedroomTemperature
Be too generic: sensor.sensor1, light.light
Be too verbose: sensor.bedroom_temperature_sensor_reading
Include implementation details: sensor.template_average_temp
Use ambiguous terms: sensor.bedroom_temp1

✅ Do:

Use location-based names: sensor.bedroom_temperature
Keep it simple: light.bedroom_ceiling
Use underscores: sensor.bedroom_temperature
Use lowercase: sensor.bedroom_temperature
Be descriptive: sensor.bedroom_temperature
Be concise: sensor.bedroom_temp (if needed)
Focus on purpose: sensor.indoor_average_temperature
Use clear terms: sensor.bedroom_temperature_main

Migration Guide

Renaming Existing Entities

When renaming entities to follow these conventions:

Plan: Document current names and proposed new names
Map: Create mapping of old → new entity IDs
Find: Use tools to find all references (automations, scripts, scenes, dashboards)
Update: Update all references to use new names
Test: Verify all automations and scripts still work
Commit: Commit changes to version control

Tools Available

export_entities.py - Export entity inventory
propose_ids.py - Generate compliant entity IDs
find_references.py - Find entity references
ws_rename_entities.py - Rename entities via WebSocket

Migration Playbook

See tools/migration_playbook.md for detailed migration procedures.

Validation

Automated Validation

Use the provided tools to validate entity naming:

# Export current entities
python tools/export_entities.py

# Generate proposed compliant names
python tools/propose_ids.py

# Find references before renaming
python tools/find_references.py <entity_id>

# Rename entities
python tools/ws_rename_entities.py

Manual Validation

Check each entity against the 4-rule system:

Rule 1: Is domain + area unique? If yes, stop.
Rule 2: Do multiple entities differ by location? If yes, add location.
Rule 3: Do multiple entities differ by function? If yes, add function.
Rule 4: Need both? Add both in order: location then function.

Appendix A: Complete Pattern Reference

Note: This appendix summarizes patterns from the main document. If there is a discrepancy, the main document sections take precedence.

All Entity Patterns

# Core entities
light.<area>_<location>
switch.<area>_<location>_<function>
sensor.<area>_<location>_<measurement>
binary_sensor.<area>_<location>_<detection>

# Media & entertainment
media_player.<area>_<device>
camera.<area>_<location>_<view>
remote.<area>_<device>

# Climate & environment
climate.<area>_<location>
fan.<area>_<type>
weather.<location>

# Security & safety
lock.<area>
alarm_control_panel.<area>
siren.<area>_<location>

# Cleaning
vacuum.<area>
lawn_mower.<area>

# Configuration & control
button.<device>_<action>
select.<device>_<setting>
number.<device>_<value>
text.<device>_<purpose>

# System
update.<device>_<component>
event.<device>_<trigger>
conversation.<assistant>_<area>
image.<source>_<content>

# Helpers
input_boolean.<purpose>_<state>
input_number.<purpose>_<value>
input_select.<purpose>_<options>
input_text.<purpose>_<content>
input_datetime.<event>_<aspect>
timer.<area>_<purpose>                    # e.g., timer.backyard_floodlight_auto_off
counter.<item>                             # e.g., counter.doorbell_rings

# Location & presence
zone.<location>
person.<name>
device_tracker.<identifier>

# Automations, scripts, scenes
automation.<area>_<trigger>_<action>
script.<area>_<action>_<qualifier>
scene.<area>_<mood_or_activity>

Appendix B: Area Definitions

Standard Areas

Indoor Areas:

bedroom, master_bedroom, guest_bedroom
living_room, family_room, rec_room
kitchen, dining_room
bathroom, master_bathroom, guest_bathroom
office, study
hallway, entryway, foyer
closet, pantry, laundry_room
garage, basement, attic

Outdoor Areas:

front_yard, backyard
driveway, porch, deck, patio
garden, shed, garage_exterior

Multi-Area Designations:

home           # Whole home
upstairs       # Upper floor
downstairs     # Lower floor
exterior       # All outdoor
interior       # All indoor

Area Assignment Rules

Single Room: Use specific room name
Multiple Rooms: Use primary room or combined name
Entire Floor: Use floor name (upstairs, downstairs)
Whole Home: Use home
Exterior: Use exterior or specific outdoor area
No Physical Location: Use system or omit area

Appendix C: Token Guidelines

Location Token Guidelines

Use location tokens when:

Multiple entities of same type in area
Physical location is distinguishing factor
Location is meaningful and stable

Location token should be:

A noun (the "Which")
Physical place or component
Stable (doesn't change frequently)
Specific enough to distinguish

Examples:

✅ ceiling, bedside, window, door, island
❌ thing1, device, sensor, switch

Function Token Guidelines

Use function tokens when:

Multiple entities differ by purpose
Measurement or action is distinguishing factor
Function is more meaningful than location

Function token should be:

A verb or attribute (the "What")
Describes purpose or measurement
Clear and specific
Standard terminology when possible

Examples:

✅ temperature, motion, battery, restart
❌ thing, data, value, status1

Multi-Word Tokens

When tokens need multiple words:

Use underscores to connect: under_cabinet, led_color, single_tap
Keep concise: prefer temp over temperature if length is issue
Be consistent: use same terms across similar entities

Examples:

✅ under_cabinet, led_color, single_tap, automation_enabled
❌ undercabinet, ledcolor, singletap, automationenabled

Appendix D: Special Situations

When Area is Ambiguous

Scenario: Entity could belong to multiple areas.

Solution: Use the primary or most frequently associated area.

Example:

# Sensor in open-concept living/kitchen
sensor.living_room_temperature  # Use primary area
# OR
sensor.living_kitchen_temperature # Use combined area

When Function is Complex

Scenario: Function requires multiple words.

Solution: Use underscores to connect words, keep as concise as possible.

Examples:

input_boolean.bedroom_shade_automation_enabled
input_number.bedroom_shade_night_position
sensor.bedroom_shade_reported_position
number.entryway_local_dimming_speed

When Both Location and Function are Long

Scenario: Both location and function are multi-word.

Solution: Consider abbreviations or restructuring.

Examples:

# Long but acceptable
number.rec_room_light_dimming_speed_up_remote

# Consider abbreviating if too long
number.rec_room_light_dim_speed_up_remote

# Or restructure
number.rec_room_dimmer_speed_up_remote

Appendix E: Integration-Specific Guidance

ESPHome Devices

Strategy: Rename entities to match physical location.

Before:

sensor.apollo_msr_2_173d74_co2
sensor.apollo_msr_2_173d74_temperature
binary_sensor.apollo_msr_2_173d74_occupancy

After:

sensor.kitchen_co2
sensor.kitchen_temperature
binary_sensor.kitchen_occupancy

See: Integration-Specific Patterns for the authoritative guide; Edge Cases Reference for complete ESPHome guidance.

Z-Wave/Zigbee Devices

Strategy: Rename all entities with area prefix, including diagnostics.

Functional (rename):

light.2_1_dimmer → light.rec_room
sensor.z_wave_thermostat_temperature → sensor.living_temperature

Diagnostic (also rename with area prefix):

sensor.node_8_rssi       → sensor.rec_room_dimmer_rssi
sensor.node_8_last_seen  → sensor.rec_room_dimmer_last_seen

See: Integration-Specific Patterns for the authoritative guide; Edge Cases Reference for complete Z-Wave guidance.

MQTT Entities

Strategy: Configure with proper names from the start.

Manual Configuration:

mqtt:
  sensor:
    - name: "Garage Temperature"
      unique_id: garage_temperature
      state_topic: "home/garage/temperature"

See: Edge Cases Reference for complete MQTT guidance.

Template Entities

Strategy: Use standard naming, indicate calculation in function.

Examples:

sensor.indoor_average_humidity  # ✅ Calculated average
binary_sensor.hvac_fan_status   # ✅ Derived status
sensor.home_total_power         # ✅ Sum of all power

DO NOT use template_ prefix:

❌ sensor.template_average_humidity
✅ sensor.indoor_average_humidity

See: Integration-Specific Patterns for the authoritative guide; Edge Cases Reference for complete template guidance.

Appendix F: Troubleshooting

Common Issues and Solutions

Issue: Entity ID Too Long

Problem: Entity ID exceeds 50 characters.

Solutions:

Abbreviate long words: temperature → temp, humidity → humid
Remove redundant words: light.bedroom_ceiling_light → light.bedroom_ceiling
Simplify location: light.bedroom_left_hand_side → light.bedroom_left
Restructure: sensor.bedroom_window_contact_battery → sensor.bedroom_window_battery

Issue: Duplicate Names

Problem: Two entities want the same name.

Solutions:

Add location token: light.bedroom → light.bedroom_ceiling, light.bedroom_bedside
Add function token: sensor.kitchen → sensor.kitchen_temperature, sensor.kitchen_humidity
Add qualifier: sensor.bedroom_temperature → sensor.bedroom_temperature_main, sensor.bedroom_temperature_backup

Issue: Unclear Which Rule Applies

Problem: Not sure which rule to use.

Solution: Work through the decision tree:

Is domain + area unique? → Rule 1
Differ by location? → Rule 2
Differ by function? → Rule 3
Need both? → Rule 4

Issue: Integration Creates Bad Names

Problem: Integration creates entities with poor names.

Solutions:

ESPHome: Configure entity names in ESPHome YAML
Z-Wave/Zigbee: Rename via UI after inclusion
MQTT: Use discovery with proper naming
Templates: Define with compliant IDs from start

See: Edge Cases Reference for integration-specific solutions.

Appendix G: Version History

Version 2.1 (2026-03-12)

Fixed timer/counter suffix patterns (removed redundant _timer/_count)
Added notification automation pattern
Added configuration automation entity ID pattern
Standardized alias arrow character (→)
Fixed contradictions between main doc and appendices
Updated service: to action: in YAML examples

Version 2.0 (2025-10-29)

Major Update: Comprehensive specification with detailed reference documentation.

Changes:

Added Quick Start Guide for rapid onboarding
Expanded entity type coverage from 9 to 35+ types
Added comprehensive automation naming patterns
Added comprehensive script naming patterns
Added comprehensive scene naming patterns
Added configuration object naming (dashboards, blueprints, etc.)
Added edge case documentation
Created detailed reference documentation (6 files, 11,000+ lines)
Added decision trees and flowcharts
Added quick reference tables
Added migration guidance
Added validation tools documentation

Structure:

Main specification: ~3,500 lines (this file)
Detailed references: 6 files, 11,000+ lines total
Hybrid approach: Quick reference here, comprehensive details in references

Version 1.0 (Original)

Initial specification:

Core 4-rule system
Basic entity ID patterns
Light, switch, sensor, binary_sensor examples
Scene controller example
184 lines

Appendix H: Contributing

Proposing Changes

To propose changes to this naming specification:

Document: Clearly describe the proposed change
Justify: Explain why the change is needed
Examples: Provide before/after examples
Impact: Assess impact on existing entities
Review: Submit for review and discussion

Reporting Issues

If you find issues with the naming specification:

Describe: Clearly describe the issue
Example: Provide specific example
Expected: Describe expected behavior
Actual: Describe actual behavior
Suggest: Suggest potential solution

Appendix I: Glossary

Key Terms

Area: Physical room or zone in Home Assistant (e.g., bedroom, kitchen, exterior)

Location Token: The "Which" - Physical place or component (noun) that distinguishes entities by position

Function Token: The "What" - Purpose, measurement, or attribute (verb/attribute) that distinguishes entities by function

Domain: Entity type in Home Assistant (e.g., light, sensor, switch)

Entity ID: Unique identifier for an entity (e.g., light.bedroom_ceiling)

Friendly Name: Human-readable name shown in UI (e.g., "Bedroom Ceiling")

Slug: URL-friendly identifier (e.g., humidity-dashboard)

Helper Entity: Virtual entity for automation logic (input_boolean, input_number, etc.)

Template Entity: Virtual entity created through templates (calculated, derived, aggregated)

Multi-Area Entity: Entity affecting multiple rooms or entire home

Virtual Entity: Entity not representing physical device (template, group, aggregation)

Naming Conventions

snake_case: Lowercase with underscores (e.g., bedroom_ceiling, file_name.yaml)

kebab-case: Lowercase with hyphens (e.g., humidity-dashboard, device-name)

Title Case: Capitalize main words (e.g., "Bedroom Ceiling", "Motion Activated")

UPPERCASE: All capitals (avoid in entity IDs)

camelCase: First word lowercase, subsequent words capitalized (avoid in entity IDs)

Appendix J: FAQ

Frequently Asked Questions

Q: Should I rename all my existing entities?

A: Not necessarily. Focus on:

New entities (follow conventions from start)
Problematic entities (confusing, inconsistent)
High-impact entities (frequently used in automations)
Gradual migration (rename as you touch entities)

Q: What if my entity name is too long?

A: Options:

Abbreviate long words (temperature → temp)
Remove redundant words
Simplify location/function tokens
Restructure the name
Accept longer names if clarity is important

Q: Can I use hyphens in entity IDs?

A: No. Entity IDs must use underscores only. Use hyphens only in:

Dashboard slugs (kebab-case)
ESPHome hostnames (kebab-case)
File names (can use either, but prefer snake_case)

Q: Should I include brand names in entity IDs?

A: Generally no. Use location-based names instead:

❌ sensor.aqara_temperature
✅ sensor.bedroom_temperature

Exception: When brand is the distinguishing factor:

✅ media_player.sonos_roam (portable, brand is identifier)

Q: How do I name entities from multi-sensor devices?

A: Rename each sensor individually to match location + measurement:

sensor.apollo_msr_2_co2 → sensor.kitchen_co2
sensor.apollo_msr_2_temperature → sensor.kitchen_temperature
sensor.apollo_msr_2_humidity → sensor.kitchen_humidity

Q: What about entities that move (mobile devices)?

A: Don't use area tokens for mobile entities:

✅ device_tracker.ben_iphone
✅ device_tracker.nicole_iphone
❌ device_tracker.bedroom_ben_iphone

Q: How do I name whole-home entities?

A: Use home as the area:

✅ climate.home
✅ alarm_control_panel.home
✅ sensor.home_average_temperature

Q: Should scenes include the word "scene"?

A: No, the domain already indicates it's a scene:

❌ scene.bedroom_scene_bright
✅ scene.bedroom_bright

Q: How do I name automations that activate scenes?

A: Include "scene" in the action:

✅ automation.entryway_btn1_pressed_scene_evening
✅ automation.bedroom_bedtime_scene_dim

Q: What if I have multiple temperature sensors in one room?

A: Use location tokens to distinguish:

sensor.bedroom_window_temperature
sensor.bedroom_door_temperature
sensor.bedroom_ceiling_temperature

Q: How do I name disabled/deprecated entities?

A: Keep original name. Disable via the HA UI (Settings → Devices & services → entity → Disable) and document in a comment:

# switch.bedroom_light — Deprecated 2025-10-29: Replaced by light.bedroom_ceiling
#   Disabled in entity registry, will be removed after confirming no dependencies

Q: Can I use numbers in entity IDs?

A: Yes, but prefer descriptive names:

⚠️ Acceptable: light.bedroom_1, light.bedroom_2
✅ Better: light.bedroom_ceiling, light.bedroom_bedside

Q: How do I name template/virtual entities?

A: Use standard naming, don't add template_ or virtual_ prefix:

❌ sensor.template_average_temperature
✅ sensor.indoor_average_temperature

Q: What about seasonal entities like Christmas lights?

A: Include season in name or use tags:

✅ switch.front_yard_christmas_lights
✅ switch.front_yard_lights (with tags: [seasonal, christmas])

Q: How do I handle entities during migration?

A: Run old and new in parallel, then deprecate old:

Create new entity with proper name
Run both for testing period
Update all references
Disable old entity
Delete after grace period

Appendix K: Resources

Documentation

Main Specification: This file (naming.md)
Automation Reference: naming/reference/automations_detailed.md
Script Reference: naming/reference/scripts_detailed.md
Scene Reference: naming/reference/scenes_detailed.md
Entity Types Reference: naming/reference/entity_types_detailed.md
Configuration Objects Reference: naming/reference/configuration_objects_detailed.md
Edge Cases Reference: naming/reference/edge_cases_detailed.md

Tools

Export Entities: tools/export_entities.py
Propose IDs: tools/propose_ids.py
Find References: tools/find_references.py
Rename Entities: tools/ws_rename_entities.py
Migration Playbook: tools/migration_playbook.md

Naming Audit Project

This specification is the result of a comprehensive naming audit project:

Project Plan: docs/naming_audit/00_project_plan.md
Tooling Phase: docs/naming_audit/01_phase0_tooling.md
Specification Phase: docs/naming_audit/02_phase1_specification.md
Findings: docs/naming_audit/findings/
Decisions: docs/naming_audit/decisions/

Summary

This comprehensive naming guide provides:

Quick Start: 5-minute overview for rapid onboarding
Core System: The deterministic 4-rule naming system
Entity Types: Patterns for 35+ entity types
Automations: Comprehensive automation naming patterns
Scripts: Complete script naming patterns
Scenes: Detailed scene naming patterns
Configuration: Dashboard, blueprint, package, template, ESPHome naming
Edge Cases: Multi-area, temporary, disabled, integration-specific patterns
References: Links to detailed documentation (11,000+ lines)
Tools: Validation and migration tools
Examples: 200+ real-world examples
Decision Trees: Visual guides for naming decisions

Key Principles:

Deterministic: Follow the 4-rule system
Consistent: Use same patterns for similar entities
Clear: Names should be immediately understandable
Maintainable: Easy to find and update entities
Scalable: Works for simple and complex setups

Next Steps:

Review the Quick Start Guide
Apply the 4-rule system to new entities
Consult detailed references for specific patterns
Use provided tools for validation and migration
Follow best practices for consistency

Document Version: 2.1 Last Updated: 2026-03-12 Status: Comprehensive Specification
Lines: ~3,500
Coverage: Complete naming system with detailed references

End of Main Specification

For detailed coverage of specific topics, see the reference documentation linked throughout this guide.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
LICENSE		LICENSE
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

Home Assistant Naming Guide

Table of Contents

Getting Started

Core System

Entity Types

Automations, Scripts, and Scenes

Configuration Objects

Special Cases

Reference

Quick Start Guide

5-Minute Overview

When to Use Which Pattern

The 4-Rule Naming System

Pattern Template

Rule 1: The Rule of Uniqueness

Rule 2: The Rule of Physicality

Rule 3: The Rule of Purpose

Rule 4: The Rule of Combination

Examples of the Rules in Action

Rule 1: Uniqueness (Neither)

Rule 2: Physicality (Location Only)

Rule 3: Purpose (Function Only)

Rule 4: Combination (Both)

Complex Functions

Decision Tree for Entity Naming

Common Entity Types

Lights

Switches

Sensors

Binary Sensors

Covers

Less Common Entity Types

Media & Entertainment

media_player

camera

remote

Climate & Environment

climate

fan

weather

valve

humidifier

water_heater

Security & Safety

lock

alarm_control_panel

siren

Cleaning & Maintenance

vacuum

lawn_mower

Configuration & Control

button

select

number

Helper Entities

When to Include an Area

Input Booleans

Input Numbers

Input Selects

Input Text

Input DateTime

Timers

Counters

Automation Naming

Core Pattern

Pattern Categories

Time-Based Automations

Event-Based Automations

Button/Controller Automations

Multi-Area Automations

Notification Automations

Configuration Automations

Automation Naming Examples

Decision Tree for Automation Naming

Script Naming

Core Pattern