sprinkler.cpp

Go to the documentation of this file.

#include "automation.h"
#include "sprinkler.h"

#include "esphome/core/application.h"
#include "esphome/core/helpers.h"
#include "esphome/core/log.h"
#include <cinttypes>
#include <utility>

namespace esphome {
namespace sprinkler {

static const char *const TAG = "sprinkler";

SprinklerSwitch::SprinklerSwitch() {}
SprinklerSwitch::SprinklerSwitch(switch_::Switch *sprinkler_switch) : on_switch_(sprinkler_switch) {}
SprinklerSwitch::SprinklerSwitch(switch_::Switch *off_switch, switch_::Switch *on_switch, uint32_t pulse_duration)
    : pulse_duration_(pulse_duration), off_switch_(off_switch), on_switch_(on_switch) {}

bool SprinklerSwitch::is_latching_valve() { return (this->off_switch_ != nullptr) && (this->on_switch_ != nullptr); }

void SprinklerSwitch::loop() {
  if ((this->pinned_millis_) && (millis() > this->pinned_millis_ + this->pulse_duration_)) {
    this->pinned_millis_ = 0;  // reset tracker
    if (this->off_switch_->state) {
      this->off_switch_->turn_off();
    }
    if (this->on_switch_->state) {
      this->on_switch_->turn_off();
    }
  }
}

void SprinklerSwitch::turn_off() {
  if (!this->state()) {  // do nothing if we're already in the requested state
    return;
  }
  if (this->off_switch_ != nullptr) {  // latching valve, start a pulse
    if (!this->off_switch_->state) {
      this->off_switch_->turn_on();
    }
    this->pinned_millis_ = millis();
  } else if (this->on_switch_ != nullptr) {  // non-latching valve
    this->on_switch_->turn_off();
  }
  this->state_ = false;
}

void SprinklerSwitch::turn_on() {
  if (this->state()) {  // do nothing if we're already in the requested state
    return;
  }
  if (this->off_switch_ != nullptr) {  // latching valve, start a pulse
    if (!this->on_switch_->state) {
      this->on_switch_->turn_on();
    }
    this->pinned_millis_ = millis();
  } else if (this->on_switch_ != nullptr) {  // non-latching valve
    this->on_switch_->turn_on();
  }
  this->state_ = true;
}

bool SprinklerSwitch::state() {
  if ((this->off_switch_ == nullptr) && (this->on_switch_ != nullptr)) {  // latching valve is not configured...
    return this->on_switch_->state;                                       // ...so just return the pump switch state
  }
  return this->state_;
}

void SprinklerSwitch::sync_valve_state(bool latch_state) {
  if (this->is_latching_valve()) {
    this->state_ = latch_state;
  } else if (this->on_switch_ != nullptr) {
    this->state_ = this->on_switch_->state;
  }
}

void SprinklerControllerNumber::setup() {
  float value;
  if (!this->restore_value_) {
    value = this->initial_value_;
  } else {
    this->pref_ = global_preferences->make_preference<float>(this->get_object_id_hash());
    if (!this->pref_.load(&value)) {
      if (!std::isnan(this->initial_value_)) {
        value = this->initial_value_;
      } else {
        value = this->traits.get_min_value();
      }
    }
  }
  this->publish_state(value);
}

void SprinklerControllerNumber::control(float value) {
  this->set_trigger_->trigger(value);

  this->publish_state(value);

  if (this->restore_value_)
    this->pref_.save(&value);
}

void SprinklerControllerNumber::dump_config() { LOG_NUMBER("", "Sprinkler Controller Number", this); }

SprinklerControllerSwitch::SprinklerControllerSwitch()
    : turn_on_trigger_(new Trigger<>()), turn_off_trigger_(new Trigger<>()) {}

void SprinklerControllerSwitch::loop() {
  if (!this->f_.has_value())
    return;
  auto s = (*this->f_)();
  if (!s.has_value())
    return;

  this->publish_state(*s);
}

void SprinklerControllerSwitch::write_state(bool state) {
  if (this->prev_trigger_ != nullptr) {
    this->prev_trigger_->stop_action();
  }

  if (state) {
    this->prev_trigger_ = this->turn_on_trigger_;
    this->turn_on_trigger_->trigger();
  } else {
    this->prev_trigger_ = this->turn_off_trigger_;
    this->turn_off_trigger_->trigger();
  }

  this->publish_state(state);
}

void SprinklerControllerSwitch::set_state_lambda(std::function<optional<bool>()> &&f) { this->f_ = f; }
float SprinklerControllerSwitch::get_setup_priority() const { return setup_priority::HARDWARE; }

Trigger<> *SprinklerControllerSwitch::get_turn_on_trigger() const { return this->turn_on_trigger_; }
Trigger<> *SprinklerControllerSwitch::get_turn_off_trigger() const { return this->turn_off_trigger_; }

void SprinklerControllerSwitch::setup() { this->state = this->get_initial_state_with_restore_mode().value_or(false); }

void SprinklerControllerSwitch::dump_config() { LOG_SWITCH("", "Sprinkler Switch", this); }

SprinklerValveOperator::SprinklerValveOperator() {}
SprinklerValveOperator::SprinklerValveOperator(SprinklerValve *valve, Sprinkler *controller)
    : controller_(controller), valve_(valve) {}

void SprinklerValveOperator::loop() {
  if (millis() >= this->start_millis_) {  // dummy check
    switch (this->state_) {
      case STARTING:
        if (millis() > (this->start_millis_ + this->start_delay_)) {
          this->run_();  // start_delay_ has been exceeded, so ensure both valves are on and update the state
        }
        break;

      case ACTIVE:
        if (millis() > (this->start_millis_ + this->start_delay_ + this->run_duration_)) {
          this->stop();  // start_delay_ + run_duration_ has been exceeded, start shutting down
        }
        break;

      case STOPPING:
        if (millis() > (this->stop_millis_ + this->stop_delay_)) {
          this->kill_();  // stop_delay_has been exceeded, ensure all valves are off
        }
        break;

      default:
        break;
    }
  } else {         // perhaps millis() rolled over...or something else is horribly wrong!
    this->stop();  // bail out (TODO: handle this highly unlikely situation better...)
  }
}

void SprinklerValveOperator::set_controller(Sprinkler *controller) {
  if (controller != nullptr) {
    this->controller_ = controller;
  }
}

void SprinklerValveOperator::set_valve(SprinklerValve *valve) {
  if (valve != nullptr) {
    this->state_ = IDLE;      // reset state
    this->run_duration_ = 0;  // reset to ensure the valve isn't started without updating it
    this->start_millis_ = 0;  // reset because (new) valve has not been started yet
    this->stop_millis_ = 0;   // reset because (new) valve has not been started yet
    this->kill_();            // ensure everything is off before we let go!
    this->valve_ = valve;     // finally, set the pointer to the new valve
  }
}

void SprinklerValveOperator::set_run_duration(uint32_t run_duration) {
  if (run_duration) {
    this->run_duration_ = run_duration * 1000;
  }
}

void SprinklerValveOperator::set_start_delay(uint32_t start_delay, bool start_delay_is_valve_delay) {
  this->start_delay_is_valve_delay_ = start_delay_is_valve_delay;
  this->start_delay_ = start_delay * 1000;  // because 1000 milliseconds is one second
}

void SprinklerValveOperator::set_stop_delay(uint32_t stop_delay, bool stop_delay_is_valve_delay) {
  this->stop_delay_is_valve_delay_ = stop_delay_is_valve_delay;
  this->stop_delay_ = stop_delay * 1000;  // because 1000 milliseconds is one second
}

void SprinklerValveOperator::start() {
  if (!this->run_duration_) {  // can't start if zero run duration
    return;
  }
  if (this->start_delay_ && (this->pump_switch() != nullptr)) {
    this->state_ = STARTING;  // STARTING state requires both a pump and a start_delay_
    if (this->start_delay_is_valve_delay_) {
      this->pump_on_();
    } else if (!this->pump_switch()->state()) {  // if the pump is already on, wait to switch on the valve
      this->valve_on_();                         //  to ensure consistent run time
    }
  } else {
    this->run_();  // there is no start_delay_, so just start the pump and valve
  }
  this->stop_millis_ = 0;
  this->start_millis_ = millis();  // save the time the start request was made
}

void SprinklerValveOperator::stop() {
  if ((this->state_ == IDLE) || (this->state_ == STOPPING)) {  // can't stop if already stopped or stopping
    return;
  }
  if (this->stop_delay_ && (this->pump_switch() != nullptr)) {
    this->state_ = STOPPING;  // STOPPING state requires both a pump and a stop_delay_
    if (this->stop_delay_is_valve_delay_) {
      this->pump_off_();
    } else {
      this->valve_off_();
    }
    if (this->pump_switch()->state()) {  // if the pump is still on at this point, it may be in use...
      this->valve_off_();                // ...so just switch the valve off now to ensure consistent run time
    }
  } else {
    this->kill_();  // there is no stop_delay_, so just stop the pump and valve
  }
  this->stop_millis_ = millis();  // save the time the stop request was made
}

uint32_t SprinklerValveOperator::run_duration() { return this->run_duration_ / 1000; }

uint32_t SprinklerValveOperator::time_remaining() {
  if (this->start_millis_ == 0) {
    return this->run_duration();  // hasn't been started yet
  }

  if (this->stop_millis_) {
    if (this->stop_millis_ - this->start_millis_ >= this->start_delay_ + this->run_duration_) {
      return 0;  // valve was active for more than its configured duration, so we are done
    } else {
      // we're stopped; return time remaining
      return (this->run_duration_ - (this->stop_millis_ - this->start_millis_)) / 1000;
    }
  }

  auto completed_millis = this->start_millis_ + this->start_delay_ + this->run_duration_;
  if (completed_millis > millis()) {
    return (completed_millis - millis()) / 1000;  // running now
  }
  return 0;  // run completed
}

SprinklerState SprinklerValveOperator::state() { return this->state_; }

SprinklerSwitch *SprinklerValveOperator::pump_switch() {
  if ((this->controller_ == nullptr) || (this->valve_ == nullptr)) {
    return nullptr;
  }
  if (this->valve_->pump_switch_index.has_value()) {
    return this->controller_->valve_pump_switch_by_pump_index(this->valve_->pump_switch_index.value());
  }
  return nullptr;
}

void SprinklerValveOperator::pump_off_() {
  if ((this->valve_ == nullptr) || (this->pump_switch() == nullptr)) {  // safety first!
    return;
  }
  if (this->controller_ == nullptr) {  // safety first!
    this->pump_switch()->turn_off();   // if no controller was set, just switch off the pump
  } else {                             // ...otherwise, do it "safely"
    auto state = this->state_;         // this is silly, but...
    this->state_ = BYPASS;             // ...exclude me from the pump-in-use check that set_pump_state() does
    this->controller_->set_pump_state(this->pump_switch(), false);
    this->state_ = state;
  }
}

void SprinklerValveOperator::pump_on_() {
  if ((this->valve_ == nullptr) || (this->pump_switch() == nullptr)) {  // safety first!
    return;
  }
  if (this->controller_ == nullptr) {  // safety first!
    this->pump_switch()->turn_on();    // if no controller was set, just switch on the pump
  } else {                             // ...otherwise, do it "safely"
    auto state = this->state_;         // this is silly, but...
    this->state_ = BYPASS;             // ...exclude me from the pump-in-use check that set_pump_state() does
    this->controller_->set_pump_state(this->pump_switch(), true);
    this->state_ = state;
  }
}

void SprinklerValveOperator::valve_off_() {
  if (this->valve_ == nullptr) {  // safety first!
    return;
  }
  if (this->valve_->valve_switch.state()) {
    this->valve_->valve_switch.turn_off();
  }
}

void SprinklerValveOperator::valve_on_() {
  if (this->valve_ == nullptr) {  // safety first!
    return;
  }
  if (!this->valve_->valve_switch.state()) {
    this->valve_->valve_switch.turn_on();
  }
}

void SprinklerValveOperator::kill_() {
  this->state_ = IDLE;
  this->valve_off_();
  this->pump_off_();
}

void SprinklerValveOperator::run_() {
  this->state_ = ACTIVE;
  this->valve_on_();
  this->pump_on_();
}

SprinklerValveRunRequest::SprinklerValveRunRequest() {}
SprinklerValveRunRequest::SprinklerValveRunRequest(size_t valve_number, uint32_t run_duration,
                                                   SprinklerValveOperator *valve_op)
    : valve_number_(valve_number), run_duration_(run_duration), valve_op_(valve_op) {}

bool SprinklerValveRunRequest::has_request() { return this->has_valve_; }
bool SprinklerValveRunRequest::has_valve_operator() { return !(this->valve_op_ == nullptr); }

void SprinklerValveRunRequest::set_request_from(SprinklerValveRunRequestOrigin origin) { this->origin_ = origin; }

void SprinklerValveRunRequest::set_run_duration(uint32_t run_duration) { this->run_duration_ = run_duration; }

void SprinklerValveRunRequest::set_valve(size_t valve_number) {
  this->valve_number_ = valve_number;
  this->run_duration_ = 0;
  this->valve_op_ = nullptr;
  this->has_valve_ = true;
}

void SprinklerValveRunRequest::set_valve_operator(SprinklerValveOperator *valve_op) {
  if (valve_op != nullptr) {
    this->valve_op_ = valve_op;
  }
}

void SprinklerValveRunRequest::reset() {
  this->has_valve_ = false;
  this->origin_ = USER;
  this->run_duration_ = 0;
  this->valve_op_ = nullptr;
}

uint32_t SprinklerValveRunRequest::run_duration() { return this->run_duration_; }

size_t SprinklerValveRunRequest::valve() { return this->valve_number_; }

optional<size_t> SprinklerValveRunRequest::valve_as_opt() {
  if (this->has_valve_) {
    return this->valve_number_;
  }
  return nullopt;
}

SprinklerValveOperator *SprinklerValveRunRequest::valve_operator() { return this->valve_op_; }

SprinklerValveRunRequestOrigin SprinklerValveRunRequest::request_is_from() { return this->origin_; }

Sprinkler::Sprinkler() {}
Sprinkler::Sprinkler(const std::string &name) {
  // The `name` is needed to set timers up, hence non-default constructor
  // replaces `set_name()` method previously existed
  this->name_ = name;
  this->timer_.push_back({this->name_ + "sm", false, 0, 0, std::bind(&Sprinkler::sm_timer_callback_, this)});
  this->timer_.push_back({this->name_ + "vs", false, 0, 0, std::bind(&Sprinkler::valve_selection_callback_, this)});
}

void Sprinkler::setup() { this->all_valves_off_(true); }

void Sprinkler::loop() {
  for (auto &p : this->pump_) {
    p.loop();
  }
  for (auto &v : this->valve_) {
    v.valve_switch.loop();
  }
  for (auto &vo : this->valve_op_) {
    vo.loop();
  }
  if (this->prev_req_.has_request() && this->prev_req_.valve_operator()->state() == IDLE) {
    this->prev_req_.reset();
  }
}

void Sprinkler::add_valve(SprinklerControllerSwitch *valve_sw, SprinklerControllerSwitch *enable_sw) {
  auto new_valve_number = this->number_of_valves();
  this->valve_.resize(new_valve_number + 1);
  SprinklerValve *new_valve = &this->valve_[new_valve_number];

  new_valve->controller_switch = valve_sw;
  new_valve->controller_switch->set_state_lambda([=]() -> optional<bool> {
    if (this->valve_pump_switch(new_valve_number) != nullptr) {
      return this->valve_switch(new_valve_number)->state() && this->valve_pump_switch(new_valve_number)->state();
    }
    return this->valve_switch(new_valve_number)->state();
  });

  new_valve->valve_turn_off_automation =
      make_unique<Automation<>>(new_valve->controller_switch->get_turn_off_trigger());
  new_valve->valve_shutdown_action = make_unique<sprinkler::ShutdownAction<>>(this);
  new_valve->valve_turn_off_automation->add_actions({new_valve->valve_shutdown_action.get()});

  new_valve->valve_turn_on_automation = make_unique<Automation<>>(new_valve->controller_switch->get_turn_on_trigger());
  new_valve->valve_resumeorstart_action = make_unique<sprinkler::StartSingleValveAction<>>(this);
  new_valve->valve_resumeorstart_action->set_valve_to_start(new_valve_number);
  new_valve->valve_turn_on_automation->add_actions({new_valve->valve_resumeorstart_action.get()});

  if (enable_sw != nullptr) {
    new_valve->enable_switch = enable_sw;
  }
}

void Sprinkler::add_controller(Sprinkler *other_controller) { this->other_controllers_.push_back(other_controller); }

void Sprinkler::set_controller_main_switch(SprinklerControllerSwitch *controller_switch) {
  this->controller_sw_ = controller_switch;
  controller_switch->set_state_lambda([=]() -> optional<bool> {
    for (size_t valve_number = 0; valve_number < this->number_of_valves(); valve_number++) {
      if (this->valve_[valve_number].controller_switch->state) {
        return true;
      }
    }
    return this->active_req_.has_request();
  });

  this->sprinkler_turn_off_automation_ = make_unique<Automation<>>(controller_switch->get_turn_off_trigger());
  this->sprinkler_shutdown_action_ = make_unique<sprinkler::ShutdownAction<>>(this);
  this->sprinkler_turn_off_automation_->add_actions({sprinkler_shutdown_action_.get()});

  this->sprinkler_turn_on_automation_ = make_unique<Automation<>>(controller_switch->get_turn_on_trigger());
  this->sprinkler_resumeorstart_action_ = make_unique<sprinkler::ResumeOrStartAction<>>(this);
  this->sprinkler_turn_on_automation_->add_actions({sprinkler_resumeorstart_action_.get()});
}

void Sprinkler::set_controller_auto_adv_switch(SprinklerControllerSwitch *auto_adv_switch) {
  this->auto_adv_sw_ = auto_adv_switch;
}

void Sprinkler::set_controller_queue_enable_switch(SprinklerControllerSwitch *queue_enable_switch) {
  this->queue_enable_sw_ = queue_enable_switch;
}

void Sprinkler::set_controller_reverse_switch(SprinklerControllerSwitch *reverse_switch) {
  this->reverse_sw_ = reverse_switch;
}

void Sprinkler::set_controller_standby_switch(SprinklerControllerSwitch *standby_switch) {
  this->standby_sw_ = standby_switch;

  this->sprinkler_standby_turn_on_automation_ = make_unique<Automation<>>(standby_switch->get_turn_on_trigger());
  this->sprinkler_standby_shutdown_action_ = make_unique<sprinkler::ShutdownAction<>>(this);
  this->sprinkler_standby_turn_on_automation_->add_actions({sprinkler_standby_shutdown_action_.get()});
}

void Sprinkler::set_controller_multiplier_number(SprinklerControllerNumber *multiplier_number) {
  this->multiplier_number_ = multiplier_number;
}

void Sprinkler::set_controller_repeat_number(SprinklerControllerNumber *repeat_number) {
  this->repeat_number_ = repeat_number;
}

void Sprinkler::configure_valve_switch(size_t valve_number, switch_::Switch *valve_switch, uint32_t run_duration) {
  if (this->is_a_valid_valve(valve_number)) {
    this->valve_[valve_number].valve_switch.set_on_switch(valve_switch);
    this->valve_[valve_number].run_duration = run_duration;
  }
}

void Sprinkler::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) {
  if (this->is_a_valid_valve(valve_number)) {
    this->valve_[valve_number].valve_switch.set_off_switch(valve_switch_off);
    this->valve_[valve_number].valve_switch.set_on_switch(valve_switch_on);
    this->valve_[valve_number].valve_switch.set_pulse_duration(pulse_duration);
    this->valve_[valve_number].run_duration = run_duration;
  }
}

void Sprinkler::configure_valve_pump_switch(size_t valve_number, switch_::Switch *pump_switch) {
  if (this->is_a_valid_valve(valve_number)) {
    for (size_t i = 0; i < this->pump_.size(); i++) {      // check each existing registered pump
      if (this->pump_[i].on_switch() == pump_switch) {     // if the "new" pump matches one we already have...
        this->valve_[valve_number].pump_switch_index = i;  // ...save its index in the SprinklerSwitch vector pump_...
        return;                                            // ...and we are done
      }
    }  // if we end up here, no pumps matched, so add a new one and set the valve's SprinklerSwitch at it
    this->pump_.resize(this->pump_.size() + 1);
    this->pump_.back().set_on_switch(pump_switch);
    this->valve_[valve_number].pump_switch_index = this->pump_.size() - 1;  // save the index to the new pump
  }
}

void Sprinkler::configure_valve_pump_switch_pulsed(size_t valve_number, switch_::Switch *pump_switch_off,
                                                   switch_::Switch *pump_switch_on, uint32_t pulse_duration) {
  if (this->is_a_valid_valve(valve_number)) {
    for (size_t i = 0; i < this->pump_.size(); i++) {  // check each existing registered pump
      if ((this->pump_[i].off_switch() == pump_switch_off) &&
          (this->pump_[i].on_switch() == pump_switch_on)) {  // if the "new" pump matches one we already have...
        this->valve_[valve_number].pump_switch_index = i;    // ...save its index in the SprinklerSwitch vector pump_...
        return;                                              // ...and we are done
      }
    }  // if we end up here, no pumps matched, so add a new one and set the valve's SprinklerSwitch at it
    this->pump_.resize(this->pump_.size() + 1);
    this->pump_.back().set_off_switch(pump_switch_off);
    this->pump_.back().set_on_switch(pump_switch_on);
    this->pump_.back().set_pulse_duration(pulse_duration);
    this->valve_[valve_number].pump_switch_index = this->pump_.size() - 1;  // save the index to the new pump
  }
}

void Sprinkler::configure_valve_run_duration_number(size_t valve_number,
                                                    SprinklerControllerNumber *run_duration_number) {
  if (this->is_a_valid_valve(valve_number)) {
    this->valve_[valve_number].run_duration_number = run_duration_number;
  }
}

void Sprinkler::set_divider(optional<uint32_t> divider) {
  if (!divider.has_value()) {
    return;
  }
  if (divider.value() > 0) {
    this->set_multiplier(1.0 / divider.value());
    this->set_repeat(divider.value() - 1);
  } else if (divider.value() == 0) {
    this->set_multiplier(1.0);
    this->set_repeat(0);
  }
}

void Sprinkler::set_multiplier(const optional<float> multiplier) {
  if ((!multiplier.has_value()) || (multiplier.value() < 0)) {
    return;
  }
  this->multiplier_ = multiplier.value();
  if (this->multiplier_number_ == nullptr) {
    return;
  }
  if (this->multiplier_number_->state == multiplier.value()) {
    return;
  }
  auto call = this->multiplier_number_->make_call();
  call.set_value(multiplier.value());
  call.perform();
}

void Sprinkler::set_next_prev_ignore_disabled_valves(bool ignore_disabled) {
  this->next_prev_ignore_disabled_ = ignore_disabled;
}

void Sprinkler::set_pump_start_delay(uint32_t start_delay) {
  this->start_delay_is_valve_delay_ = false;
  this->start_delay_ = start_delay;
}

void Sprinkler::set_pump_stop_delay(uint32_t stop_delay) {
  this->stop_delay_is_valve_delay_ = false;
  this->stop_delay_ = stop_delay;
}

void Sprinkler::set_valve_start_delay(uint32_t start_delay) {
  this->start_delay_is_valve_delay_ = true;
  this->start_delay_ = start_delay;
}

void Sprinkler::set_valve_stop_delay(uint32_t stop_delay) {
  this->stop_delay_is_valve_delay_ = true;
  this->stop_delay_ = stop_delay;
}

void Sprinkler::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 Sprinkler::set_valve_open_delay(const uint32_t valve_open_delay) {
  if (valve_open_delay > 0) {
    this->valve_overlap_ = false;
    this->switching_delay_ = valve_open_delay;
  } else {
    this->switching_delay_.reset();
  }
}

void Sprinkler::set_valve_overlap(uint32_t valve_overlap) {
  if (valve_overlap > 0) {
    this->valve_overlap_ = true;
    this->switching_delay_ = valve_overlap;
  } else {
    this->switching_delay_.reset();
  }
  this->pump_switch_off_during_valve_open_delay_ = false;  // incompatible option
}

void Sprinkler::set_manual_selection_delay(uint32_t manual_selection_delay) {
  if (manual_selection_delay > 0) {
    this->manual_selection_delay_ = manual_selection_delay;
  } else {
    this->manual_selection_delay_.reset();
  }
}

void Sprinkler::set_valve_run_duration(const optional<size_t> valve_number, const optional<uint32_t> run_duration) {
  if (!valve_number.has_value() || !run_duration.has_value()) {
    return;
  }
  if (!this->is_a_valid_valve(valve_number.value())) {
    return;
  }
  this->valve_[valve_number.value()].run_duration = run_duration.value();
  if (this->valve_[valve_number.value()].run_duration_number == nullptr) {
    return;
  }
  if (this->valve_[valve_number.value()].run_duration_number->state == run_duration.value()) {
    return;
  }
  auto call = this->valve_[valve_number.value()].run_duration_number->make_call();
  if (this->valve_[valve_number.value()].run_duration_number->traits.get_unit_of_measurement() == MIN_STR) {
    call.set_value(run_duration.value() / 60.0);
  } else {
    call.set_value(run_duration.value());
  }
  call.perform();
}

void Sprinkler::set_auto_advance(const bool auto_advance) {
  if (this->auto_adv_sw_ == nullptr) {
    return;
  }
  if (this->auto_adv_sw_->state == auto_advance) {
    return;
  }
  if (auto_advance) {
    this->auto_adv_sw_->turn_on();
  } else {
    this->auto_adv_sw_->turn_off();
  }
}

void Sprinkler::set_repeat(optional<uint32_t> repeat) {
  this->target_repeats_ = repeat;
  if (this->repeat_number_ == nullptr) {
    return;
  }
  if (this->repeat_number_->state == repeat.value()) {
    return;
  }
  auto call = this->repeat_number_->make_call();
  call.set_value(repeat.value_or(0));
  call.perform();
}

void Sprinkler::set_queue_enable(bool queue_enable) {
  if (this->queue_enable_sw_ == nullptr) {
    return;
  }
  if (this->queue_enable_sw_->state == queue_enable) {
    return;
  }
  if (queue_enable) {
    this->queue_enable_sw_->turn_on();
  } else {
    this->queue_enable_sw_->turn_off();
  }
}

void Sprinkler::set_reverse(const bool reverse) {
  if (this->reverse_sw_ == nullptr) {
    return;
  }
  if (this->reverse_sw_->state == reverse) {
    return;
  }
  if (reverse) {
    this->reverse_sw_->turn_on();
  } else {
    this->reverse_sw_->turn_off();
  }
}

void Sprinkler::set_standby(const bool standby) {
  if (this->standby_sw_ == nullptr) {
    return;
  }
  if (this->standby_sw_->state == standby) {
    return;
  }
  if (standby) {
    this->standby_sw_->turn_on();
  } else {
    this->standby_sw_->turn_off();
  }
}

uint32_t Sprinkler::valve_run_duration(const size_t valve_number) {
  if (!this->is_a_valid_valve(valve_number)) {
    return 0;
  }
  if (this->valve_[valve_number].run_duration_number != nullptr) {
    if (this->valve_[valve_number].run_duration_number->traits.get_unit_of_measurement() == MIN_STR) {
      return static_cast<uint32_t>(roundf(this->valve_[valve_number].run_duration_number->state * 60));
    } else {
      return static_cast<uint32_t>(roundf(this->valve_[valve_number].run_duration_number->state));
    }
  }
  return this->valve_[valve_number].run_duration;
}

uint32_t Sprinkler::valve_run_duration_adjusted(const size_t valve_number) {
  uint32_t run_duration = 0;

  if (this->is_a_valid_valve(valve_number)) {
    run_duration = this->valve_run_duration(valve_number);
  }
  run_duration = static_cast<uint32_t>(roundf(run_duration * this->multiplier()));
  // run_duration must not be less than any of these
  if ((run_duration < this->start_delay_) || (run_duration < this->stop_delay_) ||
      (run_duration < this->switching_delay_.value_or(0) * 2)) {
    return std::max(this->switching_delay_.value_or(0) * 2, std::max(this->start_delay_, this->stop_delay_));
  }
  return run_duration;
}

bool Sprinkler::auto_advance() {
  if (this->auto_adv_sw_ != nullptr) {
    return this->auto_adv_sw_->state;
  }
  return true;
}

float Sprinkler::multiplier() {
  if (this->multiplier_number_ != nullptr) {
    return this->multiplier_number_->state;
  }
  return this->multiplier_;
}

optional<uint32_t> Sprinkler::repeat() {
  if (this->repeat_number_ != nullptr) {
    return static_cast<uint32_t>(roundf(this->repeat_number_->state));
  }
  return this->target_repeats_;
}

optional<uint32_t> Sprinkler::repeat_count() {
  // if there is an active valve and auto-advance is enabled, we may be repeating, so return the count
  if (this->active_req_.has_request() && this->auto_advance()) {
    return this->repeat_count_;
  }
  return nullopt;
}

bool Sprinkler::queue_enabled() {
  if (this->queue_enable_sw_ != nullptr) {
    return this->queue_enable_sw_->state;
  }
  return true;
}

bool Sprinkler::reverse() {
  if (this->reverse_sw_ != nullptr) {
    return this->reverse_sw_->state;
  }
  return false;
}

bool Sprinkler::standby() {
  if (this->standby_sw_ != nullptr) {
    return this->standby_sw_->state;
  }
  return false;
}

void Sprinkler::start_from_queue() {
  if (this->standby()) {
    ESP_LOGD(TAG, "start_from_queue called but standby is enabled; no action taken");
    return;
  }
  if (this->multiplier() == 0) {
    ESP_LOGD(TAG, "start_from_queue called but multiplier is set to zero; no action taken");
    return;
  }
  if (this->queued_valves_.empty()) {
    return;  // if there is nothing in the queue, don't do anything
  }
  if (this->queue_enabled() && this->active_valve().has_value()) {
    return;  // if there is already a valve running from the queue, do nothing
  }

  this->set_auto_advance(false);
  this->set_queue_enable(true);

  this->reset_cycle_states_();  // just in case auto-advance is switched on later
  this->repeat_count_ = 0;
  this->fsm_kick_();  // will automagically pick up from the queue (it has priority)
}

void Sprinkler::start_full_cycle() {
  if (this->standby()) {
    ESP_LOGD(TAG, "start_full_cycle called but standby is enabled; no action taken");
    return;
  }
  if (this->multiplier() == 0) {
    ESP_LOGD(TAG, "start_full_cycle called but multiplier is set to zero; no action taken");
    return;
  }
  if (this->auto_advance() && this->active_valve().has_value()) {
    return;  // if auto-advance is already enabled and there is already a valve running, do nothing
  }

  this->set_queue_enable(false);

  this->prep_full_cycle_();
  this->repeat_count_ = 0;
  // if there is no active valve already, start the first valve in the cycle
  if (!this->active_req_.has_request()) {
    this->fsm_kick_();
  }
}

void Sprinkler::start_single_valve(const optional<size_t> valve_number, optional<uint32_t> run_duration) {
  if (this->standby()) {
    ESP_LOGD(TAG, "start_single_valve called but standby is enabled; no action taken");
    return;
  }
  if (this->multiplier() == 0) {
    ESP_LOGD(TAG, "start_single_valve called but multiplier is set to zero; no action taken");
    return;
  }
  if (!valve_number.has_value() || (valve_number == this->active_valve())) {
    return;
  }

  this->set_auto_advance(false);
  this->set_queue_enable(false);

  this->reset_cycle_states_();  // just in case auto-advance is switched on later
  this->repeat_count_ = 0;
  this->fsm_request_(valve_number.value(), run_duration.value_or(0));
}

void Sprinkler::queue_valve(optional<size_t> valve_number, optional<uint32_t> run_duration) {
  if (valve_number.has_value()) {
    if (this->is_a_valid_valve(valve_number.value()) && (this->queued_valves_.size() < this->max_queue_size_)) {
      SprinklerQueueItem item{valve_number.value(), run_duration.value()};
      this->queued_valves_.insert(this->queued_valves_.begin(), item);
      ESP_LOGD(TAG, "Valve %zu placed into queue with run duration of %" PRIu32 " seconds", valve_number.value_or(0),
               run_duration.value_or(0));
    }
  }
}

void Sprinkler::clear_queued_valves() {
  this->queued_valves_.clear();
  ESP_LOGD(TAG, "Queue cleared");
}

void Sprinkler::next_valve() {
  if (this->state_ == IDLE) {
    this->reset_cycle_states_();  // just in case auto-advance is switched on later
  }

  this->manual_valve_ = this->next_valve_number_(
      this->manual_valve_.value_or(this->active_req_.valve_as_opt().value_or(this->number_of_valves() - 1)),
      !this->next_prev_ignore_disabled_, true);

  if (!this->manual_valve_.has_value()) {
    ESP_LOGD(TAG, "next_valve was called but no valve could be started; perhaps next_prev_ignore_disabled allows only "
                  "enabled valves and no valves are enabled?");
    return;
  }

  if (this->manual_selection_delay_.has_value()) {
    this->set_timer_duration_(sprinkler::TIMER_VALVE_SELECTION, this->manual_selection_delay_.value());
    this->start_timer_(sprinkler::TIMER_VALVE_SELECTION);
  } else {
    this->fsm_request_(this->manual_valve_.value());
  }
}

void Sprinkler::previous_valve() {
  if (this->state_ == IDLE) {
    this->reset_cycle_states_();  // just in case auto-advance is switched on later
  }

  this->manual_valve_ =
      this->previous_valve_number_(this->manual_valve_.value_or(this->active_req_.valve_as_opt().value_or(0)),
                                   !this->next_prev_ignore_disabled_, true);

  if (!this->manual_valve_.has_value()) {
    ESP_LOGD(TAG, "previous_valve was called but no valve could be started; perhaps next_prev_ignore_disabled allows "
                  "only enabled valves and no valves are enabled?");
    return;
  }

  if (this->manual_selection_delay_.has_value()) {
    this->set_timer_duration_(sprinkler::TIMER_VALVE_SELECTION, this->manual_selection_delay_.value());
    this->start_timer_(sprinkler::TIMER_VALVE_SELECTION);
  } else {
    this->fsm_request_(this->manual_valve_.value());
  }
}

void Sprinkler::shutdown(bool clear_queue) {
  this->cancel_timer_(sprinkler::TIMER_VALVE_SELECTION);
  this->active_req_.reset();
  this->manual_valve_.reset();
  this->next_req_.reset();
  for (auto &vo : this->valve_op_) {
    vo.stop();
  }
  this->fsm_transition_to_shutdown_();
  if (clear_queue) {
    this->clear_queued_valves();
    this->repeat_count_ = 0;
  }
}

void Sprinkler::pause() {
  if (this->paused_valve_.has_value() || !this->active_req_.has_request()) {
    return;  // we can't pause if we're already paused or if there is no active valve
  }
  this->paused_valve_ = this->active_valve();
  this->resume_duration_ = this->time_remaining_active_valve();
  this->shutdown(false);
  ESP_LOGD(TAG, "Paused valve %zu with %" PRIu32 " seconds remaining", this->paused_valve_.value_or(0),
           this->resume_duration_.value_or(0));
}

void Sprinkler::resume() {
  if (this->standby()) {
    ESP_LOGD(TAG, "resume called but standby is enabled; no action taken");
    return;
  }

  if (this->paused_valve_.has_value() && (this->resume_duration_.has_value())) {
    // Resume only if valve has not been completed yet
    if (!this->valve_cycle_complete_(this->paused_valve_.value())) {
      ESP_LOGD(TAG, "Resuming valve %zu with %" PRIu32 " seconds remaining", this->paused_valve_.value_or(0),
               this->resume_duration_.value_or(0));
      this->fsm_request_(this->paused_valve_.value(), this->resume_duration_.value());
    }
    this->reset_resume();
  } else {
    ESP_LOGD(TAG, "No valve to resume!");
  }
}

void Sprinkler::resume_or_start_full_cycle() {
  if (this->paused_valve_.has_value() && (this->resume_duration_.has_value())) {
    this->resume();
  } else {
    this->start_full_cycle();
  }
}

void Sprinkler::reset_resume() {
  this->paused_valve_.reset();
  this->resume_duration_.reset();
}

const char *Sprinkler::valve_name(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    return this->valve_[valve_number].controller_switch->get_name().c_str();
  }
  return nullptr;
}

