Skip to main content
Entities are the fundamental building blocks of Home Assistant. They represent devices, services, and other stateful objects in your smart home.

​
What is an Entity?

An entity is an abstract representation of a function in Home Assistant. Each entity represents a specific capability or feature, such as a light, switch, sensor, or any other controllable or observable element in your home automation system.
Entities are uniquely identified by their domain, platform, and a unique ID provided by the integration.

​
Entity Structure

Every entity in Home Assistant has several key components:

​
Entity ID

Entity IDs follow the format domain.object_id, for example:
  • light.living_room
  • sensor.temperature
  • switch.bedroom_fan

​
Unique ID

Each entity has a unique identifier that persists across restarts and allows the entity to be tracked in the entity registry.

​
State

The current state of the entity (e.g., “on”, “off”, “23.5”).

​
Attributes

Additional information about the entity, such as:
  • friendly_name: Human-readable name
  • device_class: Classification of the entity
  • unit_of_measurement: Unit for numeric states
  • supported_features: Bitmask of supported features
  • icon: Icon to display in the UI

​
Entity Base Class

The Entity class in homeassistant/helpers/entity.py is the foundation for all entities in Home Assistant.

​
Key Properties

class Entity:
    """An abstract class for Home Assistant entities."""
    
    entity_id: str  # The entity ID
    hass: HomeAssistant  # Reference to Home Assistant instance
    platform: EntityPlatform  # Owning platform
    unique_id: str | None  # Unique identifier
    name: str | None  # Entity name
    state: StateType  # Current state
    available: bool  # Whether entity is available
    device_info: DeviceInfo | None  # Associated device information

​
Entity Lifecycle

Entities go through several states during their lifecycle:
  1. NOT_ADDED: Entity not yet added to a platform
  2. ADDING: Preparing for addition to a platform
  3. ADDED: Entity added and active
  4. REMOVED: Entity removed from platform
class EntityPlatformState(Enum):
    """The platform state of an entity."""

    # Not Added: Not yet added to a platform, states are not written to the
    # state machine.
    NOT_ADDED = auto()

    # Adding: Preparing for adding to a platform, states are not written to the
    # state machine.
    ADDING = auto()

    # Added: Added to a platform, states are written to the state machine.
    ADDED = auto()

    # Removed: Removed from a platform, states are not written to the
    # state machine.
    REMOVED = auto()

​
State Management

Entities update their state using methods provided by the base class:

​
Writing State

# Synchronous callback method
@callback
def async_write_ha_state(self) -> None:
    """Write the state to the state machine."""
    
# Async method with optional refresh
async def async_update_ha_state(self, force_refresh: bool = False) -> None:
    """Update Home Assistant with current state of entity."""
Always use async_write_ha_state() for simple state updates. Only use async_update_ha_state(force_refresh=True) when you need to fetch new data before writing the state.

​
Entity Categories

Entities can be categorized to indicate their purpose:
  • CONFIG: Configuration parameters
  • DIAGNOSTIC: Diagnostic information
  • None: Primary functionality (default)
from homeassistant.const import EntityCategory

entity_category: EntityCategory | None = EntityCategory.DIAGNOSTIC

​
Entity Description

The EntityDescription class provides metadata for entities: 
class EntityDescription(metaclass=FrozenOrThawed, frozen_or_thawed=True):
    """A class that describes Home Assistant entities."""

    # This is the key identifier for this entity
    key: str

    device_class: str | None = None
    entity_category: EntityCategory | None = None
    entity_registry_enabled_default: bool = True
    entity_registry_visible_default: bool = True
    force_update: bool = False
    icon: str | None = None
    has_entity_name: bool = False
    name: str | UndefinedType | None = UNDEFINED
    translation_key: str | None = None
    translation_placeholders: Mapping[str, str] | None = None
    unit_of_measurement: str | None = None

​
Entity Registry

The entity registry keeps track of all entities in Home Assistant. It provides:
  • Persistent storage of entity configuration
  • Entity ID generation
  • Tracking of disabled/hidden entities
  • Association with devices and config entries

​
Registry Entry

Each entity has a registry entry containing: 
@attr.s(frozen=True, kw_only=True, slots=True)
class RegistryEntry:
    entity_id: str
    unique_id: str
    platform: str
    domain: str
    device_id: str | None
    area_id: str | None
    config_entry_id: str | None
    disabled_by: RegistryEntryDisabler | None
    entity_category: EntityCategory | None
    labels: set[str]
    # ... and more

​
Creating Custom Entities

To create a custom entity, subclass the Entity base class or a domain-specific entity class: 
from homeassistant.helpers.entity import Entity

class MyCustomEntity(Entity):
    """Representation of my custom entity."""
    
    def __init__(self):
        """Initialize the entity."""
        self._attr_name = "My Custom Entity"
        self._attr_unique_id = "my_unique_id"
    
    @property
    def state(self):
        """Return the state of the entity."""
        return "on"
    
    async def async_update(self):
        """Fetch new state data for the entity."""
        # Update entity state here
        pass

​
Best Practices

Performance

Use _attr_ properties instead of @property methods when possible for better performance.

State Updates

Call async_write_ha_state() to update the state machine whenever the entity’s state changes.

Polling

Set should_poll = False for entities that push updates, rather than being polled.

Device Association

Provide device_info to associate entities with devices for better organization.

Devices

Learn about device management and association

State Machine

Understand how entity states are managed

Build docs developers (and LLMs) love

Get started for freeTalk to us