sprinkler.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/hal.h"
#include "esphome/core/helpers.h"
#include "esphome/components/number/number.h"
#include "esphome/components/switch/switch.h"
 
#include <array>
#include <vector>
 
namespace esphome::sprinkler {
 
inline constexpr const char *MIN_STR = "min";
 
enum SprinklerState : uint8_t {
  // NOTE: these states are used by both SprinklerValveOperator and Sprinkler (the controller)!
  IDLE,      // system/valve is off
  STARTING,  // system/valve is starting/"half open" -- either pump or valve is on, but the remaining pump/valve is not
  ACTIVE,    // system/valve is running its cycle
  STOPPING,  // system/valve is stopping/"half open" -- either pump or valve is on, but the remaining pump/valve is not
  BYPASS     // used by SprinklerValveOperator to ignore the instance checking pump status
};
 
enum SprinklerTimerIndex : uint8_t {
  TIMER_SM = 0,
  TIMER_VALVE_SELECTION = 1,
};
 
enum SprinklerValveRunRequestOrigin : uint8_t {
  USER,
  CYCLE,
  QUEUE,
};
 
class Sprinkler;                  // this component
class SprinklerControllerNumber;  // number components that appear in the front end; based on number core
class SprinklerControllerSwitch;  // switches that appear in the front end; based on switch core
class SprinklerValveOperator;     // manages all switching on/off of valves and associated pumps
class SprinklerValveRunRequest;   // tells the sprinkler controller what valve to run and for how long as well as what
                                  //  SprinklerValveOperator is handling it
template<typename... Ts> class StartSingleValveAction;
template<typename... Ts> class ShutdownAction;
template<typename... Ts> class ResumeOrStartAction;
 
struct SprinklerQueueItem {
  size_t valve_number;
  uint32_t run_duration;
};
 
struct SprinklerTimer {
  bool active;
  uint32_t time;
  uint32_t start_time;
  std::function<void()> func;
};
 
struct SprinklerValve {
  SprinklerControllerNumber *run_duration_number;
  SprinklerControllerSwitch *controller_switch;
  SprinklerControllerSwitch *enable_switch;
  switch_::Switch *valve_switch;
  uint32_t run_duration;
  optional<size_t> pump_switch_index;
  bool valve_cycle_complete;
  std::unique_ptr<ShutdownAction<>> valve_shutdown_action;
  std::unique_ptr<StartSingleValveAction<>> valve_resumeorstart_action;
  std::unique_ptr<Automation<>> valve_turn_off_automation;
  std::unique_ptr<Automation<>> valve_turn_on_automation;
};
 
class SprinklerControllerNumber final : public number::Number, public Component {
 public:
  void setup() override;
  void dump_config() override;
  float get_setup_priority() const override { return setup_priority::PROCESSOR; }
 
  Trigger<float> *get_set_trigger() { return &this->set_trigger_; }
  void set_initial_value(float initial_value) { initial_value_ = initial_value; }
  void set_restore_value(bool restore_value) { this->restore_value_ = restore_value; }
 
 protected:
  void control(float value) override;
  float initial_value_{NAN};
  bool restore_value_{true};
  Trigger<float> set_trigger_;
 
  ESPPreferenceObject pref_;
};
 
class SprinklerControllerSwitch final : public switch_::Switch, public Component {
 public:
  SprinklerControllerSwitch();
 
  void setup() override;
  void dump_config() override;
 
  void set_state_lambda(std::function<optional<bool>()> &&f);
  Trigger<> *get_turn_on_trigger() { return &this->turn_on_trigger_; }
  Trigger<> *get_turn_off_trigger() { return &this->turn_off_trigger_; }
  void loop() override;
 
  float get_setup_priority() const override;
 
 protected:
  void write_state(bool state) override;
 
