esphome 2025.5.2__py3-none-any.whl → 2025.6.0__py3-none-any.whl

esphome/components/esp32_ble/ble_event.h

@@ -2,92 +2,232 @@
 
 #ifdef USE_ESP32
 
+#include <cstddef>  // for offsetof
 #include <vector>
 
 #include <esp_gap_ble_api.h>
 #include <esp_gattc_api.h>
 #include <esp_gatts_api.h>
 
+#include "ble_scan_result.h"
+
 namespace esphome {
 namespace esp32_ble {
+
+// Compile-time verification that ESP-IDF scan complete events only contain a status field
+// This ensures our reinterpret_cast in ble.cpp is safe
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_param_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_param_cmpl structure has unexpected size");
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_start_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_start_cmpl structure has unexpected size");
+static_assert(sizeof(esp_ble_gap_cb_param_t::ble_scan_stop_cmpl_evt_param) == sizeof(esp_bt_status_t),
+              "ESP-IDF scan_stop_cmpl structure has unexpected size");
+
+// Verify the status field is at offset 0 (first member)
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_param_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_param_cmpl),
+              "status must be first member of scan_param_cmpl");
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_start_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_start_cmpl),
+              "status must be first member of scan_start_cmpl");
+static_assert(offsetof(esp_ble_gap_cb_param_t, scan_stop_cmpl.status) ==
+                  offsetof(esp_ble_gap_cb_param_t, scan_stop_cmpl),
+              "status must be first member of scan_stop_cmpl");
+
 // Received GAP, GATTC and GATTS events are only queued, and get processed in the main loop().
-// This class stores each event in a single type.
+// This class stores each event with minimal memory usage.
+// GAP events (99% of traffic) don't have the vector overhead.
+// GATTC/GATTS events use heap allocation for their param and data.
+//
+// Event flow:
+// 1. ESP-IDF BLE stack calls our static handlers in the BLE task context
+// 2. The handlers create a BLEEvent instance, copying only the data we need
+// 3. The event is pushed to a thread-safe queue
+// 4. In the main loop(), events are popped from the queue and processed
+// 5. The event destructor cleans up any external allocations
+//
+// Thread safety:
+// - GAP events: We copy only the fields we need directly into the union
+// - GATTC/GATTS events: We heap-allocate and copy the entire param struct, ensuring
+//   the data remains valid even after the BLE callback returns. The original
+//   param pointer from ESP-IDF is only valid during the callback.
 class BLEEvent {
  public:
+  // NOLINTNEXTLINE(readability-identifier-naming)
+  enum ble_event_t : uint8_t {
+    GAP,
+    GATTC,
+    GATTS,
+  };
+
+  // Constructor for GAP events - no external allocations needed
   BLEEvent(esp_gap_ble_cb_event_t e, esp_ble_gap_cb_param_t *p) {
-    this->event_.gap.gap_event = e;
-    memcpy(&this->event_.gap.gap_param, p, sizeof(esp_ble_gap_cb_param_t));
     this->type_ = GAP;
-  };
+    this->event_.gap.gap_event = e;
+
+    if (p == nullptr) {
+      return;  // Invalid event, but we can't log in header file
+    }
+
+    // Only copy the data we actually use for each GAP event type
+    switch (e) {
+      case ESP_GAP_BLE_SCAN_RESULT_EVT:
+        // Copy only the fields we use from scan results
+        memcpy(this->event_.gap.scan_result.bda, p->scan_rst.bda, sizeof(esp_bd_addr_t));
+        this->event_.gap.scan_result.ble_addr_type = p->scan_rst.ble_addr_type;
+        this->event_.gap.scan_result.rssi = p->scan_rst.rssi;
+        this->event_.gap.scan_result.adv_data_len = p->scan_rst.adv_data_len;
+        this->event_.gap.scan_result.scan_rsp_len = p->scan_rst.scan_rsp_len;
+        this->event_.gap.scan_result.search_evt = p->scan_rst.search_evt;
+        memcpy(this->event_.gap.scan_result.ble_adv, p->scan_rst.ble_adv,
+               ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX);
+        break;
+
+      case ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT:
+        this->event_.gap.scan_complete.status = p->scan_param_cmpl.status;
+        break;
+
+      case ESP_GAP_BLE_SCAN_START_COMPLETE_EVT:
+        this->event_.gap.scan_complete.status = p->scan_start_cmpl.status;
+        break;
+
+      case ESP_GAP_BLE_SCAN_STOP_COMPLETE_EVT:
+        this->event_.gap.scan_complete.status = p->scan_stop_cmpl.status;
+        break;
+
+      default:
+        // We only handle 4 GAP event types, others are dropped
+        break;
+    }
+  }
 
