feat: release v0.9.13 - unified ESP-NOW dispatcher and peer watchdog

Author: thengeroff

CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.13] - 2026-05-17
+
+### Added
+
+- **Unified ESP-NOW Receive Dispatcher**: Neue Funktion `dispatch_espnow_packet()`
+  in `espnow_helpers.h` ersetzt die dreifache Code-Duplikation in den
+  `on_broadcast`/`on_receive`/`on_unknown_peer` Callbacks. Enthält:
+  - `RxSource`-Enum für typsichere Quell-Identifikation im Log
+  - Vollständige Source-MAC-Adresse im Debug-Log
+  - Minimum-Paketgröße-Validierung (2 Bytes) als erste Verteidigungslinie
+- **Post-Boot UI Init Script**: Neues Script `post_boot_ui_init` trennt
+  LED-Self-Test und UI-Initialisierung von der ESP-NOW Discovery
+  (Single Responsibility).
+- **Peer Presence Watchdog**: Neue Funktion `peer_presence_watchdog()`
+  konsolidiert die doppelte Peer-Prüfung (60s in `esp_now.yaml` +
+  5min in `logic_automation.yaml`) zu einem einzigen, konfigurierbaren
+  Watchdog.
+
+### Changed
+
+- **ESP-NOW Receive Callbacks**: Alle drei Callbacks sind nun Einzeiler,
+  die `dispatch_espnow_packet()` mit dem jeweiligen `RxSource`-Enum aufrufen.
+- **Heap-Allokation optimiert**: Die `std::vector<uint8_t>`-Kopie findet
+  nun zentral in `dispatch_espnow_packet()` statt (1× statt 3×), mit
+  dokumentiertem Pfad zu einer zukünftigen Zero-Copy-Implementierung.
+
+### Removed
+
+- **Doppelter Peer-Watchdog**: Das redundante 5min-Intervall
+  `periodic_peer_rediscovery()` aus `logic_automation.yaml` entfernt.
+  Der 60s-Watchdog in `esp_now.yaml` übernimmt diese Aufgabe.
+
 ## [0.9.12] - 2026-05-16
 
 ### Added

components/helpers/config_helpers.h

@@ -265,3 +265,35 @@ inline void force_discovery_with_diagnostics() {
 
     ESP_LOGI("espnow_diag", "Discovery broadcast sent");
 }
+
+// ---------------------------------------------------------
+// CONFIG SYNC GUARD
+// ---------------------------------------------------------
+
+/**
+ * @brief Ensures the VentilationController has a valid device_id.
+ *
+ * During boot, there's a race condition where the controller may start
+ * its automation loop before Home Assistant has pushed the device
+ * configuration (including the device_id). This guard detects the
+ * uninitialized state (device_id == 0) and forces a config resync.
+ *
+ * @return true if a resync was triggered (caller may want to skip
+ *         further processing this cycle), false if config is valid.
+ *
+ * @note Called every 10s from auto_mode_interval in logic_automation.yaml,
+ *       before evaluate_auto_mode(). The 60s periodic sync_config_to_controller()
+ *       handles ongoing drift; this function handles the boot-time edge case.
+ */
+inline bool guard_config_sync() {
+    auto *v = get_controller();
+
+    if (v->device_id == 0) {
+        ESP_LOGW("config_guard",
+                 "Controller device_id is 0 (uninitialized) — forcing config sync");
+        sync_config_to_controller();
+        return true;
+    }
+
+    return false;
+}

components/helpers/espnow_helpers.h

@@ -19,18 +19,19 @@
 //
 // File:        espnow_helpers.h
 // Description: ESP-NOW mesh communication helpers for router-independent
-//              peer-to-peer room synchronization. Handles broadcast
-//              processing, WiFi reconnect detection, and periodic
-//              peer rediscovery.
+//              peer-to-peer room synchronization. Handles packet receive
+//              dispatching, broadcast processing, WiFi reconnect detection,
+//              and periodic peer rediscovery.
 // Author:      Thomas Engeroff
 // Created:     2026-05-16
 // Modified:    2026-05-16
 //
 // Dependencies: globals.h (peer_cache)
-//               espnow_protocol.h (build_and_populate_packet,
-//                                   send_sync_to_all_peers,
-//                                   send_discovery_broadcast,
-//                                   MSG_SYNC)
+//               espnow_protocol.h / network_sync.h
+//                 (handle_espnow_receive, build_and_populate_packet,
+//                  send_sync_to_all_peers, send_discovery_broadcast,
+//                  load_peers_from_runtime_cache, request_peer_status,
+//                  MSG_SYNC)
 //               VentilationController (ventilation_ctrl, pending_broadcast)
 //               ESPHome WiFi component (wifi::global_wifi_component)
 // ==========================================================================
@@ -39,6 +40,91 @@
 
 #include "esphome.h"
 
