#include <entity_base.h>

Inheritance diagram for esphome::EntityBase:

Data Structures
struct	EntityFlags

Public Member Functions
const StringRef &	get_name () const

void	set_name (const char *name)

void	set_name (const char *name, uint32_t object_id_hash)
	Set name with pre-computed object_id hash (avoids runtime hash calculation) Use hash=0 for dynamic names that need runtime calculation.

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

void	set_internal (bool internal)

bool	is_disabled_by_default () const

void	set_disabled_by_default (bool disabled_by_default)

EntityCategory	get_entity_category () const

void	set_entity_category (EntityCategory entity_category)

ESPDEPRECATED("Use get_icon_ref() instead for better performance (avoids string copy). Will be removed in ESPHome 2026.5.0", "2025.11.0") std void	set_icon (const char *icon)

StringRef	get_icon_ref () const

uint32_t	get_device_id () const

void	set_device (Device *device)

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
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_

const char *	icon_c_str_ {nullptr}

uint32_t	object_id_hash_ {}

Device *	device_ {}

struct esphome::EntityBase::EntityFlags	flags_

Detailed Description

Definition at line 40 of file entity_base.h.

Member Function Documentation

◆ calc_object_id_()

void esphome::EntityBase::calc_object_id_ ( )

protected

Definition at line 75 of file entity_base.cpp.

◆ ESPDEPRECATED()

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 145 of file entity_base.h.

◆ get_device()

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

inline

Definition at line 117 of file entity_base.h.

◆ get_device_id()

uint32_t esphome::EntityBase::get_device_id ( ) const

inline

Definition at line 109 of file entity_base.h.

◆ get_entity_category()

EntityCategory esphome::EntityBase::get_entity_category ( ) const

inline

Definition at line 87 of file entity_base.h.

◆ get_icon_ref()

StringRef esphome::EntityBase::get_icon_ref ( ) const

inline

Definition at line 98 of file entity_base.h.

◆ get_name()

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

Definition at line 11 of file entity_base.cpp.

◆ get_object_id_hash()

uint32_t esphome::EntityBase::get_object_id_hash ( )

Definition at line 93 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 88 of file entity_base.cpp.

◆ has_own_name()

bool esphome::EntityBase::has_own_name ( ) const

inline

Definition at line 50 of file entity_base.h.

◆ has_state()

bool esphome::EntityBase::has_state ( ) const

inline

Definition at line 121 of file entity_base.h.

◆ is_disabled_by_default()

bool esphome::EntityBase::is_disabled_by_default ( ) const

inline

Definition at line 83 of file entity_base.h.

◆ is_internal()

bool esphome::EntityBase::is_internal ( ) const

inline

Definition at line 77 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 163 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 112 of file entity_base.cpp.

◆ set_device()

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

inline

Definition at line 115 of file entity_base.h.

◆ set_disabled_by_default()

void esphome::EntityBase::set_disabled_by_default ( bool disabled_by_default )

inline

Definition at line 84 of file entity_base.h.

◆ set_entity_category()

void esphome::EntityBase::set_entity_category ( EntityCategory entity_category )

inline

Definition at line 88 of file entity_base.h.

◆ set_has_state()

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

inline

Definition at line 124 of file entity_base.h.

◆ set_icon()

void esphome::EntityBase::set_icon ( const char * icon )

Definition at line 59 of file entity_base.cpp.

◆ set_internal()

void esphome::EntityBase::set_internal ( bool internal )

inline

Definition at line 78 of file entity_base.h.

◆ set_name() [1/2]

void esphome::EntityBase::set_name ( const char * name )

Definition at line 12 of file entity_base.cpp.

◆ set_name() [2/2]

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

Set name with pre-computed object_id hash (avoids runtime hash calculation) Use hash=0 for dynamic names that need runtime calculation.

Definition at line 13 of file entity_base.cpp.

◆ 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 79 of file entity_base.cpp.

Field Documentation

◆ device_

Device* esphome::EntityBase::device_ {}

protected

Definition at line 181 of file entity_base.h.

◆ flags_

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

protected

◆ icon_c_str_

const char* esphome::EntityBase::icon_c_str_ {nullptr}

protected

Definition at line 177 of file entity_base.h.

◆ name_

StringRef esphome::EntityBase::name_

protected

Definition at line 175 of file entity_base.h.

◆ object_id_hash_

uint32_t esphome::EntityBase::object_id_hash_ {}

protected

Definition at line 179 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_()

◆ ESPDEPRECATED()

◆ get_device()

◆ get_device_id()

◆ get_entity_category()

◆ get_icon_ref()

◆ get_name()

◆ get_object_id_hash()

◆ get_object_id_to()

◆ has_own_name()

◆ has_state()

◆ is_disabled_by_default()

◆ is_internal()

◆ make_entity_preference()

◆ make_entity_preference_()

◆ set_device()

◆ set_disabled_by_default()

◆ set_entity_category()

◆ set_has_state()

◆ set_icon()

◆ set_internal()

◆ set_name() [1/2]

◆ set_name() [2/2]

◆ write_object_id_to()

Field Documentation

◆ device_

◆ flags_

◆ icon_c_str_

◆ name_

◆ object_id_hash_