#include <entity_base.h>

Inheritance diagram for esphome::EntityBase:

Data Structures
struct	EntityFlags

Public Member Functions
const StringRef &	get_name () const

bool	has_own_name () const

ESPDEPRECATED("object_id mangles names and all object_id methods are planned for removal " "(see https://github.com/esphome/backlog/issues/76). " "Now is the time to stop using object_id. If still needed, use get_object_id_to() " "which will remain available longer. get_object_id() will be removed in 2026.7.0", "2025.12.0") std uint32_t	get_object_id_hash ()

StringRef	get_object_id_to (std::span< char, OBJECT_ID_MAX_LEN > buf) const
	Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.

size_t	write_object_id_to (char *buf, size_t buf_size) const
	Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.

bool	is_internal () const

	ESPDEPRECATED ("set_internal() is undefined behavior at runtime — components and Home Assistant are NOT " "notified. Use the 'internal:' YAML key instead. Will be removed in 2027.3.0.", "2026.3.0") void set_internal(bool internal)

bool	is_disabled_by_default () const

EntityCategory	get_entity_category () const

const char *	get_device_class_to (std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer) const

template<typename T = int>
StringRef	get_device_class_ref () const

template<typename T = int>
std::string	get_device_class () const

	ESPDEPRECATED ("Use get_device_class_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") StringRef get_device_class_ref() const

ESPDEPRECATED("Use get_device_class_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") std StringRef	get_unit_of_measurement_ref () const

ESPDEPRECATED("Use get_unit_of_measurement_ref() instead for better performance (avoids string copy). Will be " "removed in ESPHome 2026.9.0", "2026.3.0") std const char *	get_icon_to (std::span< char, MAX_ICON_LENGTH > buffer) const
	Get the unit of measurement as std::string (deprecated, prefer get_unit_of_measurement_ref())

template<typename T = int>
StringRef	get_icon_ref () const

template<typename T = int>
std::string	get_icon () const

	ESPDEPRECATED ("Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") StringRef get_icon_ref() const

ESPDEPRECATED("Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") std uint32_t	get_device_id () const

Device *	get_device () const

bool	has_state () const

void	set_has_state (bool state)

	ESPDEPRECATED ("Use make_entity_preference<T>() instead, or preferences won't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0.", "2026.7.0") uint32_t get_preference_hash()
	Get a unique hash for storing preferences/settings for this entity.

template<typename T >
ESPPreferenceObject	make_entity_preference (uint32_t version=0)
	Create a preference object for storing this entity's state/settings.

Protected Member Functions
friend	void::setup ()

friend	void::original_setup ()

void	configure_entity_ (const char *name, uint32_t object_id_hash, uint32_t entity_fields)
	Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.

void	set_device_ (Device *device)

ESPPreferenceObject	make_entity_preference_ (size_t size, uint32_t version)
	Non-template helper for make_entity_preference() to avoid code bloat.

void	calc_object_id_ ()

Protected Attributes
StringRef	name_

uint32_t	object_id_hash_ {}

Device *	device_ {}

struct esphome::EntityBase::EntityFlags	flags_

uint8_t	device_class_idx_ {}

uint8_t	uom_idx_ {}

uint8_t	icon_idx_ {}

Detailed Description

Definition at line 68 of file entity_base.h.

Member Function Documentation

◆ calc_object_id_()

void esphome::EntityBase::calc_object_id_ ( )

protected

Definition at line 161 of file entity_base.cpp.

◆ configure_entity_()

void esphome::EntityBase::configure_entity_	(	const char *	name,
		uint32_t	object_id_hash,
		uint32_t	entity_fields )

protected

Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.

Bit layout of entity_fields is defined by the ENTITY_FIELD_*_SHIFT constants above.

Definition at line 14 of file entity_base.cpp.

◆ ESPDEPRECATED() [1/4]

esphome::EntityBase::ESPDEPRECATED	(	"set_internal() is undefined behavior at runtime — components and Home Assistant are NOT " "notified. Use the 'internal:' YAML key instead. Will be removed in 2027.3.0."	,
		"2026.3.0"	)