  optional<std::function<optional<bool>()>> f_;
  Trigger<> turn_on_trigger_;
  Trigger<> turn_off_trigger_;
  Trigger<> *prev_trigger_{nullptr};
};
 
class SprinklerValveOperator {
 public:
  SprinklerValveOperator();
  SprinklerValveOperator(SprinklerValve *valve, Sprinkler *controller);
  void loop();
  void set_controller(Sprinkler *controller);
  void set_valve(SprinklerValve *valve);
  void set_run_duration(uint32_t run_duration);  // set the desired run duration in seconds
  void set_start_delay(uint32_t start_delay, bool start_delay_is_valve_delay);
  void set_stop_delay(uint32_t stop_delay, bool stop_delay_is_valve_delay);
  void start();
  void stop();
  uint32_t run_duration();    // returns the desired run duration in seconds
  uint32_t time_remaining();  // returns seconds remaining (does not include stop_delay_)
  SprinklerState state() { return this->state_; }
  switch_::Switch *pump_switch();  // returns this SprinklerValveOperator's pump switch
 
 protected:
  void pump_off_();
  void pump_on_();
  void valve_off_();
  void valve_on_();
  void kill_();
  void run_();
  bool start_delay_is_valve_delay_{false};
  bool stop_delay_is_valve_delay_{false};
  uint32_t start_delay_{0};
  uint32_t stop_delay_{0};
  uint32_t run_duration_{0};
  optional<uint32_t> start_millis_{};
  optional<uint32_t> stop_millis_{};
  Sprinkler *controller_{nullptr};
  SprinklerValve *valve_{nullptr};
  SprinklerState state_{IDLE};
};
 
class SprinklerValveRunRequest {
 public:
  SprinklerValveRunRequest();
  SprinklerValveRunRequest(size_t valve_number, uint32_t run_duration, SprinklerValveOperator *valve_op);
  bool has_request() { return this->has_valve_; }
  bool has_valve_operator();
  void set_request_from(SprinklerValveRunRequestOrigin origin) { this->origin_ = origin; }
  void set_run_duration(uint32_t run_duration);
  void set_valve(size_t valve_number);
  void set_valve_operator(SprinklerValveOperator *valve_op);
  void reset();
  uint32_t run_duration();
  size_t valve() { return this->valve_number_; }
  optional<size_t> valve_as_opt();
  SprinklerValveOperator *valve_operator();
  SprinklerValveRunRequestOrigin request_is_from() { return this->origin_; }
 
 protected:
  bool has_valve_{false};
  size_t valve_number_{0};
  uint32_t run_duration_{0};
  SprinklerValveOperator *valve_op_{nullptr};
  SprinklerValveRunRequestOrigin origin_{USER};
};
 
class Sprinkler final : public Component {
 public:
  Sprinkler();
  Sprinkler(const char *name);
  void setup() override;
  void loop() override;
  void dump_config() override;
 
  void add_valve(SprinklerControllerSwitch *valve_sw, SprinklerControllerSwitch *enable_sw = nullptr);
 
  void add_controller(Sprinkler *other_controller);
 
  void set_controller_main_switch(SprinklerControllerSwitch *controller_switch);
  void set_controller_auto_adv_switch(SprinklerControllerSwitch *auto_adv_switch) {
    this->auto_adv_sw_ = auto_adv_switch;
  }
  void set_controller_queue_enable_switch(SprinklerControllerSwitch *queue_enable_switch) {
    this->queue_enable_sw_ = queue_enable_switch;
  }
  void set_controller_reverse_switch(SprinklerControllerSwitch *reverse_switch) { this->reverse_sw_ = reverse_switch; }
  void set_controller_standby_switch(SprinklerControllerSwitch *standby_switch);
 
  void set_controller_multiplier_number(SprinklerControllerNumber *multiplier_number) {
    this->multiplier_number_ = multiplier_number;
  }
  void set_controller_repeat_number(SprinklerControllerNumber *repeat_number) { this->repeat_number_ = repeat_number; }
 
  void configure_valve_switch(size_t valve_number, switch_::Switch *valve_switch, uint32_t run_duration);
 
  void configure_valve_pump_switch(size_t valve_number, switch_::Switch *pump_switch);
 
  void configure_valve_run_duration_number(size_t valve_number, SprinklerControllerNumber *run_duration_number);
 
  void set_divider(optional<uint32_t> divider);
 
  void set_multiplier(optional<float> multiplier);
 
