Descripción general de Bluetooth Low Energy
La API Qt Bluetooth de baja energía admite las funciones de periférico/servidor y central/cliente. Es compatible con todas las principales plataformas de Qt. La única excepción es la falta de compatibilidad con la función de periférico en Windows.
¿Qué es Bluetooth Low Energy?
Bluetooth Low Energy, también conocido como Bluetooth Smart, es una tecnología de red informática inalámbrica que se presentó oficialmente en 2011. Funciona en la misma frecuencia de 2,4 GHz que el Bluetooth «clásico». La principal diferencia es, tal y como indica el nombre de la tecnología, su bajo consumo energético. Esto permite que los dispositivos Bluetooth Low Energy funcionen durante meses, e incluso años, con pilas de botón. La tecnología se introdujo con la versión 4.0 de Bluetooth. Los dispositivos compatibles con esta tecnología se denominan «dispositivos Bluetooth Smart Ready». Las características clave de la tecnología son:
- Consumo energético ultrabajo en modo pico, medio y de reposo
- Capacidad para funcionar durante años con pilas de botón estándar
- Bajo coste
- Interoperabilidad entre distintos fabricantes
- Mayor alcance
Bluetooth Low Energy utiliza una arquitectura cliente-servidor. El servidor (también conocido como periférico) ofrece servicios como la temperatura o la frecuencia cardíaca y los difunde. El cliente (conocido como dispositivo central) se conecta al servidor y lee los valores difundidos por este. Un ejemplo podría ser un piso equipado con sensores «Bluetooth Smart Ready», como un termostato o sensores de humedad o presión. Estos sensores son dispositivos periféricos que transmiten los valores ambientales del piso. Al mismo tiempo, un teléfono móvil o un ordenador podría conectarse a dichos sensores, recuperar sus valores y presentárselos al usuario como parte de una aplicación más amplia de control ambiental.
Estructura básica del servicio
Bluetooth Low Energy se basa en dos protocolos: ATT (Protocolo de Atributos) y GATT (Perfil de Atributos Genéricos). Estos especifican las capas de comunicación que utiliza todo dispositivo compatible con Bluetooth Smart Ready.
Protocolo ATT
El componente básico del ATT es un atributo. Cada atributo consta de tres elementos:
- un valor: la carga útil o la información deseada
- un UUID: el tipo de atributo (utilizado por GATT)
- un identificador de 16 bits: un identificador único para el atributo
El servidor almacena los atributos y el cliente utiliza el protocolo ATT para leer y escribir valores en el servidor.
Perfil GATT
GATT define la agrupación de un conjunto de atributos asignando un significado a los UUID predefinidos. La tabla siguiente muestra un ejemplo de servicio que expone la frecuencia cardíaca en un día concreto. Los valores reales se almacenan en las dos características:
| Identificador | UUID | Valor | Descripción |
|---|---|---|---|
| 0x0001 | 0x2800 | UUID 0x180D | Inicio del servicio de frecuencia cardíaca |
| 0x0002 | 0x2803 | UUID 0x2A37, identificador de valor: 0x0003 | Característica de tipo «Medición de la frecuencia cardíaca» (HRM) |
| 0x0003 | 0x2A37 | 65 lpm | Valor de la frecuencia cardíaca |
| 0x0004 | 0x2803 | UUID 0x2A08, identificador de valor: 0x0005 | Característica de tipo Fecha y hora |
| 0x0005 | 0x2A08 | 18/08/2014 11:00 | Fecha y hora de la medición |
| 0x0006 | 0x2800 | UUID xxxxxx | Inicio del siguiente servicio |
| ... | ... | ... | ... |
El GATT especifica que el UUID utilizado anteriormente 0x2800 marca el inicio de una definición de servicio. Todos los atributos que siguen a 0x2800 forman parte del servicio hasta que se encuentre el siguiente 0x2800 o se llegue al final. De manera similar, el conocido UUID 0x2803 indica que hay una característica y que cada una de ellas tiene un tipo que define la naturaleza del valor. El ejemplo anterior utiliza los UUID 0x2A08 (Fecha y hora) y 0x2A37 (Medición de la frecuencia cardíaca). Cada uno de los UUID anteriores ha sido definido por el Bluetooth Special Interest Group y puede consultarse en las especificaciones GATT. Aunque es recomendable utilizar UUID predefinidos cuando estén disponibles, es perfectamente posible utilizar UUID nuevos y aún no utilizados para los tipos de características y servicios.
En general, cada servicio puede constar de una o más características. Una característica contiene datos y puede describirse con mayor detalle mediante descriptores, que proporcionan información adicional o medios para manipular la característica. Todos los servicios, características y descriptores se identifican mediante su UUID de 128 bits. Por último, es posible incluir servicios dentro de otros servicios (véase la imagen siguiente).

