Qt Bluetooth

The Bluetooth API provides connectivity between Bluetooth enabled devices.

Currently, the API is supported on the following platforms:

Overview

Bluetooth is a short-range (less than 100 meters) wireless technology. It has a reasonably high data transfer rate of 2.1 Mbit/s, 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 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 components in the Qt6 package:

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

See also the Build with CMake overview.

Building with qmake

Add bluetooth to the QT variable:

QT += bluetooth

Related Information

Building Qt Bluetooth

Despite the fact that the module can be built for all Qt platforms, the module is not ported to all of them. Not supported platforms employ a fake or dummy backend which is automatically selected when the platform is not supported. The dummy backend reports appropriate error messages and values which allow the Qt Bluetooth developer 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.

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) do not require either of QApplication or QGuiApplication.

Guides

• Classic Bluetooth Overview
• Bluetooth Low Energy Overview

Reference

• C++ Classes

Logging Categories

The QtBluetooth module exports the following logging categories:

Logging categories can be used to enable additional warning and debug output for QtBluetooth. More detailed information about logging can be 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
  • QML Bluetooth PingPong
  • Bluetooth Low Energy Heart Rate Game
  • Bluetooth Low Energy Heart Rate Server
  • Bluetooth Low Energy Scanner
• C++
  • Bluetooth Chat
  • Bluetooth Scanner

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.