十六 Home Assistant 蓝牙 Api

最新推荐文章于 2025-02-20 11:54:12 发布

道古云飞

最新推荐文章于 2025-02-20 11:54:12 发布

阅读量1k

点赞数 17

分类专栏： Home Assistant 集成文章标签： python 智能家居

本文链接：https://blog.youkuaiyun.com/tre4321/article/details/144377392

版权

Home Assistant 集成专栏收录该内容

27 篇文章

订阅专栏

蓝牙API

订阅蓝牙发现

某些集成可能需要立即知晓设备何时被发现。蓝牙集成提供了一个注册API，当发现与特定键值匹配的新设备时会接收回调。使用 manifest.json 中 bluetooth 的相同格式进行匹配。除了 manifest.json 中使用的匹配器外，address 也可用作匹配器。

提供了 bluetooth.async_register_callback 函数来启用此功能。该函数返回一个回调，调用时将取消注册。

以下示例展示了在Switchbot设备在附近时注册以获取回调：

from homeassistant.components import bluetooth
...
@callback
def _async_discovered_device(service_info: bluetooth.BluetoothServiceInfoBleak, change: bluetooth.BluetoothChange) -> None:
    """订阅蓝牙变化。"""
    _LOGGER.warning("新的服务信息: %s", service_info)
entry.async_on_unload(
    bluetooth.async_register_callback(
        hass, _async_discovered_device, {"service_uuid": "cba20d00 - 224d - 11e6 - 9fb8 - 0002a5d5c51b", "connectable": False}, bluetooth.BluetoothScanningMode.ACTIVE
    )
)

以下示例展示了为HomeKit设备注册以获取回调：

from homeassistant.components import bluetooth
...
entry.async_on_unload(
    bluetooth.async_register_callback(
        hass, _async_discovered_homekit_device, {"manufacturer_id": 76, "manufacturer_data_first_byte": 6}, bluetooth.BluetoothScanningMode.ACTIVE
    )
)

以下示例展示了为Nespresso Prodigios注册以获取回调：

from homeassistant.components import bluetooth
...
entry.async_on_unload(
    bluetooth.async_register_callback(
        hass, _async_nespresso_found, {"local_name": "Prodigio_*"}, bluetooth.BluetoothScanningMode.ACTIVE
    )
)

以下示例展示了为地址为 44:33:11:22:33:22 的设备注册以获取回调：

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"}, bluetooth.BluetoothScanningMode.ACTIVE
    )
)

获取共享的BleakScanner实例

需要 BleakScanner 实例的集成应调用 bluetooth.async_get_scanner API。此API返回单个 BleakScanner 的包装器，允许集成共享而不会使系统过载。

from homeassistant.components import bluetooth
scanner = bluetooth.async_get_scanner(hass)

确定扫描器是否正在运行

蓝牙集成可能已设置，但没有可连接的适配器或遥控器。bluetooth.async_scanner_count API可用于确定是否有正在运行的扫描器能够接收广播或生成可用于连接设备的 BLEDevice。如果没有扫描器能够生成可连接的 BLEDevice 对象，集成可能希望在设置期间引发更有用的错误。

from homeassistant.components import bluetooth
count = bluetooth.async_scanner_count(hass, connectable=True)

订阅不可用回调

要在蓝牙堆栈无法再看到设备时获取回调，请调用 bluetooth.async_track_unavailable API。出于性能原因，一旦设备不再可见，可能需要长达五分钟才能获得回调。

如果 connectable 参数设置为 True，如果任何可连接的控制器能够到达设备，则该设备将被视为可用。如果只有不可连接的控制器能够到达设备，则该设备将被视为不可用。如果该参数设置为 False，则只要任何控制器能够看到该设备，该设备就将被视为可用。

from homeassistant.components import bluetooth
def _unavailable_callback(info: bluetooth.BluetoothServiceInfoBleak) -> None:
    _LOGGER.debug("%s不再可见", info.address)
cancel = bluetooth.async_track_unavailable(hass, _unavailable_callback, "44:44:33:11:23:42", connectable=True)

查明可用性超时

可用性基于设备上次已知广播以来的时间。此超时是根据设备的常规广播模式自动学习的。可以使用 bluetooth.async_get_learned_advertising_interval API查明此超时。

from homeassistant.components import bluetooth
learned_interval = bluetooth.async_get_learned_advertising_interval(hass, "44:44:33:11:23:42")

如果广告间隔尚不清楚，这将返回 None。在这种情况下，不可用性跟踪将尝试该地址的回退间隔。以下示例返回由集成手动设置的间隔：

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")

如果设备没有学习到的间隔或回退间隔，则使用硬编码的安全默认间隔：

from homeassistant.components import bluetooth
default_fallback_interval = bluetooth.FALLBACK_MAXIMUM_STALE_ADVERTISEMENT_SECONDS

