Merge pull request #5193 from tonhuisman/feature/Commands-add-looptimersetandrun

[Commands] Add commands LoopTimerSetAndRun (_ms)

Author: TD-er

docs/source/Plugin/P000_commands.repl

@@ -357,6 +357,15 @@
 
     N.B. the timernr is shared between ``TimerSet`` and ``LoopTimerSet``"
     "
+    LoopTimerSetAndRun
+    
+    LoopTimerSetAndRun_ms","
+    Set a Loop-Timer using ``LoopTimerSet`` or ``LoopTimerSet_ms`` and immediately run the first iteration.
+
+    If a ``<nr of loops>`` value > 0 is included in the command, that count is decremented by 1 for the first iteration, as expected.
+    
+    Useful for setting a keep-alive timer, and also send the initial keep-alive signal immediately."
+    "
     meminfo","
     :red:`Internal`","
     Will send summary of struct sizes to the serial port.

docs/source/Rules/Rules.rst

@@ -1746,6 +1746,11 @@ Added on 2020/08/12:
 * ``loopTimerSet``  To create a repeating timer with constant interval (seconds).
 * ``loopTimerSet_ms``  Same as ``loopTimerSet``, with msec interval.
 
+Added on 2024/12/23:
+
+* ``loopTimerSetAndRun``  Same as ``loopTimerSet``, and immediately starts the 1st iteration.
+* ``loopTimerSetAndRun_ms``  Same as ``loopTimerSetAndRun``, with msec interval.
+
 Here a small example to show how to start/stop and pause loop timers.
 This can be used to create quite complex timing schemas, especially when
 using multiple timers which are set to a relative prime interval.

src/src/Commands/InternalCommands.cpp

@@ -319,13 +319,15 @@ bool InternalCommands::executeInternalCommand()
 #ifndef BUILD_NO_DIAGNOSTIC_COMMANDS
     case ESPEasy_cmd_e::jsonportstatus:             COMMAND_CASE_A(Command_JSONPortStatus, -1);              // Diagnostic.h
 #endif // ifndef BUILD_NO_DIAGNOSTIC_COMMANDS
-    case ESPEasy_cmd_e::let:                        COMMAND_CASE_A(Command_Rules_Let,         2);            // Rules.h
-    case ESPEasy_cmd_e::load:                       COMMAND_CASE_A(Command_Settings_Load,     0);            // Settings.h
-    case ESPEasy_cmd_e::logentry:                   COMMAND_CASE_A(Command_logentry,         -1);            // Diagnostic.h
-    case ESPEasy_cmd_e::looptimerset:               COMMAND_CASE_A(Command_Loop_Timer_Set,    3);            // Timers.h
-    case ESPEasy_cmd_e::looptimerset_ms:            COMMAND_CASE_A(Command_Loop_Timer_Set_ms, 3);            // Timers.h
-    case ESPEasy_cmd_e::longpulse:                  COMMAND_CASE_A(Command_GPIO_LongPulse,    5);            // GPIO.h
-    case ESPEasy_cmd_e::longpulse_ms:               COMMAND_CASE_A(Command_GPIO_LongPulse_Ms, 5);            // GPIO.h
+    case ESPEasy_cmd_e::let:                        COMMAND_CASE_A(Command_Rules_Let,               2);      // Rules.h
+    case ESPEasy_cmd_e::load:                       COMMAND_CASE_A(Command_Settings_Load,           0);      // Settings.h
+    case ESPEasy_cmd_e::logentry:                   COMMAND_CASE_A(Command_logentry,               -1);      // Diagnostic.h
+    case ESPEasy_cmd_e::looptimerset:               COMMAND_CASE_A(Command_Loop_Timer_Set,          3);      // Timers.h
+    case ESPEasy_cmd_e::looptimerset_ms:            COMMAND_CASE_A(Command_Loop_Timer_Set_ms,       3);      // Timers.h
+    case ESPEasy_cmd_e::looptimersetandrun:         COMMAND_CASE_A(Command_Loop_Timer_SetAndRun,    3);      // Timers.h
+    case ESPEasy_cmd_e::looptimersetandrun_ms:      COMMAND_CASE_A(Command_Loop_Timer_SetAndRun_ms, 3);      // Timers.h
+    case ESPEasy_cmd_e::longpulse:                  COMMAND_CASE_A(Command_GPIO_LongPulse,          5);      // GPIO.h
+    case ESPEasy_cmd_e::longpulse_ms:               COMMAND_CASE_A(Command_GPIO_LongPulse_Ms,       5);      // GPIO.h
 #ifndef BUILD_NO_DIAGNOSTIC_COMMANDS
     case ESPEasy_cmd_e::logportstatus:              COMMAND_CASE_A(Command_logPortStatus,     0);            // Diagnostic.h
     case ESPEasy_cmd_e::lowmem:                     COMMAND_CASE_A(Command_Lowmem,            0);            // Diagnostic.h

src/src/Commands/InternalCommands_decoder.cpp

@@ -103,6 +103,8 @@ const char Internal_commands_l[] PROGMEM =
   "logentry|"
   "looptimerset|"
   "looptimerset_ms|"
+  "looptimersetandrun|"
+  "looptimersetandrun_ms|"
   "longpulse|"
   "longpulse_ms|"
 #ifndef BUILD_NO_DIAGNOSTIC_COMMANDS

