PyBluez2：Python 蓝牙开发的核心库
一、PyBluez2 简介
PyBluez2 是 Python 的开源蓝牙编程库，支持蓝牙 2.0+、BLE（低功耗蓝牙）和传统蓝牙协议栈的开发。它提供了对蓝牙硬件适配器的底层控制，适用于设备发现、配对、数据传输和服务解析等场景。其核心优势包括：
- 跨平台支持：兼容 Linux、Windows、macOS 系统
- 协议丰富性：支持 HID、SPP、L2CAP、GATT 等协议
- 简洁的 API：抽象底层复杂性，提供高层次的蓝牙操作接口
- 社区驱动：持续更新，修复蓝牙 5.0+ 新特性支持
二、安装指南
1. 系统要求
| 操作系统 | 版本要求 | 依赖库 |
|---|---|---|
| Linux | Ubuntu 20.04+/Debian 11+ | bluez >= 5.60 |
| Windows | 10/11 (64位) | Microsoft Bluetooth Stack |
| macOS | 10.15+ | CoreBluetooth.framework |
2. 安装步骤
Linux/macOS
# 使用 pip 安装最新版本
pip install pybluez2# 验证安装
python3 -c "import bluetooth; print(bluetooth.__version__)"Windows
# 下载预编译 wheel 文件（推荐）
https://github.com/pybluez/pybluez2/releases/download/v0.10.2/pybluez2‑0.10.2‑cp310‑cp311‑win_amd64.whl# 安装 wheel 文件
pip install pybluez2‑0.10.2‑cp310‑cp311‑win_amd64.whl三、基础使用指南
1. 初始化蓝牙适配器
import bluetooth# 获取所有蓝牙适配器名称
adapters = bluetooth.get_available_adapters()
print(f"Available adapters: {adapters}")# 使用第一个适配器（索引从0开始）
adapter_name = adapters[0]
adapter = bluetooth.BluetoothAdapter(adapter_name)
adapter.start()2. 设备发现
扫描附近设备
devices = adapter.discover_devices()
print(f"Found {len(devices)} devices:")
for addr, name in devices:print(f" {addr}: {name}")通过 UUID 过滤设备
uuids = [bluetooth.UUID('1101')] # HID 服务 UUID
devices = adapter.discover_devices_with_uuids(uuids)
print(f"Found HID devices: {devices}")3. 建立连接
传统蓝牙 SPP 连接
# 服务 UUID（示例：串口服务）
service_uuid = bluetooth.UUID('00001101')# 查找设备并连接
device_addr = "00:1A:5D:6B:3E:D1"
device = bluetooth.BluetoothDevice(device_addr)
device.connect(service_uuid)# 发送数据
device.send("Hello from PyBluez2!")BLE 连接（低功耗蓝牙）
# 扫描 BLE 设备
ble_devices = adapter.discover_ble_devices()
print(f"Found {len(ble_devices)} BLE devices.")# 连接设备
device_addr = "00:1A:5D:6B:3E:D1"
device = bluetooth.BluetoothDevice(device_addr)
device.connect()# 发现 GATT 服务
services = device.gatt_discover_services()
print(f"Services: {services}")# 读取特征值
service_uuid = bluetooth.UUID('00002a37') # 心率特征
characteristic = device.gatt_get_characteristic(service_uuid)
value = characteristic.read()
print(f"Heart Rate: {value.decode('utf-8')}")四、高级配置
1. 适配器配置
设置蓝牙电源模式
adapter.set_power_mode(bluetooth.PowerMode.POWER_OFF) # 关闭蓝牙
adapter.set_power_mode(bluetooth.PowerMode.POWER_ON) # 开启蓝牙启用发现模式
adapter.start_discovery()
adapter.stop_discovery()2. BLE 服务开发
定义自定义服务
from bluetooth import UUID, Service, Characteristicclass MyService(Service):uuid = UUID('12345678-1234-5678-1234-56789abcdeff')characteristics = [Characteristic(uuid=UUID('12345678-1234-5678-1234-56789abcdeff01'),properties=['read', 'write'])]注册服务到适配器
adapter.add_service(MyService())
adapter.start()3. 数据传输优化
使用 L2CAP 通道
# 创建 L2CAP 通道
channel = adapter.open_l2cap_channel(device_addr, psm=17)
channel.send(b"Data chunk")五、典型应用场景
1. 蓝牙设备控制
- 智能家居：控制蓝牙灯泡（发送 RGB 值）
- 穿戴设备：读取心率/步数数据
2. 工业自动化
- BLE 传感器网络：采集温度/湿度数据
- Modbus over BLE：与工业设备通信
3. 物联网网关
- 多设备聚合：同时连接 10+ BLE 设备并汇总数据
六、常见问题与解决方案
| 问题现象 | 解决方案 |
|---|---|
| 无法发现设备 | 检查蓝牙适配器是否开启并支持 HCI |
| 连接失败 | 确保设备处于配对模式（BLE 需主动配对） |
| 权限不足 | Linux 下需 sudo 或配置蓝牙权限 |
| 蓝牙 5.0 兼容性问题 | 使用最新版本 PyBluez2（>=0.10.0） |
七、学习资源
- 官方文档：https://github.com/pybluez/pybluez2
- API 参考：PyBluez — PyBluez master documentation
- 实战案例：https://github.com/pybluez/pybluez2/tree/main/examples
结语
PyBluez2 是 Python 生态中不可或缺的蓝牙开发工具，无论是构建智能家居系统、物联网网关，还是进行蓝牙协议研究，都能提供强大的支持。建议从基础的设备发现和数据传输开始实践，逐步探索 BLE 服务和复杂网络功能。对于企业级应用，可结合 Flask/Django 开发蓝牙 Web 服务。
)
