Merge branch 'ble_events_ring_buffer' into integration

esphome/components/esp32_ble_tracker/esp32_ble_tracker.cpp

@@ -118,7 +118,8 @@ void ESP32BLETracker::loop() {
   }
   bool promote_to_connecting = discovered && !searching && !connecting;
 
-  // Process scan results from lock-free ring buffer
+  // Process scan results from lock-free SPSC ring buffer
+  // Consumer side: This runs in the main loop thread
   if (this->scanner_state_ == ScannerState::RUNNING) {
     size_t read_idx = this->ring_read_index_.load(std::memory_order_relaxed);
     size_t write_idx = this->ring_write_index_.load(std::memory_order_acquire);
@@ -398,7 +399,9 @@ void ESP32BLETracker::gap_scan_event_handler(const BLEScanResult &scan_result) {
   ESP_LOGV(TAG, "gap_scan_result - event %d", scan_result.search_evt);
 
   if (scan_result.search_evt == ESP_GAP_SEARCH_INQ_RES_EVT) {
-    // Lock-free ring buffer write
+    // Lock-free SPSC ring buffer write (Producer side)
+    // This runs in the ESP-IDF Bluetooth stack callback thread
+    // IMPORTANT: Only this thread writes to ring_write_index_
     size_t write_idx = this->ring_write_index_.load(std::memory_order_relaxed);
     size_t next_write_idx = (write_idx + 1) % SCAN_RESULT_BUFFER_SIZE;
     size_t read_idx = this->ring_read_index_.load(std::memory_order_acquire);

esphome/components/esp32_ble_tracker/esp32_ble_tracker.h

@@ -284,11 +284,14 @@ class ESP32BLETracker : public Component,
   bool raw_advertisements_{false};
   bool parse_advertisements_{false};
 
-  // Lock-free ring buffer for scan results
+  // Lock-free Single-Producer Single-Consumer (SPSC) ring buffer for scan results
+  // Producer: ESP-IDF Bluetooth stack callback (gap_scan_event_handler)
+  // Consumer: ESPHome main loop (loop() method)
+  // This design ensures zero blocking in the BT callback and prevents scan result loss
   BLEScanResult *scan_ring_buffer_;
-  std::atomic<size_t> ring_write_index_{0};
+  std::atomic<size_t> ring_write_index_{0};      // Written only by BT callback (producer)
-  std::atomic<size_t> ring_read_index_{0};
+  std::atomic<size_t> ring_read_index_{0};       // Written only by main loop (consumer)
-  std::atomic<size_t> scan_results_dropped_{0};
+  std::atomic<size_t> scan_results_dropped_{0};  // Tracks buffer overflow events
 
   esp_bt_status_t scan_start_failed_{ESP_BT_STATUS_SUCCESS};
   esp_bt_status_t scan_set_param_failed_{ESP_BT_STATUS_SUCCESS};