Home Assistant Entity & Device Naming Best Practice

Posts

Proper naming conventions in Home Assistant transform a chaotic smart home into an organized, maintainable system. Without consistent naming, you’ll struggle to find devices, create automations, and troubleshoot issues as your setup grows. Good naming conventions make your smart home scalable and intuitive for everyone in your household.

This guide provides a structured approach to naming that grows with your system, inspired by the Home Assistant Naming Convention repository maintained by the community.

Three Essential Naming Categories

  • General: For location-based devices like lights, switches, and sensors installed throughout your home.
  • Personal Devices and Pets: For user-specific devices like phones, fitness trackers, and pet monitoring equipment.
  • Network Entities: For infrastructure devices like routers, access points, and network monitoring equipment.

General Structure Naming Convention

Entity ID Format: <domain>.<device_id_with_location>_<function>_<identifier>

Device Name Format: <location>_<device_type>_<identifier>

Component Definitions

  • location_code: Indicates the specific location where the device is installed or controlled
  • device: Represents the type of device
  • function: Detail that provides additional information about the specific function of the device
  • identifier: Number or short name that distinguishes similar devices or functions
  • user_code: Initials or nickname of the device owner
  • domain: light, sensor, binary_sensor (on/off type sensors, motion, contact, leak detectors), switch, climate (AC, radiator), media_player (speakers, TVs, audio systems), camera, cover (blinds, curtains, garage doors), device_tracker (phones, Wi-Fi presence sensors, GPS devices)

Examples

Single-button switch in bedroom1:

  • Device: bedroom1_switch_sonoff_1
  • Entity ID: switch.bedroom1_switch_sonoff_1_button

Multi-button switch in bedroom1:

  • Device: bedroom1_switch_sonoff_2
  • Entity IDs:
    • switch.bedroom1_switch_sonoff_2_button_1
    • switch.bedroom1_switch_sonoff_2_button_2
    • switch.bedroom1_switch_sonoff_2_button_3

Personal Devices and Pets Naming Convention

Entity ID Format: <domain>.<device_id_with_who>_<function>_<identifier>

Device Name Format: <who>_<device_name>_<identifier>

Examples

Phone tracking:

  • Device: john_phone_pixel
  • Entity ID: device_tracker.john_phone_pixel

Health monitoring:

  • Device: maria_bp_monitor
  • Entity IDs:
    • sensor.maria_bp_monitor_systolic
    • sensor.maria_bp_monitor_diastolic

Fitness tracking:

  • Device: maria_fitbit
  • Entity ID: sensor.maria_fitbit_heart_rate

Network Entities Naming Convention

Entity ID Format: <domain>.<device_type>_<function>_<identifier>

Device Name Format: <device_type>_<function>_<identifier>

Examples

Router monitoring:

  • Device: home_router_main
  • Entity IDs:
    • binary_sensor.home_router_main_online
    • sensor.home_router_main_uptime

Key Benefits

  • Scalability: Easy to add new devices without breaking existing patterns
  • Clarity: Anyone can understand what a device does from its name
  • Automation: Consistent naming makes group operations and automations simpler
  • Maintenance: Troubleshooting becomes faster when everything is logically organized

Start with these conventions from day one, and your Home Assistant setup will remain manageable as it grows from a few devices to hundreds.