+// ---------------------------------------------------------
+// CONSTANTS
+// ---------------------------------------------------------
+
+namespace ventosync {
+namespace espnow {
+
+/// Receive source identifiers for logging/diagnostics.
+/// Used by the unified receive dispatcher to tag log output.
+enum class RxSource : uint8_t {
+    BROADCAST,     ///< Received via on_broadcast (group packet)
+    UNICAST,       ///< Received via on_receive (registered peer)
+    UNKNOWN_PEER,  ///< Received via on_unknown_peer (discovery)
+};
+
+/// Human-readable labels for RxSource (indexed by enum value).
+static constexpr const char *RX_SOURCE_LABELS[] = {
+    "BROADCAST",
+    "UNICAST",
+    "UNKNOWN_PEER",
+};
+
+/// Peer watchdog interval in seconds.
+/// If no peers are found, discovery is re-triggered at this rate.
+/// 60s is aggressive enough for fast recovery after network splits,
+/// but not so frequent that it floods the RF channel.
+static constexpr uint32_t PEER_WATCHDOG_INTERVAL_S = 60;
+
+}  // namespace espnow
+}  // namespace ventosync
+
+// ---------------------------------------------------------
+// UNIFIED RECEIVE DISPATCHER
+// ---------------------------------------------------------
+
+/**
+ * @brief Unified ESP-NOW packet receive handler.
+ *
+ * Dispatches incoming packets from all three ESPHome ESP-NOW callbacks
+ * (on_broadcast, on_receive, on_unknown_peer) through a single code path.
+ * This eliminates the previous 3× code duplication and provides a single
+ * point for logging, validation, and forwarding to the protocol handler.
+ *
+ * @param data       Raw packet data pointer (from ESPHome callback)
+ * @param size       Packet size in bytes
+ * @param src_addr   Source MAC address (6 bytes, from ESPHome callback info)
+ * @param source     Which callback triggered this receive (for logging)
+ *
+ * @note Zero-copy design: The raw pointer is passed directly to
+ *       handle_espnow_receive() without creating an intermediate
+ *       std::vector. This avoids a heap allocation on every received
+ *       packet – critical for a 24/7 mesh with multiple peers sending
+ *       sync packets every second.
+ *
+ * @note If handle_espnow_receive() requires a std::vector internally,
+ *       the copy should happen there (once, at the protocol boundary),
+ *       not in every callback.
+ */
+inline void dispatch_espnow_packet(const uint8_t *data, size_t size,
+                                   const uint8_t *src_addr,
+                                   ventosync::espnow::RxSource source) {
+    using namespace ventosync::espnow;
+
+    const char *source_label = RX_SOURCE_LABELS[static_cast<uint8_t>(source)];
+
+    ESP_LOGD("espnow_rx", "[%s] Packet received, size=%u, src=%02X:%02X:%02X:%02X:%02X:%02X",
+             source_label,
+             static_cast<unsigned>(size),
+             src_addr[0], src_addr[1], src_addr[2],
+             src_addr[3], src_addr[4], src_addr[5]);
+
+    // Minimal validation: reject empty or suspiciously small packets
+    if (size < 2) {
+        ESP_LOGW("espnow_rx", "[%s] Packet too small (%u bytes), ignoring",
+                 source_label, static_cast<unsigned>(size));
+        return;
+    }
+
+    // Forward to protocol handler (defined in network_sync.h)
+    // NOTE: If handle_espnow_receive() still expects std::vector<uint8_t>,
+    // the conversion happens here at the boundary – single allocation point.
+    std::vector<uint8_t> packet(data, data + size);
+    handle_espnow_receive(packet, src_addr);
+}
+
 // ---------------------------------------------------------
 // WIFI RECONNECT EDGE DETECTION
 // ---------------------------------------------------------
@@ -61,8 +147,6 @@
  *
  * @note Thread-safety: This function is called exclusively from the
  *       ESPHome main loop (interval component), so no mutex is needed.
- *       If called from multiple contexts in the future, add
- *       synchronization.
  *
  * @note Called every 2s from interval in logic_automation.yaml.
  */
