feat: sendAck(), state-overwrite fix, and 3 ATtiny88↔ESP8266 bidirectional IoT examples

Co-authored-by: petesramek <2333452+petesramek@users.noreply.github.com>
Agent-Logs-Url: https://github.com/petesramek/tiny-link/sessions/86755db5-0da8-4952-a821-d2b33def396a

Author: Copilot

README.md

@@ -202,7 +202,53 @@ void serialEvent() {
 > 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.
+For a complete two-device IoT scenario in all three modes, see the
+[`IoT_Sensor_Gateway_*`](examples/) family of examples below.
+
+---
+
+## 🌐 IoT Sensor Gateway — Full Bidirectional Examples
+
+The `IoT_Sensor_Gateway_*` examples demonstrate a realistic ATtiny88 ↔ ESP8266
+system: the ATtiny88 reads a temperature sensor, the ESP8266 requests readings
+every 60 seconds and forwards them to a cloud endpoint.
+
+### Scenario
+
+```
+ATtiny88                              ESP8266
+    │◄──── Handshake ───────────────────►│  begin() on both sides
+    │             both: WAIT_FOR_SYNC    │
+    │                                    │
+    │◄═══ TYPE_CMD (request) ════════════│  every 60 s
+    │═══ ACK ════════════════════════════►│  sendAck() in callback
+    │═══ TYPE_DATA (temp + uptime) ═════►│
+    │◄══ ACK ════════════════════════════ │  sendAck() in callback
+    │                         ESP: posts to cloud
+```
+
+### `sendAck()` — Releasing the Peer from AWAITING_ACK
+
+When `begin()` is called (handshake mode), every `sendData()` puts the sender
+into `AWAITING_ACK`.  The receiver must call `sendAck()` to release it promptly:
+
+```cpp
+void onReceive(const SensorMessage& data) {
+    link.sendAck();          // ← release peer from AWAITING_ACK immediately
+    link.sendData(TYPE_DATA, response);  // reply — safe to call from callback
+}
+```
+
+### Three Update Modes, Side by Side
+
+| Example folder                     | update() driven by   | ISR-safe callbacks? | HW interrupt? |
+|------------------------------------|----------------------|---------------------|---------------|
+| `IoT_Sensor_Gateway_Polling`       | `loop()`             | ✅ Yes              | ❌ No         |
+| `IoT_Sensor_Gateway_TimerISR`      | Hardware timer ISR   | ⚠ Deferred only    | ✅ Yes        |
+| `IoT_Sensor_Gateway_SerialEvent`   | `serialEvent()`      | ✅ Yes              | ❌ No         |
+
+> **Mode 2 (Timer ISR) rule:** callbacks fire inside a hardware ISR — only set
+> `volatile` flags there.  Call `sendAck()` and `sendData()` from `loop()`.
 
 
 ## 📊 Performance & Telemetry

examples/Auto_Update/README.md

@@ -1,16 +1,18 @@
 # Auto Update — Three Ways to Drive TinyLink
 
-This example demonstrates **all three supported update modes** side by side so
-you can choose the one that best fits your hardware and application constraints.
-
-TinyLink's engine must be called periodically to process incoming serial bytes,
-manage protocol timeouts, and fire callbacks.  Previously, interrupt-driven
-updates required an explicit `enableAutoUpdate()` call.  Since v0.4.x that step
-is **no longer required**: the constructor automatically registers the instance,
-so every mode works with zero extra setup.
+> **Looking for a complete two-device example?**  
+> The [`IoT_Sensor_Gateway_Polling`](../IoT_Sensor_Gateway_Polling/README.md),
+> [`IoT_Sensor_Gateway_TimerISR`](../IoT_Sensor_Gateway_TimerISR/README.md), and
+> [`IoT_Sensor_Gateway_SerialEvent`](../IoT_Sensor_Gateway_SerialEvent/README.md)
+> examples show a full ATtiny88 ↔ ESP8266 bidirectional scenario — with
+> handshake, request, ACK, response, and cloud upload — in each of the three
+> update modes.  This folder contains minimal single-device mode sketches for
+> quick reference.
 
 ---
 
+# Auto Update — Mode Reference Sketches
+
 ## 🔍 Mode Comparison
 
 | | Mode 1 — Main Loop | Mode 2 — Timer ISR | Mode 3 — serialEvent() |

examples/IoT_Sensor_Gateway_Polling/ATtiny88_Sensor.ino

@@ -0,0 +1,70 @@
+/**
+ * IoT_Sensor_Gateway — Mode 1 (Polling / Main Loop)
+ * Device: ATtiny88 — Temperature Sensor Node
+ *
+ * Responsibilities:
+ *   1. Establish a TinyLink connection with the ESP8266 via begin().
+ *   2. Wait for a TYPE_CMD request from the ESP8266.
+ *   3. Acknowledge the request with sendAck() so the ESP8266 exits AWAITING_ACK.
+ *   4. Read the temperature sensor and send back a TYPE_DATA response.
+ *   5. Repeat every time the ESP8266 asks (nominally every 60 s).
+ *
+ * Update mode: link.update() called in loop() — works on every board,
+ * no hardware interrupts or extra libraries required.
+ *
+ * Wiring (ATtiny88 @ 5 V  ↔  ESP8266 @ 3.3 V):
+ *   ATtiny88 TX (PD1) → [1 kΩ]─┬─ ESP8266 RX
+ *                                └─[2 kΩ]─ GND   (voltage divider)
+ *   ATtiny88 RX (PD0) ──────────── ESP8266 TX     (3.3 V safe on Tiny88 input)
+ *   GND ────────────────────────── GND
+ */
+
+#include <TinyLink.h>
+#include <adapters/TinyArduinoAdapter.h>
+#include "SharedData.h"
+
+using namespace tinylink;
+
+TinyArduinoAdapter adapter(Serial);
+TinyLink<SensorMessage, TinyArduinoAdapter> link(adapter);
+
+// ---------------------------------------------------------------------------
+// Sensor stub — replace with your real sensor library (e.g. DallasTemperature)
+// ---------------------------------------------------------------------------
+float readTemperature() {
+    // Example: analogRead on ATtiny88 pin, scaled to °C
+    return 21.5f;  // stub value
+}
+
+// ---------------------------------------------------------------------------
+// Callback: fires when a TYPE_CMD request arrives from the ESP8266
+// ---------------------------------------------------------------------------
+void onRequest(const SensorMessage& req) {
+    // Step 1: ACK immediately — releases the ESP8266 from AWAITING_ACK.
+    link.sendAck();
+
+    // Step 2: Read sensor and send the response back.
+    SensorMessage resp;
+    resp.requestId   = req.requestId;     // echo so ESP8266 can correlate
+    resp.temperature = readTemperature();
+    resp.uptime      = static_cast<uint32_t>(millis());
+
+    link.sendData(TYPE_DATA, resp);
+    // ATtiny88 now enters AWAITING_ACK; ESP8266 will call sendAck() when it
+    // processes the data frame.
+}
+
+// ---------------------------------------------------------------------------
+
+void setup() {
+    Serial.begin(9600);
+    link.onDataReceived(onRequest);
+    link.begin();   // Initiate TinyLink handshake with the ESP8266.
+                    // Both sides call begin(); whoever boots first retries
+                    // every 1 s until the other side answers.
+}
+
+void loop() {
+    link.update();  // Drive the TinyLink engine.
+                    // All application logic lives in the onRequest() callback.
+}

examples/IoT_Sensor_Gateway_Polling/ESP8266_Gateway.ino

@@ -0,0 +1,103 @@
+/**
+ * IoT_Sensor_Gateway — Mode 1 (Polling / Main Loop)
+ * Device: ESP8266 — IoT Gateway
+ *
+ * Responsibilities:
+ *   1. Connect to Wi-Fi.
+ *   2. Establish a TinyLink connection with the ATtiny88 via begin().
+ *   3. Every 60 seconds, send a TYPE_CMD request to the ATtiny88.
+ *   4. When the ATtiny88 sends back a TYPE_DATA response, acknowledge it
+ *      with sendAck() and forward the temperature reading to the cloud.
+ *
+ * Update mode: link.update() called in loop() — portable, zero extra setup.
+ *
+ * Wiring: see ATtiny88_Sensor.ino
+ */
+
+#include <TinyLink.h>
+#include <adapters/TinyArduinoAdapter.h>
+#include <ESP8266WiFi.h>
+#include <ESP8266HTTPClient.h>
+#include "SharedData.h"
+
+using namespace tinylink;
+
+// ---------------------------------------------------------------------------
+// Configuration — update before uploading
+// ---------------------------------------------------------------------------
+const char* WIFI_SSID    = "YourSSID";
+const char* WIFI_PASS    = "YourPassword";
+const char* ENDPOINT_URL = "http://api.example.com/temperature";
+
+const unsigned long REQUEST_INTERVAL_MS = 60000UL;  // 60 s between requests
+
+// ---------------------------------------------------------------------------
+
+TinyArduinoAdapter adapter(Serial);
+TinyLink<SensorMessage, TinyArduinoAdapter> link(adapter);
+
+static uint8_t       requestId   = 0;
+static unsigned long lastRequest = 0;
+
+// ---------------------------------------------------------------------------
+// Send the temperature reading to the cloud endpoint
+// ---------------------------------------------------------------------------
+void postToCloud(const SensorMessage& data) {
+    if (WiFi.status() != WL_CONNECTED) return;
+
+    WiFiClient  client;
+    HTTPClient  http;
+    http.begin(client, ENDPOINT_URL);
+    http.addHeader("Content-Type", "application/json");
+
+    char body[96];
+    snprintf(body, sizeof(body),
+             "{\"id\":%u,\"temp\":%.2f,\"uptime\":%lu}",
+             (unsigned)data.requestId,
+             (double)data.temperature,
+             (unsigned long)data.uptime);
+
+    int code = http.POST(body);  // blocks until response or timeout
+    http.end();
+    (void)code;  // log or handle error code as needed
+}
+
+// ---------------------------------------------------------------------------
+// Callback: fires when a TYPE_DATA response arrives from the ATtiny88
+// ---------------------------------------------------------------------------
+void onSensorData(const SensorMessage& data) {
+    // Step 1: ACK the response — releases the ATtiny88 from AWAITING_ACK.
+    link.sendAck();
+
+    // Step 2: Forward the reading to the cloud.
+    postToCloud(data);
+}
+
+// ---------------------------------------------------------------------------
+
+void setup() {
+    Serial.begin(9600);
+
+    WiFi.begin(WIFI_SSID, WIFI_PASS);
+    while (WiFi.status() != WL_CONNECTED) { delay(100); }
+
+    link.onDataReceived(onSensorData);
+    link.begin();   // Initiate TinyLink handshake with the ATtiny88.
+}
+
+void loop() {
+    link.update();  // Drive the TinyLink engine.
+
+    // Every 60 s (once the link is up): request a sensor reading.
+    if (link.connected() &&
+            (millis() - lastRequest >= REQUEST_INTERVAL_MS)) {
+
+        SensorMessage req;
+        req.requestId   = requestId++;
+        req.temperature = 0.0f;   // not used in requests
+        req.uptime      = static_cast<uint32_t>(millis());
+
+        link.sendData(TYPE_CMD, req);   // → ATtiny88 receives this as a Cmd
+        lastRequest = millis();
+    }
+}

examples/IoT_Sensor_Gateway_Polling/README.md

@@ -0,0 +1,87 @@
+# IoT Sensor Gateway — Mode 1: Main-Loop Polling
+
+ATtiny88 temperature sensor node ↔ ESP8266 Wi-Fi gateway.  
+This is the **simplest update mode**: `link.update()` called once per `loop()`.  
+No hardware interrupts or extra libraries are required — works on every Arduino-compatible board.
+
+---
+
+## 🗺 Hardware Wiring
+
+```
+ATtiny88 (5 V)       Connection              ESP8266 (3.3 V)
+──────────────────   ───────────────────     ──────────────────
+TX (PD1)          → [1 kΩ]──┬──────────── → RX
+                             └──[2 kΩ]── GND  (voltage divider)
+RX (PD0)          ──────────────────────── ← TX  (3.3 V safe on Tiny88 input)
+GND               ──────────────────────── GND (common)
+```
+
+---
+
+## 📡 Protocol Flow
+
+```
+ATtiny88                              ESP8266
+    │                                     │
+    │◄──── HS(v=0) ─────────────────────►│  begin() on both sides
+    │───── HS(v=1) ────────────────────►  │  (retries every 1 s until peer answers)
+    │         both reach WAIT_FOR_SYNC    │
+    │                                     │
+    │◄═══ TYPE_CMD (requestId=N) ════════│  every 60 s
+    │                         ESP: AWAITING_ACK
+    │═══ ACK ════════════════════════════►│  sendAck() in onRequest()
+    │                         ESP: WAIT_FOR_SYNC
+    │═══ TYPE_DATA (temp, uptime) ═══════►│  sendData() in onRequest()
+    │               ATtiny88: AWAITING_ACK│
+    │◄══ ACK ════════════════════════════ │  sendAck() in onSensorData()
+    │               ATtiny88: WAIT_FOR_SYNC
+    │                         ESP posts to cloud
+    │                                     │
+    │         ... 60 seconds ...          │
+```
+
+---
+
+## 🔑 Key Points
+
+- **`begin()`** initiates the TinyLink handshake.  Both sides call it; whoever
+  boots first retries automatically every 1 second.
+- **`sendAck()`** releases the peer from `AWAITING_ACK` without waiting for the
+  timeout.  Call it first in every `onDataReceived` callback.
+- **`sendData()` from inside a callback** is safe and sets the sender into
+  `AWAITING_ACK` correctly (the state is preserved, not overwritten).
+- **`link.type()`** returns `TYPE_CMD` or `TYPE_DATA` so a single callback can
+  distinguish request from response if needed.
+
+---
+
+## 🔄 Update Mode: Main-Loop Polling
+
+```cpp
+void loop() {
+    link.update();  // ← the only required call
+}
+```
+
+| Attribute             | Value                              |
+|-----------------------|------------------------------------|
+| Hardware interrupt?   | ❌ No                              |
+| Extra library?        | ❌ No                              |
+| Works if loop blocks? | ❌ No — keep `loop()` responsive   |
+| Min RAM overhead      | 0 bytes                            |
+
+> For a version that survives a blocking `loop()`, see
+> **IoT_Sensor_Gateway_TimerISR**.  
+> For a zero-interrupt reactive alternative, see
+> **IoT_Sensor_Gateway_SerialEvent**.
+
+---
+
+## 🚀 How to Run
+
+1. Edit `WIFI_SSID`, `WIFI_PASS`, and `ENDPOINT_URL` in `ESP8266_Gateway.ino`.
+2. Upload `ATtiny88_Sensor.ino` to the ATtiny88 (set clock to 8 MHz).
+3. Upload `ESP8266_Gateway.ino` to the ESP8266.
+4. Open the ESP8266 Serial Monitor (9600 baud) to observe the handshake and the
+   60-second data cycles.

examples/IoT_Sensor_Gateway_Polling/SharedData.h

@@ -0,0 +1,30 @@
+/**
+ * @file SharedData.h
+ * @brief Common payload type used by both the ATtiny88 sensor node and the
+ *        ESP8266 gateway in all three IoT_Sensor_Gateway examples.
+ *
+ * Both devices instantiate:
+ *   TinyLink<SensorMessage, TinyArduinoAdapter> link(adapter);
+ *
+ * The TinyLink wire type (TYPE_CMD / TYPE_DATA) tells the receiver which
+ * direction the frame is travelling:
+ *
+ *   TYPE_CMD  ('C')  ESP8266 → ATtiny88  "please send a sensor reading"
+ *   TYPE_DATA ('D')  ATtiny88 → ESP8266  sensor reading + uptime
+ */
+
+#pragma once
+#include <stdint.h>
+#include "protocol/MessageType.h"
+
+struct SensorMessage {
+    uint8_t  requestId;    /**< Request counter. Response echoes this value.    */
+    float    temperature;  /**< Degrees Celsius. Set to 0.0 in request frames.  */
+    uint32_t uptime;       /**< Sender's millis() at send time. 0 in requests.  */
+} __attribute__((packed));
+
+// Convenience constants — avoid scattering the cast everywhere.
+static const uint8_t TYPE_CMD  =
+    static_cast<uint8_t>(tinylink::MessageType::Cmd);
+static const uint8_t TYPE_DATA =
+    static_cast<uint8_t>(tinylink::MessageType::Data);