[ble_device_base] Deprecate address_str in favor of address_str_to (#18092)

esphome/components/ble_device_base/ble_device.cpp

@@ -129,7 +129,7 @@ void ESPBTDevice::parse_scan_rst(const esp32_ble::BLEScanResult &scan_result) {
   this->scan_result_ = &scan_result;
   // BLEScanResult's bda is most-significant octet first; the neutral ingest
   // takes the BLE controller (LSB-first) order, so reverse — address_uint64()/
-  // address_str() then produce exactly the historical esp32 values.
+  // address_str_to() then produce exactly the historical esp32 values.
   uint8_t mac_lsb_first[6];
   for (uint8_t i = 0; i < 6; i++)
     mac_lsb_first[i] = scan_result.bda[5 - i];
@@ -346,6 +346,7 @@ void ESPBTDevice::from_scan_result(const uint8_t *mac, int rssi, uint8_t addr_ty
 #endif  // ESPHOME_LOG_HAS_VERY_VERBOSE
 }
 
+// Remove before 2027.2.0
 std::string ESPBTDevice::address_str() const {
   char buf[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
   return std::string(this->address_str_to(buf));

esphome/components/ble_device_base/ble_device.h

@@ -172,8 +172,9 @@ class ESPBTDevice {
   static constexpr size_t MAC_ADDRESS_PRETTY_BUFFER_SIZE = esphome::MAC_ADDRESS_PRETTY_BUFFER_SIZE;
 
   /// Return MAC as "XX:XX:XX:XX:XX:XX" string.
+  ESPDEPRECATED("Use address_str_to() instead. Removed in 2027.2.0.", "2026.8.0")
   std::string address_str() const;
-  /// Buffer overload: writes "XX:XX:XX:XX:XX:XX\0" into buf (>= 18 bytes), returns buf.
+  /// Writes "XX:XX:XX:XX:XX:XX\0" into buf (>= MAC_ADDRESS_PRETTY_BUFFER_SIZE bytes), returns buf.
   const char *address_str_to(char *buf) const;
 #if defined(__cpp_lib_span)
   const char *address_str_to(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf) const {

tests/component_tests/bk72xx_ble_tracker/config/test_automations.yaml

@@ -20,7 +20,7 @@ bk72xx_ble_tracker:
         - AC:37:43:77:5F:4C
         - 11:22:33:44:55:66
       then:
-        - lambda: 'ESP_LOGD("t", "%s", x.address_str().c_str());'
+        - lambda: 'char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE]; ESP_LOGD("t", "%s", x.address_str_to(addr));'
   on_ble_service_data_advertise:
     - service_uuid: ABCDABCD-ABCD-ABCD-ABCD-ABCDABCDABCD
       mac_address: AC:37:43:77:5F:4C

tests/component_tests/ln882h_ble_tracker/config/test_automations.yaml

@@ -20,7 +20,7 @@ ln882h_ble_tracker:
         - AC:37:43:77:5F:4C
         - 11:22:33:44:55:66
       then:
-        - lambda: 'ESP_LOGD("t", "%s", x.address_str().c_str());'
+        - lambda: 'char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE]; ESP_LOGD("t", "%s", x.address_str_to(addr));'
   on_ble_service_data_advertise:
     - service_uuid: ABCDABCD-ABCD-ABCD-ABCD-ABCDABCDABCD
       mac_address: AC:37:43:77:5F:4C

tests/components/bk72xx_ble_tracker/validate-automations.bk72xx-ard.yaml

@@ -15,13 +15,15 @@ bk72xx_ble_tracker:
     - mac_address: AC:37:43:77:5F:4C
       then:
         - lambda: |-
-            ESP_LOGD("main", "The device address is %s", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address is %s", x.address_str_to(addr));
     - mac_address:
         - AC:37:43:77:5F:4C
         - AC:37:43:77:5F:4D
       then:
         - lambda: |-
-            ESP_LOGD("main", "The device address is %s", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address is %s", x.address_str_to(addr));
   on_ble_service_data_advertise:
     - service_uuid: ABCD
       # mac_address exercises the UUID triggers' set_address() codegen branch.

tests/components/ble_device_base/test_address.cpp

@@ -8,7 +8,7 @@ namespace esphome::ble_device_base::testing {
 
 // from_scan_result() ingests BLE controller order (LSB-first); the public
 // accessors must expose the historical esp32 semantics: address() in printable
-// (MSB-first) order, address_uint64() with byte 0 in the LSB, address_str()
+// (MSB-first) order, address_uint64() with byte 0 in the LSB, address_str_to()
 // printed MSB-first.
 namespace {
 // Device AA:BB:CC:DD:EE:FF — controller order delivers FF first.
@@ -25,7 +25,14 @@ TEST(BleDeviceAddress, AccessorsMatchEsp32Semantics) {
 
   EXPECT_EQ(device.address_uint64(), 0xAABBCCDDEEFFULL);
 
+  char buf[ESPBTDevice::MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+  EXPECT_STREQ(device.address_str_to(buf), "AA:BB:CC:DD:EE:FF");
+
+  // The deprecated wrapper must keep returning the same string until its 2027.2.0 removal.
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
   EXPECT_EQ(device.address_str(), "AA:BB:CC:DD:EE:FF");
+#pragma GCC diagnostic pop
 }
 
 // mac_lsb_first_to_uint64() packs the controller-order bytes a raw-advertisement

tests/components/esp32_ble_tracker/common.yaml

@@ -12,18 +12,21 @@ esp32_ble_tracker:
       then:
         # yamllint disable rule:line-length
         - lambda: !lambda |-
-            ESP_LOGD("main", "The device address (%s) exists in list", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address (%s) exists in list", x.address_str_to(addr));
         # yamllint enable rule:line-length
     - mac_address: AC:37:43:77:5F:4C
       then:
         # yamllint disable rule:line-length
         - lambda: !lambda |-
-            ESP_LOGD("main", "The device address is %s", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address is %s", x.address_str_to(addr));
         # yamllint enable rule:line-length
     - then:
         # yamllint disable rule:line-length
         - lambda: !lambda |-
-            ESP_LOGD("main", "The device address is %s", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address is %s", x.address_str_to(addr));
         # yamllint enable rule:line-length
   on_ble_service_data_advertise:
     - service_uuid: ABCD

tests/components/ln882h_ble_tracker/test-automations.ln882x-ard.yaml

@@ -16,7 +16,8 @@ ln882h_ble_tracker:
     - mac_address: AC:37:43:77:5F:4C
       then:
         - lambda: |-
-            ESP_LOGD("main", "The device address is %s", x.address_str().c_str());
+            char addr[MAC_ADDRESS_PRETTY_BUFFER_SIZE];
+            ESP_LOGD("main", "The device address is %s", x.address_str_to(addr));
   on_ble_service_data_advertise:
     - service_uuid: ABCD
       then: