esphome 2025.7.4__py3-none-any.whl → 2025.8.0__py3-none-any.whl

esphome/components/esp32_ble/ble_event.h

@@ -3,16 +3,14 @@
 #ifdef USE_ESP32
 
 #include <cstddef>  // for offsetof
-#include <vector>
-
+#include <cstring>  // for memcpy
 #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 {
+namespace esphome::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
@@ -63,10 +61,24 @@ static_assert(offsetof(esp_ble_gap_cb_param_t, read_rssi_cmpl.rssi) == sizeof(es
 static_assert(offsetof(esp_ble_gap_cb_param_t, read_rssi_cmpl.remote_addr) == sizeof(esp_bt_status_t) + sizeof(int8_t),
               "remote_addr must follow rssi in read_rssi_cmpl");
 
+// Param struct sizes on ESP32
+static constexpr size_t GATTC_PARAM_SIZE = 28;
+static constexpr size_t GATTS_PARAM_SIZE = 32;
+
+// Maximum size for inline storage of data
+// GATTC: 80 - 28 (param) - 8 (other fields) = 44 bytes for data
+// GATTS: 80 - 32 (param) - 8 (other fields) = 40 bytes for data
+static constexpr size_t GATTC_INLINE_DATA_SIZE = 44;
+static constexpr size_t GATTS_INLINE_DATA_SIZE = 40;
+
+// Verify param struct sizes
+static_assert(sizeof(esp_ble_gattc_cb_param_t) == GATTC_PARAM_SIZE, "GATTC param size unexpected");
+static_assert(sizeof(esp_ble_gatts_cb_param_t) == GATTS_PARAM_SIZE, "GATTS param size unexpected");
+
 // Received GAP, GATTC and GATTS events are only queued, and get processed in the main loop().
 // 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.
+// GAP events (99% of traffic) don't have the heap allocation overhead.
+// GATTC/GATTS events use heap allocation for their param and inline storage for small data.
 //
 // Event flow:
 // 1. ESP-IDF BLE stack calls our static handlers in the BLE task context
@@ -113,21 +125,21 @@ class BLEEvent {
     this->init_gap_data_(e, p);
   }
 
-  // Constructor for GATTC events - uses heap allocation
-  // IMPORTANT: The heap allocation is REQUIRED and must not be removed as an optimization.
-  // The param pointer from ESP-IDF is only valid during the callback execution.
-  // Since BLE events are processed asynchronously in the main loop, we must create
-  // our own copy to ensure the data remains valid until the event is processed.
+  // Constructor for GATTC events - param stored inline, data may use heap
+  // IMPORTANT: We MUST copy the param struct because the pointer from ESP-IDF
+  // is only valid during the callback execution. Since BLE events are processed
+  // asynchronously in the main loop, we store our own copy inline to ensure
+  // the data remains valid until the event is processed.
   BLEEvent(esp_gattc_cb_event_t e, esp_gatt_if_t i, esp_ble_gattc_cb_param_t *p) {
     this->type_ = GATTC;
     this->init_gattc_data_(e, i, p);
   }
 
-  // Constructor for GATTS events - uses heap allocation
-  // IMPORTANT: The heap allocation is REQUIRED and must not be removed as an optimization.
-  // The param pointer from ESP-IDF is only valid during the callback execution.
-  // Since BLE events are processed asynchronously in the main loop, we must create
-  // our own copy to ensure the data remains valid until the event is processed.
+  // Constructor for GATTS events - param stored inline, data may use heap
+  // IMPORTANT: We MUST copy the param struct because the pointer from ESP-IDF
+  // is only valid during the callback execution. Since BLE events are processed
+  // asynchronously in the main loop, we store our own copy inline to ensure
+  // the data remains valid until the event is processed.
   BLEEvent(esp_gatts_cb_event_t e, esp_gatt_if_t i, esp_ble_gatts_cb_param_t *p) {
     this->type_ = GATTS;
     this->init_gatts_data_(e, i, p);
@@ -137,25 +149,32 @@ class BLEEvent {
   ~BLEEvent() { this->release(); }
 
   // Default constructor for pre-allocation in pool
-  BLEEvent() : type_(GAP) {}
+  BLEEvent() : event_{}, type_(GAP) {}
 
   // Invoked on return to EventPool - clean up any heap-allocated data
   void release() {
-    if (this->type_ == GAP) {
-      return;
-    }
-    if (this->type_ == GATTC) {
-      delete this->event_.gattc.gattc_param;
-      delete this->event_.gattc.data;
-      this->event_.gattc.gattc_param = nullptr;
-      this->event_.gattc.data = nullptr;
-      return;
-    }
-    if (this->type_ == GATTS) {
-      delete this->event_.gatts.gatts_param;
-      delete this->event_.gatts.data;
-      this->event_.gatts.gatts_param = nullptr;
-      this->event_.gatts.data = nullptr;
+    switch (this->type_) {
+      case GAP:
+        // GAP events don't have heap allocations
+        break;
+      case GATTC:
+        // Param is now stored inline, only delete heap data if it was heap-allocated
+        if (!this->event_.gattc.is_inline && this->event_.gattc.data.heap_data != nullptr) {
+          delete[] this->event_.gattc.data.heap_data;
+        }
+        // Clear critical fields to prevent issues if type changes
+        this->event_.gattc.is_inline = false;
+        this->event_.gattc.data.heap_data = nullptr;
+        break;
+      case GATTS:
+        // Param is now stored inline, only delete heap data if it was heap-allocated
+        if (!this->event_.gatts.is_inline && this->event_.gatts.data.heap_data != nullptr) {
+          delete[] this->event_.gatts.data.heap_data;
+        }
+        // Clear critical fields to prevent issues if type changes
+        this->event_.gatts.is_inline = false;
+        this->event_.gatts.data.heap_data = nullptr;
+        break;
     }
   }
 
@@ -207,20 +226,30 @@ class BLEEvent {
 
     // 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;  // Heap-allocated
-      std::vector<uint8_t> *data;             // Heap-allocated
-    } gattc;                                  // 16 bytes (pointers only)
+      esp_ble_gattc_cb_param_t gattc_param;  // Stored inline (28 bytes)
+      esp_gattc_cb_event_t gattc_event;      // 4 bytes
+      union {
+        uint8_t *heap_data;                           // 4 bytes when heap-allocated
+        uint8_t inline_data[GATTC_INLINE_DATA_SIZE];  // 44 bytes when stored inline
+      } data;                                         // 44 bytes total
+      uint16_t data_len;                              // 2 bytes
+      esp_gatt_if_t gattc_if;                         // 1 byte
+      bool is_inline;                                 // 1 byte - true when data is stored inline
+    } gattc;                                          // Total: 80 bytes
 
     // 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;  // Heap-allocated
-      std::vector<uint8_t> *data;             // Heap-allocated
-    } gatts;                                  // 16 bytes (pointers only)
-  } event_;                                   // 80 bytes
+      esp_ble_gatts_cb_param_t gatts_param;  // Stored inline (32 bytes)
+      esp_gatts_cb_event_t gatts_event;      // 4 bytes
+      union {
+        uint8_t *heap_data;                           // 4 bytes when heap-allocated
+        uint8_t inline_data[GATTS_INLINE_DATA_SIZE];  // 40 bytes when stored inline
+      } data;                                         // 40 bytes total
+      uint16_t data_len;                              // 2 bytes
+      esp_gatt_if_t gatts_if;                         // 1 byte
+      bool is_inline;                                 // 1 byte - true when data is stored inline
+    } gatts;                                          // Total: 80 bytes
+  } event_;                                           // 80 bytes
 
   ble_event_t type_;
 
