Qt蓝牙

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

目前，该API支持以下平台

API功能	Android	iOS	Linux (BlueZ 5.x)	macOS	Windows
经典蓝牙	x		x	x	x
蓝牙LE中心	x	x	x	x	x
蓝牙LE外围	x	x	x	x

概述

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

Qt蓝牙支持蓝牙低能耗开发，用于客户端/中心角色的用例。更详细的信息可在蓝牙低能耗概述部分找到。

使用模块

使用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蓝牙模块使用新的QPermission API来处理蓝牙权限。这意味着Qt本身不再查询这些权限，因此需要从客户端应用中直接完成此操作。

请参阅应用程序权限页以了解如何将新的QPermission API集成到应用程序中的示例。

构建Qt蓝牙

虽然该模块可以用于所有Qt平台，但该模块并未部署到所有这些平台。在不支持的平台上使用虚拟后端，当平台不受支持时将自动选择虚拟后端。虚拟后端报告适当的错误消息和值，这使得您可以在运行时检测到当前平台不受支持。虚拟后端在Linux上也选择，如果在构建时间找不到BlueZ开发头或在构建Qt时没有Qt D-Bus支持。

在构建和运行时，通过适当的警告突出显示虚拟后端的使用。

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产生对QGuiApplication的依赖。但是，可以设置环境变量QT_EVENT_DISPATCHER_CORE_FOUNDATION=1来解决这个问题。

不使用传统蓝牙的应用程序可以找到QtBluetooth的一个子集可用，因为CoreBluetooth（蓝牙低功耗）不需要QApplication或QGuiApplication。

文章和指南

参考

C++类

日志分类

QtBluetooth模块导出以下日志分类

日志分类	说明
qt.bluetooth	启用在QtBluetooth中跨平台代码路径的日志记录
qt.bluetooth.android	启用Android实现的日志记录
qt.bluetooth.bluez	启用BLuez/Linux实现的日志记录
qt.bluetooth.ios	启用iOS实现的日志记录
qt.bluetooth.osx	启用macOS实现的日志记录
qt.bluetooth.windows	启用Windows实现的日志记录

日志分类能够为QtBluetooth提供额外的警告和调试输出。有关日志记录的更详细内容请参阅QLoggingCategory。一种快速启用所有QtBluetooth日志记录的方法是将以下行添加到main()函数

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

示例

模块演变

Qt蓝牙模块变更列出了针对Qt 6系列Qt所做的模块API和功能的重要变更。

许可和归属

Qt Bluetooth可在The Qt Company的商业许可下使用。此外，它还可以在GNU Lesser General Public License, version 3或GNU General Public License, version 2下使用。有关更多详细资料请参阅Qt许可。

在Linux上，Qt蓝牙使用一个独立的可执行文件sdpscanner，以便与官方的Linux蓝牙协议栈BlueZ集成。BlueZ可在GNU通用公共许可证，版本2下使用。

BlueZ

仅GNU通用公共许可证v2.0（这不会强制用户代码变成GPL。更多详情请查看详细信息。）