optional<SprinklerValveRunRequestOrigin> Sprinkler::active_valve_request_is_from() {
  if (this->active_req_.has_request()) {
    return this->active_req_.request_is_from();
  }
  return nullopt;
}

optional<size_t> Sprinkler::active_valve() {
  if (!this->valve_overlap_ && this->prev_req_.has_request() &&
      (this->prev_req_.valve_operator()->state() == STARTING || this->prev_req_.valve_operator()->state() == ACTIVE)) {
    return this->prev_req_.valve_as_opt();
  }
  return this->active_req_.valve_as_opt();
}

optional<size_t> Sprinkler::paused_valve() { return this->paused_valve_; }

optional<size_t> Sprinkler::queued_valve() {
  if (!this->queued_valves_.empty()) {
    return this->queued_valves_.back().valve_number;
  }
  return nullopt;
}

optional<size_t> Sprinkler::manual_valve() { return this->manual_valve_; }

size_t Sprinkler::number_of_valves() { return this->valve_.size(); }

bool Sprinkler::is_a_valid_valve(const size_t valve_number) {
  return ((valve_number >= 0) && (valve_number < this->number_of_valves()));
}

bool Sprinkler::pump_in_use(SprinklerSwitch *pump_switch) {
  if (pump_switch == nullptr) {
    return false;  // we can't do anything if there's nothing to check
  }
  // a pump must be considered "in use" if a (distribution) valve it supplies is active. this means:
  //  - at least one SprinklerValveOperator:
  //    - has a valve loaded that depends on this pump
  //    - is in a state that depends on the pump: (ACTIVE and _possibly_ STARTING/STOPPING)
  //  - if NO SprinklerValveOperator is active but there is a run request pending (active_req_.has_request()) and the
  //     controller state is STARTING, valve open delay is configured but NOT pump_switch_off_during_valve_open_delay_
  for (auto &vo : this->valve_op_) {  // first, check if any SprinklerValveOperator has a valve dependent on this pump
    if ((vo.state() != BYPASS) && (vo.pump_switch() != nullptr)) {
      // the SprinklerValveOperator is configured with a pump; now check if it is the pump of interest
      if ((vo.pump_switch()->off_switch() == pump_switch->off_switch()) &&
          (vo.pump_switch()->on_switch() == pump_switch->on_switch())) {
        // now if the SprinklerValveOperator has a pump and it is either ACTIVE, is STARTING with a valve delay or
        //  is STOPPING with a valve delay, its pump can be considered "in use", so just return indicating this now
        if ((vo.state() == ACTIVE) ||
            ((vo.state() == STARTING) && this->start_delay_ && this->start_delay_is_valve_delay_) ||
            ((vo.state() == STOPPING) && this->stop_delay_ && this->stop_delay_is_valve_delay_)) {
          return true;
        }
      }
    }
  }  // if we end up here, no SprinklerValveOperator was in a "give-away" state indicating that the pump is in use...
  if (!this->valve_overlap_ && !this->pump_switch_off_during_valve_open_delay_ && this->switching_delay_.has_value() &&
      this->active_req_.has_request() && (this->state_ != STOPPING)) {
    // ...the controller is configured to keep the pump on during a valve open delay, so just return
    //  whether or not the next valve shares the same pump
    return (pump_switch->off_switch() == this->valve_pump_switch(this->active_req_.valve())->off_switch()) &&
           (pump_switch->on_switch() == this->valve_pump_switch(this->active_req_.valve())->on_switch());
  }
  return false;
}

