蓝牙 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 低功耗蓝牙概述 章节。
Using a Qt module's C++ API requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake .
使用
find_package()
command to locate the needed module component in the
Qt6
包：
find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)
更多细节，见 构建采用 CMake 概述。
To configure the module for building with qmake, add the module as a value of the
QT
variable in the project's .pro file:
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.
Since Qt 6.5 the Linux peripheral support has two backend alternatives: BlueZ DBus and Bluetooth kernel API. The Bluez DBus backend introduced in Qt 6.5 is intended as the eventual successor of the lower abstraction level kernel backend.
The BlueZ DBus API is more limited in terms of features and is therefore not the default backend for compatibility reasons.
The BlueZ DBus backend can be configured to use by setting the QT_BLUETOOTH_USE_DBUS_PERIPHERAL environment variable. The QLowEnergyController peripheral instantiation then introspects the presence of BlueZ DBus peripheral APIs on the local bluetooth adapter. The minimum version requirement for BlueZ is 5.56.
One noteworthy difference is that with BlueZ DBus peripheral backend the user process no longer needs to have the CAP_NET_ADMIN capability (eg. run as root).
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 lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.
Qt Bluetooth 在商业许可下是可用的来自 Qt 公司 。此外，它是可用的根据 GNU LGPL (次一般公共许可) 第 3 版 ，或 GNU GPL (一般公共许可) 第 2 版 。见 Qt 许可 进一步了解细节。
在 Linux，Qt Bluetooth 使用单独可执行文件
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.) |