feat: auto-register in constructor; zero-setup ISR; three-mode comparison example and tests

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>
Agent-Logs-Url: https://github.com/petesramek/tiny-link/sessions/512c208c-f77a-4c3e-b8b4-c67795265687

Author: Copilot

README.md

@@ -148,6 +148,63 @@ void loop() {
 **Use Callbacks** if you want to keep your communication logic completely separated from your application logic. This is highly recommended as it makes the `TinyLink` engine more reactive.
 
 
+## 🔄 Auto-Update Modes
+
+TinyLink's protocol engine must be called periodically to process incoming bytes,
+manage timeouts, and fire callbacks.  There are **three supported ways** to drive
+it — choose the one that fits your hardware and application:
+
+| | Mode 1 — Main Loop | Mode 2 — Timer ISR | Mode 3 — serialEvent() |
+|---|---|---|---|
+| **How** | `link.update()` in `loop()` | `autoUpdateISR()` on a hardware timer | `autoUpdateISR()` from `serialEvent()` |
+| **Hardware interrupt?** | ❌ No | ✅ Timer required | ❌ No |
+| **Extra setup call?** | None | Timer init + `attachInterrupt` | None |
+| **`enableAutoUpdate()`?** | Not needed | Not needed | Not needed |
+| **Works if loop() blocks?** | ❌ No | ✅ Yes | ❌ No |
+| **Best for** | Any board, simplest code | Deterministic, busy loops | No-timer boards, reactive RX |
+
+### Mode 1 — Main Loop (default, works everywhere)
+
+```cpp
+void loop() {
+    link.update();  // ← only required call; works on every board
+}
+```
+
+### Mode 2 — Timer ISR (deterministic, interrupt-driven)
+
+The constructor auto-registers the instance — no `enableAutoUpdate()` needed.
+
+```cpp
+#include <TimerOne.h>
+
+void setup() {
+    Timer1.initialize(1000);  // 1 ms
+    Timer1.attachInterrupt(TinyLink<MyData, TinyArduinoAdapter>::autoUpdateISR);
+    // No enableAutoUpdate() call required.
+}
+// loop() does not need to call update() at all.
+```
+
+### Mode 3 — serialEvent() (zero-setup, no timer needed)
+
+Arduino calls `serialEvent()` automatically between `loop()` iterations when
+Serial bytes are waiting — no library or interrupt configuration required.
+
+```cpp
+void serialEvent() {
+    TinyLink<MyData, TinyArduinoAdapter>::autoUpdateISR();
+}
+// setup() and loop() have no TinyLink maintenance calls.
+```
+
+> **Multi-instance note:** When you have two `TinyLink<T,Adapter>` objects of
+> the same type, the last-constructed one is the default ISR target.  Call
+> `link.enableAutoUpdate()` on the desired instance to override.
+
+See `examples/Auto_Update/` for all three modes with a full side-by-side comparison.
+
+
 ## 📊 Performance & Telemetry
 
 Monitor link health in real-time to diagnose wiring issues:

examples/Auto_Update/Mode1_MainLoop.ino

@@ -0,0 +1,53 @@
+/**
+ * Auto_Update — Mode 1: Main-Loop Polling
+ *
+ * The simplest, most portable update mode.  No hardware interrupts are
+ * required.  Call link.update() once per loop iteration; TinyLink handles
+ * all framing, checksumming, and dispatching internally.
+ *
+ * Works on every Arduino-compatible board, including devices without any
+ * hardware timer interrupt support (e.g. MH-Tiny88, ATtiny-class MCUs).
+ *
+ * Platform: any Arduino-compatible board
+ * Wiring  : Serial TX → peer RX, Serial RX ← peer TX
+ */
+
+#include <TinyLink.h>
+#include <adapters/TinyArduinoAdapter.h>
+#include "SharedData.h"
+
+using namespace tinylink;
+
+TinyArduinoAdapter adapter(Serial);
+TinyLink<SensorData, TinyArduinoAdapter> link(adapter);
+
+// ----- Callback (fires inside update()) ----------------------------------
+
+void onReceive(const SensorData& d) {
+    Serial.print(F("[RX] uptime="));
+    Serial.print(d.uptime);
+    Serial.print(F("  temp="));
+    Serial.println(d.temperature);
+}
+
+// -------------------------------------------------------------------------
+
+void setup() {
+    Serial.begin(9600);
+    link.onDataReceived(onReceive);
+    // No extra setup — just start using update() in the loop.
+}
+
+void loop() {
+    // *** The only thing required to drive TinyLink ***
+    link.update();
+
+    // Send a reading every 2 seconds.
+    static uint32_t lastSend = 0;
+    static uint8_t  appSeq   = 0;
+    if (millis() - lastSend > 2000) {
+        SensorData msg = { millis(), 24.5f, appSeq++ };
+        link.sendData(TYPE_DATA, msg);
+        lastSend = millis();
+    }
+}

examples/Auto_Update/Mode2_TimerISR.ino

@@ -0,0 +1,66 @@
+/**
+ * Auto_Update — Mode 2: Hardware Timer ISR
+ *
+ * Uses a hardware timer to call TinyLink::autoUpdateISR() at a fixed rate
+ * (here: every 1 ms via the TimerOne library).  The main loop is free of any
+ * TinyLink maintenance calls; the ISR drives the engine automatically.
+ *
+ * autoUpdateISR() is ready to use immediately after construction — no
+ * enableAutoUpdate() call is needed for the standard single-instance setup.
+ * Call enableAutoUpdate() only if you need to switch which of several same-type
+ * instances is driven by the ISR.
+ *
+ * When to choose this mode:
+ *   - The main loop has variable, unpredictable timing (busy-wait, delays).
+ *   - You want deterministic, fixed-rate protocol maintenance.
+ *   - A hardware timer is available (most Uno/Mega/ESP32/STM32 boards).
+ *
+ * Dependencies: TimerOne library (Arduino IDE Library Manager)
+ *               https://github.com/PaulStoffregen/TimerOne
+ *
+ * Platform: Arduino Uno/Mega (AVR) and any board supported by TimerOne
+ * Wiring  : Serial TX → peer RX, Serial RX ← peer TX
+ */
+
+#include <TinyLink.h>
+#include <adapters/TinyArduinoAdapter.h>
+#include <TimerOne.h>          // Install via Library Manager
+#include "SharedData.h"
+
+using namespace tinylink;
+
+TinyArduinoAdapter adapter(Serial);
+TinyLink<SensorData, TinyArduinoAdapter> link(adapter);
+
+// ----- Callback (fires inside the ISR-driven update()) -------------------
+
+void onReceive(const SensorData& d) {
+    // Keep ISR callbacks short — avoid Serial.print() inside an ISR on AVR.
+    // Use a flag/buffer and process in loop() for safety on AVR targets.
+    (void)d;
+}
+
+// -------------------------------------------------------------------------
+
+void setup() {
+    Serial.begin(9600);
+    link.onDataReceived(onReceive);
+
+    // Attach the static ISR function to Timer1 (fires every 1 000 µs = 1 ms).
+    // No enableAutoUpdate() required — the constructor already registered this
+    // instance.
+    Timer1.initialize(1000);
+    Timer1.attachInterrupt(TinyLink<SensorData, TinyArduinoAdapter>::autoUpdateISR);
+}
+
+void loop() {
+    // update() is NOT called here — the timer ISR handles it automatically.
+
+    static uint32_t lastSend = 0;
+    static uint8_t  appSeq   = 0;
+    if (millis() - lastSend > 2000) {
+        SensorData msg = { millis(), 24.5f, appSeq++ };
+        link.sendData(TYPE_DATA, msg);
+        lastSend = millis();
+    }
+}

examples/Auto_Update/Mode3_SerialEvent.ino

@@ -0,0 +1,80 @@
+/**
+ * Auto_Update — Mode 3: serialEvent() (Zero-Interrupt Fallback)
+ *
+ * Arduino calls serialEvent() automatically between loop() iterations
+ * whenever bytes are waiting in the hardware Serial RX FIFO.  This gives
+ * near-immediate reaction to incoming data without needing a hardware timer
+ * or UART RX interrupt.
+ *
+ * autoUpdateISR() is called from serialEvent() — the function name "ISR" is
+ * kept for API consistency; serialEvent() is not a true hardware interrupt
+ * on Arduino, but it provides equivalent zero-extra-step auto-update
+ * behaviour on every Arduino board regardless of timer availability.
+ *
+ * When to choose this mode:
+ *   - No hardware timer is available or all timers are already occupied.
+ *   - You want zero-setup auto-update without any third-party library.
+ *   - Targeting boards where timer interrupt APIs differ across cores
+ *     (e.g., megaTinyCore, ATtinyCore).
+ *
+ * Limitation: serialEvent() is not called while the MCU is inside a blocking
+ *   function (delay(), analogRead() >10 ms, etc.).  Keep loop() responsive.
+ *
+ * Platform: any Arduino-compatible board
+ * Wiring  : Serial TX → peer RX, Serial RX ← peer TX
+ */
+
+#include <TinyLink.h>
+#include <adapters/TinyArduinoAdapter.h>
+#include "SharedData.h"
+
+using namespace tinylink;
+
+TinyArduinoAdapter adapter(Serial);
+TinyLink<SensorData, TinyArduinoAdapter> link(adapter);
+
+// ----- Callback -----------------------------------------------------------
+
+static volatile bool g_dataReady = false;
+static SensorData    g_latest;
+
+void onReceive(const SensorData& d) {
+    g_latest    = d;
+    g_dataReady = true;
+}
+
+// ----- Arduino serialEvent() — called between loop() iterations -----------
+//
+// No extra setup required; the constructor already registered the instance.
+// Simply forward to autoUpdateISR() for API consistency and portability.
+//
+void serialEvent() {
+    TinyLink<SensorData, TinyArduinoAdapter>::autoUpdateISR();
+}
+
+// -------------------------------------------------------------------------
+
+void setup() {
+    Serial.begin(9600);
+    link.onDataReceived(onReceive);
+    // No enableAutoUpdate(), no timer setup — serialEvent() handles it all.
+}
+
+void loop() {
+    // Process any data that arrived via serialEvent().
+    if (g_dataReady) {
+        g_dataReady = false;
+        Serial.print(F("[RX] uptime="));
+        Serial.print(g_latest.uptime);
+        Serial.print(F("  temp="));
+        Serial.println(g_latest.temperature);
+    }
+
+    static uint32_t lastSend = 0;
+    static uint8_t  appSeq   = 0;
+    if (millis() - lastSend > 2000) {
+        SensorData msg = { millis(), 24.5f, appSeq++ };
+        link.sendData(TYPE_DATA, msg);
+        lastSend = millis();
+    }
+}