Entity Base Class

Base class for all Home Assistant entities with state and attribute management.

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