summaryrefslogtreecommitdiffstats
path: root/src/bluetooth/doc/src/bluetooth-index.qdoc
blob: 6277c81f032bf6a7b42d0a0a584825cd8870cdd3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qtbluetooth-index.html
\title Qt Bluetooth
\brief Qt Bluetooth enables connectivity between Bluetooth enabled devices.
\ingroup technology-apis

The Bluetooth API provides connectivity between Bluetooth enabled devices.

Currently, the API is supported on the following platforms:

\table
\header
    \li API Feature
    \li \l {Qt for Android}{Android}
    \li \l {Qt for iOS}{iOS}
    \li \l {Qt for Linux/X11}{Linux (BlueZ 4.x/5.x)}
    \li \l {Qt for OS X}{macOS}
    \li \l {Qt for WinRT}{WinRT}
    \li \l {Qt for Windows}{Windows}
\row
    \li Classic Bluetooth
    \li x
    \li x
    \li x
    \li x
    \li x
    \li
\row
    \li Bluetooth LE Central
    \li x
    \li x
    \li x
    \li x
    \li x
    \li
\row
    \li Bluetooth LE Peripheral
    \li x
    \li x
    \li x
    \li x
    \li
    \li
\row
    \li Bluetooth LE Advertisement & Scanning
    \li
    \li
    \li
    \li
    \li
    \li
\endtable

\section1 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
\l {Bluetooth Low Energy Overview}{Bluetooth Low Energy Overview} section.

A new addition since the Qt Bluetooth 5.7 release covers support for Bluetooth Low Energy
applications performing the peripheral/server role. This new API remains in Technology Preview.

\section1 Getting Started

To use the C++ library in your application, add the following configuration
option to your \c .pro file:

\snippet snippets.pro contacts project modification

To use the classes of the module in your application you need the following
import statement in your \c .qml file:

\snippet doc_src_qtbluetooth.qml import

\section1 Related Information

\section2 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 such as Windows desktop
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.

\section2 Guides
\list
    \li \l {Qt Bluetooth Overview}{Classic Bluetooth Overview}
    \li \l {Bluetooth Low Energy Overview}
\endlist

\section2 Reference
\list
    \li \l {Qt Bluetooth QML Types}{QML Types}
    \li \l {Qt Bluetooth C++ Classes}{C++ Classes}
\endlist

\section2 Logging Categories

The \l QtBluetooth module exports the following
\l {Configuring Categories}{logging categories}:

\table
\header
    \li Logging Category
    \li Description
\row
    \li qt.bluetooth
    \li Enables logging of cross platform code path in QtBluetooth
\row
    \li qt.bluetooth.android
    \li Enables logging of the \l {Qt for Android} {Android} implementation
\row
    \li qt.bluetooth.bluez
    \li Enables logging of the BLuez/Linux implementation
\row
    \li qt.bluetooth.ios
    \li Enables logging of the \l {Qt for iOS} {iOS} implementation
\row
    \li qt.bluetooth.osx
    \li Enables logging of the \l {Qt for macOS} {macOS} implementation
\row
    \li qt.bluetooth.qml
     \li Enables logging of the QtBluetooth QML implementation
\row
    \li qt.bluetooth.winrt
    \li Enables logging of the \l {Qt for WinRT} {WinRT} implementation
\endtable

Logging categories can be used to enable additional warning and debug output
for QtBluetooth. More detailed information about logging can be found in \l QLoggingCategory.
A quick way to enable all QtBluetooth logging is to add the following line to the \c main() function:

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

\section2 Examples
\list
    \li QML
    \list
        \li \l {scanner}{QML Bluetooth Scanner}
        \li \l {picturetransfer}{QML Bluetooth Picture Push}
        \li \l {pingpong}{QML Bluetooth PingPong}
        \li \l {chat}{QML Bluetooth Chat}
        \li \l {heartlistener}{Bluetooth Low Energy Heart Listener}
        \li \l {heartrate-game}{Bluetooth Low Energy Heart Rate Game}
        \li \l {heartrate-server}{Bluetooth Low Energy Heart Rate Server}
        \li \l {lowenergyscanner}{Bluetooth Low Energy Scanner}
    \endlist
    \li C++
    \list
        \li \l {btchat}{Bluetooth Chat}
        \li \l {btscanner}{Bluetooth Scanner}
        \li \l {btfiletransfer}{Bluetooth File Transfer}
    \endlist
\endlist

\section1 Licenses and Attributions

Qt Bluetooth is available under commercial licenses from \l{The Qt Company}.
In addition, it is available under the
\l{GNU Lesser General Public License, version 3}, or
the \l{GNU General Public License, version 2}.
See \l{Qt Licensing} for further details.

On Linux, Qt Bluetooth uses a separate executable, \c sdpscanner,
to integrate with the official Linux bluetooth protocol stack
BlueZ. BlueZ is available under the \l{GNU General Public License,
version 2}.

\generatelist{groupsbymodule attributions-qtbluetooth}
*/