void Sprinkler::set_pump_state(SprinklerSwitch *pump_switch, bool state) {
  if (pump_switch == nullptr) {
    return;  // we can't do anything if there's nothing to check
  }

  bool hold_pump_on = false;

  for (auto &controller : this->other_controllers_) {  // check if the pump is in use by another controller
    if (controller != this) {                          // dummy check
      if (controller->pump_in_use(pump_switch)) {
        hold_pump_on = true;  // if another controller says it's using this pump, keep it on
                              // at this point we know if there exists another SprinklerSwitch that is "on" with its
                              //  off_switch_ and on_switch_ pointers pointing to the same pair of switch objects
      }
    }
  }
  if (hold_pump_on) {
    // at this point we know if there exists another SprinklerSwitch that is "on" with its
    //  off_switch_ and on_switch_ pointers pointing to the same pair of switch objects...
    pump_switch->sync_valve_state(true);  // ...so ensure our state is consistent
    ESP_LOGD(TAG, "Leaving pump on because another controller instance is using it");
  }

  if (state) {  // ...and now we can set the new state of the switch
    pump_switch->turn_on();
  } else if (!hold_pump_on && !this->pump_in_use(pump_switch)) {
    pump_switch->turn_off();
  } else if (hold_pump_on) {               // we must assume the other controller will switch off the pump when done...
    pump_switch->sync_valve_state(false);  // ...this only impacts latching valves
  }
}

