jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-19 07:16:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add new bluetooth APIs for working with unavailability timeout (#1935)

Browse Source 
Co-authored-by: J. Nick Koston <nick@koston.org>
This commit is contained in:
Jc2k 2023-09-24 09:45:41 +01:00 committed by GitHub
parent 6a3c7e9e8c
commit a22a591cac
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/core/bluetooth/api.md
View File

@ -105,6 +105,35 @@ def _unavailable_callback(info: bluetooth.BluetoothServiceInfoBleak) -> None:
cancel = bluetooth.async_track_unavailable(hass, _unavailable_callback, "44:44:33:11:23:42", connectable=True)
```
### Finding out the availability timeout
Availability is based on the time since the device's last known broadcast. This timeout is learned automatically based on the device's regular broadcasting pattern. You can find out this with the `bluetooth.async_get_learned_advertising_interval` API.
```python
from homeassistant.components import bluetooth
learned_interval = bluetooth.async_get_learned_advertising_interval(hass, "44:44:33:11:23:42")
```
If the advertising interval is not yet known, this will return `None`. In that case, unavailability tracking will try the fallback interval for that address. The below example returns the interval that has been set manually by an integration:
```python
from homeassistant.components import bluetooth
bluetooth.async_set_fallback_availability_interval(hass, "44:44:33:11:23:42", 64.0)
fallback_interval = bluetooth.async_get_fallback_availability_interval(hass, "44:44:33:11:23:42")
```
If there is no learned interval or fallback interval for the device, a hardcoded safe default interval is used:
```python
from homeassistant.components import bluetooth
default_fallback_interval = bluetooth.FALLBACK_MAXIMUM_STALE_ADVERTISEMENT_SECONDS
```
### Fetching the bleak `BLEDevice` from the `address`
Integrations should avoid the overhead of starting an additional scanner to resolve the address by calling the `bluetooth.async_ble_device_from_address` API, which returns a `BLEDevice` for the nearest configured `bluetooth` adapter that can reach the device. If no adapters can reach the device, the `bluetooth.async_ble_device_from_address` API, will return `None`.