> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.
# Entities
> Understanding entities in Home Assistant Core
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
```python theme={null}
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
```python homeassistant/helpers/entity.py:218-235 theme={null}
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
```python theme={null}
# 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)
```python theme={null}
from homeassistant.const import EntityCategory
entity_category: EntityCategory | None = EntityCategory.DIAGNOSTIC
```
## Entity Description
The `EntityDescription` class provides metadata for entities:
```python homeassistant/helpers/entity.py:240-257 theme={null}
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:
```python theme={null}
@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:
```python theme={null}
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
Use `_attr_` properties instead of `@property` methods when possible for better performance.
Call `async_write_ha_state()` to update the state machine whenever the entity's state changes.
Set `should_poll = False` for entities that push updates, rather than being polled.
Provide `device_info` to associate entities with devices for better organization.
## Related Resources
Learn about device management and association
Understand how entity states are managed