From 9bbdee9f5498e2873fc4c0cc247b19c0e0e762ed Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Mon, 11 Jul 2022 17:14:05 +0200 Subject: [PATCH] Update bluetooth for additional matchers and API calls (#1398) Co-authored-by: Franck Nijhof --- docs/network_discovery.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/network_discovery.md b/docs/network_discovery.md index 083c8576..9ba99578 100644 --- a/docs/network_discovery.md +++ b/docs/network_discovery.md @@ -11,7 +11,7 @@ Home Assistant has built-in helpers to support mDNS/Zeroconf and SSDP. If your i ### Subscribing to Bluetooth discoveries -Some integrations may need to know when a device is discovered right away. The Bluetooth integration provides a registration API to receive callbacks when a new device is discovered that matches specific key values. The same format for `bluetooth` in [`manifest.json`](creating_integration_manifest.md#bluetooth) is used for matching. +Some integrations may need to know when a device is discovered right away. The Bluetooth integration provides a registration API to receive callbacks when a new device is discovered that matches specific key values. The same format for `bluetooth` in [`manifest.json`](creating_integration_manifest.md#bluetooth) is used for matching. In addition to the matchers used in the `manifest.json`, `address` can also be used as a matcher. The function `bluetooth.async_register_callback` is provided to enable this ability. The function returns a callback that will cancel the registration when called. @@ -62,6 +62,42 @@ entry.async_on_unload( ) ``` + +The below example shows registering to get callbacks for a device with the address `44:33:11:22:33:22`. + +```python +from homeassistant.components import bluetooth + +... + +entry.async_on_unload( + bluetooth.async_register_callback( + hass, _async_specific_device_found, {"address": "44:33:11:22:33:22")} + ) +) +``` + +### Checking if a device is present + +To determine if a device is still present, call the `bluetooth.async_address_present` API. This call is helpful if your integration needs the device to be present to consider it available. As this call can be expensive with many devices, we recommend only calling it every five minutes. + +```python +from homeassistant.components import bluetooth + +bluetooth.async_address_present(hass, "44:44:33:11:23:42") +``` + +### Fetching all discovered devices + +To access the list of previous discoveries, call the `bluetooth.async_discovered_service_info` API. Only devices that are still present will be in the cache. + +```python +from homeassistant.components import bluetooth + +service_infos = bluetooth.async_discovered_service_info(hass) +``` + + ## mDNS/Zeroconf Home Assistant uses the [python-zeroconf](https://github.com/jstasiak/python-zeroconf) package for mDNS support. As running multiple mDNS implementations on a single host is not recommended, Home Assistant provides internal helper APIs to access the running `Zeroconf` and `AsyncZeroconf` instances.