Qt Bluetooth

蓝牙 API 用于在支持蓝牙的设备之间建立连接。

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

概述

蓝牙是一种短距离（小于 100 米）的无线技术。其数据传输速率为 2.1 Mbps，非常适合在设备之间传输数据。蓝牙连接基于基本的设备管理功能，例如扫描设备、收集设备信息以及在设备之间交换数据。

Qt Bluetooth 支持蓝牙低功耗（BLE）开发，适用于客户端/中心节点等使用场景。更多详细信息请参阅“蓝牙低功耗概述”部分。

使用该模块

要使用 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 在构建时未启用Qt D-Bus 支持，则在 Linux 系统上也会选择该虚拟后端。

在构建和运行过程中，系统会通过相应的警告提示来强调虚拟后端的使用情况。

Linux 特定

自 Qt 6.5 起，Linux 外设支持提供了两种后端选项：BlueZ DBus 和蓝牙内核 API。自 Qt 6.7 起，DBus 后端已成为默认后端。

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 Bluetooth 中会导致对 `QGuiApplication` 的依赖。不过，您可以设置环境变量 `QT_EVENT_DISPATCHER_CORE_FOUNDATION=1 ` 来规避此问题。

对于不使用经典蓝牙的应用程序，QtBluetooth 仅提供部分功能，因为 CoreBluetooth（蓝牙低功耗）不需要QApplication 或QGuiApplication 。

文章与指南

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

参考

• C++ Classes

日志类别

QtBluetooth 模块导出以下logging categories ：

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

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

示例

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

模块演进

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

许可与归属

Qt Bluetooth 该模块由The Qt Company 提供商业许可。此外，它还遵循GNU 较少通用公共许可证第 3 版或GNU 通用公共许可证第 2 版。更多详细信息请参阅Qt 许可。

在 Linux 系统上，Qt Bluetooth 使用一个独立的可执行文件sdpscanner 来与官方的 Linux 蓝牙协议栈 BlueZ 集成。BlueZ 根据GNU 通用公共许可证第 2 版发布。