Qt Bluetooth

蓝牙 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

概述

Bluetooth is a short-range (less than 100 meters) wireless technology. It has a data transfer rate of 2.1 Mbps, which makes it ideal for transferring data between devices. Bluetooth connectivity is based on basic device management, such as scanning for devices, gathering information about them, and exchanging data between them.

Qt Bluetooth supports Bluetooth Low Energy development for client/central role use cases. Further details can be found in the 低功耗蓝牙概述 章节。

使用模块

使用 Qt 模块的 C++ API 要求直接 (或透过其它依赖) 链接到模块库。几个构建工具对此有专用支持,包括 CMake and qmake .

构建采用 CMake

使用 find_package() 命令定位所需模块组件在 Qt6 包:

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

更多细节,见 构建采用 CMake 概述。

采用 qmake 构建

要配置采用 qmake 构建模块,添加模块作为值为 QT 变量在工程的 .pro 文件:

QT += bluetooth
					

权限

Starting from Qt 6.6, the Qt Bluetooth module uses new QPermission API 处理 蓝牙 permissions. This means that Qt itself no longer queries for these permissions, so this needs to be done directly from the client application.

请参考 应用程序权限 page for an example of how to integrate the new QPermission API into the application.

构建 Qt Bluetooth

Even though the module can be built for all Qt platforms, the module is not ported to all of them. Non-supported platforms employ a dummy backend that is automatically selected when the platform is not supported. The dummy backend reports appropriate error messages and values, which enables you to detect at runtime that the current platform is not supported. The dummy backend is also selected on Linux if BlueZ development headers are not found during build time or Qt was built without Qt D-Bus support.

The usage of the dummy backend is highlighted via an appropriate warning while building and running.

Linux Specific

Since Qt 6.5 the Linux peripheral support has two backend alternatives: BlueZ DBus and Bluetooth Kernel API. The DBus backend is the default backend since Qt 6.7.

BlueZ DBus is the newer BlueZ stack and possibly the eventual successor of the older Kernel API. It is a bit more limited in terms of features, but in a typical usage this should not matter. One notable benefit of using the DBus backend is that the user process no longer needs to have the CAP_NET_ADMIN capability (for example by running as root user).

The DBus backend requires BlueZ version 5.56 or higher, and that it provides the needed DBus APIs. If these requirements are not met, Qt automatically falls back to the Bluetooth Kernel API backend.

The older kernel backend can also be selected manually by setting the QT_BLUETOOTH_USE_KERNEL_PERIPHERAL 环境变量。

macOS Specific

The Bluetooth API on macOS requires a certain type of event dispatcher that in Qt causes a dependency to QGuiApplication . However, you can set the environment variable QT_EVENT_DISPATCHER_CORE_FOUNDATION=1 to circumvent this issue.

Applications that don't use Classic Bluetooth will find a subset of QtBluetooth is available, as CoreBluetooth (Bluetooth LE) don't require QApplication or QGuiApplication .

文章和指南

参考

日志类别

The QtBluetooth 模块导出下列 日志类别 :

日志类别 描述
qt.bluetooth Enables logging of cross platform code path in QtBluetooth
qt.bluetooth.android Enables logging of the Android 实现
qt.bluetooth.bluez Enables logging of the BLuez/Linux implementation
qt.bluetooth.ios Enables logging of the iOS 实现
qt.bluetooth.osx Enables logging of the macOS 实现
qt.bluetooth.windows Enables logging of the Windows 实现

Logging categories enable additional warning and debug output for QtBluetooth . More detailed information about logging is found in QLoggingCategory . A quick way to enable all QtBluetooth logging is to add the following line to the main() 函数:

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

范例

模块演变

Changes to Qt Bluetooth 列出了 Qt 的 Qt 6 系列在模块 API 和功能上所做出的重要改变。

许可和归属

Qt Bluetooth 在商业许可下是可用的来自 Qt 公司 。此外,它是可用的根据 GNU LGPL (次一般公共许可) 第 3 版 ,或 GNU GPL (一般公共许可) 第 2 版 。见 Qt 许可 进一步了解细节。

On Linux, Qt Bluetooth uses a separate executable, sdpscanner , to integrate with the official Linux bluetooth protocol stack BlueZ. BlueZ is available under the GNU GPL (一般公共许可) 第 2 版 .

BlueZ

GNU General Public License v2.0 only (This does not force user code to be GPL'ed. For more info see details.)