Merge dev-v1.5.6 into main for v1.5.6 release

Author: DerekSeaman

ESPHome Devices/irk-capture-base.yaml

@@ -32,7 +32,7 @@ esphome:
   friendly_name: ${friendly_name}
   project:
     name: "derekseaman.irk-capture"
-    version: "1.5.4"
+    version: "1.5.6"
 
 # IMPORTANT: Do NOT include esp32_ble:, esp32_ble_tracker:, or bluetooth_proxy: here.
 # The irk_capture component fully initializes and manages NimBLE itself.

ESPHome Devices/irk-capture-full.yaml

@@ -57,7 +57,7 @@ esphome:
   friendly_name: ${friendly_name}
   project:
     name: "derekseaman.irk-capture"
-    version: "1.5.4"
+    version: "1.5.6"
 
 # IMPORTANT: Do NOT include esp32_ble:, esp32_ble_tracker:, or bluetooth_proxy: here.
 # The irk_capture component fully initializes and manages NimBLE itself.

RELEASE_NOTES_v1.5.6.md

@@ -0,0 +1,13 @@
+# Release Notes v1.5.6
+
+## Reliability Fixes
+
+- **Fixed MAC rotation race condition**: `refresh_mac()` now sets the `suppress_next_adv_` flag before triggering disconnect, preventing `handle_gap_disconnect` from restarting advertising while the MAC rotation is still in progress.
+- **Component fails cleanly on critical init errors**: `setup()` now calls `mark_failed()` and returns early if the FreeRTOS mutex cannot be created, and `register_gatt_services()` marks the component as failed if GATT registration fails.
+- **NVS profile range validation**: Persisted BLE profile values are now range-checked before `static_cast`, preventing undefined behavior from corrupted NVS data.
+- **BLE name whitespace trimming**: `sanitize_ble_name()` now trims leading and trailing spaces after character filtering, preventing names like `" IRK "` from wasting bytes in the advertising packet.
+- **Fixed `host_synced_` cross-core visibility**: Changed from plain `bool` to `std::atomic<bool>` to ensure the NimBLE task's write is visible to the ESPHome main loop on dual-core ESP32 variants.
+
+## Code Quality
+
+- **Added explicit standard library includes**: Added `<string>`, `<vector>` to header and `<cstring>` to implementation, removing reliance on transitive includes from ESPHome/NimBLE headers.

components/irk_capture/irk_capture.cpp

@@ -3,6 +3,7 @@
 // ESP32-only implementation - requires Bluetooth hardware
 #ifdef USE_ESP32
 
+#include <cstring>
 #include <esp_random.h>
 #include <esp_timer.h>
 #include <freertos/FreeRTOS.h>
