From 202b31f711653467aa3c0fb3b216ff7be3b8922f Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 5 Aug 2026 13:33:32 -0500 Subject: [PATCH] [ble_device_base] Deprecate address_str in favor of address_str_to (#18092) --- esphome/components/ble_device_base/ble_device.cpp | 3 ++- esphome/components/ble_device_base/ble_device.h | 3 ++- .../bk72xx_ble_tracker/config/test_automations.yaml | 2 +- .../ln882h_ble_tracker/config/test_automations.yaml | 2 +- .../validate-automations.bk72xx-ard.yaml | 6 ++++-- tests/components/ble_device_base/test_address.cpp | 9 ++++++++- tests/components/esp32_ble_tracker/common.yaml | 9 ++++++--- .../ln882h_ble_tracker/test-automations.ln882x-ard.yaml | 3 ++- 8 files changed, 26 insertions(+), 11 deletions(-) diff --git a/esphome/components/ble_device_base/ble_device.cpp b/esphome/components/ble_device_base/ble_device.cpp index 9c3e1d4397..2235c08598 100644 --- a/esphome/components/ble_device_base/ble_device.cpp +++ b/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)); diff --git a/esphome/components/ble_device_base/ble_device.h b/esphome/components/ble_device_base/ble_device.h index 2d2cb5796b..716bc026f2 100644 --- a/esphome/components/ble_device_base/ble_device.h +++ b/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 buf) const { diff --git a/tests/component_tests/bk72xx_ble_tracker/config/test_automations.yaml b/tests/component_tests/bk72xx_ble_tracker/config/test_automations.yaml index a60e7cca05..994855b782 100644 --- a/tests/component_tests/bk72xx_ble_tracker/config/test_automations.yaml +++ b/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 diff --git a/tests/component_tests/ln882h_ble_tracker/config/test_automations.yaml b/tests/component_tests/ln882h_ble_tracker/config/test_automations.yaml index 16a215f026..883d20b7ce 100644 --- a/tests/component_tests/ln882h_ble_tracker/config/test_automations.yaml +++ b/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 diff --git a/tests/components/bk72xx_ble_tracker/validate-automations.bk72xx-ard.yaml b/tests/components/bk72xx_ble_tracker/validate-automations.bk72xx-ard.yaml index 407d19e67d..e110369b0b 100644 --- a/tests/components/bk72xx_ble_tracker/validate-automations.bk72xx-ard.yaml +++ b/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. diff --git a/tests/components/ble_device_base/test_address.cpp b/tests/components/ble_device_base/test_address.cpp index 9e4bca4c57..f1eebcbfc1 100644 --- a/tests/components/ble_device_base/test_address.cpp +++ b/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 diff --git a/tests/components/esp32_ble_tracker/common.yaml b/tests/components/esp32_ble_tracker/common.yaml index 564cf1f6ea..9c880dbf1a 100644 --- a/tests/components/esp32_ble_tracker/common.yaml +++ b/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 diff --git a/tests/components/ln882h_ble_tracker/test-automations.ln882x-ard.yaml b/tests/components/ln882h_ble_tracker/test-automations.ln882x-ard.yaml index 3291ef9d8b..3cd3ce28b2 100644 --- a/tests/components/ln882h_ble_tracker/test-automations.ln882x-ard.yaml +++ b/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: