QLowEnergyController Class
The QLowEnergyController class provides access to Bluetooth Low Energy Devices. More...
| Header: | #include <QLowEnergyController> |
| qmake: | QT += bluetooth |
| Since: | Qt 5.4 |
| Inherits: | QObject. |
Public Types
| enum | ControllerState { UnconnectedState, ConnectingState, ConnectedState, DiscoveringState, DiscoveredState, ClosingState } |
| enum | Error { NoError, UnknownError, UnknownRemoteDeviceError, NetworkError, InvalidBluetoothAdapterError } |
| enum | RemoteAddressType { PublicAddress, RandomAddress } |
Public Functions
| QLowEnergyController(const QBluetoothAddress & remoteDevice, QObject * parent = 0) | |
| QLowEnergyController(const QBluetoothAddress & remoteDevice, const QBluetoothAddress & localDevice, QObject * parent = 0) | |
| ~QLowEnergyController() | |
| void | connectToDevice() |
| QLowEnergyService * | createServiceObject(const QBluetoothUuid & serviceUuid, QObject * parent = 0) |
| void | disconnectFromDevice() |
| void | discoverServices() |
| Error | error() const |
| QString | errorString() const |
| QBluetoothAddress | localAddress() const |
| QBluetoothAddress | remoteAddress() const |
| RemoteAddressType | remoteAddressType() const |
| QList<QBluetoothUuid> | services() const |
| void | setRemoteAddressType(RemoteAddressType type) |
| ControllerState | state() const |
- 31 public functions inherited from QObject
Signals
| void | connected() |
| void | disconnected() |
| void | discoveryFinished() |
| void | error(QLowEnergyController::Error newError) |
| void | serviceDiscovered(const QBluetoothUuid & newService) |
| void | stateChanged(QLowEnergyController::ControllerState state) |
- 2 signals inherited from QObject
Additional Inherited Members
- 1 property inherited from QObject
- 1 public slot inherited from QObject
- 11 static public members inherited from QObject
- 9 protected functions inherited from QObject
Detailed Description
The QLowEnergyController class provides access to Bluetooth Low Energy Devices.
QLowEnergyController acts as the entry point for Bluetooth Low Energy development. Each QLowEnergyController instance acts as placeholder towards a remote Low Energy device enabling connection control, service discovery and state tracking.
Bluetooth Low Energy defines two types of devices; the peripheral and the central. Each role performs a different task. The peripheral device provides data which is utilized by central devices. An example might be a humidity sensor which measures the moisture in a winter garden. A device such as a mobile phone might read the sensor's value and display it to the user in the greater context of all sensors in the same environment. In this case the sensor is the peripheral device and the mobile phone acts as the central device.
At the moment Qt only supports the central role and therefore the remote device can only be a device acting as a peripheral. This implies that the local device acts within the boundaries of the central role as per the Bluetooth 4.0 specification.
The first step is to establish a connection via connectToDevice(). Once the connection has been established, the controller's state() changes to QLowEnergyController::ConnectedState and the connected() signal is emitted. It is important to mention that the remote device can usually only be connected to a single device. Therefore it is not possible to have multiple instances of this class being connected to the same remote device. The disconnectFromDevice() function is used to break the existing connection.
The second step after establishing the connection is to discover the services offered by the remote peripheral device. This process is started via discoverServices() and has finished once the discoveryFinished() signal has been emitted. The discovered services can be enumerated via services().
The last step is to create service objects. The createServiceObject() function acts as factory for each service object and expects the service UUID as parameter. The calling context should take ownership of the returned QLowEnergyService instance.
Any QLowEnergyService, QLowEnergyCharacteristic or QLowEnergyDescriptor instance which is later created from this controller's connection becomes invalid as soon as the controller disconnects from the remote Bluetooth Low Energy device.
Note: This class is provided by Qt 5.4 as part of a Bluetooth Low Energy Tech Preview. Some API elements may change until the final release of the feature.
See also QLowEnergyService, QLowEnergyCharacteristic, and QLowEnergyDescriptor.
Member Type Documentation
enum QLowEnergyController::ControllerState
Indicates the state of the controller object.
| Constant | Value | Description |
|---|---|---|
QLowEnergyController::UnconnectedState | 0 | The controller is not connected to a remote device. |
QLowEnergyController::ConnectingState | 1 | The controller is attempting to connect to a remote device. |
QLowEnergyController::ConnectedState | 2 | The controller is connected to a remote device. |
QLowEnergyController::DiscoveringState | 3 | The controller is retrieving the list of services offered by the remote device. |
QLowEnergyController::DiscoveredState | 4 | The controller has discovered all services offered by the remote device. |
QLowEnergyController::ClosingState | 5 | The controller is about to be disconnected from the remote device. |
enum QLowEnergyController::Error
Indicates all possible error conditions found during the controller's existence.
| Constant | Value | Description |
|---|---|---|
QLowEnergyController::NoError | 0 | No error has occurred. |
QLowEnergyController::UnknownError | 1 | An unknown error has occurred. |
QLowEnergyController::UnknownRemoteDeviceError | 2 | The remote Bluetooth Low Energy device with the address passed to the constructor of this class cannot be found. |
QLowEnergyController::NetworkError | 3 | The attempt to read from or write to the remote device failed. |
QLowEnergyController::InvalidBluetoothAdapterError | 4 | The local Bluetooth device with the address passed to the constructor of this class cannot be found or there is no local Bluetooth device. |
enum QLowEnergyController::RemoteAddressType
Indicates what type of Bluetooth address the remote device uses.
| Constant | Value | Description |
|---|---|---|
QLowEnergyController::PublicAddress | 0 | The peripheral uses a public Bluetooth address. |
QLowEnergyController::RandomAddress | 1 | A random address is a Bluetooth Low Energy security feature. Peripherals using such addresses may frequently change their Bluetooth address. This information is needed when trying to connect to a peripheral. |
Member Function Documentation
QLowEnergyController::QLowEnergyController(const QBluetoothAddress & remoteDevice, QObject * parent = 0)
Constructs a new instance of this class with parent.
The remoteDevice must contain the address of the remote Bluetooth Low Energy device to which this object should attempt to connect later on.
The controller uses the local default Bluetooth adapter for the connection management.
QLowEnergyController::QLowEnergyController(const QBluetoothAddress & remoteDevice, const QBluetoothAddress & localDevice, QObject * parent = 0)
Constructs a new instance of this class with parent.
The remoteDevice must contain the address of the remote Bluetooth Low Energy device to which this object should attempt to connect later on.
The connection is established via localDevice. If localDevice is invalid, the local default device is automatically selected. If localDevice specifies a local device that is not a local Bluetooth adapter, error() is set to InvalidBluetoothAdapterError once connectToDevice() is called.
QLowEnergyController::~QLowEnergyController()
Destroys the QLowEnergyController instance.
void QLowEnergyController::connectToDevice()
Connects to the remote Bluetooth Low Energy device.
This function does nothing if the controller's state() is UnconnectedState. The connected() signal is emitted once the connection is successfully established.
See also disconnectFromDevice().
[signal] void QLowEnergyController::connected()
This signal is emitted when the controller successfully connects to the remote Low Energy device.
QLowEnergyService * QLowEnergyController::createServiceObject(const QBluetoothUuid & serviceUuid, QObject * parent = 0)
Creates an instance of the service represented by serviceUuid. The serviceUuid parameter must have been obtained via services().
The caller takes ownership of the returned pointer and may pass a parent parameter as default owner.
This function returns a null pointer if no service with serviceUuid can be found on the remote device or the controller is disconnected.
This function can return instances for secondary services too. The include relationships between services can be expressed via QLowEnergyService::includedServices().
If this function is called multiple times using the same service UUID, the returned QLowEnergyService instances share their internal data. Therefore if one of the instances initiates the discovery of the service details, the other instances automatically transition into the discovery state too.
See also services().
void QLowEnergyController::disconnectFromDevice()
Disconnects from the remote device.
Any QLowEnergyService, QLowEnergyCharacteristic or QLowEnergyDescriptor instance that resulted from the current connection is automatically invalidated. Once any of those objects become invalid they remain invalid even if this controller object reconnects.
See also connectToDevice().
[signal] void QLowEnergyController::disconnected()
This signal is emitted when the controller disconnects from the remote Low Energy device.
void QLowEnergyController::discoverServices()
Initiates the service discovery process.
The discovery progress is indicated via the serviceDiscovered() signal. The discoveryFinished() signal is emitted when the process has finished.
If the controller instance is not connected or the controller has performed the service discovery already this function will do nothing.
[signal] void QLowEnergyController::discoveryFinished()
This signal is emitted when the running service discovery finishes. The signal is not emitted if the discovery process finishes with an error.
See also discoverServices() and error().
Error QLowEnergyController::error() const
Returns the last occurred error or NoError.
[signal] void QLowEnergyController::error(QLowEnergyController::Error newError)
This signal is emitted when an error occurs. The newError parameter describes the error that occurred.
See also error() and errorString().
QString QLowEnergyController::errorString() const
Returns a textual representation of the last occurred error. The string is translated.
QBluetoothAddress QLowEnergyController::localAddress() const
Returns the address of the local Bluetooth adapter being used for the communication.
If this class instance was requested to use the default adapter but there was no default adapter when creating this class instance, the returned QBluetoothAddress will be null.
See also QBluetoothAddress::isNull().
QBluetoothAddress QLowEnergyController::remoteAddress() const
Returns the address of the remote Bluetooth Low Energy device.
RemoteAddressType QLowEnergyController::remoteAddressType() const
Returns the type of remoteAddress(). By default, this value is initialized to PublicAddress.
See also setRemoteAddressType().
[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid & newService)
This signal is emitted each time a new service is discovered. The newService parameter contains the UUID of the found service.
See also discoverServices() and discoveryFinished().
QList<QBluetoothUuid> QLowEnergyController::services() const
Returns the list of services offered by the remote device.
The list contains all primary and secondary services.
See also createServiceObject().
void QLowEnergyController::setRemoteAddressType(RemoteAddressType type)
Sets the remote address type. The type is required to connect to the remote Bluetooth Low Energy device.
See also remoteAddressType().
ControllerState QLowEnergyController::state() const
Returns the current state of the controller.
See also stateChanged().
[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)
This signal is emitted when the controller's state changes. The new state can also be retrieved via state().
See also state().
© 2015 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.