Skip to main content
The homeassistant.helpers.entity module provides the Entity base class and related utilities for creating entities in Home Assistant.

​
Entity Class

The Entity class is an abstract base class that all Home Assistant entities must inherit from.

​
Key Properties

​
entity_id
str
Unique identifier for the entity (format: domain.object_id)
​
name
str | UndefinedType | None
Name of the entity
​
state
StateType
Current state of the entity
​
available
bool
default:"True"
Whether the entity is available
​
unique_id
str | None
Unique identifier for the entity across restarts
​
device_info
DeviceInfo | None
Information about the device this entity belongs to
​
icon
str | None
Icon to use in the frontend (format: mdi:icon-name)
​
entity_picture
str | None
URL of picture to use in the frontend
​
assumed_state
bool
default:"False"
True if unable to access real state of the entity
​
should_poll
bool
default:"True"
True if entity has to be polled for state, False if entity pushes its state
​
supported_features
int | None
Flag of features supported by the entity
​
device_class
str | None
Device class of the entity from component DEVICE_CLASSES
​
unit_of_measurement
str | None
Unit of measurement for the entity’s value
​
entity_category
EntityCategory | None
Category of the entity (config, diagnostic)

​
Key Methods

​
async_write_ha_state

Write the state to the state machine. 
@callback
def async_write_ha_state(self) -> None:
    """Write the state to the state machine."""
Must be called from the event loop. This is the preferred method for updating entity state.

​
async_update_ha_state

Update Home Assistant with current state of entity.
​
force_refresh
bool
default:"False"
If True, update entity before setting state
async def async_update_ha_state(self, force_refresh: bool = False) -> None:
    """Update Home Assistant with current state of entity."""

​
async_schedule_update_ha_state

Schedule an update ha state change task.
​
force_refresh
bool
default:"False"
If True, force entity refresh
@callback
def async_schedule_update_ha_state(self, force_refresh: bool = False) -> None:
    """Schedule an update ha state change task."""

​
async_on_remove

Add a function to call when entity is removed or not added.
​
func
CALLBACK_TYPE
required
Callback function to call on removal
@callback
def async_on_remove(self, func: CALLBACK_TYPE) -> None:
    """Add a function to call when entity is removed."""

​
Helper Functions

​
generate_entity_id

Generate a unique entity ID based on given entity IDs or used IDs.
​
entity_id_format
str
required
Format string for entity ID (e.g., "light.{}")
​
name
str | None
required
Name to use for generating the entity ID
​
current_ids
list[str] | None
default:"None"
List of currently used entity IDs
​
hass
HomeAssistant | None
default:"None"
Home Assistant instance (required if current_ids is None)
​
return
str
Generated unique entity ID
from homeassistant.helpers.entity import generate_entity_id

entity_id = generate_entity_id(
    "light.{}",
    "Living Room",
    hass=hass
)
# Returns: "light.living_room"

​
get_capability

Get a capability attribute of an entity.
​
hass
HomeAssistant
required
Home Assistant instance
​
entity_id
str
required
Entity ID to get capability from
​
capability
str
required
Name of capability to retrieve
​
return
Any | None
Capability value or None if not found

​
get_device_class

Get device class of an entity.
​
hass
HomeAssistant
required
Home Assistant instance
​
entity_id
str
required
Entity ID
​
return
str | None
Device class or None

​
get_supported_features

Get supported features for an entity.
​
hass
HomeAssistant
required
Home Assistant instance
​
entity_id
str
required
Entity ID
​
return
int
Bitfield of supported features (0 if none)

​
get_unit_of_measurement

Get unit of measurement of an entity.
​
hass
HomeAssistant
required
Home Assistant instance
​
entity_id
str
required
Entity ID
​
return
str | None
Unit of measurement or None

​
EntityDescription

Dataclass that describes Home Assistant entities.
​
key
str
required
Key identifier for this entity
​
device_class
str | None
default:"None"
Device class
​
entity_category
EntityCategory | None
default:"None"
Category of entity
​
entity_registry_enabled_default
bool
default:"True"
Whether entity should be enabled when first added
​
entity_registry_visible_default
bool
default:"True"
Whether entity should be visible when first added
​
force_update
bool
default:"False"
Force state update even if value hasn’t changed
​
icon
str | None
default:"None"
Icon for the entity
​
has_entity_name
bool
default:"False"
Whether the name describes only the entity itself
​
name
str | UndefinedType | None
default:"UNDEFINED"
Name of the entity
​
translation_key
str | None
default:"None"
Translation key for the entity name
​
unit_of_measurement
str | None
default:"None"
Unit of measurement

​
Constants

  • SLOW_UPDATE_WARNING = 10 - Seconds before warning about slow updates
  • FLOAT_PRECISION - Precision for float state representation
  • CAPABILITIES_UPDATE_LIMIT = 100 - Max capability updates per hour before warning

Build docs developers (and LLMs) love

Get started for freeTalk to us