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/components/number/number.h"
#include "esphome/components/switch/switch.h"

#include <vector>

namespace esphome {
namespace sprinkler {

const std::string 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 SprinklerSwitch;            // switches representing any valve or pump; provides abstraction for latching valves
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;

class SprinklerSwitch {
 public:
  SprinklerSwitch();
  SprinklerSwitch(switch_::Switch *sprinkler_switch);
  SprinklerSwitch(switch_::Switch *off_switch, switch_::Switch *on_switch, uint32_t pulse_duration);

  bool is_latching_valve();  // returns true if configured as a latching valve
  void loop();               // called as a part of loop(), used for latching valve pulses
  uint32_t pulse_duration() { return this->pulse_duration_; }
  bool state();  // returns the switch's current state
  void set_off_switch(switch_::Switch *off_switch) { this->off_switch_ = off_switch; }
  void set_on_switch(switch_::Switch *on_switch) { this->on_switch_ = on_switch; }
  void set_pulse_duration(uint32_t pulse_duration) { this->pulse_duration_ = pulse_duration; }
  void sync_valve_state(
      bool latch_state);  // syncs internal state to switch; if latching valve, sets state to latch_state
  void turn_off();        // sets internal flag and actuates the switch
  void turn_on();         // sets internal flag and actuates the switch
  switch_::Switch *off_switch() { return this->off_switch_; }
  switch_::Switch *on_switch() { return this->on_switch_; }

 protected:
  bool state_{false};
  uint32_t pulse_duration_{0};
  uint64_t pinned_millis_{0};
  switch_::Switch *off_switch_{nullptr};  // only used for latching valves
  switch_::Switch *on_switch_{nullptr};   // used for both latching and non-latching valves
};

struct SprinklerQueueItem {
  size_t valve_number;
  uint32_t run_duration;
};

struct SprinklerTimer {
  const std::string name;
  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;
  SprinklerSwitch 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 : 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() const { return 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_ = new Trigger<float>();

  ESPPreferenceObject pref_;
};

class SprinklerControllerSwitch : 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() const;
  Trigger<> *get_turn_off_trigger() const;
  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();          // returns the valve's state/status
  SprinklerSwitch *pump_switch();  // returns this SprinklerValveOperator's pump's SprinklerSwitch

 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};
  uint64_t start_millis_{0};
  uint64_t stop_millis_{0};
  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();
  bool has_valve_operator();
  void set_request_from(SprinklerValveRunRequestOrigin 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();
  optional<size_t> valve_as_opt();
  SprinklerValveOperator *valve_operator();
  SprinklerValveRunRequestOrigin request_is_from();

 protected:
  bool has_valve_{false};
  size_t valve_number_{0};
  uint32_t run_duration_{0};
  SprinklerValveOperator *valve_op_{nullptr};
  SprinklerValveRunRequestOrigin origin_{USER};
};

class Sprinkler : public Component {
 public:
  Sprinkler();
  Sprinkler(const std::string &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);
  void set_controller_queue_enable_switch(SprinklerControllerSwitch *queue_enable_switch);
  void set_controller_reverse_switch(SprinklerControllerSwitch *reverse_switch);
  void set_controller_standby_switch(SprinklerControllerSwitch *standby_switch);

  void set_controller_multiplier_number(SprinklerControllerNumber *multiplier_number);
  void set_controller_repeat_number(SprinklerControllerNumber *repeat_number);

  void configure_valve_switch(size_t valve_number, switch_::Switch *valve_switch, uint32_t run_duration);
  void configure_valve_switch_pulsed(size_t valve_number, switch_::Switch *valve_switch_off,
                                     switch_::Switch *valve_switch_on, uint32_t pulse_duration, uint32_t run_duration);

  void configure_valve_pump_switch(size_t valve_number, switch_::Switch *pump_switch);
  void configure_valve_pump_switch_pulsed(size_t valve_number, switch_::Switch *pump_switch_off,
                                          switch_::Switch *pump_switch_on, uint32_t pulse_duration);

  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);

  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);

  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();

  const char *valve_name(size_t valve_number);

  optional<SprinklerValveRunRequestOrigin> active_valve_request_is_from();

  optional<size_t> active_valve();

  optional<size_t> paused_valve();

  optional<size_t> queued_valve();

  optional<size_t> manual_valve();

  size_t number_of_valves();

  bool is_a_valid_valve(size_t valve_number);

  bool pump_in_use(SprinklerSwitch *pump_switch);

  void set_pump_state(SprinklerSwitch *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);

  SprinklerSwitch *valve_switch(size_t valve_number);

  SprinklerSwitch *valve_pump_switch(size_t valve_number);

  SprinklerSwitch *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_();

  std::string req_as_str_(SprinklerValveRunRequestOrigin origin);

  std::string 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};

  std::string 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<SprinklerSwitch> pump_;

  std::vector<SprinklerValve> valve_;

  std::vector<SprinklerValveOperator> valve_op_{2};

  std::vector<SprinklerTimer> 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 sprinkler
}  // namespace esphome