diff options
Diffstat (limited to 'src/bluetooth/doc/src/bluetooth-le-overview.qdoc')
| -rw-r--r-- | src/bluetooth/doc/src/bluetooth-le-overview.qdoc | 63 |
1 files changed, 55 insertions, 8 deletions
diff --git a/src/bluetooth/doc/src/bluetooth-le-overview.qdoc b/src/bluetooth/doc/src/bluetooth-le-overview.qdoc index 70d9908a..8e78c487 100644 --- a/src/bluetooth/doc/src/bluetooth-le-overview.qdoc +++ b/src/bluetooth/doc/src/bluetooth-le-overview.qdoc @@ -34,10 +34,11 @@ Low Energy devices. \tableofcontents - The Qt Bluetooth Low Energy API was introduced by Qt 5.4. Since Qt 5.5 the API - is final and a compatibility guarantee is given for future releases. - At the moment, Qt supports the Bluetooth Low Energy central role. - For more details on this limitation see below. + The Qt Bluetooth Low Energy API for the central role was introduced by Qt 5.4. + Since Qt 5.5 that part of the API is final and a compatibility guarantee is given for + future releases. + In Qt 5.7, additional API supporting the peripheral role was added as a Technology Preview, + with the backend only implemented for Linux/BlueZ. \section1 What Is Bluetooth Low Energy @@ -159,10 +160,13 @@ Low Energy devices. \section1 Using Qt Bluetooth Low Energy API - This section describes how to use the Bluetooth Low Energy API provided by Qt. Currently the API - permits creating connections to peripheral devices, discovering their services, as well as reading - and writing data stored on the device. The example code below is taken from the - \l {heartlistener}{Heart Listener} example. + This section describes how to use the Bluetooth Low Energy API provided by Qt. + On the client side, the API permits creating connections to peripheral devices, discovering + their services, as well as reading and writing data stored on the device. + On the server side, it allows to set up services, advertise them, and get notified when the + client writes characteristics. + The example code below is taken from the \l {heartlistener}{Heart Listener} and + \l {heartrate-server}{Heart Rate Server} examples. \section2 Establishing a Connection @@ -240,4 +244,47 @@ Low Energy devices. \l {https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx}{Bluetooth SIG} whereas others may follow a custom protocol. The above code snippet demonstrates how to the read the standardized HeartRate value. + + \section2 Advertising Services + + If we are implementing a GATT server application on a peripheral device, we need to define the + services we want to offer to central devices and advertise them: + + \snippet heartrate-server/main.cpp Advertising Data + \snippet heartrate-server/main.cpp Start Advertising + + Now potential clients can connect to our device, discover the provided service and + register themselves to get notified of changes to the characteristic value. + This part of the API was already covered by the above sections. + + \section2 Implementing a Service on the Peripheral Device + + The first step is to define the service, its characteristics and descriptors. This is achieved + using the \l QLowEnergyServiceData, \l QLowEnergyCharacteristicData and + \l QLowEnergyDescriptorData classes. These classes act as containers or building blocks for the + essential information that comprises the to-be-defined Bluetooth Low Energy service. + The code snippet below defines a simple HeartRate service which publishes + the measured beats per minute. An example where such a service could be used is a wrist watch. + + \snippet heartrate-server/main.cpp Service Data + + The resulting \c serviceData object can be published as described in the + \l {Advertising Services} section above. Despite the partial information overlap between the + information wrapped by \l QLowEnergyServiceData and \l QLowEnergyAdvertisingData the two classes + serve two very different tasks. The advertising data is published to nearby devices and often + limited in scope due to its size restriction of 29 bytes. Therefore they are not always 100% + complete. By comparison the service data contained inside of \l QLowEnergyServiceData provides + the complete set of service data and only becomes visible to the connecting client when a + connection with an active service discovery has been performed. + + The next section demonstrates how the service can update the heart rate value. Depending on the + nature of the service it may have to comply with the official service definition + as defined on \l {https://www.bluetooth.org}. Other services may be completely custom. The + heart rate service was adopted and its specification can be found under + \l {https://www.bluetooth.com/specifications/adopted-specifications}. + + \snippet heartrate-server/main.cpp Provide Heartbeat + + In general characteristic and descriptor value updates on the peripheral device use the same + methods as connecting Bluetooth Low Energy devices. */ |