Best practices for integration authors
Integrations that need to use a Bluetooth adapter should add
manifest.jsonentry 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
BLEDeviceobject instead of the
addressto avoid the client starting a scanner to find the
BLEDevice. Call the
bluetooth.async_ble_device_from_addressAPI if you only have the
bluetooth.async_get_scannerAPI to get a
BleakScannerinstance 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.
Avoid reusing a
BleakClientbetween connections since this will make connecting less reliable.
Fetch a new
bluetooth.async_ble_device_from_addressAPI each time a connection is made. Alternatively, register a callback with
bluetooth.async_register_callbackand replace a cached
BLEDeviceeach time a callback is received. The details of a
BLEDeviceobject may change due to a change in the active adapter or environment.
Use a connection timeout of at least ten (10) seconds as
BlueZmust resolve services when connecting to a new or updated device for the first time. Transient connection errors are frequent when connecting, and connections are not always successful on the first attempt. The
bleak-retry-connectorPyPI package can take the guesswork out of quickly and reliably establishing a connection to a device.
Connectable and non-connectable Bluetooth controllers
Home Assistant has support for remote Bluetooth controllers. Some controllers only support listening for advertisement data and do not support connecting to devices. Since many devices only need to receive advertisements, we have the concept of connectable devices and non-connectable devices. Suppose the device does not require an active connection. In that case, the
connectable argument should be set to
False to opt-in on receiving data from controllers that do not support making outgoing connections. When
connectable is set to
False, data from
connectable and non-connectable controllers will be provided.
The default value for
True. If the integration has some devices that require connections and some devices that do not, the
manifest.json should set the flag appropriately for the device. If it is impossible to construct a matcher to differentiate between similar devices, check the
connectable property in the config flow discovery
BluetoothServiceInfoBleak and reject flows for devices needing outgoing connections.