inline

Definition at line 106 of file entity_base.h.

◆ ESPDEPRECATED() [2/4]

esphome::EntityBase::ESPDEPRECATED	(	"Use get_device_class_to() instead. Will be removed in ESPHome 2026.9.0"	,
		"2026.3.0"	) const

◆ ESPDEPRECATED() [3/4]

esphome::EntityBase::ESPDEPRECATED	(	"Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0"	,
		"2026.3.0"	) const

◆ ESPDEPRECATED() [4/4]

esphome::EntityBase::ESPDEPRECATED	(	"Use make_entity_preference<T>()	instead,
		or preferences won 't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0."	,
		"2026.7.0"	)

inline

Get a unique hash for storing preferences/settings for this entity.

This method returns a hash that uniquely identifies the entity for the purpose of storing preferences (such as calibration, state, etc.). Unlike get_object_id_hash(), this hash also incorporates the device_id (if devices are enabled), ensuring uniqueness across multiple devices that may have entities with the same object_id.

Use this method when storing or retrieving preferences/settings that should be unique per device-entity pair. Use get_object_id_hash() when you need a hash that identifies the entity regardless of the device it belongs to.

For backward compatibility, if device_id is 0 (the main device), the hash is unchanged from previous versions, so existing single-device configurations will continue to work.

Returns: uint32_t The unique hash for preferences, including device_id if available.

Definition at line 215 of file entity_base.h.

◆ get_device()

Device * esphome::EntityBase::get_device ( ) const

inline

Definition at line 187 of file entity_base.h.

◆ get_device_class()

template<typename T = int>

std::string esphome::EntityBase::get_device_class ( ) const

inline

Definition at line 132 of file entity_base.h.

◆ get_device_class_ref()

template<typename T = int>

StringRef esphome::EntityBase::get_device_class_ref ( ) const

inline

Definition at line 127 of file entity_base.h.

◆ get_device_class_to()

const char * esphome::EntityBase::get_device_class_to ( std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer ) const

Definition at line 68 of file entity_base.cpp.

◆ get_device_id()

ESPDEPRECATED("Use get_icon_to() instead. Will be removed in ESPHome 2026.9.0", "2026.3.0") std uint32_t esphome::EntityBase::get_device_id ( ) const

inline

Definition at line 180 of file entity_base.h.

◆ get_entity_category()

EntityCategory esphome::EntityBase::get_entity_category ( ) const

inline

Definition at line 117 of file entity_base.h.

◆ get_icon()

template<typename T = int>

std::string esphome::EntityBase::get_icon ( ) const

inline

Definition at line 165 of file entity_base.h.

◆ get_icon_ref()

template<typename T = int>

StringRef esphome::EntityBase::get_icon_ref ( ) const

inline

Definition at line 160 of file entity_base.h.

◆ get_icon_to()

const char * esphome::EntityBase::get_icon_to ( std::span< char, MAX_ICON_LENGTH > buffer ) const

Get the unit of measurement as std::string (deprecated, prefer get_unit_of_measurement_ref())

Definition at line 117 of file entity_base.cpp.

◆ get_name()

const StringRef & esphome::EntityBase::get_name ( ) const

Definition at line 12 of file entity_base.cpp.

◆ get_object_id_hash()

uint32_t esphome::EntityBase::get_object_id_hash ( )

Definition at line 179 of file entity_base.cpp.

◆ get_object_id_to()

StringRef esphome::EntityBase::get_object_id_to ( std::span< char, OBJECT_ID_MAX_LEN > buf ) const

Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.

Definition at line 174 of file entity_base.cpp.

◆ get_unit_of_measurement_ref()

StringRef esphome::EntityBase::get_unit_of_measurement_ref ( ) const

Definition at line 105 of file entity_base.cpp.

◆ has_own_name()

bool esphome::EntityBase::has_own_name ( ) const

inline