  void set_next_prev_ignore_disabled_valves(bool ignore_disabled) {
    this->next_prev_ignore_disabled_ = ignore_disabled;
  }
 
  void set_pump_start_delay(uint32_t start_delay);
 
  void set_pump_stop_delay(uint32_t stop_delay);
 
  void set_valve_start_delay(uint32_t start_delay);
 
  void set_valve_stop_delay(uint32_t stop_delay);
 
  void set_pump_switch_off_during_valve_open_delay(bool pump_switch_off_during_valve_open_delay) {
    this->pump_switch_off_during_valve_open_delay_ = pump_switch_off_during_valve_open_delay;
  }
 
  void set_valve_open_delay(uint32_t valve_open_delay);
 
  void set_valve_overlap(uint32_t valve_overlap);
 
  void set_manual_selection_delay(uint32_t manual_selection_delay);
 
  void set_valve_run_duration(optional<size_t> valve_number, optional<uint32_t> run_duration);
 
  void set_auto_advance(bool auto_advance);
 
  void set_repeat(optional<uint32_t> repeat);
 
  void set_queue_enable(bool queue_enable);
 
  void set_reverse(bool reverse);
 
  void set_standby(bool standby);
 
  uint32_t valve_run_duration(size_t valve_number);
 
  uint32_t valve_run_duration_adjusted(size_t valve_number);
 
  bool auto_advance();
 
  float multiplier();
 
  optional<uint32_t> repeat();
 
  optional<uint32_t> repeat_count();
 
  bool queue_enabled();
 
  bool reverse();
 
  bool standby();
 
  void start_from_queue();
 
  void start_full_cycle();
 
  void start_single_valve(optional<size_t> valve_number, optional<uint32_t> run_duration = nullopt);
 
  void queue_valve(optional<size_t> valve_number, optional<uint32_t> run_duration);
 
  void clear_queued_valves();
 
  void next_valve();
 
  void previous_valve();
 
  void shutdown(bool clear_queue = false);
 
  void pause();
 
  void resume();
 
  void resume_or_start_full_cycle();
 
  void reset_resume();
 
  ESPDEPRECATED("Use valve_log_name() or control_switch()->get_name_to() instead. Will be removed in ESPHome 2027.5.0",
                "2026.11.0")
  const char *valve_name(size_t valve_number);
  const LogString *valve_log_name(size_t valve_number);
 
  optional<SprinklerValveRunRequestOrigin> active_valve_request_is_from();
 
  optional<size_t> active_valve();
 
  optional<size_t> paused_valve() { return this->paused_valve_; }
 
  optional<size_t> queued_valve();
 
  optional<size_t> manual_valve() { return this->manual_valve_; }
 
  size_t number_of_valves() { return this->valve_.size(); }
 
  bool is_a_valid_valve(size_t valve_number);
 
  bool pump_in_use(switch_::Switch *pump_switch);
 
  void set_pump_state(switch_::Switch *pump_switch, bool state);
 
  uint32_t total_cycle_time_all_valves();
 
  uint32_t total_cycle_time_enabled_valves();
 
  uint32_t total_cycle_time_enabled_incomplete_valves();
 
  uint32_t total_queue_time();
 
  optional<uint32_t> time_remaining_active_valve();
 
  optional<uint32_t> time_remaining_current_operation();
 
  bool any_controller_is_active();
 
  SprinklerState controller_state() { return this->state_; };
 
  SprinklerControllerSwitch *control_switch(size_t valve_number);
 
  SprinklerControllerSwitch *enable_switch(size_t valve_number);
 
  switch_::Switch *valve_switch(size_t valve_number);
 
  switch_::Switch *valve_pump_switch(size_t valve_number);
 
  switch_::Switch *valve_pump_switch_by_pump_index(size_t pump_index);
 
 protected:
  bool valve_is_enabled_(size_t valve_number);
 
  void mark_valve_cycle_complete_(size_t valve_number);
 
  bool valve_cycle_complete_(size_t valve_number);
 
  optional<size_t> next_valve_number_(optional<size_t> first_valve = nullopt, bool include_disabled = true,
                                      bool include_complete = true);
 
