light_state.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/component.h"
#include "esphome/core/entity_base.h"
#include "esphome/core/optional.h"
#include "esphome/core/preferences.h"
#include "esphome/core/string_ref.h"
#include "light_call.h"
#include "esp_color_correction.h"
#include "light_color_values.h"
#include "light_effect.h"
#include "light_traits.h"
#include "light_transformer.h"
 
#include "esphome/core/hal.h"
#include "esphome/core/helpers.h"
#include "esphome/core/progmem.h"
#include <strings.h>
#include <vector>
 
namespace esphome::light {
 
class LightOutput;
class LightState;
 
class LightRemoteValuesListener {
 public:
  virtual void on_light_remote_values_update() = 0;
};
 
class LightTargetStateReachedListener {
 public:
  virtual void on_light_target_state_reached() = 0;
};
 
struct LightStateRTCState {
  // Group 4-byte aligned members first
  float brightness{1.0f};
  float color_brightness{1.0f};
  float red{1.0f};
  float green{1.0f};
  float blue{1.0f};
  float white{1.0f};
  float color_temp{1.0f};
  float cold_white{1.0f};
  float warm_white{1.0f};
  uint32_t effect{0};
  // Group smaller members at the end
  ColorMode color_mode{ColorMode::UNKNOWN};
  bool state{false};
};
 
class LightState : public EntityBase, public Component {
 public:
  LightState(LightOutput *output);
 
  LightTraits get_traits();
 
  LightCall turn_on();
  LightCall turn_off();
  LightCall toggle();
 
  const LightColorValues &get_reported_values() const {
#ifdef USE_LIGHT_TRANSITION_PUBLISH_INTERVAL
    if (this->transition_publish_enabled_) {
      return this->current_values;
    }
#endif
    return this->remote_values;
  }
 
  bool is_transitioning() const { return this->transformer_ != nullptr; }
  LightCall make_call();
 
  // ========== INTERNAL METHODS ==========
  // (In most use cases you won't need these)
  void setup() override;
  void dump_config() override;
  void loop() override;
  float get_setup_priority() const override { return setup_priority::HARDWARE - 1.0f; }
 
  LightColorValues current_values;
 
  LightColorValues remote_values;
 
  void publish_state();
 
  LightOutput *get_output() const;
 
  StringRef get_effect_name();
 
  void add_remote_values_listener(LightRemoteValuesListener *listener);
 
  void add_target_state_reached_listener(LightTargetStateReachedListener *listener);
 
  void set_default_transition_length(uint32_t default_transition_length) {
    this->default_transition_length_ = default_transition_length;
  }
  uint32_t get_default_transition_length() const { return this->default_transition_length_; }
 
#ifdef USE_LIGHT_FLASH_TRANSITION_LENGTH
  void set_flash_transition_length(uint32_t flash_transition_length) {
    this->flash_transition_length_ = flash_transition_length;
  }
  uint32_t get_flash_transition_length() const { return this->flash_transition_length_; }
#else
  // Remove before 2027.4.0
  ESPDEPRECATED("set_flash_transition_length() does nothing unless flash_transition_length is set in YAML. Removed in "
                "2027.4.0",
                "2026.10.0")
  void set_flash_transition_length(uint32_t flash_transition_length) {}
  uint32_t get_flash_transition_length() const { return 0; }
#endif
 
  // Remove before 2027.4.0
  ESPDEPRECATED("set_gamma_correct() does nothing; gamma is fixed at build time by gamma_correct in YAML. Removed in "
                "2027.4.0",
                "2026.10.0")
  void set_gamma_correct(float gamma_correct) {}
  float get_gamma_correct() const;
 
#ifdef USE_LIGHT_TRANSITION_PUBLISH_INTERVAL
  void set_transition_state_publish_interval(uint32_t transition_state_publish_interval) {
    this->transition_state_publish_interval_ = transition_state_publish_interval;
  }
  uint32_t get_transition_state_publish_interval() const { return this->transition_state_publish_interval_; }
#endif
 
#ifdef USE_LIGHT_GAMMA_LUT
  void set_gamma_table(const GammaTable *table) { this->gamma_table_ = table; }
 
  const uint16_t *get_gamma_table() const { return this->gamma_table_ != nullptr ? this->gamma_table_->lut : nullptr; }
 
  float gamma_correct_lut(float value) const;
  float gamma_uncorrect_lut(float value) const;
#else
  float gamma_correct_lut(float value) const { return value; }
  float gamma_uncorrect_lut(float value) const { return value; }
#endif  // USE_LIGHT_GAMMA_LUT
 
  void set_state_callback(void (*callback)(LightStateRTCState &, bool restored)) { this->state_callback_ = callback; }
 
  void set_save_enabled(bool save_enabled) { this->save_enabled_ = save_enabled; }
 
#ifdef USE_LIGHT_RESUME_EFFECT
  void set_resume_effect(bool resume_effect) { this->resume_effect_ = resume_effect; }
#endif  // USE_LIGHT_RESUME_EFFECT
 
  bool supports_effects() const { return !this->effects_.empty(); }
 
  const FixedVector<LightEffect *> &get_effects() const { return this->effects_; }
 
  void add_effects(const std::initializer_list<LightEffect *> &effects);
 
  size_t get_effect_count() const { return this->effects_.size(); }
 