uint32_t Sprinkler::total_cycle_time_all_valves() {
  uint32_t total_time_remaining = 0;

  for (size_t valve = 0; valve < this->number_of_valves(); valve++) {
    total_time_remaining += this->valve_run_duration_adjusted(valve);
  }

  if (this->valve_overlap_) {
    total_time_remaining -= this->switching_delay_.value_or(0) * (this->number_of_valves() - 1);
  } else {
    total_time_remaining += this->switching_delay_.value_or(0) * (this->number_of_valves() - 1);
  }

  return total_time_remaining;
}

uint32_t Sprinkler::total_cycle_time_enabled_valves() {
  uint32_t total_time_remaining = 0;
  uint32_t valve_count = 0;

  for (size_t valve = 0; valve < this->number_of_valves(); valve++) {
    if (this->valve_is_enabled_(valve)) {
      total_time_remaining += this->valve_run_duration_adjusted(valve);
      valve_count++;
    }
  }

  if (valve_count) {
    if (this->valve_overlap_) {
      total_time_remaining -= this->switching_delay_.value_or(0) * (valve_count - 1);
    } else {
      total_time_remaining += this->switching_delay_.value_or(0) * (valve_count - 1);
    }
  }

  return total_time_remaining;
}

uint32_t Sprinkler::total_cycle_time_enabled_incomplete_valves() {
  uint32_t total_time_remaining = 0;
  uint32_t enabled_valve_count = 0;
  uint32_t incomplete_valve_count = 0;

  for (size_t valve = 0; valve < this->number_of_valves(); valve++) {
    if (this->valve_is_enabled_(valve)) {
      enabled_valve_count++;
      if (!this->valve_cycle_complete_(valve)) {
        if (!this->active_valve().has_value() || (valve != this->active_valve().value())) {
          total_time_remaining += this->valve_run_duration_adjusted(valve);
          incomplete_valve_count++;
        } else {
          // to get here, there must be an active valve and this valve must be equal to 'valve'
          if (this->active_req_.valve_operator() == nullptr) {  // no SVO has been assigned yet so it hasn't started
            total_time_remaining += this->valve_run_duration_adjusted(valve);
            incomplete_valve_count++;
          }
        }
      }
    }
  }

  if (incomplete_valve_count >= enabled_valve_count) {
    incomplete_valve_count--;
  }
  if (incomplete_valve_count) {
    if (this->valve_overlap_) {
      total_time_remaining -= this->switching_delay_.value_or(0) * incomplete_valve_count;
    } else {
      total_time_remaining += this->switching_delay_.value_or(0) * incomplete_valve_count;
    }
  }

  return total_time_remaining;
}

