added INTERVAL() debug helper function

ArduinoTrace.h

@@ -196,11 +196,25 @@ inline void pause(TSerial &serial) {
     ArduinoTrace::pause(ARDUINOTRACE_SERIAL);                 \
   } while (false)
 
+// Self contained interval timer that returns true once the interval has
+// elapsed.
+#define INTERVAL(ms)            \
+  ([]() -> bool {               \
+    static uint32_t _last = 0;  \
+    uint32_t _now = millis();   \
+    if (_now - _last >= (ms)) { \
+      _last = _now;             \
+      return true;              \
+    }                           \
+    return false;               \
+  }())
+
 #else  // ie ARDUINOTRACE_ENABLE == 0
 
 #define ARDUINOTRACE_INIT(bauds)
 #define TRACE()
 #define DUMP(variable)
 #define BREAK()
+#define INTERVAL(ms) false
 
 #endif

CHANGELOG.md

@@ -1,6 +1,11 @@
 ArduinoTrace: changelog
 =======================
 
+1.3.0 (2025/11/22)
+------------------
+
+* Added `INTERVAL()` macro
+
 1.2.0 (2021/02/07)
 ------------------
 

README.md

@@ -26,6 +26,9 @@ void loop() {
   value++;
   DUMP(value);
   BREAK();
+
+  if (INTERVAL(1000))
+    TRACE();
 }
 ```
 
@@ -35,6 +38,7 @@ The program above would print:
 MyProgram.ino:7: void setup()
 MyProgram.ino:12: value = 1
 MyProgram.ino:13: BREAK! (press [enter] to continue)
+MyProgram.ino:16: void setup()
 MyProgram.ino:12: value = 2
 MyProgram.ino:13: BREAK! (press [enter] to continue)
 MyProgram.ino:12: value = 3
@@ -55,6 +59,7 @@ MyProgram.ino:13: BREAK! (press [enter] to continue)
     - line number
     - variable's name
     - variable's value
+* `INTERVAL(variable)` is a self contained timer that returns true each time the interval (in milliseconds) has elapsed.
 * `BREAK()` pauses the program until you send a line-break to the Serial
 * `TRACE()` and `DUMP(variable)` work at global scope, provided that you call `ARDUINOTRACE_INIT()` to initialize the Serial port.
 * Flushes the Serial port to make sure that each line is complete

examples/BasicTracing/BasicTracing.ino

@@ -15,4 +15,8 @@ void loop() {
   value++;
   DUMP(value);
   BREAK();
+
+  // this will only print every 1000ms
+  if (INTERVAL(1000))
+    DUMP(VALUE);
 }

keywords.txt

@@ -1,3 +1,4 @@
 TRACE	KEYWORD2
 DUMP	KEYWORD2
 BREAK	KEYWORD2
+INTERVAL KEYWORD2

library.json

@@ -7,12 +7,15 @@
     "type": "git",
     "url": "https://github.com/bblanchon/ArduinoTrace.git"
   },
-  "version": "1.2.0",
+  "version": "1.3.0",
   "authors": {
     "name": "Benoit Blanchon",
     "url": "https://blog.benoitblanchon.fr"
   },
-  "exclude": [".github", "extras"],
+  "exclude": [
+    ".github",
+    "extras"
+  ],
   "frameworks": "arduino",
   "platforms": "*"
-}
+}

library.properties

@@ -1,5 +1,5 @@
 name=ArduinoTrace
-version=1.2.0
+version=1.3.0
 author=Benoit Blanchon <blog.benoitblanchon.fr>
 maintainer=Benoit Blanchon <blog.benoitblanchon.fr>
 sentence=A dead-simple tracing library to debug your programs