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
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt local connectivty modules.
**
** $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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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$
**
****************************************************************************/
/*!
\ingroup technology-apis
\title Qt Bluetooth Overview
\page qtbluetooth-overview.html
\brief The Qt Bluetooth API enables connectivity with other regular Bluetooth
and Bluetooth Low Energy enabled devices.
\tableofcontents
With the Qt Bluetooth API typical use cases are:
\list
\li Retrieve information about the local Bluetooth device.
\li Scan for other Bluetooth devices in range and retrieve information about them.
\li Push files to remote devices using the OBEX Object Push Profile (OPP)
\li Connect to remote devices through a RFCOMM channel using the Serial Port Profile (SPP).
\li Create a RFCOMM server that allows incoming connections using SPP.
\li Retrieve specification about Bluetooth Low Energy device.
\li Connect to Bluetooth Low Energy device.
\li Receive advertisement from Bluetooth Low Energy device.
\endlist
Note that the Object Push Profile is not supported on Android.
The following sections describe how to use the Qt Bluetooth C++ API classes
for the above use cases.
\section1 Retrieving Local Device Information
The Qt Bluetooth API has three main purposes. The first one is to
obtain local and remote device information. The first steps in retrieving device information are
to check if Bluetooth is available on the device and read the local device address and name.
QBluetoothLocalDevice is the class that provides all of this information. Additionally you can use it
to turn Bluetooth on/off, set the visibility of the device and determine the current connections.
\snippet doc_src_qtbluetooth.cpp turningon
\section1 Scanning for Bluetooth Devices
Similar to the QBluetoothLocalDevice, the API offers QBluetoothDeviceInfo which provides
similar information for remote devices. Although you can just create QBluetoothDeviceInfo objects on
your own and fill them with data, the easier way is to use the QBluetoothDeviceDiscoveryAgent to
start an automated search for visible Bluetooth devices within the connectable range.
\snippet doc_src_qtbluetooth.cpp device_discovery
\section1 Pushing Files to Remote Devices
Once the desired device was found, there are two main use cases provided by Qt Bluetooth. The
simpler one is to send files via the Obex Object Push Profile (OPP). As the name describes, this
profile can only push files from one device to another, but not pull files or browse the remote
file system. Because of this limitation, this profile does not require the two devices to be
paired before exchanging data. To push files to remote devices, create a
QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in
the request by calling its \l {QBluetoothTransferManager::put()}{put()} function.
\snippet doc_src_qtbluetooth.cpp sendfile
\section1 Exchanging Data Between Devices
The more flexible approach for communication between two Bluetooth enabled devices, is to
create a virtual serial port connection and freely exchange data over that connection. This can
be done by the Serial Port Profile (SPP). The Serial Port Profile emulates a serial connection
over the Bluetooth transport protocol RFCOMM.
To be able to receive incoming SPP connections, you need to listen to incoming connections using
\l QBluetoothServer.
\snippet btchat/chatserver.cpp Create the server
Connect to this server from another device playing the client role by using a
QBluetoothSocket:
\snippet btchat/chatclient.cpp startClient
Using such a connection allows to exchange any form of data in both directions.
It is perfectly suited for gaming or for syncing the state between two instances of
an application on two devices. For more detailed descriptions on how to configure the server
and client, please refer to the detailed description sections in the \l QBluetoothServer and
\l QBluetoothSocket classes. A good example to start with SPP is the \l{btchat}{Bluetooth Chat}
example.
\section1 Bluetooth Low Energy
Bluetooth Low Energy (in later text BLE), also known as Bluetooth Smart is a wireless computer
network technology, which was officially introduced in 2011. It works at the same,
2,4HGz frequency, as ”classic” Bluetooth. The main difference is, as stated by its technology name,
low energy consumption. It provides an opportunity for BLE devices to operate for months,
even years, on coin-cell batteries. This technology was introduced with Bluetooth v 4.0
and devices which support this technology are called Bluetooth Smart Ready Devices.
The key features of technology are:
\list
\li Ultra-low peak, average and idle mode power consumption
\li Ability to run for years on standard, coin-cell batteries
\li Low cost
\li Multi-vendor interoperability
\li Enhanced range
\endlist
BLE uses a client-server architecture. The server (BLE device) offers services (temperature,
heart rate or any other measurements) and advertises them. The client (PC, smartphone
or any other Bluetooth Smart Ready device) connects to the server and reads the values
advertised by the server. The BLE API is based on GATT (Generic Attribute Profile) concepts.
GATT commands are initiated by the client, as mentioned above, and the server is receiving
GATT commands and sends replies.
These GATT commands initiate the services, which consist of characteristics. A characteristic
is data that is being transferred. Each characteristic has descriptors, which give additional
information about the characteristic. Services, characteristics and descriptors are recognized
by their 128bits UUIDs.
To be able to get and read characteristics, it is required to connect to the LE device service.
\snippet heartlistener/heartrate.cpp Connect signals
We start a service discovery with a \l QBluetoothServiceDiscoveryAgent class and connect its
signal \l serviceDiscovered(QLowEnergyServiceInfo) to the slot in the application.
This way, it is possible to store all LE services or connect to the desired one.
\l QLowEnergyController is used for connecting to service, emitting values,
receiving emitted errors from the service and characteristics, and disconnecting from the service.
Even though it is possible to connect to an LE service before the service scan is done,
it is advisable to do it after the service scan is done.
\snippet heartlistener/heartrate.cpp Connecting to service
In the code example above, the wanted characteristics will be enabled for the notifications, but not
all of them have that option as explained in \l QLowEnergyController documentation. In this case,
it was a characteristic \l QBluetoothUuid::HeartRateMeasurement.
Finally, to receive updates, we defined the slot where we read the emitted value.
\snippet heartlistener/heartrate.cpp Reading value
The returned value is the hexadecimal value. The procedure of reading and converting hexadecimal
value properly depends on the BLE devices that is sending updates since every device has a different
value structure.
*/
|