uint32_t Sprinkler::total_queue_time() {
  uint32_t total_time_remaining = 0;
  uint32_t valve_count = 0;

  for (auto &valve : this->queued_valves_) {
    if (valve.run_duration) {
      total_time_remaining += valve.run_duration;
    } else {
      total_time_remaining += this->valve_run_duration_adjusted(valve.valve_number);
    }
    valve_count++;
  }

  if (valve_count) {
    if (this->valve_overlap_) {
      total_time_remaining -= this->switching_delay_.value_or(0) * (valve_count - 1);
    } else {
      total_time_remaining += this->switching_delay_.value_or(0) * (valve_count - 1);
    }
  }

  return total_time_remaining;
}

optional<uint32_t> Sprinkler::time_remaining_active_valve() {
  if (this->active_req_.has_request()) {  // first try to return the value based on active_req_...
    if (this->active_req_.valve_operator() != nullptr) {
      return this->active_req_.valve_operator()->time_remaining();
    }
  }
  if (this->prev_req_.has_request()) {  // try to return the value based on prev_req_...
    if (this->prev_req_.valve_operator() != nullptr) {
      return this->prev_req_.valve_operator()->time_remaining();
    }
  }
  return nullopt;
}

optional<uint32_t> Sprinkler::time_remaining_current_operation() {
  if (!this->time_remaining_active_valve().has_value() && this->state_ == IDLE) {
    return nullopt;
  }

  auto total_time_remaining = this->time_remaining_active_valve().value_or(0);
  if (this->auto_advance()) {
    total_time_remaining += this->total_cycle_time_enabled_incomplete_valves();
    if (this->repeat().value_or(0) > 0) {
      total_time_remaining +=
          (this->total_cycle_time_enabled_valves() * (this->repeat().value_or(0) - this->repeat_count().value_or(0)));
    }
  }

  if (this->queue_enabled()) {
    total_time_remaining += this->total_queue_time();
  }
  return total_time_remaining;
}

