Qt Bluetooth

蓝牙 API 提供蓝牙设备之间的连接。

目前，该 API 支持以下平台：

概述

蓝牙是一种短距离（小于 100 米）无线技术。它的数据传输速率为 2.1 Mbps，是设备间传输数据的理想选择。蓝牙连接基于基本的设备管理，如扫描设备、收集设备信息和在设备间交换数据。

Qt Bluetooth 支持蓝牙低功耗开发，适用于客户端/中心角色用例。更多详情，请参阅蓝牙低功耗概述部分。

使用模块

使用 Qt 模块的 C++ API 需要直接或通过其他依赖关系与模块库链接。有几种构建工具为此提供了专门支持，包括CMake和qmake。

使用 CMake 构建

使用find_package() 命令在Qt6 软件包中找到所需的模块组件：

find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)

更多详情，请参阅使用 CMake 构建概述。

使用 qmake 构建

要配置模块以便用 qmake 构建，请在项目的 .pro 文件中添加模块作为QT 变量的值：

QT += bluetooth

权限

从 Qt 6.6 开始，Qt Bluetooth 模块使用新的QPermission API 来处理Bluetooth 权限。这意味着 Qt 本身不再查询这些权限，因此需要直接从客户端应用程序进行查询。

有关如何将新的QPermission API 集成到应用程序中的示例，请参阅应用程序权限页面。

相关信息

构建Qt Bluetooth

尽管模块可在所有 Qt 平台上构建，但模块并未移植到所有平台。不支持的平台会使用一个虚拟后端，当平台不支持时，虚拟后端会自动被选中。虚拟后端会报告适当的错误信息和值，从而让你能在运行时检测到当前平台不支持。如果在构建过程中没有找到 BlueZ 开发头文件，或 Qt XML 在构建时不支持Qt D-Bus ，在 Linux 上也会选择虚拟后端。

在构建和运行过程中，会通过适当的警告提示使用虚拟后端。

Linux 专用

自 Qt 6.5 起，Linux 外围设备支持有两种后端可供选择：BlueZ DBus 和蓝牙内核 API。DBus 后端是 Qt 6.7 后的默认后端。

BlueZ DBus 是较新的 BlueZ 协议栈，可能是较早的内核 API 的最终继承者。它的功能比较有限，但在一般使用情况下这并不重要。使用 DBus 后端的一个显著好处是，用户进程不再需要具备CAP_NET_ADMIN功能（例如以root 用户身份运行）。

DBus 后端要求 BlueZ 版本为 5.56 或更高，并提供所需的 DBus API。如果不满足这些要求，Qt 会自动退回到蓝牙内核 API 后端。

也可通过设置QT_BLUETOOTH_USE_KERNEL_PERIPHERAL环境变量手动选择较旧的内核后端。

macOS 专用

macOS 上的蓝牙 API 需要某种类型的事件派发器，在 Qt 中会导致对QGuiApplication 的依赖。不过，你可以设置环境变量QT_EVENT_DISPATCHER_CORE_FOUNDATION=1 来规避这个问题。

不使用经典蓝牙的应用程序会发现QtBluetooth 的子集可用，因为 CoreBluetooth（蓝牙 LE）不需要QApplication 或QGuiApplication 。

文章和指南

• 经典蓝牙概述
• 低功耗蓝牙概述

参考资料

• C++ Classes

日志类别

QtBluetooth 模块导出以下logging categories ：

日志类别可为QtBluetooth 启用额外的警告和调试输出。有关日志记录的更多详细信息，请参阅QLoggingCategory 。启用所有QtBluetooth 日志的快速方法是在main() 函数中添加以下一行：

QLoggingCategory::setFilterRules(QStringLiteral("qt.bluetooth* = true"));

示例

• QML
  • 蓝牙低功耗心率游戏
  • 蓝牙低功耗心率服务器
  • 蓝牙低功耗扫描仪
• C++
  • 蓝牙聊天

模块演变

Qt Bluetooth 的变更列出了为 Qt 6 系列 Qt 所做的模块 API 和功能方面的重要变更。

许可证和归属

Qt Bluetooth Qt 6 是根据Qt 公司的商业许可提供的。此外，它还可以在GNU Lesser General Public License 第 3 版或GNU General Public License 第 2 版下使用。更多详情，请参阅Qt 许可。

在 Linux 上，Qt Bluetooth 使用单独的可执行文件sdpscanner 与官方 Linux 蓝牙协议栈 BlueZ 集成。BlueZ 采用GNU 通用公共许可证第 2 版。