  uint32_t get_current_effect_index() const { return this->active_effect_index_; }
 
  uint32_t get_effect_index(const std::string &effect_name) const {
    if (str_equals_case_insensitive(effect_name, "none")) {
      return 0;
    }
    for (size_t i = 0; i < this->effects_.size(); i++) {
      if (str_equals_case_insensitive(effect_name, this->effects_[i]->get_name())) {
        return i + 1;  // Effects are 1-indexed in active_effect_index_
      }
    }
    return 0;  // Effect not found
  }
 
  uint32_t get_effect_index(const char *name, size_t len) const {
    if (len == 4 && ESPHOME_strncasecmp_P(name, ESPHOME_PSTR("none"), 4) == 0) {
      return 0;
    }
    StringRef ref(name, len);
    for (size_t i = 0; i < this->effects_.size(); i++) {
      if (str_equals_case_insensitive(ref, this->effects_[i]->get_name())) {
        return i + 1;
      }
    }
    return 0;
  }
 
  LightEffect *get_effect_by_index(uint32_t index) const {
    if (index == 0 || index > this->effects_.size()) {
      return nullptr;
    }
    return this->effects_[index - 1];  // Effects are 1-indexed in active_effect_index_
  }
 
  std::string get_effect_name_by_index(uint32_t index) const {
    if (index == 0) {
      return "None";
    }
    if (index > this->effects_.size()) {
      return "";  // Invalid index
    }
    return std::string(this->effects_[index - 1]->get_name());
  }
 
  void current_values_as_binary(bool *binary) { this->current_values.as_binary(binary); }
 
  void current_values_as_brightness(float *brightness);
 
  void current_values_as_rgb(float *red, float *green, float *blue);
 
  void current_values_as_rgbw(float *red, float *green, float *blue, float *white);
 
  void current_values_as_rgbww(float *red, float *green, float *blue, float *cold_white, float *warm_white,
                               bool constant_brightness = false);
 
  void current_values_as_rgbct(float *red, float *green, float *blue, float *color_temperature,
                               float *white_brightness);
 
  void current_values_as_cwww(float *cold_white, float *warm_white, bool constant_brightness = false);
 
  void current_values_as_ct(float *color_temperature, float *white_brightness);
 
  bool is_transformer_active() const { return this->is_transformer_active_; }
 
 protected:
  friend LightOutput;
  friend LightCall;
  friend class AddressableLight;
  friend class LightFlashTransformer;
 
  void start_effect_(uint32_t effect_index);
  LightEffect *get_active_effect_();
  void stop_effect_();
  void start_transition_(const LightColorValues &target, uint32_t length, bool set_remote_values);
 
  void start_flash_(const LightColorValues &target, uint32_t length, bool set_remote_values);
 
  void set_immediately_(const LightColorValues &target, bool set_remote_values);
 
#ifdef USE_LIGHT_TRANSITION_PUBLISH_INTERVAL
  void set_transformer_remote_values_(const LightColorValues &target, bool set_remote_values);
#else
  void set_transformer_remote_values_(const LightColorValues &target, bool set_remote_values) {
    if (set_remote_values) {
      this->remote_values = target;
    }
  }
#endif
 
  void save_remote_values_();
 
  void disable_loop_if_idle_();
 
  void schedule_write_() {
    this->next_write_ = true;
    this->enable_loop();
  }
 
  LightOutput *output_;
  std::unique_ptr<LightTransformer> transformer_{nullptr};
  FixedVector<LightEffect *> effects_;
  ESPPreferenceObject rtc_;
 
  std::unique_ptr<std::vector<LightRemoteValuesListener *>> remote_values_listeners_;
 
  std::unique_ptr<std::vector<LightTargetStateReachedListener *>> target_state_reached_listeners_;
 
  void (*state_callback_)(LightStateRTCState &, bool restored){nullptr};
 
  uint32_t default_transition_length_{};
#ifdef USE_LIGHT_FLASH_TRANSITION_LENGTH
  uint32_t flash_transition_length_{};  // Keep in sync with DEFAULT_FLASH_TRANSITION_LENGTH in __init__.py
#endif
#ifdef USE_LIGHT_TRANSITION_PUBLISH_INTERVAL
  uint32_t transition_state_publish_interval_{0};
  uint32_t last_transition_state_publish_{0};
#endif
#ifdef USE_LIGHT_GAMMA_LUT
  const GammaTable *gamma_table_{nullptr};
#endif  // USE_LIGHT_GAMMA_LUT
 
  uint16_t active_effect_index_{};
#ifdef USE_LIGHT_RESUME_EFFECT
  uint16_t previous_effect_index_{0};
#endif  // USE_LIGHT_RESUME_EFFECT
  bool next_write_{true};  // a plain bool: it is the most written flag, and still shares the index's word
  // for effects, true if a transformer (transition) is active.
  bool is_transformer_active_ : 1 {false};
  bool save_enabled_ : 1 {false};
#ifdef USE_LIGHT_TRANSITION_PUBLISH_INTERVAL
  bool transition_publish_enabled_ : 1 {false};
#endif
#ifdef USE_LIGHT_RESUME_EFFECT
  bool resume_effect_ : 1 {false};
#endif  // USE_LIGHT_RESUME_EFFECT
};
 
}  // namespace esphome::light