<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- bluetooth-overview.qdoc -->
<title>Qt Bluetooth Overview | Qt Bluetooth 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtbluetooth-index.html">Qt Bluetooth</a></td><td >Qt Bluetooth Overview</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtbluetooth-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#retrieving-local-device-information">Retrieving Local Device Information</a></li>
<li class="level1"><a href="#scanning-for-bluetooth-devices">Scanning for Bluetooth Devices</a></li>
<li class="level1"><a href="#pushing-files-to-remote-devices">Pushing Files to Remote Devices</a></li>
<li class="level1"><a href="#exchanging-data-between-devices">Exchanging Data Between Devices</a></li>
<li class="level1"><a href="#bluetooth-low-energy">Bluetooth Low Energy</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Bluetooth Overview</h1>
<span class="subtitle"></span>
<!-- $$$qtbluetooth-overview.html-description -->
<div class="descr"> <a name="details"></a>
<p>With the Qt Bluetooth API typical use cases are:</p>
<ul>
<li>Retrieve information about the local Bluetooth device.</li>
<li>Scan for other Bluetooth devices in range and retrieve information about them.</li>
<li>Push files to remote devices using the OBEX Object Push Profile (OPP)</li>
<li>Connect to remote devices through a RFCOMM channel using the Serial Port Profile (SPP).</li>
<li>Create a RFCOMM server that allows incoming connections using SPP.</li>
<li>Retrieve specification about Bluetooth Low Energy device.</li>
<li>Connect to Bluetooth Low Energy device.</li>
<li>Receive advertisement from Bluetooth Low Energy device.</li>
</ul>
<p>Note that the Object Push Profile is not supported on Android and Windows.</p>
<p>Note that parts of RFCOMM functionality cannot be configured by Qt on Windows. A service's ServiceClassIds and ProtocolDescriptorList are filled automatically by Windows. Therefore registering a service with custom values for these fields might not yield the expected result on Windows.</p>
<p>The following sections describe how to use the Qt Bluetooth C++ API classes for the above use cases.</p>
<a name="retrieving-local-device-information"></a>
<h2 id="retrieving-local-device-information">Retrieving Local Device Information</h2>
<p>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. <a href="qbluetoothlocaldevice.html">QBluetoothLocalDevice</a> 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.</p>
<pre class="cpp">
<span class="type"><a href="qbluetoothlocaldevice.html">QBluetoothLocalDevice</a></span> localDevice;
<span class="type">QString</span> localDeviceName;
<span class="comment">// Check if Bluetooth is available on this device</span>
<span class="keyword">if</span> (localDevice<span class="operator">.</span>isValid()) {
<span class="comment">// Turn Bluetooth on</span>
localDevice<span class="operator">.</span>powerOn();
<span class="comment">// Read local device name</span>
localDeviceName <span class="operator">=</span> localDevice<span class="operator">.</span>name();
<span class="comment">// Make it visible to others</span>
localDevice<span class="operator">.</span>setHostMode(<span class="type"><a href="qbluetoothlocaldevice.html">QBluetoothLocalDevice</a></span><span class="operator">::</span>HostDiscoverable);
<span class="comment">// Get connected devices</span>
<span class="type">QList</span><span class="operator"><</span><span class="type"><a href="qbluetoothaddress.html">QBluetoothAddress</a></span><span class="operator">></span> remotes;
remotes <span class="operator">=</span> localDevice<span class="operator">.</span>connectedDevices();
}
</pre>
<a name="scanning-for-bluetooth-devices"></a>
<h2 id="scanning-for-bluetooth-devices">Scanning for Bluetooth Devices</h2>
<p>Similar to the <a href="qbluetoothlocaldevice.html">QBluetoothLocalDevice</a>, the API offers <a href="qbluetoothdeviceinfo.html">QBluetoothDeviceInfo</a> which provides similar information for remote devices. Although you can just create <a href="qbluetoothdeviceinfo.html">QBluetoothDeviceInfo</a> objects on your own and fill them with data, the easier way is to use the <a href="qbluetoothdevicediscoveryagent.html">QBluetoothDeviceDiscoveryAgent</a> to start an automated search for visible Bluetooth devices within the connectable range.</p>
<pre class="cpp">
<span class="type">void</span> MyClass<span class="operator">::</span>startDeviceDiscovery()
{
<span class="comment">// Create a discovery agent and connect to its signals</span>
<span class="type"><a href="qbluetoothdevicediscoveryagent.html">QBluetoothDeviceDiscoveryAgent</a></span> <span class="operator">*</span>discoveryAgent <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qbluetoothdevicediscoveryagent.html">QBluetoothDeviceDiscoveryAgent</a></span>(<span class="keyword">this</span>);
connect(discoveryAgent<span class="operator">,</span> SIGNAL(deviceDiscovered(<span class="type"><a href="qbluetoothdeviceinfo.html">QBluetoothDeviceInfo</a></span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(deviceDiscovered(<span class="type"><a href="qbluetoothdeviceinfo.html">QBluetoothDeviceInfo</a></span>)));
<span class="comment">// Start a discovery</span>
discoveryAgent<span class="operator">-</span><span class="operator">></span>start();
<span class="comment">//...</span>
}
<span class="comment">// In your local slot, read information about the found devices</span>
<span class="type">void</span> MyClass<span class="operator">::</span>deviceDiscovered(<span class="keyword">const</span> <span class="type"><a href="qbluetoothdeviceinfo.html">QBluetoothDeviceInfo</a></span> <span class="operator">&</span>device)
{
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Found new device:"</span> <span class="operator"><</span><span class="operator"><</span> device<span class="operator">.</span>name() <span class="operator"><</span><span class="operator"><</span> <span class="char">'('</span> <span class="operator"><</span><span class="operator"><</span> device<span class="operator">.</span>address()<span class="operator">.</span>toString() <span class="operator"><</span><span class="operator"><</span> <span class="char">')'</span>;
}
</pre>
<a name="pushing-files-to-remote-devices"></a>
<h2 id="pushing-files-to-remote-devices">Pushing Files to Remote Devices</h2>
<p>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 <a href="qbluetoothtransferrequest.html">QBluetoothTransferRequest</a> and ask the <a href="qbluetoothtransfermanager.html">QBluetoothTransferManager</a> to push the file contained in the request by calling its <a href="qbluetoothtransfermanager.html#put">put()</a> function.</p>
<pre class="cpp">
<span class="comment">// Create a transfer manager</span>
<span class="type"><a href="qbluetoothtransfermanager.html">QBluetoothTransferManager</a></span> <span class="operator">*</span>transferManager <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qbluetoothtransfermanager.html">QBluetoothTransferManager</a></span>(<span class="keyword">this</span>);
<span class="comment">// Create the transfer request and file to be sent</span>
<span class="type"><a href="qbluetoothaddress.html">QBluetoothAddress</a></span> remoteAddress(<span class="string">"00:11:22:33:44:55:66"</span>);
<span class="type"><a href="qbluetoothtransferrequest.html">QBluetoothTransferRequest</a></span> request(remoteAddress);
<span class="type">QFile</span> <span class="operator">*</span>file <span class="operator">=</span> <span class="keyword">new</span> <span class="type">QFile</span>(<span class="string">"testfile.txt"</span>);
<span class="comment">// Ask the transfer manager to send it</span>
<span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span> <span class="operator">*</span>reply <span class="operator">=</span> transferManager<span class="operator">-</span><span class="operator">></span>put(request<span class="operator">,</span> file);
<span class="keyword">if</span> (reply<span class="operator">-</span><span class="operator">></span>error() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span><span class="operator">::</span>NoError) {
<span class="comment">// Connect to the reply's signals to be informed about the status and do cleanups when done</span>
<span class="type">QObject</span><span class="operator">::</span>connect(reply<span class="operator">,</span> SIGNAL(finished(<span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span><span class="operator">*</span>))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(transferFinished(<span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span><span class="operator">*</span>)));
<span class="type">QObject</span><span class="operator">::</span>connect(reply<span class="operator">,</span> SIGNAL(error(<span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span><span class="operator">::</span>TransferError))<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> SLOT(error(<span class="type"><a href="qbluetoothtransferreply.html">QBluetoothTransferReply</a></span><span class="operator">::</span>TransferError)));
} <span class="keyword">else</span> {
qWarning() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Cannot push testfile.txt:"</span> <span class="operator"><</span><span class="operator"><</span> reply<span class="operator">-</span><span class="operator">></span>errorString();
}
</pre>
<a name="exchanging-data-between-devices"></a>
<h2 id="exchanging-data-between-devices">Exchanging Data Between Devices</h2>
<p>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.</p>
<p>To be able to receive incoming SPP connections, you need to listen to incoming connections using <a href="qbluetoothserver.html">QBluetoothServer</a>.</p>
<pre class="cpp">
rfcommServer <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qbluetoothserver.html">QBluetoothServer</a></span>(<span class="type"><a href="qbluetoothserviceinfo.html">QBluetoothServiceInfo</a></span><span class="operator">::</span>RfcommProtocol<span class="operator">,</span> <span class="keyword">this</span>);
connect(rfcommServer<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qbluetoothserver.html">QBluetoothServer</a></span><span class="operator">::</span>newConnection<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> <span class="type">QOverload</span><span class="operator"><</span><span class="operator">></span><span class="operator">::</span>of(<span class="operator">&</span>ChatServer<span class="operator">::</span>clientConnected));
bool result <span class="operator">=</span> rfcommServer<span class="operator">-</span><span class="operator">></span>listen(localAdapter);
<span class="keyword">if</span> (<span class="operator">!</span>result) {
qWarning() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Cannot bind chat server to"</span> <span class="operator"><</span><span class="operator"><</span> localAdapter<span class="operator">.</span>toString();
<span class="keyword">return</span>;
}
</pre>
<p>Connect to this server from another device playing the client role by using a <a href="qbluetoothsocket.html">QBluetoothSocket</a>:</p>
<pre class="cpp">
<span class="type">void</span> ChatClient<span class="operator">::</span>startClient(<span class="keyword">const</span> <span class="type"><a href="qbluetoothserviceinfo.html">QBluetoothServiceInfo</a></span> <span class="operator">&</span>remoteService)
{
<span class="keyword">if</span> (socket)
<span class="keyword">return</span>;
<span class="comment">// Connect to service</span>
socket <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span>(<span class="type"><a href="qbluetoothserviceinfo.html">QBluetoothServiceInfo</a></span><span class="operator">::</span>RfcommProtocol);
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"Create socket"</span>;
socket<span class="operator">-</span><span class="operator">></span>connectToService(remoteService);
qDebug() <span class="operator"><</span><span class="operator"><</span> <span class="string">"ConnectToService done"</span>;
connect(socket<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span><span class="operator">::</span>readyRead<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>ChatClient<span class="operator">::</span>readSocket);
connect(socket<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span><span class="operator">::</span>connected<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="type">QOverload</span><span class="operator"><</span><span class="operator">></span><span class="operator">::</span>of(<span class="operator">&</span>ChatClient<span class="operator">::</span>connected));
connect(socket<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span><span class="operator">::</span>disconnected<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>ChatClient<span class="operator">::</span>disconnected);
connect(socket<span class="operator">,</span> <span class="type">QOverload</span><span class="operator"><</span><span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span><span class="operator">::</span>SocketError<span class="operator">></span><span class="operator">::</span>of(<span class="operator">&</span><span class="type"><a href="qbluetoothsocket.html">QBluetoothSocket</a></span><span class="operator">::</span>error)<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>ChatClient<span class="operator">::</span>onSocketErrorOccurred);
}
</pre>
<p>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 <a href="qbluetoothserver.html">QBluetoothServer</a> and <a href="qbluetoothsocket.html">QBluetoothSocket</a> classes. A good example to start with SPP is the <a href="qtbluetooth-btchat-example.html">Bluetooth Chat</a> example.</p>
<a name="bluetooth-low-energy"></a>
<h2 id="bluetooth-low-energy">Bluetooth Low Energy</h2>
<p>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 <a href="qtbluetooth-le-overview.html">Bluetooth Low Energy Overview</a>.</p>
</div>
<!-- @@@qtbluetooth-overview.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> 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. </p>
</div>
</body>
</html>