Uso de la API de baja energía de Qt Bluetooth
En esta sección se describe cómo utilizar la API de Bluetooth Low Energy que proporciona Qt. En el lado del cliente, la API permite establecer conexiones con dispositivos periféricos, detectar sus servicios, así como leer y escribir datos almacenados en el dispositivo. En el lado del servidor, permite configurar servicios, anunciarlos y recibir notificaciones cuando el cliente escribe características. El código de ejemplo que aparece a continuación se ha extraído de los ejemplos «Heart Rate Game » y «Heart Rate Server ».
Establecimiento de una conexión
Para poder leer y escribir las características del dispositivo periférico Bluetooth Low Energy, es necesario localizarlo y conectarse a él. Para ello, es necesario que el dispositivo periférico anuncie su presencia y sus servicios. Iniciamos la búsqueda de dispositivos con la ayuda de la clase ` QBluetoothDeviceDiscoveryAgent `. Nos conectamos a su señal ` QBluetoothDeviceDiscoveryAgent::deviceDiscovered()` e iniciamos la búsqueda con ` start()`:
m_deviceDiscoveryAgent = new QBluetoothDeviceDiscoveryAgent(this);
m_deviceDiscoveryAgent->setLowEnergyDiscoveryTimeout(15000);
connect(m_deviceDiscoveryAgent, &QBluetoothDeviceDiscoveryAgent::deviceDiscovered,
this, &DeviceFinder::addDevice);
connect(m_deviceDiscoveryAgent, &QBluetoothDeviceDiscoveryAgent::errorOccurred,
this, &DeviceFinder::scanError);
connect(m_deviceDiscoveryAgent, &QBluetoothDeviceDiscoveryAgent::finished,
this, &DeviceFinder::scanFinished);
connect(m_deviceDiscoveryAgent, &QBluetoothDeviceDiscoveryAgent::canceled,
this, &DeviceFinder::scanFinished);
m_deviceDiscoveryAgent->start(QBluetoothDeviceDiscoveryAgent::LowEnergyMethod);Dado que solo nos interesan los dispositivos de baja energía, filtramos el tipo de dispositivo en la ranura de recepción. El tipo de dispositivo se puede determinar mediante el indicador de « QBluetoothDeviceInfo::coreConfigurations()». La señal « deviceDiscovered()» puede emitirse varias veces para un mismo dispositivo a medida que se descubren más detalles. Aquí emparejamos estos descubrimientos de dispositivos para que el usuario solo vea los dispositivos individuales:
void DeviceFinder::addDevice(const QBluetoothDeviceInfo &device)
{
// If device is LowEnergy-device, add it to the list
if (device.coreConfigurations() & QBluetoothDeviceInfo::LowEnergyCoreConfiguration) {
auto devInfo = new DeviceInfo(device);
auto it = std::find_if(m_devices.begin(), m_devices.end(),
[devInfo](DeviceInfo *dev) {
return devInfo->getAddress() == dev->getAddress();
});
if (it == m_devices.end()) {
m_devices.append(devInfo);
} else {
auto oldDev = *it;
*it = devInfo;
delete oldDev;
}
setInfo(tr("Low Energy device found. Scanning more..."));
setIcon(IconProgress);
}
//...
}Una vez conocida la dirección del dispositivo periférico, utilizamos la clase ` QLowEnergyController `. Esta clase es el punto de entrada para todo el desarrollo de Bluetooth Low Energy. El constructor de la clase acepta el ` QBluetoothAddress` del dispositivo remoto. Por último, configuramos los slots habituales y nos conectamos directamente al dispositivo mediante ` connectToDevice()`:
m_control = QLowEnergyController::createCentral(m_currentDevice->getDevice(), this);
connect(m_control, &QLowEnergyController::serviceDiscovered,
this, &DeviceHandler::serviceDiscovered);
connect(m_control, &QLowEnergyController::discoveryFinished,
this, &DeviceHandler::serviceScanDone);
connect(m_control, &QLowEnergyController::errorOccurred, this,
[this](QLowEnergyController::Error error) {
Q_UNUSED(error);
setError("Cannot connect to remote device.");
setIcon(IconError);
});
connect(m_control, &QLowEnergyController::connected, this, [this]() {
setInfo("Controller connected. Search services...");
setIcon(IconProgress);
m_control->discoverServices();
});
connect(m_control, &QLowEnergyController::disconnected, this, [this]() {
setError("LowEnergy controller disconnected");
setIcon(IconError);
});
// Connect
m_control->connectToDevice();Búsqueda de servicios
El fragmento de código anterior muestra cómo la aplicación inicia la búsqueda de servicios una vez establecida la conexión.
La ranura « serviceDiscovered() » que aparece a continuación se activa como resultado de la señal « QLowEnergyController::serviceDiscovered()» y proporciona un informe de progreso intermitente. Dado que estamos hablando de la aplicación «heart listener», que supervisa los dispositivos HeartRate cercanos, ignoramos cualquier servicio que no sea de tipo « QBluetoothUuid::ServiceClassUuid::HeartRate ».
void DeviceHandler::serviceDiscovered(const QBluetoothUuid &gatt)
{
if (gatt == QBluetoothUuid(QBluetoothUuid::ServiceClassUuid::HeartRate)) {
setInfo("Heart Rate service discovered. Waiting for service scan to be done...");
setIcon(IconProgress);
m_foundHeartRateService = true;
}
}Finalmente, se emite la señal QLowEnergyController::discoveryFinished() para indicar que la detección de servicios se ha completado con éxito. Siempre que se haya encontrado un servicio HeartRate, se crea una instancia de QLowEnergyService para representar dicho servicio. El objeto de servicio devuelto proporciona las señales necesarias para las notificaciones de actualización, y la detección de los detalles del servicio se activa mediante QLowEnergyService::discoverDetails():
// If heartRateService found, create new service
if (m_foundHeartRateService)
m_service = m_control->createServiceObject(QBluetoothUuid(QBluetoothUuid::ServiceClassUuid::HeartRate), this);
if (m_service) {
connect(m_service, &QLowEnergyService::stateChanged, this, &DeviceHandler::serviceStateChanged);
connect(m_service, &QLowEnergyService::characteristicChanged, this, &DeviceHandler::updateHeartRateValue);
connect(m_service, &QLowEnergyService::descriptorWritten, this, &DeviceHandler::confirmedDescriptorWrite);
m_service->discoverDetails();
} else {
setError("Heart Rate Service not found.");
setIcon(IconError);
}Durante la búsqueda de detalles, el estado « state » () del servicio pasa de « RemoteService » a « RemoteServiceDiscovering » y, finalmente, termina en « RemoteServiceDiscovered »:
void DeviceHandler::serviceStateChanged(QLowEnergyService::ServiceState s)
{
switch (s) {
case QLowEnergyService::RemoteServiceDiscovering:
setInfo(tr("Discovering services..."));
setIcon(IconProgress);
break;
case QLowEnergyService::RemoteServiceDiscovered:
{
setInfo(tr("Service discovered."));
setIcon(IconBluetooth);
const QLowEnergyCharacteristic hrChar =
m_service->characteristic(QBluetoothUuid(QBluetoothUuid::CharacteristicType::HeartRateMeasurement));
if (!hrChar.isValid()) {
setError("HR Data not found.");
setIcon(IconError);
break;
}
m_notificationDesc = hrChar.descriptor(QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration);
if (m_notificationDesc.isValid())
m_service->writeDescriptor(m_notificationDesc, QByteArray::fromHex("0100"));
break;
}
default:
//nothing for now
break;
}
emit aliveChanged();
}Interacción con el dispositivo periférico
En el ejemplo de código anterior, la característica deseada es de tipo HeartRateMeasurement. Dado que la aplicación mide los cambios en la frecuencia cardíaca, debe habilitar las notificaciones de cambio para dicha característica. Tenga en cuenta que no todas las características proporcionan notificaciones de cambio. Dado que la característica «HeartRate» se ha estandarizado, es posible suponer que se pueden recibir notificaciones. En última instancia, QLowEnergyCharacteristic::properties() debe tener activado el indicador « QLowEnergyCharacteristic::Notify » y debe existir un descriptor de tipo QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration para confirmar la disponibilidad de una notificación adecuada.
Por último, procesamos el valor de la característica HeartRate, según el estándar Bluetooth Low Energy:
void DeviceHandler::updateHeartRateValue(const QLowEnergyCharacteristic &c, const QByteArray &value)
{
// ignore any other characteristic change -> shouldn't really happen though
if (c.uuid() != QBluetoothUuid(QBluetoothUuid::CharacteristicType::HeartRateMeasurement))
return;
auto data = reinterpret_cast<const quint8 *>(value.constData());
quint8 flags = *data;
//Heart Rate
int hrvalue = 0;
if (flags & 0x1) // HR 16 bit? otherwise 8 bit
hrvalue = static_cast<int>(qFromLittleEndian<quint16>(data[1]));
else
hrvalue = static_cast<int>(data[1]);
addMeasurement(hrvalue);
}En general, el valor de una característica es una serie de bytes. La interpretación exacta de esos bytes depende del tipo de característica y de la estructura del valor. La Bluetooth SIG ha estandarizado un número significativo de ellos, mientras que otros pueden seguir un protocolo personalizado. El fragmento de código anterior muestra cómo leer el valor estandarizado de «HeartRate».
Servicios de publicidad
Si estamos implementando una aplicación de servidor GATT en un dispositivo periférico, debemos definir los servicios que queremos ofrecer a los dispositivos centrales y anunciarlos:
QLowEnergyAdvertisingData advertisingData;
advertisingData.setDiscoverability(QLowEnergyAdvertisingData::DiscoverabilityGeneral);
advertisingData.setIncludePowerLevel(true);
advertisingData.setLocalName("HeartRateServer");
advertisingData.setServices(QList<QBluetoothUuid>() << QBluetoothUuid::ServiceClassUuid::HeartRate);
bool errorOccurred = false;
const std::unique_ptr<QLowEnergyController> leController(QLowEnergyController::createPeripheral());
auto errorHandler = [&leController, &errorOccurred](QLowEnergyController::Error errorCode) {
qWarning().noquote().nospace() << errorCode << " occurred: "
<< leController->errorString();
if (errorCode != QLowEnergyController::RemoteHostClosedError) {
qWarning("Heartrate-server quitting due to the error.");
errorOccurred = true;
QCoreApplication::quit();
}
};
QObject::connect(leController.get(), &QLowEnergyController::errorOccurred, errorHandler);
std::unique_ptr<QLowEnergyService> service(leController->addService(serviceData));
leController->startAdvertising(QLowEnergyAdvertisingParameters(), advertisingData,
advertisingData);
if (errorOccurred)
return-1;Ahora los clientes potenciales pueden conectarse a nuestro dispositivo, detectar el servicio proporcionado y registrarse para recibir notificaciones sobre los cambios en el valor de la característica. Esta parte de la API ya se ha tratado en las secciones anteriores.
Implementación de un servicio en el dispositivo periférico
El primer paso consiste en definir el servicio, sus características y sus descriptores. Esto se consigue utilizando las clases QLowEnergyServiceData, QLowEnergyCharacteristicData y QLowEnergyDescriptorData. Estas clases actúan como contenedores o bloques de construcción de la información esencial que conforma el servicio Bluetooth Low Energy que se va a definir. El fragmento de código que se muestra a continuación define un sencillo servicio HeartRate que publica los latidos por minuto medidos. Un ejemplo en el que se podría utilizar un servicio de este tipo es un reloj de pulsera.
QLowEnergyCharacteristicData charData;
charData.setUuid(QBluetoothUuid::CharacteristicType::HeartRateMeasurement);
charData.setValue(QByteArray(2, 0));
charData.setProperties(QLowEnergyCharacteristic::Notify);
const QLowEnergyDescriptorData clientConfig(QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration,
QByteArray(2, 0));
charData.addDescriptor(clientConfig);
QLowEnergyServiceData serviceData;
serviceData.setType(QLowEnergyServiceData::ServiceTypePrimary);
serviceData.setUuid(QBluetoothUuid::ServiceClassUuid::HeartRate);
serviceData.addCharacteristic(charData);El objeto ` serviceData ` resultante puede publicarse tal y como se describe en la sección «Servicios de publicidad» anterior. A pesar de que existe un solapamiento parcial entre la información que contienen ` QLowEnergyServiceData ` y ` QLowEnergyAdvertisingData `, ambas clases cumplen funciones muy diferentes. Los datos de publicidad se envían a los dispositivos cercanos y suelen tener un alcance limitado debido a la restricción de tamaño de 29 bytes. Por lo tanto, no siempre están completos al 100 %. En comparación, los datos de servicio contenidos en QLowEnergyServiceData proporcionan el conjunto completo de datos de servicio y solo se hacen visibles para el cliente que se conecta cuando se ha establecido una conexión con un descubrimiento de servicios activo.
La siguiente sección muestra cómo el servicio puede actualizar el valor de la frecuencia cardíaca. Dependiendo de la naturaleza del servicio, es posible que deba cumplir con la definición oficial de servicio tal y como se establece en https://www.bluetooth.org. Otros servicios pueden ser totalmente personalizados. Se ha adoptado el servicio de frecuencia cardíaca y su especificación se puede consultar en https://www.bluetooth.com/specifications/adopted-specifications.
QTimer heartbeatTimer;
quint8 currentHeartRate = 60;
enum ValueChange { ValueUp, ValueDown } valueChange = ValueUp;
const auto heartbeatProvider = [&service, ¤tHeartRate, &valueChange]() {
QByteArray value;
value.append(char(0)); // Flags that specify the format of the value.
value.append(char(currentHeartRate)); // Actual value.
QLowEnergyCharacteristic characteristic
= service->characteristic(QBluetoothUuid::CharacteristicType::HeartRateMeasurement);
Q_ASSERT(characteristic.isValid());
service->writeCharacteristic(characteristic, value); // Potentially causes notification.
if (currentHeartRate == 60)
valueChange = ValueUp;
else if (currentHeartRate == 100)
valueChange = ValueDown;
if (valueChange == ValueUp)
++currentHeartRate;
else
--currentHeartRate;
};
QObject::connect(&heartbeatTimer, &QTimer::timeout, heartbeatProvider);
heartbeatTimer.start(1000);En general, las actualizaciones de los valores de las características y los descriptores en el dispositivo periférico utilizan los mismos métodos que para conectar dispositivos Bluetooth Low Energy.
Nota: Para utilizar Qt Bluetooth (tanto en el rol central como en el periférico) en iOS, debes proporcionar un archivo Info.plist que contenga la descripción de uso. Según la documentación de CoreBluetooth: tu aplicación se bloqueará si su Info.plist no incluye claves de descripción de uso para los tipos de datos a los que necesita acceder. Para acceder a las API de Core Bluetooth en aplicaciones vinculadas en iOS 13 o versiones posteriores, incluye la clave NSBluetoothAlwaysUsageDescription. En iOS 12 y versiones anteriores, incluye NSBluetoothPeripheralUsageDescription para acceder a los datos de los dispositivos periféricos Bluetooth.
© 2026 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.