Qt Bluetooth Overview

With the Qt Bluetooth API typical use cases are:

Retrieve information about the local Bluetooth device.
Scan for other Bluetooth devices in range and retrieve information about them.
Push files to remote devices using the OBEX Object Push Profile (OPP)
Connect to remote devices through a RFCOMM channel using the Serial Port Profile (SPP).
Create a RFCOMM server that allows incoming connections using SPP.
Retrieve specification about Bluetooth Low Energy device.
Connect to Bluetooth Low Energy device.
Receive advertisement from Bluetooth Low Energy device.

Note that the Object Push Profile is not supported on Android and Windows.

Note: Parts of RFCOMM functionality cannot be configured by Qt on Windows. A service's ServiceClassIds and ProtocolDescriptorList are filled automatically. Therefore, registering a service with custom values for these fields might not yield the expected result on Windows.

Note: The Received Signal Strength Indicator (RSSI), as well as the Manufacturer Specific Data advertised by Bluetooth LE devices are not supported by the Win32 backend. Also, it is only possible to find devices that have been previously paired through Windows Settings.

The following sections describe how to use the Qt Bluetooth C++ API classes for the above use cases.

Retrieving Local Device Information

The Qt Bluetooth API has three main purposes. The first one is to obtain local and remote device information. The first steps in retrieving device information are to check if Bluetooth is available on the device and read the local device address and name. QBluetoothLocalDevice is the class that provides all of this information. Additionally you can use it to turn Bluetooth on/off, set the visibility of the device and determine the current connections.

 QBluetoothLocalDevice localDevice;
 QString localDeviceName;

 // Check if Bluetooth is available on this device
 if (localDevice.isValid()) {

     // Turn Bluetooth on
     localDevice.powerOn();

     // Read local device name
     localDeviceName = localDevice.name();

     // Make it visible to others
     localDevice.setHostMode(QBluetoothLocalDevice::HostDiscoverable);

     // Get connected devices
     QList<QBluetoothAddress> remotes;
     remotes = localDevice.connectedDevices();
 }

Scanning for Bluetooth Devices

Similar to the QBluetoothLocalDevice, the API offers QBluetoothDeviceInfo which provides similar information for remote devices. Although you can just create QBluetoothDeviceInfo objects on your own and fill them with data, the easier way is to use the QBluetoothDeviceDiscoveryAgent to start an automated search for visible Bluetooth devices within the connectable range.

 void MyClass::startDeviceDiscovery()
 {

     // Create a discovery agent and connect to its signals
     QBluetoothDeviceDiscoveryAgent *discoveryAgent = new QBluetoothDeviceDiscoveryAgent(this);
     connect(discoveryAgent, SIGNAL(deviceDiscovered(QBluetoothDeviceInfo)),
             this, SLOT(deviceDiscovered(QBluetoothDeviceInfo)));

     // Start a discovery
     discoveryAgent->start();

     //...
 }

 // In your local slot, read information about the found devices
 void MyClass::deviceDiscovered(const QBluetoothDeviceInfo &device)
 {
     qDebug() << "Found new device:" << device.name() << '(' << device.address().toString() << ')';
 }

Pushing Files to Remote Devices

Once the desired device was found, there are two main use cases provided by Qt Bluetooth. The simpler one is to send files via the Obex Object Push Profile (OPP). As the name describes, this profile can push files from one device to another. Currently it is not possible to pull files or browse the remote file system. The profile does not require the two devices to be paired before exchanging data. To push files to remote devices, create a QBluetoothTransferRequest and ask the QBluetoothTransferManager to push the file contained in the request by calling its put() function.

 // Create a transfer manager
 QBluetoothTransferManager *transferManager = new QBluetoothTransferManager(this);

 // Create the transfer request and file to be sent
 QBluetoothAddress remoteAddress("00:11:22:33:44:55:66");
 QBluetoothTransferRequest request(remoteAddress);
 QFile *file = new QFile("testfile.txt");

 // Ask the transfer manager to send it
 QBluetoothTransferReply *reply = transferManager->put(request, file);
 if (reply->error() == QBluetoothTransferReply::NoError) {

     // Connect to the reply's signals to be informed about the status and do cleanups when done
     QObject::connect(reply, SIGNAL(finished(QBluetoothTransferReply*)),
                      this, SLOT(transferFinished(QBluetoothTransferReply*)));
     QObject::connect(reply, SIGNAL(error(QBluetoothTransferReply::TransferError)),
                      this, SLOT(error(QBluetoothTransferReply::TransferError)));
 } else {
     qWarning() << "Cannot push testfile.txt:" << reply->errorString();
 }

Exchanging Data Between Devices

The more flexible approach for communication between two Bluetooth enabled devices, is to create a virtual serial port connection and freely exchange data over that connection. This can be done by the Serial Port Profile (SPP). The Serial Port Profile emulates a serial connection over the Bluetooth transport protocol RFCOMM.

To be able to receive incoming SPP connections, you need to listen to incoming connections using QBluetoothServer.

 rfcommServer = new QBluetoothServer(QBluetoothServiceInfo::RfcommProtocol, this);
 connect(rfcommServer, &QBluetoothServer::newConnection,
         this, QOverload<>::of(&ChatServer::clientConnected));
 bool result = rfcommServer->listen(localAdapter);
 if (!result) {
     qWarning() << "Cannot bind chat server to" << localAdapter.toString();
     return;
 }

Connect to this server from another device playing the client role by using a QBluetoothSocket:

 void ChatClient::startClient(const QBluetoothServiceInfo &remoteService)
 {
     if (socket)
         return;

     // Connect to service
     socket = new QBluetoothSocket(QBluetoothServiceInfo::RfcommProtocol);
     qDebug() << "Create socket";
     socket->connectToService(remoteService);
     qDebug() << "ConnectToService done";

     connect(socket, &QBluetoothSocket::readyRead, this, &ChatClient::readSocket);
     connect(socket, &QBluetoothSocket::connected, this, QOverload<>::of(&ChatClient::connected));
     connect(socket, &QBluetoothSocket::disconnected, this, &ChatClient::disconnected);
     connect(socket, QOverload<QBluetoothSocket::SocketError>::of(&QBluetoothSocket::error),
             this, &ChatClient::onSocketErrorOccurred);

 }

Using such a connection allows to exchange any form of data in both directions. It is perfectly suited for gaming or for syncing the state between two instances of an application on two devices. For more detailed descriptions on how to configure the server and client, please refer to the detailed description sections in the QBluetoothServer and QBluetoothSocket classes. A good example to start with SPP is the Bluetooth Chat example.

Bluetooth Low Energy

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 Bluetooth Low Energy Overview.

Contents

Qt Bluetooth Overview

Retrieving Local Device Information

Scanning for Bluetooth Devices

Pushing Files to Remote Devices

Exchanging Data Between Devices

Bluetooth Low Energy