+  // Constructor for GATTC events - uses heap allocation
+  // Creates a copy of the param struct since the original is only valid during the callback
   BLEEvent(esp_gattc_cb_event_t e, esp_gatt_if_t i, esp_ble_gattc_cb_param_t *p) {
+    this->type_ = GATTC;
     this->event_.gattc.gattc_event = e;
     this->event_.gattc.gattc_if = i;
-    memcpy(&this->event_.gattc.gattc_param, p, sizeof(esp_ble_gattc_cb_param_t));
-    // Need to also make a copy of relevant event data.
+
+    if (p == nullptr) {
+      this->event_.gattc.gattc_param = nullptr;
+      this->event_.gattc.data = nullptr;
+      return;  // Invalid event, but we can't log in header file
+    }
+
+    // Heap-allocate param and data
+    // Heap allocation is used because GATTC/GATTS events are rare (<1% of events)
+    // while GAP events (99%) are stored inline to minimize memory usage
+    this->event_.gattc.gattc_param = new esp_ble_gattc_cb_param_t(*p);
+
+    // Copy data for events that need it
     switch (e) {
       case ESP_GATTC_NOTIFY_EVT:
-        this->data.assign(p->notify.value, p->notify.value + p->notify.value_len);
-        this->event_.gattc.gattc_param.notify.value = this->data.data();
+        this->event_.gattc.data = new std::vector<uint8_t>(p->notify.value, p->notify.value + p->notify.value_len);
+        this->event_.gattc.gattc_param->notify.value = this->event_.gattc.data->data();
         break;
       case ESP_GATTC_READ_CHAR_EVT:
       case ESP_GATTC_READ_DESCR_EVT:
-        this->data.assign(p->read.value, p->read.value + p->read.value_len);
-        this->event_.gattc.gattc_param.read.value = this->data.data();
+        this->event_.gattc.data = new std::vector<uint8_t>(p->read.value, p->read.value + p->read.value_len);
+        this->event_.gattc.gattc_param->read.value = this->event_.gattc.data->data();
         break;
       default:
+        this->event_.gattc.data = nullptr;
         break;
     }
-    this->type_ = GATTC;
-  };
+  }
 
