Qt Bluetooth
The Bluetooth API provides connectivity between Bluetooth enabled devices.
Currently, the API is supported on the following platforms:
API Feature | Android | iOS | Linux (BlueZ 5.x) | macOS | Windows |
---|---|---|---|---|---|
Classic Bluetooth | x | x | x | x | |
Bluetooth LE Central | x | x | x | x | x |
Bluetooth LE Peripheral | x | x | x | x |
Overview
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 Bluetooth Low Energy Overview section.
Using the Module
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.
Building with CMake
Use the find_package()
command to locate the needed module component in the Qt6
package:
find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)
For more details, see the Build with CMake overview.
Building with qmake
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
Permissions
Starting from Qt 6.6, the Qt Bluetooth module uses new QPermission API to handle Bluetooth permissions. This means that Qt itself no longer queries for these permissions, so this needs to be done directly from the client application.
Please refer to the Application Permissions page for an example of how to integrate the new QPermission API into the application.
Related Information
Building 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 environment variable.
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.
Articles and Guides
Reference
Logging Categories
The QtBluetooth module exports the following logging categories:
Logging Category | Description |
---|---|
qt.bluetooth | Enables logging of cross platform code path in QtBluetooth |
qt.bluetooth.android | Enables logging of the Android implementation |
qt.bluetooth.bluez | Enables logging of the BLuez/Linux implementation |
qt.bluetooth.ios | Enables logging of the iOS implementation |
qt.bluetooth.osx | Enables logging of the macOS implementation |
qt.bluetooth.windows | Enables logging of the Windows implementation |
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()
function:
QLoggingCategory::setFilterRules(QStringLiteral("qt.bluetooth* = true"));
Examples
- QML
- C++
Module Evolution
Changes to Qt Bluetooth lists important changes in the module API and functionality that were done for the Qt 6 series of Qt.
Licenses and Attributions
Qt Bluetooth is available under commercial licenses from The Qt Company. In addition, it is available under the GNU Lesser General Public License, version 3, or the GNU General Public License, version 2. See Qt Licensing for further details.
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 General Public License, version 2.
GNU General Public License v2.0 only (This does not force user code to be GPL'ed. For more info see details.) |
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.