Add Bluetooth API to clear address from match history (home-assistant#154355)

Author: bdraco

homeassistant/components/bluetooth/__init__.py

@@ -57,6 +57,7 @@
     _get_manager,
     async_address_present,
     async_ble_device_from_address,
+    async_clear_address_from_match_history,
     async_current_scanners,
     async_discovered_service_info,
     async_get_advertisement_callback,
@@ -115,6 +116,7 @@
     "HomeAssistantRemoteScanner",
     "async_address_present",
     "async_ble_device_from_address",
+    "async_clear_address_from_match_history",
     "async_current_scanners",
     "async_discovered_service_info",
     "async_get_advertisement_callback",

homeassistant/components/bluetooth/api.py

@@ -193,6 +193,20 @@ def async_rediscover_address(hass: HomeAssistant, address: str) -> None:
     _get_manager(hass).async_rediscover_address(address)
 
 
+@hass_callback
+def async_clear_address_from_match_history(hass: HomeAssistant, address: str) -> None:
+    """Clear an address from the integration matcher history.
+
+    This allows future advertisements from this address to trigger discovery
+    even if the advertisement content has changed but the service data UUIDs
+    remain the same.
+
+    Unlike async_rediscover_address, this does not immediately re-trigger
+    discovery with the current advertisement in history.
+    """
+    _get_manager(hass).async_clear_address_from_match_history(address)
+
+
 @hass_callback
 def async_register_scanner(
     hass: HomeAssistant,

homeassistant/components/bluetooth/manager.py

@@ -120,6 +120,19 @@ def async_rediscover_address(self, address: str) -> None:
         if service_info := self._all_history.get(address):
             self._async_trigger_matching_discovery(service_info)
 
+    @hass_callback
+    def async_clear_address_from_match_history(self, address: str) -> None:
+        """Clear an address from the integration matcher history.
+
+        This allows future advertisements from this address to trigger discovery
+        even if the advertisement content has changed but the service data UUIDs
+        remain the same.
+
+        Unlike async_rediscover_address, this does not immediately re-trigger
+        discovery with the current advertisement in history.
+        """
+        self._integration_matcher.async_clear_address(address)
+
     def _discover_service_info(self, service_info: BluetoothServiceInfoBleak) -> None:
         matched_domains = self._integration_matcher.match_domains(service_info)
         if self._debug:

tests/components/bluetooth/test_init.py

@@ -19,6 +19,7 @@
     BluetoothScanningMode,
     BluetoothServiceInfo,
     HaBluetoothConnector,
+    async_clear_address_from_match_history,
     async_process_advertisements,
     async_rediscover_address,
     async_track_unavailable,
@@ -1175,6 +1176,61 @@ async def test_rediscovery(
         assert mock_config_flow.mock_calls[1][1][0] == "switchbot"
 
 
+@pytest.mark.usefixtures("enable_bluetooth")
+async def test_clear_address_from_match_history(
+    hass: HomeAssistant, mock_bleak_scanner_start: MagicMock
+) -> None:
+    """Test clearing match history without re-triggering discovery."""
+    mock_bt = [
+        {"domain": "switchbot", "service_uuid": "cba20d00-224d-11e6-9fb8-0002a5d5c51b"}
+    ]
+    with (
+        patch(
+            "homeassistant.components.bluetooth.async_get_bluetooth",
+            return_value=mock_bt,
+        ),
+        patch.object(hass.config_entries.flow, "async_init") as mock_config_flow,
+    ):
+        await async_setup_with_default_adapter(hass)
+        hass.bus.async_fire(EVENT_HOMEASSISTANT_STARTED)
+        await hass.async_block_till_done()
+
+        assert len(mock_bleak_scanner_start.mock_calls) == 1
+
+        switchbot_device = generate_ble_device("44:44:33:11:23:45", "wohand")
+        switchbot_adv = generate_advertisement_data(
+            local_name="wohand", service_uuids=["cba20d00-224d-11e6-9fb8-0002a5d5c51b"]
+        )
+        switchbot_adv_2 = generate_advertisement_data(
+            local_name="wohand",
+            service_uuids=["cba20d00-224d-11e6-9fb8-0002a5d5c51b"],
+            manufacturer_data={1: b"\x01"},
+        )
+        inject_advertisement(hass, switchbot_device, switchbot_adv)
+        await hass.async_block_till_done()
+
+        inject_advertisement(hass, switchbot_device, switchbot_adv)
+        await hass.async_block_till_done()
+
+        assert len(mock_config_flow.mock_calls) == 1
+        assert mock_config_flow.mock_calls[0][1][0] == "switchbot"
+
+        # Clear match history - should NOT trigger immediate rediscovery
+        async_clear_address_from_match_history(hass, "44:44:33:11:23:45")
+        await hass.async_block_till_done()
+
+        # No new discovery should have been triggered
+        assert len(mock_config_flow.mock_calls) == 1
+
+        # But when we inject new advertisement with different data, it should be discovered
+        inject_advertisement(hass, switchbot_device, switchbot_adv_2)
+        await hass.async_block_till_done()
+
+        # Now discovery should happen because history was cleared and data changed
+        assert len(mock_config_flow.mock_calls) == 2
+        assert mock_config_flow.mock_calls[1][1][0] == "switchbot"
+
+
 @pytest.mark.usefixtures("macos_adapter")
 async def test_async_discovered_device_api(
     hass: HomeAssistant, mock_bleak_scanner_start: MagicMock