+  // Constructor for GATTS events - uses heap allocation
+  // Creates a copy of the param struct since the original is only valid during the callback
   BLEEvent(esp_gatts_cb_event_t e, esp_gatt_if_t i, esp_ble_gatts_cb_param_t *p) {
+    this->type_ = GATTS;
     this->event_.gatts.gatts_event = e;
     this->event_.gatts.gatts_if = i;
-    memcpy(&this->event_.gatts.gatts_param, p, sizeof(esp_ble_gatts_cb_param_t));
-    // Need to also make a copy of relevant event data.
+
+    if (p == nullptr) {
+      this->event_.gatts.gatts_param = nullptr;
+      this->event_.gatts.data = nullptr;
+      return;  // Invalid event, but we can't log in header file
+    }
+
+    // Heap-allocate param and data
+    // Heap allocation is used because GATTC/GATTS events are rare (<1% of events)
+    // while GAP events (99%) are stored inline to minimize memory usage
+    this->event_.gatts.gatts_param = new esp_ble_gatts_cb_param_t(*p);
+
+    // Copy data for events that need it
     switch (e) {
       case ESP_GATTS_WRITE_EVT:
-        this->data.assign(p->write.value, p->write.value + p->write.len);
-        this->event_.gatts.gatts_param.write.value = this->data.data();
+        this->event_.gatts.data = new std::vector<uint8_t>(p->write.value, p->write.value + p->write.len);
+        this->event_.gatts.gatts_param->write.value = this->event_.gatts.data->data();
         break;
       default:
+        this->event_.gatts.data = nullptr;
         break;
     }
-    this->type_ = GATTS;
-  };
+  }
+
+  // Destructor to clean up heap allocations
+  ~BLEEvent() {
+    switch (this->type_) {
+      case GATTC:
+        delete this->event_.gattc.gattc_param;
+        delete this->event_.gattc.data;
+        break;
+      case GATTS:
+        delete this->event_.gatts.gatts_param;
+        delete this->event_.gatts.data;
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Disable copy to prevent double-delete
+  BLEEvent(const BLEEvent &) = delete;
+  BLEEvent &operator=(const BLEEvent &) = delete;
 
   union {
     // NOLINTNEXTLINE(readability-identifier-naming)
     struct gap_event {
       esp_gap_ble_cb_event_t gap_event;
-      esp_ble_gap_cb_param_t gap_param;
-    } gap;
+      union {
+        BLEScanResult scan_result;  // 73 bytes
+        // This matches ESP-IDF's scan complete event structures
+        // All three (scan_param_cmpl, scan_start_cmpl, scan_stop_cmpl) have identical layout
+        struct {
+          esp_bt_status_t status;
+        } scan_complete;  // 1 byte
+      };
+    } gap;  // 80 bytes total
 
     // NOLINTNEXTLINE(readability-identifier-naming)
     struct gattc_event {
       esp_gattc_cb_event_t gattc_event;
       esp_gatt_if_t gattc_if;
-      esp_ble_gattc_cb_param_t gattc_param;
-    } gattc;
+      esp_ble_gattc_cb_param_t *gattc_param;  // Heap-allocated
+      std::vector<uint8_t> *data;             // Heap-allocated
+    } gattc;                                  // 16 bytes (pointers only)
 
     // NOLINTNEXTLINE(readability-identifier-naming)
     struct gatts_event {
       esp_gatts_cb_event_t gatts_event;
       esp_gatt_if_t gatts_if;
-      esp_ble_gatts_cb_param_t gatts_param;
-    } gatts;
-  } event_;
+      esp_ble_gatts_cb_param_t *gatts_param;  // Heap-allocated
+      std::vector<uint8_t> *data;             // Heap-allocated
+    } gatts;                                  // 16 bytes (pointers only)
+  } event_;                                   // 80 bytes
 
-  std::vector<uint8_t> data{};
-  // NOLINTNEXTLINE(readability-identifier-naming)
-  enum ble_event_t : uint8_t {
-    GAP,
-    GATTC,
-    GATTS,
-  } type_;
+  ble_event_t type_;
+
+  // Helper methods to access event data
+  ble_event_t type() const { return type_; }
+  esp_gap_ble_cb_event_t gap_event_type() const { return event_.gap.gap_event; }
+  const BLEScanResult &scan_result() const { return event_.gap.scan_result; }
+  esp_bt_status_t scan_complete_status() const { return event_.gap.scan_complete.status; }
 };
 
+// BLEEvent total size: 84 bytes (80 byte union + 1 byte type + 3 bytes padding)
+
 }  // namespace esp32_ble
 }  // namespace esphome
 

esphome/components/esp32_ble/ble_scan_result.h

@@ -0,0 +1,24 @@
+#pragma once
+
+#ifdef USE_ESP32
+
+#include <esp_gap_ble_api.h>
+
+namespace esphome {
+namespace esp32_ble {
+
+// Structure for BLE scan results - only fields we actually use
+struct __attribute__((packed)) BLEScanResult {
+  esp_bd_addr_t bda;
+  uint8_t ble_addr_type;
+  int8_t rssi;
+  uint8_t ble_adv[ESP_BLE_ADV_DATA_LEN_MAX + ESP_BLE_SCAN_RSP_DATA_LEN_MAX];
+  uint8_t adv_data_len;
+  uint8_t scan_rsp_len;
+  uint8_t search_evt;
+};  // ~73 bytes vs ~400 bytes for full esp_ble_gap_cb_param_t
+
+}  // namespace esp32_ble
+}  // namespace esphome
+
+#endif

esphome/components/esp32_ble/ble_uuid.h

@@ -1,7 +1,7 @@
 #pragma once
 
-#include "esphome/core/helpers.h"
 #include "esphome/core/hal.h"
+#include "esphome/core/helpers.h"
 
 #ifdef USE_ESP32
 

esphome/components/esp32_ble/queue.h

@@ -2,52 +2,78 @@
 
 #ifdef USE_ESP32
 
-#include <mutex>
-#include <queue>
-
-#include <freertos/FreeRTOS.h>
-#include <freertos/semphr.h>
+#include <atomic>
+#include <cstddef>
 
 /*
  * BLE events come in from a separate Task (thread) in the ESP32 stack. Rather
- * than trying to deal with various locking strategies, all incoming GAP and GATT
- * events will simply be placed on a semaphore guarded queue. The next time the
- * component runs loop(), these events are popped off the queue and handed at
- * this safer time.
+ * than using mutex-based locking, this lock-free queue allows the BLE
+ * task to enqueue events without blocking. The main loop() then processes
+ * these events at a safer time.
+ *
+ * This is a Single-Producer Single-Consumer (SPSC) lock-free ring buffer.
+ * The BLE task is the only producer, and the main loop() is the only consumer.
  */
 
 namespace esphome {
 namespace esp32_ble {
 
-template<class T> class Queue {
+template<class T, size_t SIZE> class LockFreeQueue {
  public:
-  Queue() { m_ = xSemaphoreCreateMutex(); }
+  LockFreeQueue() : head_(0), tail_(0), dropped_count_(0) {}
 
-  void push(T *element) {
+  bool push(T *element) {
     if (element == nullptr)
-      return;
-    // It is not called from main loop. Thus it won't block main thread.
-    xSemaphoreTake(m_, portMAX_DELAY);
-    q_.push(element);
-    xSemaphoreGive(m_);
+      return false;
+
+    size_t current_tail = tail_.load(std::memory_order_relaxed);
+    size_t next_tail = (current_tail + 1) % SIZE;
+
+    if (next_tail == head_.load(std::memory_order_acquire)) {
+      // Buffer full
+      dropped_count_.fetch_add(1, std::memory_order_relaxed);
+      return false;
+    }
+
+    buffer_[current_tail] = element;
+    tail_.store(next_tail, std::memory_order_release);
+    return true;
   }
 
   T *pop() {
-    T *element = nullptr;
-
-    if (xSemaphoreTake(m_, 5L / portTICK_PERIOD_MS)) {
-      if (!q_.empty()) {
-        element = q_.front();
-        q_.pop();
-      }
-      xSemaphoreGive(m_);
+    size_t current_head = head_.load(std::memory_order_relaxed);
+
+    if (current_head == tail_.load(std::memory_order_acquire)) {
+      return nullptr;  // Empty
     }
+
+    T *element = buffer_[current_head];
+    head_.store((current_head + 1) % SIZE, std::memory_order_release);
     return element;
   }
 
+  size_t size() const {
+    size_t tail = tail_.load(std::memory_order_acquire);
+    size_t head = head_.load(std::memory_order_acquire);
+    return (tail - head + SIZE) % SIZE;
+  }
+
+  size_t get_and_reset_dropped_count() { return dropped_count_.exchange(0, std::memory_order_relaxed); }
+
+  void increment_dropped_count() { dropped_count_.fetch_add(1, std::memory_order_relaxed); }
+
+  bool empty() const { return head_.load(std::memory_order_acquire) == tail_.load(std::memory_order_acquire); }
+
+  bool full() const {
+    size_t next_tail = (tail_.load(std::memory_order_relaxed) + 1) % SIZE;
+    return next_tail == head_.load(std::memory_order_acquire);
+  }
+
  protected:
-  std::queue<T *> q_;
-  SemaphoreHandle_t m_;
+  T *buffer_[SIZE];
+  std::atomic<size_t> head_;
+  std::atomic<size_t> tail_;
+  std::atomic<size_t> dropped_count_;
 };
 
 }  // namespace esp32_ble

esphome/components/esp32_ble_client/ble_client_base.cpp

@@ -45,8 +45,10 @@ void BLEClientBase::loop() {
 float BLEClientBase::get_setup_priority() const { return setup_priority::AFTER_BLUETOOTH; }
 
 void BLEClientBase::dump_config() {
-  ESP_LOGCONFIG(TAG, "  Address: %s", this->address_str().c_str());
-  ESP_LOGCONFIG(TAG, "  Auto-Connect: %s", TRUEFALSE(this->auto_connect_));
+  ESP_LOGCONFIG(TAG,
+                "  Address: %s\n"
+                "  Auto-Connect: %s",
+                this->address_str().c_str(), TRUEFALSE(this->auto_connect_));
   std::string state_name;
   switch (this->state()) {
     case espbt::ClientState::INIT:

esphome/components/esp32_ble_server/__init__.py

@@ -4,7 +4,7 @@ from esphome import automation
 import esphome.codegen as cg
 from esphome.components import esp32_ble
 from esphome.components.esp32 import add_idf_sdkconfig_option
-from esphome.components.esp32_ble import bt_uuid
+from esphome.components.esp32_ble import BTLoggers, bt_uuid
 import esphome.config_validation as cv
 from esphome.config_validation import UNDEFINED
 from esphome.const import (
@@ -525,6 +525,9 @@ async def to_code_characteristic(service_var, char_conf):
 
 
 async def to_code(config):
+    # Register the loggers this component needs
+    esp32_ble.register_bt_logger(BTLoggers.GATT, BTLoggers.SMP)
+
     var = cg.new_Pvariable(config[CONF_ID])
 
     await cg.register_component(var, config)

esphome/components/esp32_ble_server/ble_characteristic.cpp

@@ -2,6 +2,7 @@
 #include "ble_server.h"
 #include "ble_service.h"
 
+#include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
 
 #ifdef USE_ESP32

esphome/components/esp32_ble_server/ble_server.h

@@ -43,7 +43,6 @@ class BLEServer : public Component,
   float get_setup_priority() const override;
   bool can_proceed() override;
 
-  void teardown();
   bool is_running();
 
   void set_manufacturer_data(const std::vector<uint8_t> &data) {

esphome/components/esp32_ble_tracker/__init__.py

@@ -1,14 +1,15 @@
 from __future__ import annotations
 
-from collections.abc import MutableMapping
+from collections.abc import Callable, MutableMapping
 import logging
-from typing import Any, Callable
+from typing import Any
 
 from esphome import automation
 import esphome.codegen as cg
 from esphome.components import esp32_ble
 from esphome.components.esp32 import add_idf_sdkconfig_option
 from esphome.components.esp32_ble import (
+    BTLoggers,
     bt_uuid,
     bt_uuid16_format,
     bt_uuid32_format,
@@ -259,11 +260,15 @@ ESP_BLE_DEVICE_SCHEMA = cv.Schema(
 
 
 async def to_code(config):
+    # Register the loggers this component needs
+    esp32_ble.register_bt_logger(BTLoggers.BLE_SCAN)
+
     var = cg.new_Pvariable(config[CONF_ID])
     await cg.register_component(var, config)
 
     parent = await cg.get_variable(config[esp32_ble.CONF_BLE_ID])
     cg.add(parent.register_gap_event_handler(var))
+    cg.add(parent.register_gap_scan_event_handler(var))
     cg.add(parent.register_gattc_event_handler(var))
     cg.add(parent.register_ble_status_event_handler(var))
     cg.add(var.set_parent(parent))