bool Sprinkler::any_controller_is_active() {
  if (this->state_ != IDLE) {
    return true;
  }

  for (auto &controller : this->other_controllers_) {
    if (controller != this) {  // dummy check
      if (controller->controller_state() != IDLE) {
        return true;
      }
    }
  }
  return false;
}

SprinklerControllerSwitch *Sprinkler::control_switch(size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    return this->valve_[valve_number].controller_switch;
  }
  return nullptr;
}

SprinklerControllerSwitch *Sprinkler::enable_switch(size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    return this->valve_[valve_number].enable_switch;
  }
  return nullptr;
}

SprinklerSwitch *Sprinkler::valve_switch(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    return &this->valve_[valve_number].valve_switch;
  }
  return nullptr;
}

SprinklerSwitch *Sprinkler::valve_pump_switch(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number) && this->valve_[valve_number].pump_switch_index.has_value()) {
    return &this->pump_[this->valve_[valve_number].pump_switch_index.value()];
  }
  return nullptr;
}

SprinklerSwitch *Sprinkler::valve_pump_switch_by_pump_index(size_t pump_index) {
  if (pump_index < this->pump_.size()) {
    return &this->pump_[pump_index];
  }
  return nullptr;
}

bool Sprinkler::valve_is_enabled_(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    if (this->valve_[valve_number].enable_switch != nullptr) {
      return this->valve_[valve_number].enable_switch->state;
    } else {
      return true;
    }
  }
  return false;
}

void Sprinkler::mark_valve_cycle_complete_(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    ESP_LOGD(TAG, "Marking valve %u complete", valve_number);
    this->valve_[valve_number].valve_cycle_complete = true;
  }
}

bool Sprinkler::valve_cycle_complete_(const size_t valve_number) {
  if (this->is_a_valid_valve(valve_number)) {
    return this->valve_[valve_number].valve_cycle_complete;
  }
  return false;
}

optional<size_t> Sprinkler::next_valve_number_(const optional<size_t> first_valve, const bool include_disabled,
                                               const bool include_complete) {
  auto valve = first_valve.value_or(0);
  size_t start = first_valve.has_value() ? 1 : 0;

  if (!this->is_a_valid_valve(valve)) {
    valve = 0;
  }

  for (size_t offset = start; offset < this->number_of_valves(); offset++) {
    auto valve_of_interest = valve + offset;
    if (!this->is_a_valid_valve(valve_of_interest)) {
      valve_of_interest -= this->number_of_valves();
    }

    if ((this->valve_is_enabled_(valve_of_interest) || include_disabled) &&
        (!this->valve_cycle_complete_(valve_of_interest) || include_complete)) {
      return valve_of_interest;
    }
  }
  return nullopt;
}

