ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
light_call.h
Go to the documentation of this file.
1#pragma once
2
6
7namespace esphome {
8
9// Forward declaration
10struct LogString;
11
12namespace light {
13
14class LightState;
15class LightTraits;
16
24class LightCall {
25 public:
26 explicit LightCall(LightState *parent) : parent_(parent) {}
27
29 LightCall &set_state(optional<bool> state);
38 LightCall &set_transition_length(optional<uint32_t> transition_length);
49 LightCall &set_flash_length(optional<uint32_t> flash_length);
53 LightCall &set_brightness(optional<float> brightness);
55 LightCall &set_brightness(float brightness);
57 LightCall &set_brightness_if_supported(float brightness);
58
60 LightCall &set_color_mode(optional<ColorMode> color_mode);
65
67 LightCall &set_color_brightness(optional<float> brightness);
69 LightCall &set_color_brightness(float brightness);
76 LightCall &set_red(optional<float> red);
81 LightCall &set_red(float red);
88 LightCall &set_green(optional<float> green);
93 LightCall &set_green(float green);
100 LightCall &set_blue(optional<float> blue);
105 LightCall &set_blue(float blue);
107 LightCall &set_blue_if_supported(float blue);
109 LightCall &set_white(optional<float> white);
111 LightCall &set_white(float white);
113 LightCall &set_white_if_supported(float white);
115 LightCall &set_color_temperature(optional<float> color_temperature);
117 LightCall &set_color_temperature(float color_temperature);
119 LightCall &set_color_temperature_if_supported(float color_temperature);
121 LightCall &set_cold_white(optional<float> cold_white);
123 LightCall &set_cold_white(float cold_white);
125 LightCall &set_cold_white_if_supported(float cold_white);
127 LightCall &set_warm_white(optional<float> warm_white);
129 LightCall &set_warm_white(float warm_white);
131 LightCall &set_warm_white_if_supported(float warm_white);
133 LightCall &set_effect(optional<std::string> effect);
135 LightCall &set_effect(const std::string &effect) { return this->set_effect(effect.data(), effect.size()); }
137 LightCall &set_effect(const char *effect) { return this->set_effect(effect, strlen(effect)); }
139 LightCall &set_effect(StringRef effect) { return this->set_effect(effect.c_str(), effect.size()); }
141 LightCall &set_effect(const char *effect, size_t len);
143 LightCall &set_effect(uint32_t effect_number);
144 LightCall &set_effect(optional<uint32_t> effect_number);
146 LightCall &set_publish(bool publish);
148 LightCall &set_save(bool save);
149
150 // Getter methods to check if values are set
151 bool has_state() const { return (flags_ & FLAG_HAS_STATE) != 0; }
152 bool has_brightness() const { return (flags_ & FLAG_HAS_BRIGHTNESS) != 0; }
153 bool has_color_brightness() const { return (flags_ & FLAG_HAS_COLOR_BRIGHTNESS) != 0; }
154 bool has_red() const { return (flags_ & FLAG_HAS_RED) != 0; }
155 bool has_green() const { return (flags_ & FLAG_HAS_GREEN) != 0; }
156 bool has_blue() const { return (flags_ & FLAG_HAS_BLUE) != 0; }
157 bool has_white() const { return (flags_ & FLAG_HAS_WHITE) != 0; }
159 bool has_cold_white() const { return (flags_ & FLAG_HAS_COLD_WHITE) != 0; }
160 bool has_warm_white() const { return (flags_ & FLAG_HAS_WARM_WHITE) != 0; }
161 bool has_color_mode() const { return (flags_ & FLAG_HAS_COLOR_MODE) != 0; }
162
172 LightCall &set_rgb(float red, float green, float blue);
183 LightCall &set_rgbw(float red, float green, float blue, float white);
185
186 void perform();
187
188 protected:
191
194
200 void transform_parameters_(const LightTraits &traits);
201
202 // Bits 0-7 index unit_fields_[] in validate_(); don't reorder (asserts in light_call.cpp).
221 static constexpr uint16_t CLAMP_FLAGS_MASK = 0x00FFu; // bits 0-7
222 // Flags a plain turn-on may carry; any other flag means the caller asked for something specific
225
226 inline bool has_transition_() { return (this->flags_ & FLAG_HAS_TRANSITION) != 0; }
227 inline bool has_flash_() { return (this->flags_ & FLAG_HAS_FLASH) != 0; }
228 inline bool has_effect_() { return (this->flags_ & FLAG_HAS_EFFECT) != 0; }
229 inline bool get_publish_() { return (this->flags_ & FLAG_PUBLISH) != 0; }
230 inline bool get_save_() { return (this->flags_ & FLAG_SAVE) != 0; }
231
232 // Helper to set flag - defaults to true for common case
233 void set_flag_(FieldFlags flag, bool value = true) ESPHOME_ALWAYS_INLINE { assign_bits(this->flags_, flag, value); }
234
235 // Helper to clear flag - reduces code size for common case
236 void clear_flag_(FieldFlags flag) ESPHOME_ALWAYS_INLINE { this->flags_ &= ~flag; }
237
238 // Helper to log unsupported feature and clear flag - reduces code duplication
239 void log_and_clear_unsupported_(FieldFlags flag, const LogString *feature, bool use_color_mode_log);
240
242
243 // Light state values - use flags_ to check if a value has been set.
249
250 // Smaller members at the end for better packing
251 uint16_t flags_{FLAG_PUBLISH | FLAG_SAVE}; // Tracks which values are set
253 bool state_;
254};
255
256} // namespace light
257} // namespace esphome
StringRef is a reference to a string owned by something else.
Definition string_ref.h:31
constexpr const char * c_str() const
Definition string_ref.h:78
constexpr size_type size() const
Definition string_ref.h:79
This class represents a requested change in a light state.
Definition light_call.h:24
bool has_color_mode() const
Definition light_call.h:161
bool has_color_temperature() const
Definition light_call.h:158
LightCall & set_color_mode_if_supported(ColorMode color_mode)
Set the color mode of the light, if this mode is supported.
LightCall & set_color_temperature(optional< float > color_temperature)
Set the color temperature of the light in mireds for CWWW or RGBWW lights.
LightCall & set_publish(bool publish)
Set whether this light call should trigger a publish state.
LightCall & set_state(bool state)
Set the binary ON/OFF state of the light.
void log_and_clear_unsupported_(FieldFlags flag, const LogString *feature, bool use_color_mode_log)
LightCall & set_flash_length(uint32_t flash_length)
Start and set the flash length of this call in milliseconds.
LightCall & set_color_brightness(optional< float > brightness)
Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)
bool has_warm_white() const
Definition light_call.h:160
void set_flag_(FieldFlags flag, bool value=true) ESPHOME_ALWAYS_INLINE
Definition light_call.h:233
LightCall & set_effect(const char *effect)
Set the effect of the light by its name (const char * overload to resolve ambiguity).
Definition light_call.h:137
LightCall & set_cold_white(float cold_white)
Set the cold white value of the light from 0.0 to 1.0.
bool has_brightness() const
Definition light_call.h:152
LightCall & set_rgb(float red, float green, float blue)
Set the RGB color of the light by RGB values.
bool has_cold_white() const
Definition light_call.h:159
LightCall & set_blue(float blue)
Set the blue RGB value of the light from 0.0 to 1.0.
void transform_parameters_(const LightTraits &traits)
Some color modes also can be set using non-native parameters, transform those calls.
LightCall & set_transition_length_if_supported(uint32_t transition_length)
Set the transition length property if the light supports transitions.
bool has_color_brightness() const
Definition light_call.h:153
LightCall & set_red_if_supported(float red)
Set the red property if the light supports RGB.
LightCall & set_effect(optional< std::string > effect)
Set the effect of the light by its name.
LightCall & set_color_brightness_if_supported(float brightness)
Set the color brightness property if the light supports RGBW.
LightCall & set_white(optional< float > white)
Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.
LightCall & set_transition_length(uint32_t transition_length)
Set the transition length of this call in milliseconds.
LightCall & set_color_temperature(float color_temperature)
Set the color temperature of the light in mireds for CWWW or RGBWW lights.
LightCall & set_green(optional< float > green)
Set the green RGB value of the light from 0.0 to 1.0.
LightCall & set_white(float white)
Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.
LightCall & set_color_mode(ColorMode color_mode)
Set the color mode of the light.
LightCall(LightState *parent)
Definition light_call.h:26
LightCall & set_green_if_supported(float green)
Set the green property if the light supports RGB.
LightCall & set_warm_white(optional< float > warm_white)
Set the warm white value of the light from 0.0 to 1.0.
LightCall & set_rgbw(float red, float green, float blue, float white)
Set the RGBW color of the light by RGB values.
LightCall & set_save(bool save)
Set whether this light call should trigger a save state to recover them at startup....
LightCall & set_effect(const std::string &effect)
Set the effect of the light by its name.
Definition light_call.h:135
LightCall & set_color_temperature_if_supported(float color_temperature)
Set the color_temperature property if the light supports color temperature.
void clear_flag_(FieldFlags flag) ESPHOME_ALWAYS_INLINE
Definition light_call.h:236
LightCall & set_blue(optional< float > blue)
Set the blue RGB value of the light from 0.0 to 1.0.
LightCall & set_flash_length(optional< uint32_t > flash_length)
Start and set the flash length of this call in milliseconds.
static constexpr uint16_t STATE_ONLY_FLAGS_MASK
Definition light_call.h:223
LightCall & set_cold_white(optional< float > cold_white)
Set the cold white value of the light from 0.0 to 1.0.
LightCall & set_red(optional< float > red)
Set the red RGB value of the light from 0.0 to 1.0.
LightCall & set_brightness(float brightness)
Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)
LightCall & set_green(float green)
Set the green RGB value of the light from 0.0 to 1.0.
ColorMode get_active_color_mode_()
Get the currently targeted, or active if none set, color mode.
static constexpr uint16_t VALUE_FLAGS_MASK
Definition light_call.h:224
LightCall & set_white_if_supported(float white)
Set the white property if the light supports RGB.
LightCall & set_cold_white_if_supported(float cold_white)
Set the cold white property if the light supports cold white output.
LightCall & set_warm_white_if_supported(float warm_white)
Set the warm white property if the light supports cold white output.
ColorMode compute_color_mode_(const LightTraits &traits)
LightCall & set_warm_white(float warm_white)
Set the warm white value of the light from 0.0 to 1.0.
static constexpr uint16_t CLAMP_FLAGS_MASK
Definition light_call.h:221
LightCall & set_brightness_if_supported(float brightness)
Set the brightness property if the light supports brightness.
LightColorValues validate_()
Validate all properties and return the target light color values.
LightCall & set_brightness(optional< float > brightness)
Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)
LightCall & set_blue_if_supported(float blue)
Set the blue property if the light supports RGB.
LightCall & from_light_color_values(const LightColorValues &values)
LightCall & set_state(optional< bool > state)
Set the binary ON/OFF state of the light.
LightCall & set_color_brightness(float brightness)
Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)
LightCall & set_color_mode(optional< ColorMode > color_mode)
Set the color mode of the light.
LightCall & set_red(float red)
Set the red RGB value of the light from 0.0 to 1.0.
color_mode_bitmask_t get_suitable_color_modes_mask_()
Get potential color modes bitmask for this light call.
LightCall & set_transition_length(optional< uint32_t > transition_length)
Set the transition length of this call in milliseconds.
LightCall & set_effect(StringRef effect)
Set the effect of the light by its name (StringRef overload to resolve ambiguity, zero-copy).
Definition light_call.h:139
This class represents the color state for a light object.
This class represents the communication layer between the front-end MQTT layer and the hardware outpu...
Definition light_state.h:68
This class is used to represent the capabilities of a light.
Definition light_traits.h:9
bool state
Definition fan.h:2
uint16_t color_mode_bitmask_t
Definition color_mode.h:109
ColorMode
Color modes are a combination of color capabilities that can be used at the same time.
Definition color_mode.h:50
uint32_t value
Definition hal.cpp:41
ESPHOME_ALWAYS_INLINE constexpr void assign_bits(T &value, std::type_identity_t< T > mask, bool on)
Set the bits of mask in value when on is true, clear them otherwise.
Definition helpers.h:1150
const void size_t len
Definition hal.h:68