Qt 5.6 | Qt Bluetooth | C++ Classes | QLowEnergyController

Qt 5.6.3 Reference Documentation

# QLowEnergyController Class

The QLowEnergyController class provides access to Bluetooth Low Energy Devices. More...

Header: | #include <QLowEnergyController>
qmake: | QT += bluetooth
Since: | Qt 5.4

- List of all members, including inherited members
- Obsolete members

## Public Types

enum | ControllerState { UnconnectedState, ConnectingState, ConnectedState, DiscoveringState, DiscoveredState, ClosingState }
enum | Error { NoError, UnknownError, UnknownRemoteDeviceError, NetworkError, InvalidBluetoothAdapterError, ConnectionError }
enum | RemoteAddressType { PublicAddress, RandomAddress }

## Public Functions

| QLowEnergyController(const QBluetoothDeviceInfo &remoteDeviceInfo, QObject *parent = Q_NULLPTR)
| ~QLowEnergyController()
void | connectToDevice()
QLowEnergyService * | createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = Q_NULLPTR)
void | disconnectFromDevice()
void | discoverServices()
Error | error() const
QString | errorString() const
QBluetoothAddress | localAddress() const
QBluetoothAddress | remoteAddress() const
RemoteAddressType | remoteAddressType() const
QString | remoteName() const
QList<QBluetoothUuid> | services() const
void | setRemoteAddressType(RemoteAddressType type)
ControllerState | state() const

## Signals

void | connected()
void | disconnected()
void | discoveryFinished()
void | error(QLowEnergyController::Error newError)
void | serviceDiscovered(const QBluetoothUuid &newService)
void | stateChanged(QLowEnergyController::ControllerState state)

## 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 some platforms such as a BlueZ based Linux cannot maintain two connected instances of QLowEnergyController to the same remote device. In such cases the second call to connectToDevice() may fail. This limitation may disappear at some stage in the future. 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.

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.
`QLowEnergyController::ConnectionError` | `5` | The attempt to connect to the remote device failed. This value was introduced by Qt 5.5.

### 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 QBluetoothDeviceInfo &remoteDeviceInfo, QObject *parent = Q_NULLPTR)

Constructs a new instance of this class with parent.

The remoteDeviceInfo must contain the details 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.

This function was introduced in Qt 5.5.

### 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 not equal to UnconnectedState. The connected() signal is emitted once the connection is successfully established.

On Linux/BlueZ systems, it is not possible to connect to the same remote device using two instances of this class. The second call to this function may fail with an error. This limitation may be removed in future releases.

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 = Q_NULLPTR)

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.

This function does nothing if the controller is in the UnconnectedState.

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.

Note: Some platforms internally cache the service list of a device which was discovered in the past. This can be problematic if the remote device changed its list of services or their inclusion tree. If this behavior is a problem, the best workaround is to temporarily turn Bluetooth off. This causes a reset of the cache data. Currently Android exhibits such a cache behavior.

### `[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.

Note: Signal error is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

      connect(lowEnergyController, static_cast<void(QLowEnergyController::*)(QLowEnergyController::Error)>(&QLowEnergyController::error),
          [=](QLowEnergyController::Error newError){ /* ... */ });

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().

### QString QLowEnergyController::remoteName() const

Returns the name of the remote Bluetooth Low Energy device.

This function was introduced in Qt 5.5.

### `[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().