从地址获取bleak `BLEDevice`

集成应通过调用 bluetooth.async_ble_device_from_address API来避免启动额外扫描器以解析地址的开销，该API返回可到达设备的最近配置的 bluetooth 适配器的 BLEDevice。如果没有适配器能够到达设备，bluetooth.async_ble_device_from_address API将返回 None。

假设集成希望从可连接和不可连接的控制器接收数据。在这种情况下，只要至少有一个可连接的控制器在范围内，它就可以在想要进行传出连接时将 BLEDevice 替换为可连接的设备。

from homeassistant.components import bluetooth
ble_device = bluetooth.async_ble_device_from_address(hass, "44:44:33:11:23:42", connectable=True)

获取设备的最新 `BluetoothServiceInfoBleak`

最新的广告和设备数据可通过 bluetooth.async_last_service_info API获取，该API从具有最佳RSSI（接收信号强度指示）的请求可连接类型的扫描器返回 BluetoothServiceInfoBleak。

from homeassistant.components import bluetooth
service_info = bluetooth.async_last_service_info(hass, "44:44:33:11:23:42", connectable=True)

检查设备是否存在

要确定设备是否仍然存在，请调用 bluetooth.async_address_present API。如果您的集成需要设备存在才能将其视为可用，此调用很有用。

from homeassistant.components import bluetooth
bluetooth.async_address_present(hass, "44:44:33:11:23:42", connectable=True)

获取所有已发现的设备

要访问先前发现的设备列表，请调用 bluetooth.async_discovered_service_info API。只有仍然存在的设备才会在缓存中。

from homeassistant.components import bluetooth
service_infos = bluetooth.async_discovered_service_info(hass, connectable=True)

获取每个蓝牙适配器的所有已发现设备和广告数据

要独立访问每个适配器接收到的先前发现的设备列表和广告数据，请调用 bluetooth.async_scanner_devices_by_address API。该调用返回 BluetoothScannerDevice 对象列表。同一设备和广告数据可能会多次出现，每个到达它的蓝牙适配器出现一次。

from homeassistant.components import bluetooth
device = bluetooth.async_scanner_devices_by_address(hass, "44:44:33:11:23:42", connectable=True)
# device.ble_device是一个bleak `BLEDevice`
# device.advertisement是一个bleak `AdvertisementData`
# device.scanner是发现设备的扫描器

触发设备重新发现

当从Home Assistant中删除配置项或设备时，触发其地址的重新发现，以确保无需重新启动Home Assistant即可对其进行设置。如果您的集成每个配置项管理多个设备，则可以利用设备注册表的蓝牙连接属性。

from homeassistant.components import bluetooth
bluetooth.async_rediscover_address(hass, "44:44:33:11:23:42")

等待特定广告

要等待特定广告，请调用 bluetooth.async_process_advertisements API。

from homeassistant.components import bluetooth
def _process_more_advertisements(
    service_info: BluetoothServiceInfoBleak,
) -> bool:
    """等待制造商数据中包含323的广告。"""
    return 323 in service_info.manufacturer_data
service_info = await bluetooth.async_process_advertisements(
    hass,
    _process_more_advertisements,
    {"address": discovery_info.address, "connectable": False},
    BluetoothScanningMode.ACTIVE,
    ADDITIONAL_DISCOVERY_TIMEOUT
)

注册外部扫描器

提供蓝牙适配器的集成应在其 manifest.json 的 dependencies 中添加 bluetooth，并将其添加到 bluetooth_adapters 集成的 after_dependencies 中。

要注册外部扫描器，请调用 bluetooth.async_register_scanner API。扫描器必须继承自 BaseHaScanner。

如果扫描器需要连接槽管理以避免使适配器过载，请通过 connection_slots 参数传递连接槽的整数值。

from homeassistant.components import bluetooth
cancel = bluetooth.async_register_scanner(hass, scanner, connection_slots=slots)

扫描器需要以 BluetoothServiceInfoBleak 对象的形式将广告数据提供给中央蓝牙管理器。将数据发送到中央管理器所需的回调可以通过 bluetooth.async_get_advertisement_callback API获取。

callback = bluetooth.async_get_advertisement_callback(hass)
callback(BluetoothServiceInfoBleak(...))

总结

此文档主要介绍了Home Assistant中蓝牙API的相关功能及使用方法。涵盖了订阅蓝牙发现、获取共享扫描器实例、确定扫描器运行状态、订阅不可用回调、查明可用性超时、获取设备相关信息（如BLEDevice、最新服务信息、设备存在状态、所有已发现设备等）、触发设备重新发现、等待特定广告以及注册外部扫描器等操作的API使用方式，为开发者在Home Assistant中进行蓝牙设备相关的集成开发提供了详细的接口说明和操作指导，有助于开发者更高效地利用蓝牙功能与设备进行交互。