@@ -234,6 +263,29 @@ class BLEEvent {
   const esp_ble_sec_t &security() const { return event_.gap.security; }
 
  private:
+  // Helper to copy data with inline storage optimization
+  template<typename EventStruct, size_t InlineSize>
+  void copy_data_with_inline_storage_(EventStruct &event, const uint8_t *src_data, uint16_t len,
+                                      uint8_t **param_value_ptr) {
+    event.data_len = len;
+    if (len > 0) {
+      if (len <= InlineSize) {
+        event.is_inline = true;
+        memcpy(event.data.inline_data, src_data, len);
+        *param_value_ptr = event.data.inline_data;
+      } else {
+        event.is_inline = false;
+        event.data.heap_data = new uint8_t[len];
+        memcpy(event.data.heap_data, src_data, len);
+        *param_value_ptr = event.data.heap_data;
+      }
+    } else {
+      event.is_inline = false;
+      event.data.heap_data = nullptr;
+      *param_value_ptr = nullptr;
+    }
+  }
+
   // Initialize GAP event data
   void init_gap_data_(esp_gap_ble_cb_event_t e, esp_ble_gap_cb_param_t *p) {
     this->event_.gap.gap_event = e;
@@ -318,35 +370,38 @@ class BLEEvent {
     this->event_.gattc.gattc_if = i;
 
     if (p == nullptr) {
-      this->event_.gattc.gattc_param = nullptr;
-      this->event_.gattc.data = nullptr;
+      // Zero out the param struct when null
+      memset(&this->event_.gattc.gattc_param, 0, sizeof(this->event_.gattc.gattc_param));
+      this->event_.gattc.is_inline = false;
+      this->event_.gattc.data.heap_data = nullptr;
+      this->event_.gattc.data_len = 0;
       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
-    // IMPORTANT: This heap allocation provides clear ownership semantics:
-    // - The BLEEvent owns the allocated memory for its lifetime
-    // - The data remains valid from the BLE callback context until processed in the main loop
-    // - Without this copy, we'd have use-after-free bugs as ESP-IDF reuses the callback memory
-    this->event_.gattc.gattc_param = new esp_ble_gattc_cb_param_t(*p);
+    // Copy param struct inline (no heap allocation!)
+    // GATTC/GATTS events are rare (<1% of events) but we can still store them inline
+    // along with small data payloads, eliminating all heap allocations for typical BLE operations
+    // CRITICAL: This copy is REQUIRED for memory safety - the ESP-IDF param pointer
+    // is only valid during the callback and will be reused/freed after we return
+    this->event_.gattc.gattc_param = *p;
 
     // Copy data for events that need it
     // The param struct contains pointers (e.g., notify.value) that point to temporary buffers.
     // We must copy this data to ensure it remains valid when the event is processed later.
     switch (e) {
       case ESP_GATTC_NOTIFY_EVT:
-        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();
+        copy_data_with_inline_storage_<decltype(this->event_.gattc), GATTC_INLINE_DATA_SIZE>(
+            this->event_.gattc, p->notify.value, p->notify.value_len, &this->event_.gattc.gattc_param.notify.value);
         break;
       case ESP_GATTC_READ_CHAR_EVT:
       case ESP_GATTC_READ_DESCR_EVT:
-        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();
+        copy_data_with_inline_storage_<decltype(this->event_.gattc), GATTC_INLINE_DATA_SIZE>(
+            this->event_.gattc, p->read.value, p->read.value_len, &this->event_.gattc.gattc_param.read.value);
         break;
       default:
-        this->event_.gattc.data = nullptr;
+        this->event_.gattc.is_inline = false;
+        this->event_.gattc.data.heap_data = nullptr;
+        this->event_.gattc.data_len = 0;
         break;
     }
   }
@@ -357,30 +412,33 @@ class BLEEvent {
     this->event_.gatts.gatts_if = i;
 
     if (p == nullptr) {
-      this->event_.gatts.gatts_param = nullptr;
-      this->event_.gatts.data = nullptr;
+      // Zero out the param struct when null
+      memset(&this->event_.gatts.gatts_param, 0, sizeof(this->event_.gatts.gatts_param));
+      this->event_.gatts.is_inline = false;
+      this->event_.gatts.data.heap_data = nullptr;
+      this->event_.gatts.data_len = 0;
       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
-    // IMPORTANT: This heap allocation provides clear ownership semantics:
-    // - The BLEEvent owns the allocated memory for its lifetime
-    // - The data remains valid from the BLE callback context until processed in the main loop
-    // - Without this copy, we'd have use-after-free bugs as ESP-IDF reuses the callback memory
-    this->event_.gatts.gatts_param = new esp_ble_gatts_cb_param_t(*p);
+    // Copy param struct inline (no heap allocation!)
+    // GATTC/GATTS events are rare (<1% of events) but we can still store them inline
+    // along with small data payloads, eliminating all heap allocations for typical BLE operations
+    // CRITICAL: This copy is REQUIRED for memory safety - the ESP-IDF param pointer
+    // is only valid during the callback and will be reused/freed after we return
+    this->event_.gatts.gatts_param = *p;
 
     // Copy data for events that need it
     // The param struct contains pointers (e.g., write.value) that point to temporary buffers.
     // We must copy this data to ensure it remains valid when the event is processed later.
     switch (e) {
       case ESP_GATTS_WRITE_EVT:
-        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();
+        copy_data_with_inline_storage_<decltype(this->event_.gatts), GATTS_INLINE_DATA_SIZE>(
+            this->event_.gatts, p->write.value, p->write.len, &this->event_.gatts.gatts_param.write.value);
         break;
       default:
-        this->event_.gatts.data = nullptr;
+        this->event_.gatts.is_inline = false;
+        this->event_.gatts.data.heap_data = nullptr;
+        this->event_.gatts.data_len = 0;
         break;
     }
   }
@@ -390,12 +448,20 @@ class BLEEvent {
 // The gap member in the union should be 80 bytes (including the gap_event enum)
 static_assert(sizeof(decltype(((BLEEvent *) nullptr)->event_.gap)) <= 80, "gap_event struct has grown beyond 80 bytes");
 
+// Verify GATTC and GATTS structs don't exceed GAP struct size
+// This ensures the union size is determined by GAP (the most common event type)
+static_assert(sizeof(decltype(((BLEEvent *) nullptr)->event_.gattc)) <=
+                  sizeof(decltype(((BLEEvent *) nullptr)->event_.gap)),
+              "gattc_event struct exceeds gap_event size - union size would increase");
+static_assert(sizeof(decltype(((BLEEvent *) nullptr)->event_.gatts)) <=
+                  sizeof(decltype(((BLEEvent *) nullptr)->event_.gap)),
+              "gatts_event struct exceeds gap_event size - union size would increase");
+
 // Verify esp_ble_sec_t fits within our union
 static_assert(sizeof(esp_ble_sec_t) <= 73, "esp_ble_sec_t is larger than BLEScanResult");
 
 // BLEEvent total size: 84 bytes (80 byte union + 1 byte type + 3 bytes padding)
 
-}  // namespace esp32_ble
-}  // namespace esphome
+}  // namespace esphome::esp32_ble
 
 #endif

esphome/components/esp32_ble/ble_scan_result.h

@@ -4,8 +4,7 @@
 
 #include <esp_gap_ble_api.h>
 
-namespace esphome {
-namespace esp32_ble {
+namespace esphome::esp32_ble {
 
 // Structure for BLE scan results - only fields we actually use
 struct __attribute__((packed)) BLEScanResult {
@@ -18,7 +17,6 @@ struct __attribute__((packed)) BLEScanResult {
   uint8_t search_evt;
 };  // ~73 bytes vs ~400 bytes for full esp_ble_gap_cb_param_t
 
-}  // namespace esp32_ble
-}  // namespace esphome
+}  // namespace esphome::esp32_ble
 
 #endif

esphome/components/esp32_ble/ble_uuid.cpp

@@ -1,14 +1,14 @@
 #include "ble_uuid.h"
 
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_UUID
 
 #include <cstring>
 #include <cstdio>
 #include <cinttypes>
 #include "esphome/core/log.h"
 
-namespace esphome {
-namespace esp32_ble {
+namespace esphome::esp32_ble {
 
 static const char *const TAG = "esp32_ble";
 
@@ -189,7 +189,7 @@ std::string ESPBTUUID::to_string() const {
   return "";
 }
 
-}  // namespace esp32_ble
-}  // namespace esphome
+}  // namespace esphome::esp32_ble
 
-#endif
+#endif  // USE_ESP32_BLE_UUID
+#endif  // USE_ESP32

esphome/components/esp32_ble/ble_uuid.h

@@ -1,15 +1,16 @@
 #pragma once
 
+#include "esphome/core/defines.h"
 #include "esphome/core/hal.h"
 #include "esphome/core/helpers.h"
 
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_UUID
 
 #include <string>
 #include <esp_bt_defs.h>
 
-namespace esphome {
-namespace esp32_ble {
+namespace esphome::esp32_ble {
 
 class ESPBTUUID {
  public:
@@ -41,7 +42,7 @@ class ESPBTUUID {
   esp_bt_uuid_t uuid_;
 };
 
-}  // namespace esp32_ble
-}  // namespace esphome
+}  // namespace esphome::esp32_ble
 
-#endif
+#endif  // USE_ESP32_BLE_UUID
+#endif  // USE_ESP32

esphome/components/esp32_ble_beacon/__init__.py

@@ -65,6 +65,8 @@ FINAL_VALIDATE_SCHEMA = esp32_ble.validate_variant
 
 
 async def to_code(config):
+    cg.add_define("USE_ESP32_BLE_UUID")
+
     uuid = config[CONF_UUID].hex
     uuid_arr = [
         cg.RawExpression(f"0x{uuid[i : i + 2]}") for i in range(0, len(uuid), 2)
@@ -82,6 +84,8 @@ async def to_code(config):
     cg.add(var.set_measured_power(config[CONF_MEASURED_POWER]))
     cg.add(var.set_tx_power(config[CONF_TX_POWER]))
 
+    cg.add_define("USE_ESP32_BLE_ADVERTISING")
+
     if CORE.using_esp_idf:
         add_idf_sdkconfig_option("CONFIG_BT_ENABLED", True)
         add_idf_sdkconfig_option("CONFIG_BT_BLE_42_FEATURES_SUPPORTED", True)

esphome/components/esp32_ble_client/__init__.py

@@ -2,7 +2,7 @@ import esphome.codegen as cg
 from esphome.components import esp32_ble_tracker
 
 AUTO_LOAD = ["esp32_ble_tracker"]
-CODEOWNERS = ["@jesserockz"]
+CODEOWNERS = ["@jesserockz", "@bdraco"]
 DEPENDENCIES = ["esp32"]
 
 esp32_ble_client_ns = cg.esphome_ns.namespace("esp32_ble_client")

esphome/components/esp32_ble_client/ble_characteristic.cpp

@@ -5,9 +5,9 @@
 #include "esphome/core/log.h"
 
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_DEVICE
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 static const char *const TAG = "esp32_ble_client";
 
@@ -93,7 +93,7 @@ esp_err_t BLECharacteristic::write_value(uint8_t *new_val, int16_t new_val_size)
   return write_value(new_val, new_val_size, ESP_GATT_WRITE_TYPE_NO_RSP);
 }
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
+#endif  // USE_ESP32_BLE_DEVICE
 #endif  // USE_ESP32

esphome/components/esp32_ble_client/ble_characteristic.h

@@ -1,6 +1,9 @@
 #pragma once
 
+#include "esphome/core/defines.h"
+
 #ifdef USE_ESP32
+#ifdef USE_ESP32_BLE_DEVICE
 
 #include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
 
@@ -8,8 +11,7 @@
 
 #include <vector>
 
-namespace esphome {
-namespace esp32_ble_client {
+namespace esphome::esp32_ble_client {
 
 namespace espbt = esphome::esp32_ble_tracker;
 
@@ -33,7 +35,7 @@ class BLECharacteristic {
   BLEService *service;
 };
 
-}  // namespace esp32_ble_client
-}  // namespace esphome
+}  // namespace esphome::esp32_ble_client
 
+#endif  // USE_ESP32_BLE_DEVICE
 #endif  // USE_ESP32