Provide a documentation overview for Bluetooth LE

Change-Id: I252c085f5b3ea6ccc2820a1f59d9228745ae2900
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

3 files changed, 270 insertions, 64 deletions

diff --git a/src/bluetooth/doc/src/bluetooth-index.qdoc b/src/bluetooth/doc/src/bluetooth-index.qdoc
index afdf2600..9e691613 100644
--- a/src/bluetooth/doc/src/bluetooth-index.qdoc
+++ b/src/bluetooth/doc/src/bluetooth-index.qdoc
@@ -35,7 +35,9 @@ The Bluetooth API provides connectivity between Bluetooth enabled devices.
 
 Currently the API is supported on \l{Qt for Android}{Android},
 \l{Qt for BlackBerry}{BlackBerry 10} and
-\l{Qt for Linux/X11}{Linux} (\l{http://www.bluez.org}{Bluez 4.x}).
+\l{Qt for Linux/X11}{Linux} (\l{http://www.bluez.org}{BlueZ 4.x/5.x}).
+
+
 
 \section1 Overview
 
@@ -45,6 +47,12 @@ 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.
 
+This Qt release contains a Technology Preview of the new Qt Bluetooth
+Low Energy API. Further details can be found in the
+\l {Bluetooth Low Energy Overview}{Bluetooth Low Energy Overview} section.
+The Tech Preview supports BlueZ 4 & 5 based Linux systems. Support for
+further platforms is being planned.
+
 \section1 Getting started
 
 To use the C++ library in your application, add the following configuration
@@ -61,7 +69,8 @@ import statement in your \c .qml file:
 
 \section2 Guides
 \list
-    \li \l {Qt Bluetooth Overview}
+    \li \l {Qt Bluetooth Overview}{Classic Bluetooth Overview}
+    \li \l {Bluetooth Low Energy Overview} (Tech Preview)
 \endlist
 
 \section2 Reference
@@ -77,8 +86,8 @@ import statement in your \c .qml file:
         \li \l {scanner}{QML Bluetooth Scanner}
         \li \l {picturetransfer}{QML Bluetooth Picture Push}
         \li \l {pingpong}{QML Bluetooth PingPong}
+        \li \l {heartlistener}{Bluetooth Low Energy Heart Listener}
         \li \l {lowenergyscanner}{Bluetooth Low Energy Scanner}
-        \li \l {heartlistener}{Heart Listener}
     \endlist
     \li C++
     \list
diff --git a/src/bluetooth/doc/src/bluetooth-le-overview.qdoc b/src/bluetooth/doc/src/bluetooth-le-overview.qdoc
new file mode 100644
index 00000000..958e623d
--- /dev/null
+++ b/src/bluetooth/doc/src/bluetooth-le-overview.qdoc
@@ -0,0 +1,254 @@
+/****************************************************************************
+**
+** Copyright (C) 2014 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 Bluetooth Low Energy Overview
+\page qtbluetooth-le-overview.html
+\brief The Qt Bluetooth Low Energy API enables communication between Bluetooth
+Low Energy devices.
+
+\tableofcontents
+
+    \section1 Technology Preview
+
+    The Qt Bluetooth Low Energy API has been introduced in Qt 5.4.
+    The API is considered to be a preview of the technology and currently only works
+    on BlueZ 4 & 5 based Linux systems. Support for further platforms, for example Android,
+    is currently being worked on and will be added by later Qt releases. In addition,
+    Qt only supports the central role. For more details on this limitation see below.
+
+    While the API is not yet frozen it is close to its final stage.
+    We would like to encourage you to send us feedback and bug reports related to
+    this new feature.
+
+    \section1 What Is Bluetooth Low Energy
+
+    Bluetooth Low Energy, also known as Bluetooth Smart, is a wireless computer
+    network technology, which was officially introduced in 2011. It works on the same
+    2.4 GHz frequency as ”classic” Bluetooth. The main difference is, as stated by its technology name,
+    low energy consumption. It provides an opportunity for Bluetooth Low Energy devices to
+    operate for months, even years, on coin-cell batteries. The technology was introduced by
+    \l {https://www.bluetooth.org/en-us/specification/adopted-specifications}{Bluetooth v4.0}.
+    Devices which support this technology are called Bluetooth Smart Ready Devices.
+    The key features of the 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
+
+    Bluetooth Low Energy uses a client-server architecture. The server (also
+    known as peripheral) offers services such as temperature or heart rate
+    and advertises them. The client (known as central
+    device) connects to the server and reads the values advertised by the server.
+    An example might be an apartment with Bluetooth Smart Ready sensors such
+    as a thermostat, humidity or pressure sensor. Those sensors are peripheral
+    devices advertising the environment values of the apartment. At the same time
+    a mobile phone or computer might connect to those sensors, retrieve their
+    values and present them as part of a larger environment control application
+    to the user.
+
+    \section1 Basic Service Structure
+
+    Bluetooth Low Energy is based on two protocols: ATT (Attribute Protocol)
+    and GATT (Generic Attribute Profile). They specify the communication layers
+    used by every Bluetooth Smart Ready device.
+
+    \section2 ATT Protocol
+
+    The basic building block of ATT is an \e attribute. Each attribute consists of
+    three elements:
+
+    \list
+        \li a value - the payload or desirable piece of information
+        \li a UUID - the type of attribute (used by GATT)
+        \li a 16-bit handle - a unique identifier for the attribute
+    \endlist
+
+    The server stores the attributes and the client uses the ATT protocol to
+    read and write values on the server.
+
+    \section2 GATT Profile
+
+    GATT defines grouping for a set of attributes by applying a meaning to predefined
+    UUIDs. The table below shows an example service exposing a heart rate
+    on a particular day. The actual values are stored inside the two characteristics:
+
+    \table
+    \header
+        \li Handle
+        \li UUID
+        \li Value
+        \li Description
+    \row
+        \li 0x0001
+        \li 0x2800
+        \li UUID 0x180D
+        \li Begin Heart Rate service
+    \row
+        \li 0x0002
+        \li 0x2803
+        \li UUID 0x2A37, Value handle: 0x0003
+        \li Characteristic of type \e {Heart Rate Measurement (HRM)}
+    \row
+        \li 0x0003
+        \li 0x2A37
+        \li 65 bpm
+        \li Heart rate value
+    \row
+        \li 0x0004
+        \li 0x2803
+        \li UUID 0x2A08, Value handle: 0x0006
+        \li Characteristic of type Date Time
+    \row
+        \li 0x0005
+        \li 0x2A08
+        \li 18/08/2014 11:00
+        \li Date and Time of the measurement
+    \row
+        \li 0x0006
+        \li 0x2800
+        \li UUID xxxxxx
+        \li Begin next service
+    \row
+        \li ...
+        \li ...
+        \li ...
+        \li ...
+    \endtable
+
+    GATT specifies that the above used UUID \c 0x2800 marks the begin of a service definition.
+    Every attribute following \c 0x2800 is part of the service until the next \c 0x2800 or the
+    end is encountered. In similar ways the well known UUID \c 0x2803 states that a characteristic
+    is to be found and each of the characteristics has a type defining the nature of the value.
+    The example above uses the UUIDs \c 0x2A08 (Date Time) and \c 0x2A37 (Heart Rate Measurement).
+    Each of the above UUIDs is defined by the \l {https://bluetooth.org}{Bluetooth Special Interest Group}.
+    and can be found in the
+    \l{https://developer.bluetooth.org/gatt/Pages/default.aspx}{GATT specification}. While it
+    is advisable to use pre-defined UUIDs where available it is entirely possible to use new and not
+    yet used UUIDs for characteristic and service types.
+
+    In general, each service may consist of one or more characteristics. A characteristic
+    contains data and can be further described by descriptors, which provide additional
+    information or means of manipulating the characteristic. All services, characteristics and
+    descriptors are recognized by their 128-bit UUID. Finally, it is possible to include
+    services inside of services (see picture below).
+
+    \image peripheral-structure.png
+
+    \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.
+
+    \note As of Qt 5.4 the Qt Bluetooth Low Energy API is in tech preview mode and supports Linux
+    with BlueZ 4 & 5. Only the last versions of Bluez 4.x (v 4.101 confirmed to work) and Linux kernels
+    from version 3.5 onwards support this feature.
+
+    \section2 Establishing a Connection
+
+    To be able to read and write the characteristics of the Bluetooth Low Energy peripheral device,
+    it is necessary to find and connect the device. This requires the peripheral device to advertise
+    its presence and services. We start the device discovery with the help of the
+    \l QBluetoothDeviceDiscoveryAgent class. We connect to its \l {QBluetoothDeviceDiscoveryAgent::deviceDiscovered()}
+    signal and start the search with \l {QBluetoothDeviceDiscoveryAgent::start()}{start()}:
+
+    \snippet heartlistener/heartrate.cpp devicediscovery-1
+    \snippet heartlistener/heartrate.cpp devicediscovery-2
+
+    Since we are only interested in Low Energy devices we filter the device type within the
+    receiving slot. The device type can be ascertained using the \l QBluetoothDeviceInfo::coreConfigurations()
+    flag:
+
+    \snippet heartlistener/heartrate.cpp devicediscovery-3
+    \snippet heartlistener/heartrate.cpp devicediscovery-4
+
+    Once the address of the peripheral device is known we use the \l QLowEnergyController class.
+    This class is the entry point for all Bluetooth Low Energy development. The  constructor of the class
+    accepts the remote device's \l QBluetoothAddress. Finally we set up the customary slots and
+    directly connect to the device using
+    \l {QLowEnergyController::connectToDevice()}{connectToDevice()}:
+
+    \snippet heartlistener/heartrate.cpp Connect signals
+
+    \section2 Service Search
+
+    As soon as the connection is established we initiate the service discovery:
+
+    \snippet heartlistener/heartrate.cpp Connecting to service
+
+    The \c serviceDiscovered() slot below is triggered as a result of the
+    \l {QLowEnergyController::serviceDiscovered()} signal and provides an intermittent progress report.
+    Since we are talking about the heart listener app which monitors HeartRate devices in the vicinity
+    we ignore any service that is not of type \l QBluetoothUuid::HeartRate.
+
+    \snippet heartlistener/heartrate.cpp Filter HeartRate service 1
+
+    Eventually the \l {QLowEnergyController::discoveryFinished()} signal is emitted to indicate
+    the successful completion of the service discovery. Provided a HeartRate service was found,
+    a \l QLowEnergyService instance is created to represent the service. The returned service object
+    provides the required signals for update notifications and the discovery of service details
+    is triggered using \l QLowEnergyService::discoverDetails():
+
+    \snippet heartlistener/heartrate.cpp Filter HeartRate service 2
+
+    During the detail search the service's \l {QLowEnergyService::state()}{state()} transitions
+    from \l {QLowEnergyService::DiscoveryRequired}{DiscoveryRequired} to
+    \l {QLowEnergyService::DiscoveringServices}{DiscoveringServices} and eventually ends with
+    \l {QLowEnergyService::ServiceDiscovered}{ServiceDiscovered}:
+
+    \snippet heartlistener/heartrate.cpp Find HRM characteristic
+
+    \section2 Interaction with the Peripheral Device
+
+    In the code example above, the desired characteristic is of type
+    \l {QBluetoothUuid::HeartRateMeasurement}{HeartRateMeasurement}. Since the application measures
+    the heart rate changes, it must enable change notifications for the characteristic.
+    Note that not all characteristics provide change notifications. Since the HeartRate characteristic
+    has been standardized it is possible to assume that notifications can be received. Ultimately
+    \l QLowEnergyCharacteristic::properties() must have the \l {QLowEnergyCharacteristic::Notify} flag
+    set and a descriptor of type \l {QBluetoothUuid::ClientCharacteristicConfiguration} must exist to confirm
+    the availability of an appropriate notification.
+
+    Finally, we process the value of the HeartRate characteristic, as per Bluetooth Low Energy standard:
+
+    \snippet heartlistener/heartrate.cpp Reading value 1
+    \snippet heartlistener/heartrate.cpp Reading value 2
+
+    In general a characteristic value is a series of bytes. The precise interpretation of
+    those bytes depends on the characteristic type and value structure.
+    A significant number has been standardized by the
+    \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.
+*/
diff --git a/src/bluetooth/doc/src/bluetooth-overview.qdoc b/src/bluetooth/doc/src/bluetooth-overview.qdoc
index e20a1d22..81d6270a 100644
--- a/src/bluetooth/doc/src/bluetooth-overview.qdoc
+++ b/src/bluetooth/doc/src/bluetooth-overview.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Copyright (C) 2014 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.
@@ -109,64 +109,7 @@
 
     \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, and the server processes them. Each command is
-    usually answered by a reply.
-
-    Each BLE service may consist of one or more characteristics. A characteristic
-    contains data  and can be further described by descriptors, which provide additional
-    information or means of manipulating the characteristic. All services, characteristics and
-    descriptors are recognized by their 128bits UUIDs. Further details on known uuids can be found
-    in \l QBluetoothUuid.
-
-    To be able to read and write characteristics, it is necessary to connect to the LE service.
-
-    \snippet heartlistener/heartrate.cpp Connect signals
-
-    We start a service discovery with a \l QBluetoothServiceDiscoveryAgent class and connect its
-    \l {QBluetoothServiceDiscoveryAgent::}{serviceDiscovered()} signal. Within the receiving slot we connect to the desired service.
-    \l QLowEnergyController is used to connect or disconnect to services, emits service-related value changes
-    and propagates errors in relation to the service management.
-
-    Even though it is possible to connect to an LE service before the service scan is done,
-    it is advisable to delay until after the service search has finished.
-
-    \snippet heartlistener/heartrate.cpp Connecting to service
-
-    In the code example above, the desired characteristics is of type
-    \l {QBluetoothUuid::HeartRateMeasurement}{HeartRateMeasurement}. Since the application measures
-    the heart rate changes, it must enable change notifications for the characteristic.
-    Note that not all characteristics provide change notifications. Since the HeartRate characteristic
-    has been standardized it is possible to assume that notifications can be received. Ultimately
-    \l QLowEnergyCharacteristicInfo::isNotificationCharacteristic() must return \c true to
-    verify the availability of notifications.
-
-    Finally, we process the value of the HeartRate characteristic, as per Bluetooth Low Energy standard:
-
-    \snippet heartlistener/heartrate.cpp Reading value
-
-    In general a characterisitic value is a series of hexadecimal numbers. The precise interpretation of
-    those hexadecimal numbers depends on the characteristic type and its value structure.
-    A significant number has been standardized by the
-    \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.
+    Bluetooth Low Energy, also known as Bluetooth Smart, is a new technology enabling
+    devices with low energy consumption to communicate with each other. More details about
+    this technology and the related Qt APIs can be found in the \l {Bluetooth Low Energy Overview}.
 */