@@ -23,7 +24,7 @@ namespace esphome {
 namespace irk_capture {
 
 static const char* const TAG = "irk_capture";
-static constexpr char VERSION[] = "1.5.5";
+static constexpr char VERSION[] = "1.5.6";
 static constexpr char HEX[] = "0123456789abcdef";
 
 // Global instance pointer for NimBLE callbacks that don't accept user args
@@ -70,6 +71,7 @@ THREAD SAFETY RULES:
 -    RAII MutexGuard class ensures exception-safe lock/unlock
 -    Mutex MUST be released before calling BLE stack APIs (prevents deadlock)
 -    UI updates (publish_state) are safe outside mutex (internally thread-safe)
+-    host_synced_ uses std::atomic<bool> (one-shot write from NimBLE, reads from main loop)
 
 IMPORTANT: Do NOT rely on "aligned writes are atomic" - always use mutex for
 shared state to ensure:
@@ -821,6 +823,15 @@ std::string IRKCaptureComponent::sanitize_ble_name(const std::string& name) {
     }
   }
 
+  // Trim leading and trailing whitespace
+  size_t start = sanitized.find_first_not_of(' ');
+  size_t end = sanitized.find_last_not_of(' ');
+  if (start != std::string::npos) {
+    sanitized = sanitized.substr(start, end - start + 1);
+  } else {
+    sanitized.clear();
+  }
+
   // Final validation: ensure we have at least one character
   if (sanitized.empty()) {
     ESP_LOGW(TAG, "BLE name contained only invalid characters, using default 'IRK Capture'");
@@ -1293,17 +1304,22 @@ void IRKCaptureComponent::setup() {
   state_mutex_ = xSemaphoreCreateMutex();
   if (!state_mutex_) {
     ESP_LOGE(TAG, "CRITICAL: Failed to create state mutex - thread safety compromised!");
-    // Continue anyway - component will work but may have race conditions
+    this->mark_failed();
+    return;
   }
 
   // Load persisted BLE profile from NVS (before BLE stack init so GATT is correct)
   nvs_handle_t nvs_handle;
   if (nvs_open("irk_capture", NVS_READONLY, &nvs_handle) == ESP_OK) {
     uint8_t profile_val = 0;
     if (nvs_get_u8(nvs_handle, "ble_profile", &profile_val) == ESP_OK) {
-      ble_profile_ = static_cast<BLEProfile>(profile_val);
-      ESP_LOGI(TAG, "Loaded persisted BLE profile: %s",
-               ble_profile_ == BLEProfile::KEYBOARD ? "Keyboard" : "Heart Sensor");
+      if (profile_val <= static_cast<uint8_t>(BLEProfile::KEYBOARD)) {
+        ble_profile_ = static_cast<BLEProfile>(profile_val);
+        ESP_LOGI(TAG, "Loaded persisted BLE profile: %s",
+                 ble_profile_ == BLEProfile::KEYBOARD ? "Keyboard" : "Heart Sensor");
+      } else {
+        ESP_LOGW(TAG, "Invalid persisted profile value %u, using default", profile_val);
+      }
     }
     nvs_close(nvs_handle);
   }
@@ -1717,6 +1733,7 @@ void IRKCaptureComponent::register_gatt_services() {
   if (rc == 0) rc = ble_gatts_add_svcs(gatt_svcs);
   if (rc != 0) {
     ESP_LOGE(TAG, "GATT registration failed rc=%d", rc);
+    this->mark_failed();
     return;
   }
   hr_char_handle_ = g_hr_handle;
@@ -1890,6 +1907,10 @@ void IRKCaptureComponent::refresh_mac() {
     mac_rotation_retries_ = 0;  // Reset retry counter for new rotation attempt
     std::memcpy(pending_mac_, temp_mac, sizeof(pending_mac_));
 
+    // Prevent handle_gap_disconnect from restarting advertising immediately,
+    // which would race with ble_hs_id_set_rnd() in loop() (BLE_HS_EBUSY)
+    suppress_next_adv_ = true;
+
     // Snapshot connection state for disconnect logic
     should_stop_adv = advertising_;
     conn_handle_copy = conn_handle_;

components/irk_capture/irk_capture.h

@@ -1,5 +1,9 @@
 #pragma once
 
+#include <atomic>
+#include <string>
+#include <vector>
+
 #include "esphome/components/button/button.h"
 #include "esphome/components/select/select.h"
 #include "esphome/components/switch/switch.h"
@@ -264,8 +268,9 @@ class IRKCaptureComponent : public Component {
   uint32_t last_publish_time_ { 0 };      // Last IRK publish timestamp
   uint32_t pairing_start_time_ { 0 };     // Global pairing timeout
 
-  // Host state (ESPHome-managed host; this is a soft flag)
-  bool host_synced_ { false };
+  // Host state — written once by NimBLE task (sync_cb), read by ESPHome main task
+  // Uses std::atomic for cross-core visibility without requiring state_mutex_
+  std::atomic<bool> host_synced_ { false };
 
   // Timer targets and cached peer ids
   struct Timers {