1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtbluetooth-index.html
7\brief Qt Bluetooth enables connectivity between Bluetooth enabled devices.
8\ingroup technology-apis
10The Bluetooth API provides connectivity between Bluetooth enabled devices.
12Currently, the API is supported on the following platforms:
17 \li \l {Qt for Android}{Android}
18 \li \l {Qt for iOS}{iOS}
19 \li \l {Qt for Linux/X11}{Linux (BlueZ 5.x)}
21 \li \l {Qt for Windows}{Windows}
30 \li Bluetooth LE Central
37 \li Bluetooth LE Peripheral
47Bluetooth is a short-range (less than 100 meters) wireless technology. It
48has a data transfer rate of 2.1 Mbps, which makes it ideal
49for transferring data between devices. Bluetooth connectivity is based on
50basic device management, such as scanning for devices, gathering information
51about them, and exchanging data between them.
53Qt Bluetooth supports Bluetooth Low Energy development for client/central role
54use cases. Further details can be found in the
55\l {Bluetooth Low Energy Overview}{Bluetooth Low Energy Overview} section.
57\section1 Using the Module
59\include {module-use.qdocinc} {using the c++ api}
61\section2 Building with CMake
63\include {module-use.qdocinc} {building with cmake} {Bluetooth}
65\section2 Building with qmake
67\include {module-use.qdocinc} {building_with_qmake} {bluetooth}
71Starting from Qt 6.6, the Qt Bluetooth module uses new \l QPermission API
72to handle \l {QBluetoothPermission}{Bluetooth} permissions. This means that Qt
73itself no longer queries for these permissions, so this needs to be done
74directly from the client application.
76Please refer to the \l {Application Permissions} page for an example of how
77to integrate the new \l QPermission API into the application.
79\section1 Related Information
81\section2 Building Qt Bluetooth
83Even though the module can be built for all Qt platforms, the module is not
84ported to all of them. Non-supported platforms employ a dummy backend that is
85automatically selected when the platform is not supported. The dummy backend
86reports appropriate error messages and values, which enables you to detect at
87runtime that the current platform is not supported. The dummy backend is also
88selected on Linux if BlueZ development headers are not found during build time
89or Qt was built without Qt D-Bus support.
91The usage of the dummy backend is highlighted via an appropriate warning while building and running.
93\section3 Linux Specific
95Since Qt 6.5 the Linux peripheral support has two backend alternatives:
96BlueZ DBus and Bluetooth Kernel API. The DBus backend is the default
99BlueZ DBus is the newer BlueZ stack and possibly the eventual successor of the
100older Kernel API. It is a bit more limited in terms of features, but in a
101typical usage this should not matter. One notable benefit of using the DBus
102backend is that the user process no longer needs to have the
103\e CAP_NET_ADMIN capability (for example by running as \c root user).
105The DBus backend requires BlueZ version 5.56 or higher, and that it provides
106the needed DBus APIs. If these requirements are not met, Qt automatically
107falls back to the Bluetooth Kernel API backend.
109The older kernel backend can also be selected manually by setting the
110\e QT_BLUETOOTH_USE_KERNEL_PERIPHERAL environment variable.
112\section3 \macos Specific
113The Bluetooth API on \macos requires a certain type of event dispatcher
114that in Qt causes a dependency to \l QGuiApplication. However, you can set the
115environment variable \c {QT_EVENT_DISPATCHER_CORE_FOUNDATION=1} to circumvent
118Applications that don't use Classic Bluetooth will find a subset of QtBluetooth
119is available, as CoreBluetooth (Bluetooth LE) don't require \l QApplication or
122\section2 Articles and Guides
124 \li \l {Qt Bluetooth Overview}{Classic Bluetooth Overview}
125 \li \l {Bluetooth Low Energy Overview}
130 \li \l {Qt Bluetooth C++ Classes}{C++ Classes}
133\section2 Logging Categories
135The \l QtBluetooth module exports the following
136\l {Configuring Categories}{logging categories}:
144 \li Enables logging of cross platform code path in QtBluetooth
146 \li qt.bluetooth.android
147 \li Enables logging of the \l {Qt for Android} {Android} implementation
149 \li qt.bluetooth.bluez
150 \li Enables logging of the BLuez/Linux implementation
153 \li Enables logging of the \l {Qt for iOS} {iOS} implementation
156 \li Enables logging of the \l {Qt for macOS} {macOS} implementation
158 \li qt.bluetooth.windows
159 \li Enables logging of the \l {Qt for Windows} {Windows} implementation
162Logging categories enable additional warning and debug output for QtBluetooth.
163More detailed information about logging is found in \l QLoggingCategory. A
164quick way to enable all QtBluetooth logging is to add the following line to the
168 QLoggingCategory::setFilterRules(QStringLiteral("qt.bluetooth* = true"));
175 \li \l {heartrate-game}{Bluetooth Low Energy Heart Rate Game}
176 \li \l {heartrate-server}{Bluetooth Low Energy Heart Rate Server}
177 \li \l {lowenergyscanner}{Bluetooth Low Energy Scanner}
181 \li \l {btchat}{Bluetooth Chat}
185\section1 Module Evolution
187\l{Changes to Qt Bluetooth} lists important changes in the module
188API and functionality that were done for the Qt 6 series of Qt.
190\section1 Licenses and Attributions
192Qt Bluetooth is available under commercial licenses from \l{The Qt Company}.
193In addition, it is available under the
194\l{GNU Lesser General Public License, version 3}, or
195the \l{GNU General Public License, version 2}.
196See \l{Qt Licensing} for further details.
198On Linux, Qt Bluetooth uses a separate executable, \c sdpscanner,
199to integrate with the official Linux bluetooth protocol stack
200BlueZ. BlueZ is available under the \l{GNU General Public License,
203\generatelist{groupsbymodule attributions-qtbluetooth}