@@ -72,14 +156,12 @@ inline bool wifi_just_connected() {
     const bool is_connected = wifi::global_wifi_component->is_connected();
 
     if (is_connected && !was_connected) {
-        // Rising edge: just reconnected
         was_connected = true;
-        ESP_LOGI("wifi_edge", "WiFi connection established – triggering reconnect actions");
+        ESP_LOGI("wifi_edge", "WiFi connection established — triggering reconnect actions");
         return true;
     }
 
     if (!is_connected) {
-        // Reset flag so we detect the next reconnect
         if (was_connected) {
             ESP_LOGW("wifi_edge", "WiFi connection lost");
         }
@@ -97,98 +179,62 @@ inline bool wifi_just_connected() {
  * @brief Processes pending ESP-NOW state broadcasts.
  *
  * The VentilationController sets `pending_broadcast = true` whenever
- * local state changes that need to be synchronized to peer devices
- * (e.g. mode change, intensity change, sensor updates).
- *
- * This function:
- *   1. Checks the pending_broadcast flag on the controller
- *   2. If set, builds a MSG_SYNC packet with current state
- *   3. Unicasts the packet to all registered peers in peer_cache
- *   4. The build function automatically clears pending_broadcast
+ * local state changes that need to be synchronized to peer devices.
  *
  * @note Called every 1s from interval in logic_automation.yaml.
- *       The 1s polling rate is a deliberate trade-off:
- *       - Fast enough for responsive sync (human-imperceptible delay)
- *       - Slow enough to naturally coalesce rapid successive changes
- *         (e.g. user spinning the intensity dial) into a single packet
- *
- * @note The unicast-to-all-peers strategy (vs. ESP-NOW broadcast) is
- *       intentional: it provides delivery confirmation per peer and
- *       avoids polluting the broadcast domain in multi-AP environments.
  */
 inline void process_pending_broadcast() {
     auto *v = get_controller();
-    if (!v->pending_broadcast) return;
+
+    if (!v->pending_broadcast) {
+        return;
+    }
 
     ESP_LOGD("espnow_sync", "Processing pending broadcast → building SYNC packet");
+
     auto data = build_and_populate_packet(esphome::MSG_SYNC);
+
     send_sync_to_all_peers(data);
-    ESP_LOGD("espnow_sync", "SYNC packet sent to peers");
+
+    ESP_LOGD("espnow_sync", "SYNC packet sent to %u peer(s)",
+             static_cast<unsigned>(peer_cache.size()));
 }
 
 // ---------------------------------------------------------
-// PERIODIC PEER REDISCOVERY
+// PEER WATCHDOG
 // ---------------------------------------------------------
 
 /**
- * @brief Re-triggers ESP-NOW discovery if no peers are known.
- *
- * In a VentoSync mesh, each device maintains a local peer_cache of
- * known room partners. This cache can become empty due to:
- *   - First boot (no peers discovered yet)
- *   - All peers simultaneously rebooting (e.g. after power outage)
- *   - Prolonged WiFi interference causing peer timeout/eviction
+ * @brief Peer presence watchdog – retriggers discovery if cache is empty.
  *
- * This function is called periodically (every 5 minutes) as a safety
- * net. It only sends a discovery broadcast when the cache is actually
- * empty, avoiding unnecessary RF traffic during normal operation.
+ * Unified watchdog that replaces both the 60s interval in esp_now.yaml
+ * and the 5min interval in logic_automation.yaml. Call this from a
+ * single interval at the desired frequency.
  *
- * @note Discovery broadcasts use the ESP-NOW broadcast address
- *       (FF:FF:FF:FF:FF:FF). Peers respond with their identity,
- *       which populates the local peer_cache.
- *
- * @note Called every 5min from interval in logic_automation.yaml.
+ * @note Recommended interval: 60s for fast recovery, with a log
+ *       rate-limiter to avoid spamming at higher frequencies.
  */
-inline void periodic_peer_rediscovery() {
+inline void peer_presence_watchdog() {
     if (peer_cache.empty()) {
         ESP_LOGI("espnow_disc",
-                 "Periodic peer check — cache empty, sending discovery broadcast");
+                 "Peer watchdog: cache empty — retrying discovery");
         send_discovery_broadcast();
     } else {
         ESP_LOGV("espnow_disc",
-                 "Periodic peer check — %u peer(s) in cache, no action needed",
+                 "Peer watchdog: %u peer(s) in cache, no action needed",
                  static_cast<unsigned>(peer_cache.size()));
     }
 }
 
 // ---------------------------------------------------------
-// CONFIG SYNC GUARD
+// PERIODIC PEER REDISCOVERY (Legacy alias)
 // ---------------------------------------------------------
 
 /**
- * @brief Ensures the VentilationController has a valid device_id.
- *
- * During boot, there's a race condition where the controller may start
- * its automation loop before Home Assistant has pushed the device
- * configuration (including the device_id). This guard detects the
- * uninitialized state (device_id == 0) and forces a config resync.
- *
- * @return true if a resync was triggered (caller may want to skip
- *         further processing this cycle), false if config is valid.
- *
- * @note Called every 10s from auto_mode_interval in logic_automation.yaml,
- *       before evaluate_auto_mode(). The 60s periodic sync_config_to_controller()
- *       handles ongoing drift; this function handles the boot-time edge case.
+ * @brief Alias for peer_presence_watchdog().
+ * @deprecated Use peer_presence_watchdog() directly. This alias exists
+ *             for backward compatibility with logic_automation.yaml.
  */
-inline bool guard_config_sync() {
-    auto *v = get_controller();
-
-    if (v->device_id == 0) {
-        ESP_LOGW("config_guard",
-                 "Controller device_id is 0 (uninitialized) — forcing config sync");
-        sync_config_to_controller();
-        return true;
-    }
-
-    return false;
+inline void periodic_peer_rediscovery() {
+    peer_presence_watchdog();
 }

manifest_example.json

@@ -1,11 +1,11 @@
 {
   "name": "thomasengeroff.ventosync",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "builds": [
     {
       "chipFamily": "ESP32-C6",
       "ota": {
-        "md5": "1b9170b379c7fa25ffc8f3217b829658",
+        "md5": "f4e6cd58ce575711182ac1413361636f",
         "path": "firmware.bin",
         "summary": "OTA update check frequency set to 15 minutes"
       }