PyBluez2 的详细介绍、安装指南、使用方法及配置说明

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, Characteristic

class 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 服务。