ESPHome 2025.9.0-dev
Loading...
Searching...
No Matches
entity_base.h
Go to the documentation of this file.
1#pragma once
2
3#include <string>
4#include <cstdint>
5#include "string_ref.h"
6#include "helpers.h"
7#include "log.h"
8
9#ifdef USE_DEVICES
10#include "device.h"
11#endif
12
13namespace esphome {
14
20
21// The generic Entity base class that provides an interface common to all Entities.
23 public:
24 // Get/set the name of this Entity
25 const StringRef &get_name() const;
26 void set_name(const char *name);
27
28 // Get whether this Entity has its own name or it should use the device friendly_name.
29 bool has_own_name() const { return this->flags_.has_own_name; }
30
31 // Get the sanitized name of this Entity as an ID.
32 std::string get_object_id() const;
33 void set_object_id(const char *object_id);
34
35 // Get the unique Object ID of this Entity
36 uint32_t get_object_id_hash();
37
38 // Get/set whether this Entity should be hidden outside ESPHome
39 bool is_internal() const { return this->flags_.internal; }
40 void set_internal(bool internal) { this->flags_.internal = internal; }
41
42 // Check if this object is declared to be disabled by default.
43 // That means that when the device gets added to Home Assistant (or other clients) it should
44 // not be added to the default view by default, and a user action is necessary to manually add it.
45 bool is_disabled_by_default() const { return this->flags_.disabled_by_default; }
46 void set_disabled_by_default(bool disabled_by_default) { this->flags_.disabled_by_default = disabled_by_default; }
47
48 // Get/set the entity category.
50 void set_entity_category(EntityCategory entity_category) {
51 this->flags_.entity_category = static_cast<uint8_t>(entity_category);
52 }
53
54 // Get/set this entity's icon
55 std::string get_icon() const;
56 void set_icon(const char *icon);
58 static constexpr auto EMPTY_STRING = StringRef::from_lit("");
59#ifdef USE_ENTITY_ICON
60 return this->icon_c_str_ == nullptr ? EMPTY_STRING : StringRef(this->icon_c_str_);
61#else
62 return EMPTY_STRING;
63#endif
64 }
65
66#ifdef USE_DEVICES
67 // Get/set this entity's device id
68 uint32_t get_device_id() const {
69 if (this->device_ == nullptr) {
70 return 0; // No device set, return 0
71 }
72 return this->device_->get_device_id();
73 }
74 void set_device(Device *device) { this->device_ = device; }
75#endif
76
77 // Check if this entity has state
78 bool has_state() const { return this->flags_.has_state; }
79
80 // Set has_state - for components that need to manually set this
81 void set_has_state(bool state) { this->flags_.has_state = state; }
82
83 protected:
86 virtual uint32_t hash_base() { return 0L; }
87 void calc_object_id_();
88
90 const char *object_id_c_str_{nullptr};
91#ifdef USE_ENTITY_ICON
92 const char *icon_c_str_{nullptr};
93#endif
94 uint32_t object_id_hash_{};
95#ifdef USE_DEVICES
97#endif
98
99 // Bit-packed flags to save memory (1 byte instead of 5)
100 struct EntityFlags {
101 uint8_t has_own_name : 1;
102 uint8_t internal : 1;
104 uint8_t has_state : 1;
105 uint8_t entity_category : 2; // Supports up to 4 categories
106 uint8_t reserved : 2; // Reserved for future use
108};
109
110class EntityBase_DeviceClass { // NOLINT(readability-identifier-naming)
111 public:
113 std::string get_device_class();
115 void set_device_class(const char *device_class);
118 static constexpr auto EMPTY_STRING = StringRef::from_lit("");
119 return this->device_class_ == nullptr ? EMPTY_STRING : StringRef(this->device_class_);
120 }
121
122 protected:
123 const char *device_class_{nullptr};
124};
125
126class EntityBase_UnitOfMeasurement { // NOLINT(readability-identifier-naming)
127 public:
129 std::string get_unit_of_measurement();
131 void set_unit_of_measurement(const char *unit_of_measurement);
134 static constexpr auto EMPTY_STRING = StringRef::from_lit("");
135 return this->unit_of_measurement_ == nullptr ? EMPTY_STRING : StringRef(this->unit_of_measurement_);
136 }
137
138 protected:
139 const char *unit_of_measurement_{nullptr};
140};
141
146template<typename T> class StatefulEntityBase : public EntityBase {
147 public:
148 virtual bool has_state() const { return this->state_.has_value(); }
149 virtual const T &get_state() const { return this->state_.value(); }
150 virtual T get_state_default(T default_value) const { return this->state_.value_or(default_value); }
151 void invalidate_state() { this->set_state_({}); }
152
153 void add_full_state_callback(std::function<void(optional<T> previous, optional<T> current)> &&callback) {
154 if (this->full_state_callbacks_ == nullptr)
155 this->full_state_callbacks_ = new CallbackManager<void(optional<T> previous, optional<T> current)>(); // NOLINT
156 this->full_state_callbacks_->add(std::move(callback));
157 }
158 void add_on_state_callback(std::function<void(T)> &&callback) {
159 if (this->state_callbacks_ == nullptr)
160 this->state_callbacks_ = new CallbackManager<void(T)>(); // NOLINT
161 this->state_callbacks_->add(std::move(callback));
162 }
163
164 void set_trigger_on_initial_state(bool trigger_on_initial_state) {
165 this->trigger_on_initial_state_ = trigger_on_initial_state;
166 }
167
168 protected:
177 if (this->state_ != state) {
178 // call the full state callbacks with the previous and new state
179 if (this->full_state_callbacks_ != nullptr)
180 this->full_state_callbacks_->call(this->state_, state);
181 // trigger legacy callbacks only if the new state is valid and either the trigger on initial state is enabled or
182 // the previous state was valid
183 auto had_state = this->has_state();
184 this->state_ = state;
185 if (this->state_callbacks_ != nullptr && state.has_value() && (this->trigger_on_initial_state_ || had_state))
186 this->state_callbacks_->call(state.value());
187 return true;
188 }
189 return false;
190 }
192 // callbacks with full state and previous state
195};
196} // namespace esphome
uint32_t get_device_id()
Definition device.h:8
std::string get_device_class()
Get the device class, using the manual override if set.
StringRef get_device_class_ref() const
Get the device class as StringRef.
void set_device_class(const char *device_class)
Manually set the device class.
const char * device_class_
Device class override.
std::string get_unit_of_measurement()
Get the unit of measurement, using the manual override if set.
const char * unit_of_measurement_
Unit of measurement override.
void set_unit_of_measurement(const char *unit_of_measurement)
Manually set the unit of measurement.
StringRef get_unit_of_measurement_ref() const
Get the unit of measurement as StringRef.
struct esphome::EntityBase::EntityFlags flags_
void set_device(Device *device)
Definition entity_base.h:74
void set_object_id(const char *object_id)
bool has_own_name() const
Definition entity_base.h:29
uint32_t object_id_hash_
Definition entity_base.h:94
bool is_internal() const
Definition entity_base.h:39
const char * object_id_c_str_
Definition entity_base.h:90
uint32_t get_object_id_hash()
const StringRef & get_name() const
void set_entity_category(EntityCategory entity_category)
Definition entity_base.h:50
StringRef get_icon_ref() const
Definition entity_base.h:57
std::string get_icon() const
uint32_t get_device_id() const
Definition entity_base.h:68
bool is_disabled_by_default() const
Definition entity_base.h:45
void set_name(const char *name)
void set_icon(const char *icon)
void set_disabled_by_default(bool disabled_by_default)
Definition entity_base.h:46
void set_has_state(bool state)
Definition entity_base.h:81
const char * icon_c_str_
Definition entity_base.h:92
virtual uint32_t hash_base()
The hash_base() function has been deprecated.
Definition entity_base.h:86
bool has_state() const
Definition entity_base.h:78
std::string get_object_id() const
EntityCategory get_entity_category() const
Definition entity_base.h:49
void set_internal(bool internal)
Definition entity_base.h:40
An entity that has a state.
virtual const T & get_state() const
bool set_state_(const optional< T > &state)
Set a new state for this entity.
void add_full_state_callback(std::function< void(optional< T > previous, optional< T > current)> &&callback)
CallbackManager< void(T)> * state_callbacks_
void add_on_state_callback(std::function< void(T)> &&callback)
void set_trigger_on_initial_state(bool trigger_on_initial_state)
virtual bool has_state() const
virtual T get_state_default(T default_value) const
CallbackManager< void(optional< T > previous, optional< T > current)> * full_state_callbacks_
StringRef is a reference to a string owned by something else.
Definition string_ref.h:22
static constexpr StringRef from_lit(const CharT(&s)[N])
Definition string_ref.h:46
bool has_value() const
Definition optional.h:92
value_type const & value() const
Definition optional.h:94
bool state
Definition fan.h:0
Providing packet encoding functions for exchanging data with a remote host.
Definition a01nyub.cpp:7
@ ENTITY_CATEGORY_NONE
Definition entity_base.h:16
@ ENTITY_CATEGORY_CONFIG
Definition entity_base.h:17
@ ENTITY_CATEGORY_DIAGNOSTIC
Definition entity_base.h:18