Definition at line 74 of file entity_base.h.

◆ has_state()

bool esphome::EntityBase::has_state ( ) const

inline

Definition at line 191 of file entity_base.h.

◆ is_disabled_by_default()

bool esphome::EntityBase::is_disabled_by_default ( ) const

inline

Definition at line 114 of file entity_base.h.

◆ is_internal()

bool esphome::EntityBase::is_internal ( ) const

inline

Definition at line 101 of file entity_base.h.

◆ make_entity_preference()

template<typename T >

ESPPreferenceObject esphome::EntityBase::make_entity_preference ( uint32_t version = 0 )

inline

Create a preference object for storing this entity's state/settings.

Template Parameters

T	The type of data to store (must be trivially copyable)

Parameters

version Optional version hash XORed with preference key (change when struct layout changes)

Definition at line 233 of file entity_base.h.

◆ make_entity_preference_()

ESPPreferenceObject esphome::EntityBase::make_entity_preference_	(	size_t	size,
		uint32_t	version )

protected

Non-template helper for make_entity_preference() to avoid code bloat.

When preference hash algorithm changes, migration logic goes here.

Definition at line 198 of file entity_base.cpp.

◆ set_device_()

void esphome::EntityBase::set_device_ ( Device * device )

inlineprotected

Definition at line 248 of file entity_base.h.

◆ set_has_state()

void esphome::EntityBase::set_has_state ( bool state )

inline

Definition at line 194 of file entity_base.h.

◆ void::original_setup()

esphome::EntityBase::void::original_setup ( )

protected

◆ void::setup()

esphome::EntityBase::void::setup ( )

protected

◆ write_object_id_to()

size_t esphome::EntityBase::write_object_id_to	(	char *	buf,
		size_t	buf_size ) const

Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.

Definition at line 165 of file entity_base.cpp.

Field Documentation

◆ device_

Device* esphome::EntityBase::device_ {}

protected

Definition at line 260 of file entity_base.h.

◆ device_class_idx_

uint8_t esphome::EntityBase::device_class_idx_ {}

protected

Definition at line 274 of file entity_base.h.

◆ flags_

struct esphome::EntityBase::EntityFlags esphome::EntityBase::flags_

protected

◆ icon_idx_

uint8_t esphome::EntityBase::icon_idx_ {}

protected

Definition at line 280 of file entity_base.h.

◆ name_

StringRef esphome::EntityBase::name_

protected

Definition at line 257 of file entity_base.h.

◆ object_id_hash_

uint32_t esphome::EntityBase::object_id_hash_ {}

protected

Definition at line 258 of file entity_base.h.

◆ uom_idx_

uint8_t esphome::EntityBase::uom_idx_ {}

protected

Definition at line 277 of file entity_base.h.

The documentation for this class was generated from the following files:

esphome/core/entity_base.h
esphome/core/entity_base.cpp

Data Structures

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ calc_object_id_()

◆ configure_entity_()

◆ ESPDEPRECATED() [1/4]

◆ ESPDEPRECATED() [2/4]

◆ ESPDEPRECATED() [3/4]

◆ ESPDEPRECATED() [4/4]

◆ get_device()

◆ get_device_class()

◆ get_device_class_ref()

◆ get_device_class_to()

◆ get_device_id()

◆ get_entity_category()

◆ get_icon()

◆ get_icon_ref()

◆ get_icon_to()

◆ get_name()

◆ get_object_id_hash()

◆ get_object_id_to()

◆ get_unit_of_measurement_ref()

◆ has_own_name()

◆ has_state()

◆ is_disabled_by_default()

◆ is_internal()

◆ make_entity_preference()

◆ make_entity_preference_()

◆ set_device_()

◆ set_has_state()

◆ void::original_setup()

◆ void::setup()

◆ write_object_id_to()

Field Documentation

◆ device_

◆ device_class_idx_

◆ flags_

◆ icon_idx_

◆ name_

◆ object_id_hash_

◆ uom_idx_