Add support for parameters in scripts (#3538)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> fixes https://github.com/esphome/feature-requests/issues/241
2026-05-28 00:38:28 +02:00 · 2022-11-09 13:51:59 +10:00
parent 5a0bf9fee9
commit 8c122aa372
5 changed files with 243 additions and 91 deletions
@@ -2,27 +2,48 @@

 #include "esphome/core/automation.h"
 #include "esphome/core/component.h"
+#include "esphome/core/log.h"

 namespace esphome {
 namespace script {

+class ScriptLogger {
+ protected:
+  void esp_logw_(int line, const char *format, const char *param) {
+    esp_log_(ESPHOME_LOG_LEVEL_WARN, line, format, param);
+  }
+  void esp_logd_(int line, const char *format, const char *param) {
+    esp_log_(ESPHOME_LOG_LEVEL_DEBUG, line, format, param);
+  }
+  void esp_log_(int level, int line, const char *format, const char *param);
+};
+
 /// The abstract base class for all script types.
-class Script : public Trigger<> {
+template<typename... Ts> class Script : public ScriptLogger, public Trigger<Ts...> {
 public:
  /** Execute a new instance of this script.
   *
   * The behavior of this function when a script is already running is defined by the subtypes
   */
-  virtual void execute() = 0;
+  virtual void execute(Ts...) = 0;
  /// Check if any instance of this script is currently running.
  virtual bool is_running() { return this->is_action_running(); }
  /// Stop all instances of this script.
  virtual void stop() { this->stop_action(); }

+  // execute this script using a tuple that contains the arguments
+  void execute_tuple(const std::tuple<Ts...> &tuple) {
+    this->execute_tuple_(tuple, typename gens<sizeof...(Ts)>::type());
+  }
+
  // Internal function to give scripts readable names.
  void set_name(const std::string &name) { name_ = name; }

 protected:
+  template<int... S> void execute_tuple_(const std::tuple<Ts...> &tuple, seq<S...> /*unused*/) {
+    this->execute(std::get<S>(tuple)...);
+  }
+
  std::string name_;
 };

@@ -31,9 +52,16 @@ class Script : public Trigger<> {
 * If a new instance is executed while the previous one hasn't finished yet,
 * a warning is printed and the new instance is discarded.
 */
-class SingleScript : public Script {
+template<typename... Ts> class SingleScript : public Script<Ts...> {
 public:
-  void execute() override;
+  void execute(Ts... x) override {
+    if (this->is_action_running()) {
+      this->esp_logw_(__LINE__, "Script '%s' is already running! (mode: single)", this->name_.c_str());
+      return;
+    }
+
+    this->trigger(x...);
+  }
 };

 /** A script type that restarts scripts from the beginning when a new instance is started.
@@ -41,20 +69,55 @@ class SingleScript : public Script {
 * If a new instance is started but another one is already running, the existing
 * script is stopped and the new instance starts from the beginning.
 */
-class RestartScript : public Script {
+template<typename... Ts> class RestartScript : public Script<Ts...> {
 public:
-  void execute() override;
+  void execute(Ts... x) override {
+    if (this->is_action_running()) {
+      this->esp_logd_(__LINE__, "Script '%s' restarting (mode: restart)", this->name_.c_str());
+      this->stop_action();
+    }
+
+    this->trigger(x...);
+  }
 };

 /** A script type that queues new instances that are created.
 *
 * Only one instance of the script can be active at a time.
 */
-class QueueingScript : public Script, public Component {
+template<typename... Ts> class QueueingScript : public Script<Ts...>, public Component {
 public:
-  void execute() override;
-  void stop() override;
-  void loop() override;
+  void execute(Ts... x) override {
+    if (this->is_action_running()) {
+      // num_runs_ is the number of *queued* instances, so total number of instances is
+      // num_runs_ + 1
+      if (this->max_runs_ != 0 && this->num_runs_ + 1 >= this->max_runs_) {
+        this->esp_logw_(__LINE__, "Script '%s' maximum number of queued runs exceeded!", this->name_.c_str());
+        return;
+      }
+
+      this->esp_logd_(__LINE__, "Script '%s' queueing new instance (mode: queued)", this->name_.c_str());
+      this->num_runs_++;
+      return;
+    }
+
+    this->trigger(x...);
+    // Check if the trigger was immediate and we can continue right away.
+    this->loop();
+  }
+
+  void stop() override {
+    this->num_runs_ = 0;
+    Script<Ts...>::stop();
+  }
+
+  void loop() override {
+    if (this->num_runs_ != 0 && !this->is_action_running()) {
+      this->num_runs_--;
+      this->trigger();
+    }
+  }
+
  void set_max_runs(int max_runs) { max_runs_ = max_runs; }

 protected:
@@ -67,48 +130,84 @@ class QueueingScript : public Script, public Component {
 * If a new instance is started while previous ones haven't finished yet,
 * the new one is executed in parallel to the other instances.
 */
-class ParallelScript : public Script {
+template<typename... Ts> class ParallelScript : public Script<Ts...> {
 public:
-  void execute() override;
+  void execute(Ts... x) override {
+    if (this->max_runs_ != 0 && this->automation_parent_->num_running() >= this->max_runs_) {
+      this->esp_logw_(__LINE__, "Script '%s' maximum number of parallel runs exceeded!", this->name_.c_str());
+      return;
+    }
+    this->trigger(x...);
+  }
  void set_max_runs(int max_runs) { max_runs_ = max_runs; }

 protected:
  int max_runs_ = 0;
 };

-template<typename... Ts> class ScriptExecuteAction : public Action<Ts...> {
- public:
-  ScriptExecuteAction(Script *script) : script_(script) {}
+template<class S, typename... Ts> class ScriptExecuteAction;

-  void play(Ts... x) override { this->script_->execute(); }
+template<class... As, typename... Ts> class ScriptExecuteAction<Script<As...>, Ts...> : public Action<Ts...> {
+ public:
+  ScriptExecuteAction(Script<As...> *script) : script_(script) {}
+
+  using Args = std::tuple<TemplatableValue<As, Ts...>...>;
+
+  template<typename... F> void set_args(F... x) { args_ = Args{x...}; }
+
+  void play(Ts... x) override { this->script_->execute_tuple(this->eval_args_(x...)); }

 protected:
-  Script *script_;
+  // NOTE:
+  //  `eval_args_impl` functions evaluates `I`th the functions in `args` member.
+  //  and then recursively calls `eval_args_impl` for the `I+1`th arg.
+  //  if `I` = `N` all args have been stored, and nothing is done.
+
+  template<std::size_t N>
+  void eval_args_impl_(std::tuple<As...> & /*unused*/, std::integral_constant<std::size_t, N> /*unused*/,
+                       std::integral_constant<std::size_t, N> /*unused*/, Ts... /*unused*/) {}
+
+  template<std::size_t I, std::size_t N>
+  void eval_args_impl_(std::tuple<As...> &evaled_args, std::integral_constant<std::size_t, I> /*unused*/,
+                       std::integral_constant<std::size_t, N> n, Ts... x) {
+    std::get<I>(evaled_args) = std::get<I>(args_).value(x...);  // NOTE: evaluate `i`th arg, and store in tuple.
+    eval_args_impl_(evaled_args, std::integral_constant<std::size_t, I + 1>{}, n,
+                    x...);  // NOTE: recurse to next index.
+  }
+
+  std::tuple<As...> eval_args_(Ts... x) {
+    std::tuple<As...> evaled_args;
+    eval_args_impl_(evaled_args, std::integral_constant<std::size_t, 0>{}, std::tuple_size<Args>{}, x...);
+    return evaled_args;
+  }
+
+  Script<As...> *script_;
+  Args args_;
 };

-template<typename... Ts> class ScriptStopAction : public Action<Ts...> {
+template<class C, typename... Ts> class ScriptStopAction : public Action<Ts...> {
 public:
-  ScriptStopAction(Script *script) : script_(script) {}
+  ScriptStopAction(C *script) : script_(script) {}

  void play(Ts... x) override { this->script_->stop(); }

 protected:
-  Script *script_;
+  C *script_;
 };

-template<typename... Ts> class IsRunningCondition : public Condition<Ts...> {
+template<class C, typename... Ts> class IsRunningCondition : public Condition<Ts...> {
 public:
-  explicit IsRunningCondition(Script *parent) : parent_(parent) {}
+  explicit IsRunningCondition(C *parent) : parent_(parent) {}

  bool check(Ts... x) override { return this->parent_->is_running(); }

 protected:
-  Script *parent_;
+  C *parent_;
 };

-template<typename... Ts> class ScriptWaitAction : public Action<Ts...>, public Component {
+template<class C, typename... Ts> class ScriptWaitAction : public Action<Ts...>, public Component {
 public:
-  ScriptWaitAction(Script *script) : script_(script) {}
+  ScriptWaitAction(C *script) : script_(script) {}

  void play_complex(Ts... x) override {
    this->num_running_++;
@@ -137,7 +236,7 @@ template<typename... Ts> class ScriptWaitAction : public Action<Ts...>, public C
  }

 protected:
-  Script *script_;
+  C *script_;
  std::tuple<Ts...> var_{};
 };