  optional<size_t> previous_valve_number_(optional<size_t> first_valve = nullopt, bool include_disabled = true,
                                          bool include_complete = true);
 
  optional<size_t> next_valve_number_in_cycle_(optional<size_t> first_valve = nullopt);
 
  void load_next_valve_run_request_(optional<size_t> first_valve = nullopt);
 
  bool any_valve_is_enabled_();
 
  void start_valve_(SprinklerValveRunRequest *req);
 
  void all_valves_off_(bool include_pump = false);
 
  void prep_full_cycle_();
 
  void reset_cycle_states_();
 
  void fsm_request_(size_t requested_valve, uint32_t requested_run_duration = 0);
 
  void fsm_kick_();
 
  void fsm_transition_();
 
  void fsm_transition_from_shutdown_();
 
  void fsm_transition_from_valve_run_();
 
  void fsm_transition_to_shutdown_();
 
  void log_standby_warning_(const LogString *method_name);
 
  void log_multiplier_zero_warning_(const LogString *method_name);
 
  const LogString *req_as_str_(SprinklerValveRunRequestOrigin origin);
 
  const LogString *state_as_str_(SprinklerState state);
 
  void start_timer_(SprinklerTimerIndex timer_index);
  bool cancel_timer_(SprinklerTimerIndex timer_index);
  bool timer_active_(SprinklerTimerIndex timer_index);
  void set_timer_duration_(SprinklerTimerIndex timer_index, uint32_t time);
  uint32_t timer_duration_(SprinklerTimerIndex timer_index);
  std::function<void()> timer_cbf_(SprinklerTimerIndex timer_index);
 
  void valve_selection_callback_();
  void sm_timer_callback_();
 
  const uint8_t max_queue_size_{100};
 
  bool next_prev_ignore_disabled_{false};
 
  bool pump_switch_off_during_valve_open_delay_{false};
 
  bool valve_overlap_{false};
 
  bool start_delay_is_valve_delay_{false};
  bool stop_delay_is_valve_delay_{false};
 
  uint32_t start_delay_{0};
  uint32_t stop_delay_{0};
 
  const char *name_{""};
 
  SprinklerState state_{IDLE};
 
  SprinklerValveRunRequest active_req_;
 
  SprinklerValveRunRequest next_req_;
 
  SprinklerValveRunRequest prev_req_;
 
  optional<size_t> manual_valve_;
 
  optional<size_t> paused_valve_;
 
  optional<uint32_t> target_repeats_;
 
  optional<uint32_t> resume_duration_;
 
  optional<uint32_t> manual_selection_delay_;
 
  optional<uint32_t> switching_delay_;
 
  uint32_t repeat_count_{0};
 
  float multiplier_{1.0};
 
  std::vector<SprinklerQueueItem> queued_valves_;
 
  std::vector<switch_::Switch *> pump_;
 
  std::vector<SprinklerValve> valve_;
 
  std::vector<SprinklerValveOperator> valve_op_{2};
 
  std::array<SprinklerTimer, 2> timer_;
 
  std::vector<Sprinkler *> other_controllers_;
 
  SprinklerControllerSwitch *auto_adv_sw_{nullptr};
  SprinklerControllerSwitch *controller_sw_{nullptr};
  SprinklerControllerSwitch *queue_enable_sw_{nullptr};
  SprinklerControllerSwitch *reverse_sw_{nullptr};
  SprinklerControllerSwitch *standby_sw_{nullptr};
 
  SprinklerControllerNumber *multiplier_number_{nullptr};
  SprinklerControllerNumber *repeat_number_{nullptr};
 
  std::unique_ptr<ShutdownAction<>> sprinkler_shutdown_action_;
  std::unique_ptr<ShutdownAction<>> sprinkler_standby_shutdown_action_;
  std::unique_ptr<ResumeOrStartAction<>> sprinkler_resumeorstart_action_;
 
  std::unique_ptr<Automation<>> sprinkler_turn_off_automation_;
  std::unique_ptr<Automation<>> sprinkler_turn_on_automation_;
  std::unique_ptr<Automation<>> sprinkler_standby_turn_on_automation_;
};
 
}  // namespace esphome::sprinkler