optional<size_t> Sprinkler::previous_valve_number_(const optional<size_t> first_valve, const bool include_disabled,
                                                   const bool include_complete) {
  auto valve = first_valve.value_or(this->number_of_valves() - 1);
  size_t start = first_valve.has_value() ? 1 : 0;

  if (!this->is_a_valid_valve(valve)) {
    valve = this->number_of_valves() - 1;
  }

  for (size_t offset = start; offset < this->number_of_valves(); offset++) {
    auto valve_of_interest = valve - offset;
    if (!this->is_a_valid_valve(valve_of_interest)) {
      valve_of_interest += this->number_of_valves();
    }

    if ((this->valve_is_enabled_(valve_of_interest) || include_disabled) &&
        (!this->valve_cycle_complete_(valve_of_interest) || include_complete)) {
      return valve_of_interest;
    }
  }
  return nullopt;
}

optional<size_t> Sprinkler::next_valve_number_in_cycle_(const optional<size_t> first_valve) {
  if (this->reverse()) {
    return this->previous_valve_number_(first_valve, false, false);
  }
  return this->next_valve_number_(first_valve, false, false);
}

void Sprinkler::load_next_valve_run_request_(const optional<size_t> first_valve) {
  if (this->active_req_.has_request()) {
    this->prev_req_ = this->active_req_;
  } else {
    this->prev_req_.reset();
  }

  if (this->next_req_.has_request()) {
    if (!this->next_req_.run_duration()) {  // ensure the run duration is set correctly for consumption later on
      this->next_req_.set_run_duration(this->valve_run_duration_adjusted(this->next_req_.valve()));
    }
    return;  // there is already a request pending
  } else if (this->queue_enabled() && !this->queued_valves_.empty()) {
    this->next_req_.set_valve(this->queued_valves_.back().valve_number);
    this->next_req_.set_request_from(QUEUE);
    if (this->queued_valves_.back().run_duration) {
      this->next_req_.set_run_duration(this->queued_valves_.back().run_duration);
      this->queued_valves_.pop_back();
    } else if (this->multiplier()) {
      this->next_req_.set_run_duration(this->valve_run_duration_adjusted(this->queued_valves_.back().valve_number));
      this->queued_valves_.pop_back();
    } else {
      this->next_req_.reset();
    }
  } else if (this->auto_advance() && this->multiplier()) {
    if (this->next_valve_number_in_cycle_(first_valve).has_value()) {
      // if there is another valve to run as a part of a cycle, load that
      this->next_req_.set_valve(this->next_valve_number_in_cycle_(first_valve).value_or(0));
      this->next_req_.set_request_from(CYCLE);
      this->next_req_.set_run_duration(
          this->valve_run_duration_adjusted(this->next_valve_number_in_cycle_(first_valve).value_or(0)));
    } else if ((this->repeat_count_++ < this->repeat().value_or(0))) {
      ESP_LOGD(TAG, "Repeating - starting cycle %" PRIu32 " of %" PRIu32, this->repeat_count_ + 1,
               this->repeat().value_or(0) + 1);
      // if there are repeats remaining and no more valves were left in the cycle, start a new cycle
      this->prep_full_cycle_();
      if (this->next_valve_number_in_cycle_().has_value()) {  // this should always succeed here, but just in case...
        this->next_req_.set_valve(this->next_valve_number_in_cycle_().value_or(0));
        this->next_req_.set_request_from(CYCLE);
        this->next_req_.set_run_duration(
            this->valve_run_duration_adjusted(this->next_valve_number_in_cycle_().value_or(0)));
      }
    }
  }
}

bool Sprinkler::any_valve_is_enabled_() {
  for (size_t valve_number = 0; valve_number < this->number_of_valves(); valve_number++) {
    if (this->valve_is_enabled_(valve_number))
      return true;
  }
  return false;
}

void Sprinkler::start_valve_(SprinklerValveRunRequest *req) {
  if (!req->has_request()) {
    return;  // we can't do anything if the request contains nothing
  }
  if (!this->is_a_valid_valve(req->valve())) {
    return;  // we can't do anything if the valve number isn't valid
  }
  for (auto &vo : this->valve_op_) {  // find the first available SprinklerValveOperator, load it and start it up
    if (vo.state() == IDLE) {
      auto run_duration = req->run_duration() ? req->run_duration() : this->valve_run_duration_adjusted(req->valve());
      ESP_LOGD(TAG, "%s is starting valve %zu for %" PRIu32 " seconds, cycle %" PRIu32 " of %" PRIu32,
               this->req_as_str_(req->request_is_from()).c_str(), req->valve(), run_duration, this->repeat_count_ + 1,
               this->repeat().value_or(0) + 1);
      req->set_valve_operator(&vo);
      vo.set_controller(this);
      vo.set_valve(&this->valve_[req->valve()]);
      vo.set_run_duration(run_duration);
      vo.set_start_delay(this->start_delay_, this->start_delay_is_valve_delay_);
      vo.set_stop_delay(this->stop_delay_, this->stop_delay_is_valve_delay_);
      vo.start();
      return;
    }
  }
}

void Sprinkler::all_valves_off_(const bool include_pump) {
  for (size_t valve_index = 0; valve_index < this->number_of_valves(); valve_index++) {
    if (this->valve_[valve_index].valve_switch.state()) {
      this->valve_[valve_index].valve_switch.turn_off();
    }
    if (include_pump) {
      this->set_pump_state(this->valve_pump_switch(valve_index), false);
    }
  }
  ESP_LOGD(TAG, "All valves stopped%s", include_pump ? ", including pumps" : "");
}

void Sprinkler::prep_full_cycle_() {
  this->set_auto_advance(true);

  if (!this->any_valve_is_enabled_()) {
    for (auto &valve : this->valve_) {
      if (valve.enable_switch != nullptr) {
        if (!valve.enable_switch->state) {
          valve.enable_switch->turn_on();
        }
      }
    }
  }
  this->reset_cycle_states_();
}

void Sprinkler::reset_cycle_states_() {
  for (auto &valve : this->valve_) {
    valve.valve_cycle_complete = false;
  }
}

void Sprinkler::fsm_request_(size_t requested_valve, uint32_t requested_run_duration) {
  this->next_req_.set_valve(requested_valve);
  this->next_req_.set_run_duration(requested_run_duration);
  // if state is IDLE or ACTIVE, call fsm_transition_() to start it immediately;
  //  otherwise, fsm_transition() will pick up next_req_ at the next appropriate transition
  this->fsm_kick_();
}

void Sprinkler::fsm_kick_() {
  if ((this->state_ == IDLE) || (this->state_ == ACTIVE)) {
    this->fsm_transition_();
  }
}

void Sprinkler::fsm_transition_() {
  ESP_LOGVV(TAG, "fsm_transition_ called; state is %s", this->state_as_str_(this->state_).c_str());
  switch (this->state_) {
    case IDLE:  // the system was off -> start it up
      // advances to ACTIVE
      this->fsm_transition_from_shutdown_();
      break;

    case ACTIVE:
      // advances to STOPPING or ACTIVE (again)
      this->fsm_transition_from_valve_run_();
      break;

    case STARTING: {
      // follows valve open delay interval
      this->set_timer_duration_(sprinkler::TIMER_SM,
                                this->active_req_.run_duration() - this->switching_delay_.value_or(0));
      this->start_timer_(sprinkler::TIMER_SM);
      this->start_valve_(&this->active_req_);
      this->state_ = ACTIVE;
      if (this->next_req_.has_request()) {
        // another valve has been requested, so restart the timer so we pick it up quickly
        this->set_timer_duration_(sprinkler::TIMER_SM, this->manual_selection_delay_.value_or(1));
        this->start_timer_(sprinkler::TIMER_SM);
      }
      break;
    }

    case STOPPING:
      // stop_delay_ has elapsed so just shut everything off
      this->active_req_.reset();
      this->manual_valve_.reset();
      this->all_valves_off_(true);
      this->state_ = IDLE;
      break;

    default:
      break;
  }
  if (this->next_req_.has_request() && (this->state_ == IDLE)) {
    // another valve has been requested, so restart the timer so we pick it up quickly
    this->set_timer_duration_(sprinkler::TIMER_SM, this->manual_selection_delay_.value_or(1));
    this->start_timer_(sprinkler::TIMER_SM);
  }
  ESP_LOGVV(TAG, "fsm_transition_ complete; new state is %s", this->state_as_str_(this->state_).c_str());
}

