diff --git a/esphome/components/esp32_ble_tracker/esp32_ble_tracker.cpp b/esphome/components/esp32_ble_tracker/esp32_ble_tracker.cpp index 1080369ea0..6455326db4 100644 --- a/esphome/components/esp32_ble_tracker/esp32_ble_tracker.cpp +++ b/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); diff --git a/esphome/components/esp32_ble_tracker/esp32_ble_tracker.h b/esphome/components/esp32_ble_tracker/esp32_ble_tracker.h index 83799a9da7..16a100fb47 100644 --- a/esphome/components/esp32_ble_tracker/esp32_ble_tracker.h +++ b/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 ring_write_index_{0}; - std::atomic ring_read_index_{0}; - std::atomic scan_results_dropped_{0}; + std::atomic ring_write_index_{0}; // Written only by BT callback (producer) + std::atomic ring_read_index_{0}; // Written only by main loop (consumer) + std::atomic 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};