一、Qt Bluetooth 模块概述
Qt Bluetooth 模块提供了跨平台的蓝牙支持，底层通过操作系统的蓝牙堆栈实现，例如：
– Linux：BlueZ
– Windows：Windows Bluetooth Stack
– macOS：IOBluetooth
Qt 对这些底层操作进行了抽象，使开发者能够使用统一的 API完成设备发现、连接和数据传输等操作。因此，Qt 非常适合用于开发跨平台蓝牙应用。
二、环境准备与依赖安装
2.1 安装 BlueZ
CentOS / RHEL 系
sudo yum install bluez
Debian / Ubuntu 系
sudo apt-get install bluez
查看 BlueZ 版本：
bluetoothctl –version
输出示例：bluetoothctl: 5.64
2.2 安装 Qt Bluetooth 支持
使用 Qt 的 Bluetooth 模块
sudo apt-get install qtconnectivity5-dev
2.3 安装其他依赖
sudo apt install rfkill
sudo apt install libbluezqt-dev
三、配置与启动蓝牙
3.1 修改 BlueZ 主配置文件
编辑配置文件：
sudo vim /etc/bluetooth/main.conf
在文件中添加：
JustWorksRepairing=never
3.2 重启蓝牙服务
sudo systemctl restart bluetooth
3.3 解除蓝牙软封锁（rfkill）
sudo apt install rfkill
sudo rfkill unblock bluetooth
在 Qt 代码中执行：
// 执行命令：解除蓝牙封锁
QProcess::execute("sudo rfkill unblock bluetooth");
3.4 开关蓝牙
// 执行命令：关闭蓝牙
QProcess::execute("bluetoothctl power off");
// 执行命令：开启蓝牙
QProcess::execute("bluetoothctl power on");
四、发送数据（gatttool）
使用 `gatttool` 向 BLE 设备写入特征值：
gatttool -b 70:19:88:59:57:46 –char-write-req -a 0x0002 -n 13
参数说明：
| 参数 | 含义 |
|—|—|
| `-b` | 指定蓝牙设备地址 |
| `–char-write-req` | 写入特征值 |
| `-a` | 指定特征值的句柄（需根据设备文档确定） |
| `-n` | 要发送的数据（示例中为数字 13） |
五、不使用上述库文件的替代方案
1. 使用 **DBus** 与 BlueZ 交互
2. 使用 **HCI** 直接与蓝牙硬件交互
六、Docker 容器中使用蓝牙（Linux）
需要满足以下两个条件：
1. 容器的网络模式使用 **host**
2. 挂载以下目录：
-v /dev:/dev \\
-v /run/dbus:/run/dbus \\
-v /var/run/dbus:/var/run/dbus
七、常见问题与错误处理
7.1 报错日志
qt.bluetooth.bluez: Missing CAP_NET_ADMIN permission. Cannot determine whether a found address is of random or public type.
qt.bluetooth.bluez: Cannot connect to profile/service.
qt.bluetooth.bluez: QBluetoothSocketPrivateBluezDBus::connectToService called on busy socket
qt.bluetooth.bluez: void QBluetoothSocketPrivateBluez::_q_readNotify() 72 error: -1 "Resource temporarily unavailable"
7.2 报错含义
**含义**：无法关闭由外部程序创建的 BLE 连接，因此中止了当前的连接尝试。
**原因**：如果 BLE 连接是由其他程序（非当前 Qt 程序）创建的，Qt 的蓝牙模块无法直接关闭这些连接，因此只能放弃连接尝试。
7.3 清理蓝牙设备缓存
# 1. 查看所有控制器
ls /var/lib/bluetooth/
# 2. 查看某个控制器下的设备缓存
sudo ls /var/lib/bluetooth/00:16:EB:96:61:57/
# 3. 查看具体设备详情（例如 70:19:88:59:57:64）
sudo cat /var/lib/bluetooth/00:16:EB:96:61:57/70:19:88:59:57:64/info
# 4. 确认无误后，选择性删除：
# 删除单个设备缓存
sudo rm -rf /var/lib/bluetooth/00:16:EB:96:61:57/70:19:88:59:57:64
# 或删除全部缓存（谨慎！）
sudo rm -rf /var/lib/bluetooth/*
注意事项：
– 删除 `info` 文件会导致**需要重新配对设备**
– 删除 `cache/` 会使系统**重新发现 GATT 服务**（首次连接会变慢）
– 建议先备份重要配置（如耳机链路密钥）
