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
|
/****************************************************************************
**
** Copyright (C) 2016 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$
**
****************************************************************************/
/*!
\example heartrate-server
\title Bluetooth Low Energy Heart Rate Server Example
\brief An example demonstrating how to set up and advertise a GATT service. The example
demonstrates the use of the Qt Bluetooth Low Energy classes related to peripheral (slave)
functionality.
The Bluetooth Low Energy Heart Rate Server is a command-line application that shows how to
develop a Bluetooth GATT server using the Qt Bluetooth API.
The application covers setting up a service, advertising it and notifying clients about changes
to characteristic values.
The example makes use of the following Qt classes:
\list
\li \l QLowEnergyAdvertisingData
\li \l QLowEnergyAdvertisingParameters
\li \l QLowEnergyServiceData
\li \l QLowEnergyCharacteristicData
\li \l QLowEnergyDescriptorData
\li \l QLowEnergyController
\li \l QLowEnergyService
\endlist
The example implements a server application, which means it has no graphical user interface.
To visualize what it is doing, you can use the \l {heartlistener}{Heart Listener}
example, which is basically the client-side counterpart to this application.
\note On Linux, advertising requires privileged access, so you need to run
the example as root, for instance via \c sudo.
\section1 Setting up Advertising Data and Parameters
Two classes are used to configure the advertising process: \l QLowEnergyAdvertisingData to
specify which information is to be broadcast, and \l QLowEnergyAdvertisingParameters for
specific aspects such as setting the advertising interval or controlling which devices are
allowed to connect. In our example, we simply use the default parameters.
The information contained in the \l QLowEnergyAdvertisingData will be visible to other devices
that are currently scanning. They can use it to decide whether they want to establish a connection
or not. In our example, we include the type of service we offer, a name that adequately
describes our device to humans, and the transmit power level of the device. The latter is
often useful to potential clients, because they can tell how far away our device is by
comparing the received signal strength to the advertised one.
\note Space for the advertising data is very limited (only 31 bytes in total), so
variable-length data such as the device name should be kept as short as possible.
\snippet heartrate-server/main.cpp Advertising Data
\section1 Setting up Service Data
Next we configure the kind of service we want to offer. We use the \c {Heart Rate} service as
defined in the Bluetooth specification in its minimal form, that is, consisting only of the
\c {Heart Rate Measurement} characteristic. This characteristic must support the \c Notify
property (and no others), and it needs to have a \c {Client Characteristic Configuration}
descriptor, which enables clients to register to get notified about changes to characteristic
values. We set the initial heart rate value to zero, as it cannot be read anyway (the only
way the client can get at the value is via notifications).
\snippet heartrate-server/main.cpp Service Data
\section1 Advertising and Listening for Incoming Connections
Now that all the data has been set up, we can start advertising. First we create a
\l QLowEnergyController object in the
\l {QLowEnergyController::PeripheralRole} {peripheral role} and use it to create a (dynamic)
\l QLowEnergyService object from our (static) \l QLowEnergyServiceData.
Then we call \l QLowEnergyController::startAdvertising().
Note that we hand in our \l QLowEnergyAdvertisingData twice: The first argument
acts as the actual advertising data, the second one as the scan response data. They could
transport different information, but here we don't have a need for that. We also pass
a default-constructed instance of \l QLowEnergyAdvertisingParameters, because the default
advertising parameters are fine for us. If a client is interested in the advertised service,
it can now establish a connection to our device. When that happens, the device stops advertising
and the \l QLowEnergyController::connected() signal is emitted.
\note When a client disconnects, advertising does not resume automatically. If you want that
to happen, you need to connect to the \l QLowEnergyController::disconnected() signal
and call \l QLowEnergyController::startAdvertising() in the respective slot.
\snippet heartrate-server/main.cpp Start Advertising
\section1 Providing the Heartrate
So far, so good. But how does a client actually get at the heart rate? This happens by
regularly updating the value of the respective characteristic in the \l QLowEnergyService
object that we received from the \l QLowEnergyController in the code snippet above.
The source of the heart rate would normally be some kind of sensor, but in our example,
we just make up values that we let oscillate between 60 and 100. The most important part in the
following code snippet is the call to \l QLowEnergyService::writeCharacteristic. If
a client is currently connected and has enabled notifications by writing to the aforementioned
\c {Client Characteristic Configuration}, it will get notified about the new value.
\snippet heartrate-server/main.cpp Provide Heartbeat
*/
|