void Sprinkler::fsm_transition_from_shutdown_() {
  this->load_next_valve_run_request_();

  if (this->next_req_.has_request()) {  // there is a valve to run...
    this->active_req_.set_valve(this->next_req_.valve());
    this->active_req_.set_request_from(this->next_req_.request_is_from());
    this->active_req_.set_run_duration(this->next_req_.run_duration());
    this->next_req_.reset();

    this->set_timer_duration_(sprinkler::TIMER_SM,
                              this->active_req_.run_duration() - this->switching_delay_.value_or(0));
    this->start_timer_(sprinkler::TIMER_SM);
    this->start_valve_(&this->active_req_);
    this->state_ = ACTIVE;
  }
}

void Sprinkler::fsm_transition_from_valve_run_() {
  if (!this->active_req_.has_request()) {  // dummy check...
    this->fsm_transition_to_shutdown_();
    return;
  }

  if (!this->timer_active_(sprinkler::TIMER_SM)) {  // only flag the valve as "complete" if the timer finished
    if ((this->active_req_.request_is_from() == CYCLE) || (this->active_req_.request_is_from() == USER)) {
      this->mark_valve_cycle_complete_(this->active_req_.valve());
    }
  } else {
    ESP_LOGD(TAG, "Valve cycle interrupted - NOT flagging valve as complete and stopping current valve");
    for (auto &vo : this->valve_op_) {
      vo.stop();
    }
  }

  this->load_next_valve_run_request_(this->active_req_.valve());

  if (this->next_req_.has_request()) {  // there is another valve to run...
    bool same_pump =
        this->valve_pump_switch(this->active_req_.valve()) == this->valve_pump_switch(this->next_req_.valve());

    this->active_req_.set_valve(this->next_req_.valve());
    this->active_req_.set_request_from(this->next_req_.request_is_from());
    this->active_req_.set_run_duration(this->next_req_.run_duration());
    this->next_req_.reset();

    // this->state_ = ACTIVE;  // state isn't changing
    if (this->valve_overlap_ || !this->switching_delay_.has_value()) {
      this->set_timer_duration_(sprinkler::TIMER_SM,
                                this->active_req_.run_duration() - this->switching_delay_.value_or(0));
      this->start_timer_(sprinkler::TIMER_SM);
      this->start_valve_(&this->active_req_);
    } else {
      this->set_timer_duration_(
          sprinkler::TIMER_SM,
          this->switching_delay_.value() * 2 +
              (this->pump_switch_off_during_valve_open_delay_ && same_pump ? this->stop_delay_ : 0));
      this->start_timer_(sprinkler::TIMER_SM);
      this->state_ = STARTING;
    }
  } else {  // there is NOT another valve to run...
    this->fsm_transition_to_shutdown_();
  }
}

void Sprinkler::fsm_transition_to_shutdown_() {
  this->state_ = STOPPING;
  this->set_timer_duration_(sprinkler::TIMER_SM,
                            this->start_delay_ + this->stop_delay_ + this->switching_delay_.value_or(0) + 1);
  this->start_timer_(sprinkler::TIMER_SM);
}

std::string Sprinkler::req_as_str_(SprinklerValveRunRequestOrigin origin) {
  switch (origin) {
    case USER:
      return "USER";

    case CYCLE:
      return "CYCLE";

    case QUEUE:
      return "QUEUE";

    default:
      return "UNKNOWN";
  }
}

std::string Sprinkler::state_as_str_(SprinklerState state) {
  switch (state) {
    case IDLE:
      return "IDLE";

    case STARTING:
      return "STARTING";

    case ACTIVE:
      return "ACTIVE";

    case STOPPING:
      return "STOPPING";

    case BYPASS:
      return "BYPASS";

    default:
      return "UNKNOWN";
  }
}

void Sprinkler::start_timer_(const SprinklerTimerIndex timer_index) {
  if (this->timer_duration_(timer_index) > 0) {
    this->set_timeout(this->timer_[timer_index].name, this->timer_duration_(timer_index),
                      this->timer_cbf_(timer_index));
    this->timer_[timer_index].start_time = millis();
    this->timer_[timer_index].active = true;
  }
  ESP_LOGVV(TAG, "Timer %zu started for %" PRIu32 " sec", static_cast<size_t>(timer_index),
            this->timer_duration_(timer_index) / 1000);
}

bool Sprinkler::cancel_timer_(const SprinklerTimerIndex timer_index) {
  this->timer_[timer_index].active = false;
  return this->cancel_timeout(this->timer_[timer_index].name);
}

bool Sprinkler::timer_active_(const SprinklerTimerIndex timer_index) { return this->timer_[timer_index].active; }

void Sprinkler::set_timer_duration_(const SprinklerTimerIndex timer_index, const uint32_t time) {
  this->timer_[timer_index].time = 1000 * time;
}

uint32_t Sprinkler::timer_duration_(const SprinklerTimerIndex timer_index) { return this->timer_[timer_index].time; }

std::function<void()> Sprinkler::timer_cbf_(const SprinklerTimerIndex timer_index) {
  return this->timer_[timer_index].func;
}

void Sprinkler::valve_selection_callback_() {
  this->timer_[sprinkler::TIMER_VALVE_SELECTION].active = false;
  ESP_LOGVV(TAG, "Valve selection timer expired");
  if (this->manual_valve_.has_value()) {
    this->fsm_request_(this->manual_valve_.value());
    this->manual_valve_.reset();
  }
}

void Sprinkler::sm_timer_callback_() {
  this->timer_[sprinkler::TIMER_SM].active = false;
  ESP_LOGVV(TAG, "State machine timer expired");
  this->fsm_transition_();
}

void Sprinkler::dump_config() {
  ESP_LOGCONFIG(TAG, "Sprinkler Controller -- %s", this->name_.c_str());
  if (this->manual_selection_delay_.has_value()) {
    ESP_LOGCONFIG(TAG, "  Manual Selection Delay: %" PRIu32 " seconds", this->manual_selection_delay_.value_or(0));
  }
  if (this->repeat().has_value()) {
    ESP_LOGCONFIG(TAG, "  Repeat Cycles: %" PRIu32 " times", this->repeat().value_or(0));
  }
  if (this->start_delay_) {
    if (this->start_delay_is_valve_delay_) {
      ESP_LOGCONFIG(TAG, "  Pump Start Valve Delay: %" PRIu32 " seconds", this->start_delay_);
    } else {
      ESP_LOGCONFIG(TAG, "  Pump Start Pump Delay: %" PRIu32 " seconds", this->start_delay_);
    }
  }
  if (this->stop_delay_) {
    if (this->stop_delay_is_valve_delay_) {
      ESP_LOGCONFIG(TAG, "  Pump Stop Valve Delay: %" PRIu32 " seconds", this->stop_delay_);
    } else {
      ESP_LOGCONFIG(TAG, "  Pump Stop Pump Delay: %" PRIu32 " seconds", this->stop_delay_);
    }
  }
  if (this->switching_delay_.has_value()) {
    if (this->valve_overlap_) {
      ESP_LOGCONFIG(TAG, "  Valve Overlap: %" PRIu32 " seconds", this->switching_delay_.value_or(0));
    } else {
      ESP_LOGCONFIG(TAG, "  Valve Open Delay: %" PRIu32 " seconds", this->switching_delay_.value_or(0));
      ESP_LOGCONFIG(TAG, "  Pump Switch Off During Valve Open Delay: %s",
                    YESNO(this->pump_switch_off_during_valve_open_delay_));
    }
  }
  for (size_t valve_number = 0; valve_number < this->number_of_valves(); valve_number++) {
    ESP_LOGCONFIG(TAG, "  Valve %zu:", valve_number);
    ESP_LOGCONFIG(TAG, "    Name: %s", this->valve_name(valve_number));
    ESP_LOGCONFIG(TAG, "    Run Duration: %" PRIu32 " seconds", this->valve_run_duration(valve_number));
    if (this->valve_[valve_number].valve_switch.pulse_duration()) {
      ESP_LOGCONFIG(TAG, "    Pulse Duration: %" PRIu32 " milliseconds",
                    this->valve_[valve_number].valve_switch.pulse_duration());
    }
  }
  if (!this->pump_.empty()) {
    ESP_LOGCONFIG(TAG, "  Total number of pumps: %zu", this->pump_.size());
  }
  if (!this->valve_.empty()) {
    ESP_LOGCONFIG(TAG, "  Total number of valves: %zu", this->valve_.size());
  }
}

}  // namespace sprinkler
}  // namespace esphome