bluez-外设

文档

派皮

GitHub

bluez-peripheral 是一个库，用于使用 Bluez (Linux) GATT API 构建低功耗蓝牙 (BLE) 外设/服务器。

这个图书馆是为谁准备的

• 使用 Python 和 Linux（和 Bluez）的开发人员。
• 希望开发蓝牙兼容的外围设备（即其他设备连接的东西）。
• 具有低带宽要求（即不流式传输音频）。

安装

安装 bluez（例如sudo apt-get install bluez）

pip install bluez-peripheral

关贸总协定概述

GATT 是一种 BLE 协议，允许您向其他设备提供服务。您可以在Bluetooth SIG 网站上找到标准化服务列表（使用 BLE 时您可以在很大程度上忽略配置文件）。为了这个库的目的，您应该参考这些规范中的“服务特性”。

感谢 Qt 文档（GNU 自由文档许可证）

外围设备定义了它提供的服务列表。服务是公开特定数据（例如心率或鼠标位置）的特征的集合。特性也可能具有包含元数据的描述符（例如特性的单位）。服务可以选择性地包括其他服务。所有 BLE 属性（服务、特性和描述符）都由蓝牙 SIG 分配的 16 位数字标识。

特性可以根据其用途以多种模式运行。默认情况下，特性在这个库中是只读的，但是它们也可以是可写的，并在它们的值发生变化时提供通知（如事件系统）。此外，某些特性需要安全保护。您可以在蓝牙 SIG 博客上阅读有关 BLE 的更多信息。

用法

使用此库时，您需要记住一些重要的事情：

• 不要尝试创建通用访问服务或客户端特征配置描述符（如果您不知道这意味着什么，请不要担心）。这些都由 Bluez 自动处理，尝试定义它们将导致错误。
• 服务不是隐式线程化的。如果您在主线程中注册一个服务，阻塞该线程将停止您的服务（尤其是通知）工作。因此，您必须经常屈服于 asyncio 事件循环（例如使用 asyncio.sleep）并最好使用多线程。

使用该库的最简单方法是创建一个描述您希望提供的服务的类。

from bluez_peripheral.gatt.service import Service
from bluez_peripheral.gatt.characteristic import characteristic, CharacteristicFlags as CharFlags

import struct

class HeartRateService(Service):
    def __init__(self):
        # Base 16 service UUID, This should be a primary service.
        super().__init__("180D", True)

    @characteristic("2A37", CharFlags.NOTIFY)
    def heart_rate_measurement(self, options):
        # This function is called when the characteristic is read.
        # Since this characteristic is notify only this function is a placeholder.
        # You don't need this function Python 3.9+ (See PEP 614).
        # You can generally ignore the options argument 
        # (see Advanced Characteristics and Descriptors Documentation).
        pass

    def update_heart_rate(self, new_rate):
        # Call this when you get a new heartrate reading.
        # Note that notification is asynchronous (you must await something at some point after calling this).
        flags = 0

        # Bluetooth data is little endian.
        rate = struct.pack("<BB", flags, new_rate)
        self.heart_rate_measurement.changed(rate)

Bluez 使用 dbus 与 bluez-peripheral 接口以进行进程间通信。要让 Bluez 开始提供您的服务，它需要在此总线上进行注册。此外，如果您希望设备与您的设备配对，您需要注册一个代理来决定应该如何完成配对。最后，您还需要向附近的设备宣传该服务。

from bluez_peripheral.util import *
from bluez_peripheral.advert import Advertisement
from bluez_peripheral.agent import NoIoAgent
import asyncio

async def main():
    # Alternativly you can request this bus directly from dbus_next.
    bus = await get_message_bus()

    service = HeartRateService()
    await service.register(bus)

    # An agent is required to handle pairing 
    agent = NoIoAgent()
    # This script needs superuser for this to work.
    await agent.register(bus)

    adapter = await Adapter.get_first(bus)

    # Start an advert that will last for 60 seconds.
    advert = Advertisement("Heart Monitor", ["180D"], 0x0340, 60)
    await advert.register(bus, adapter)

    while True:
        # Update the heart rate.
        service.update_heart_rate(120)
        # Handle dbus requests.
        await asyncio.sleep(5)

    await bus.wait_for_disconnect()

if __name__ == "__main__":
    asyncio.run(main())

要与 bluez 通信，默认的 dbus 配置要求您属于蓝牙用户组（例如sudo useradd -aG bluetooth spacecheese）。有关更多示例，请阅读文档。