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-04-19 10:57:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update instructions for integrations that use bluetooth adapters (#1624)

Browse Source
This commit is contained in:
J. Nick Koston 2023-01-16 00:17:25 -10:00 committed by GitHub
parent bde1a15808
commit bb182b3c9a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 16 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
blog/2023-01-12-bluetooth-adapters.md Normal file
View File

@ -0,0 +1,11 @@
---
author: J. Nick Koston
authorURL: https://github.com/bdraco
title: "Bluetooth updates for 2023.2 and later"
---
Integrations that need to use a Bluetooth adapter should add `bluetooth_adapters` in [`dependencies`](/docs/creating_integration_manifest#dependencies) in their [`manifest.json`](/docs/creating_integration_manifest). The [`manifest.json`](/docs/creating_integration_manifest) entry ensures that all supported remote adapters are connected before the integration tries to use them. This replaces the need to add `bluetooth` in [`dependencies`](/docs/creating_integration_manifest#dependencies).
Integrations that provide a Bluetooth adapter should add `bluetooth` in [`dependencies`](/docs/creating_integration_manifest#dependencies) in their [`manifest.json`](/docs/creating_integration_manifest) and be added to [`after_dependencies`](/docs/creating_integration_manifest#after-dependencies) to the `bluetooth_adapters` integration.
Be sure to check out [Best practices for integration authors](/docs/bluetooth/#best-practices-for-integration-authors) when building new Bluetooth integrations.

6
docs/bluetooth.md
View File

@ -5,6 +5,8 @@ sidebar_label: "Bluetooth"
### Best practices for integration authors
- Integrations that need to use a Bluetooth adapter should add `bluetooth_adapters` in [`dependencies`](creating_integration_manifest#dependencies) in their [`manifest.json`](creating_integration_manifest). The [`manifest.json`](creating_integration_manifest) entry ensures that all supported remote adapters are connected before the integration tries to use them.
- When connecting to Bluetooth devices with `BleakClient`, always use the `BLEDevice` object instead of the `address` to avoid the client starting a scanner to find the `BLEDevice`. Call the `bluetooth.async_ble_device_from_address` API if you only have the `address`.
- Call the `bluetooth.async_get_scanner` API to get a `BleakScanner` instance and pass it to your library. The returned scanner avoids the overhead of running multiple scanners, which is significant. Additionally, the wrapped scanner will continue functioning if the user changes the Bluetooth adapter settings.
@ -23,7 +25,7 @@ The default value for `connectable` is `True`. If the integration has some devic
### 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. In addition to the matchers used in the `manifest.json`, `address` can also be used as a matcher.
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#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.
@ -214,6 +216,8 @@ service_info = await bluetooth.async_process_advertisements(
### Registering an external scanner
Integrations that provide a Bluetooth adapter should add `bluetooth` in [`dependencies`](creating_integration_manifest#dependencies) in their [`manifest.json`](creating_integration_manifest) and be added to [`after_dependencies`](creating_integration_manifest#after-dependencies) to the `bluetooth_adapters` integration.
To register an external scanner, call the `bluetooth.async_register_scanner` API. The scanner must inherit from `BaseHaScanner`.
```python