src/src/Commands/InternalCommands_decoder.h

@@ -81,6 +81,8 @@ enum class ESPEasy_cmd_e : uint8_t {
   logentry,
   looptimerset,
   looptimerset_ms,
+  looptimersetandrun,
+  looptimersetandrun_ms,
   longpulse,
   longpulse_ms,
 #ifndef BUILD_NO_DIAGNOSTIC_COMMANDS

src/src/Commands/Timer.cpp

@@ -17,14 +17,14 @@
 #include "../Helpers/Misc.h"
 #include "../Helpers/Scheduler.h"
 
-const __FlashStringHelper * command_setRulesTimer(int msecFromNow, int timerIndex, int recurringCount) {
+const __FlashStringHelper * command_setRulesTimer(int msecFromNow, int timerIndex, int recurringCount, bool startImmediately = false) {
   if (msecFromNow < 0)
   {
     addLog(LOG_LEVEL_ERROR, F("TIMER: time must be positive"));
   } else {
     // start new timer when msecFromNow > 0
     // Clear timer when msecFromNow == 0
-    if (Scheduler.setRulesTimer(msecFromNow, timerIndex, recurringCount))
+    if (Scheduler.setRulesTimer(msecFromNow, timerIndex, recurringCount, startImmediately))
     { 
       return return_command_success_flashstr();
     }
@@ -78,6 +78,34 @@ const __FlashStringHelper * Command_Loop_Timer_Set_ms (struct EventStruct *event
     );
 }
 
+const __FlashStringHelper * Command_Loop_Timer_SetAndRun (struct EventStruct *event, const char* Line)
+{
+  int recurringCount = event->Par3;
+  if (recurringCount == 0) {
+    // if the optional 3rd parameter is not given, set it to "run always"
+    recurringCount = -1;
+  }
+  return command_setRulesTimer(
+    event->Par2 * 1000, // msec from now
+    event->Par1,        // timer index
+    recurringCount,
+    true);
+}
+
+const __FlashStringHelper * Command_Loop_Timer_SetAndRun_ms (struct EventStruct *event, const char* Line)
+{
+  int recurringCount = event->Par3;
+  if (recurringCount == 0) {
+    // if the optional 3rd parameter is not given, set it to "run always"
+    recurringCount = -1;
+  }
+  return command_setRulesTimer(
+    event->Par2, // interval
+    event->Par1, // timer index
+    recurringCount,
+    true);
+}
+
 const __FlashStringHelper * Command_Timer_Pause(struct EventStruct *event, const char *Line)
 {
   if (Scheduler.pause_rules_timer(event->Par1)) {

src/src/Commands/Timer.h

@@ -7,6 +7,8 @@ const __FlashStringHelper * Command_Timer_Set (struct EventStruct *event, const
 const __FlashStringHelper * Command_Timer_Set_ms (struct EventStruct *event, const char* Line);
 const __FlashStringHelper * Command_Loop_Timer_Set (struct EventStruct *event, const char* Line);
 const __FlashStringHelper * Command_Loop_Timer_Set_ms (struct EventStruct *event, const char* Line);
+const __FlashStringHelper * Command_Loop_Timer_SetAndRun (struct EventStruct *event, const char* Line);
+const __FlashStringHelper * Command_Loop_Timer_SetAndRun_ms (struct EventStruct *event, const char* Line);
 const __FlashStringHelper * Command_Timer_Pause (struct EventStruct *event, const char* Line);
 const __FlashStringHelper * Command_Timer_Resume (struct EventStruct *event, const char* Line);
 const __FlashStringHelper * Command_Delay (struct EventStruct *event, const char* Line);

src/src/Helpers/Scheduler.h

@@ -161,9 +161,11 @@ void                 setPluginTaskTimer(unsigned long msecFromNow,
   // @param msecFromNow   Number of milli seconds from now (also used as interval for recurring)
   // @param timerIndex    The index of the timer used. (1 ... max)
   // @param recurringCount  Number of times needed to run (-1 for always)
+  // @param startImmediately  Run immediately
   bool setRulesTimer(unsigned long msecFromNow,
                      unsigned int  timerIndex,
-                     int           recurringCount = 0);
+                     int           recurringCount = 0,
+                     bool          startImmediately = false);
 
   void process_rules_timer(SchedulerTimerID timerID,
                            unsigned long lasttimer);

src/src/Helpers/Scheduler_RulesTimer.cpp

@@ -25,15 +25,15 @@ static bool checkRulesTimerIndex(unsigned int timerIndex) {
   return true;
 }
 
-bool ESPEasy_Scheduler::setRulesTimer(unsigned long msecFromNow, unsigned int timerIndex, int recurringCount) {
+bool ESPEasy_Scheduler::setRulesTimer(unsigned long msecFromNow, unsigned int timerIndex, int recurringCount, bool startImmediately) {
   if (!checkRulesTimerIndex(timerIndex)) { return false; }
 
   const RulesTimerID timerID(timerIndex);
 
   const systemTimerStruct timer_data(recurringCount, msecFromNow, timerIndex);
 
   systemTimers[timerID.mixed_id] = timer_data;
-  setNewTimerAt(timerID, millis() + msecFromNow);
+  setNewTimerAt(timerID, millis() + (startImmediately ? 10 : msecFromNow));
   return true;
 }