Escáner Bluetooth de bajo consumo
Una aplicación diseñada para explorar el contenido de dispositivos periféricos Bluetooth de bajo consumo. El ejemplo muestra el uso de todas las Qt Bluetooth clases de baja energía.
El ejemplo del escáner Bluetooth de bajo consumo muestra cómo desarrollar aplicaciones Bluetooth de bajo consumo utilizando la Qt Bluetooth API. La aplicación abarca la búsqueda de dispositivos de bajo consumo, el escaneo de sus servicios y la lectura de las características y descriptores de los servicios.

El ejemplo presenta las siguientes clases de Qt:
El ejemplo se puede utilizar con cualquier dispositivo periférico Bluetooth de baja energía. Crea una instantánea de todos los servicios, características y descriptores, y se los muestra al usuario. Por lo tanto, la aplicación ofrece una forma sencilla de explorar el contenido que ofrece un dispositivo periférico.
Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en « Examples ». Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecuta el comando « Qt: Open Qt examples » desde Command Palette y selecciona el ejemplo de la lista. Para obtener más información, consulta Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
Solicitar permiso para utilizar Bluetooth
En determinadas plataformas, es necesario conceder explícitamente permisos para utilizar Bluetooth. El ejemplo utiliza el objeto QML ` BluetoothPermission ` para comprobar y solicitar los permisos, si es necesario:
BluetoothPermission {
id: permission
communicationModes: BluetoothPermission.Access
onStatusChanged: {
if (permission.status === Qt.PermissionStatus.Denied)
Device.update = "Bluetooth permission required"
else if (permission.status === Qt.PermissionStatus.Granted)
devicesPage.toggleDiscovery()
}
}El cuadro de diálogo de solicitud de permiso se activa cuando el usuario intenta iniciar la búsqueda de dispositivos, y el estado del permiso es « Undetermined »:
onButtonClick: {
if (permission.status === Qt.PermissionStatus.Undetermined)
permission.request()
else if (permission.status === Qt.PermissionStatus.Granted)
devicesPage.toggleDiscovery()
}La detección de dispositivos se inicia si el usuario concede el permiso. De lo contrario, la aplicación no funciona.
Búsqueda de dispositivos
El primer paso consiste en localizar todos los dispositivos periféricos. Los dispositivos se pueden localizar mediante la clase ` QBluetoothDeviceDiscoveryAgent `. El proceso de detección se inicia mediante ` start()`. Cada nuevo dispositivo se anuncia a través de la señal ` deviceDiscovered()`:
discoveryAgent = new QBluetoothDeviceDiscoveryAgent(this);
discoveryAgent->setLowEnergyDiscoveryTimeout(25000);
connect(discoveryAgent, &QBluetoothDeviceDiscoveryAgent::deviceDiscovered,
this, &Device::addDevice);
connect(discoveryAgent, &QBluetoothDeviceDiscoveryAgent::errorOccurred,
this, &Device::deviceScanError);
connect(discoveryAgent, &QBluetoothDeviceDiscoveryAgent::finished,
this, &Device::deviceScanFinished);
connect(discoveryAgent, &QBluetoothDeviceDiscoveryAgent::canceled,
this, &Device::deviceScanFinished);
discoveryAgent->start(QBluetoothDeviceDiscoveryAgent::LowEnergyMethod);La siguiente ranura (slot) de ` addDevice() ` se activa como reacción al descubrimiento de un nuevo dispositivo. Filtra todos los dispositivos encontrados que tengan el indicador ` QBluetoothDeviceInfo::LowEnergyCoreConfiguration ` y los añade a una lista que se muestra al usuario. La señal ` deviceDiscovered()` puede emitirse varias veces para un mismo dispositivo a medida que se descubren más detalles. Aquí comparamos estos descubrimientos de dispositivos para que el usuario solo vea los dispositivos individuales:
void Device::addDevice(const QBluetoothDeviceInfo &info)
{
if (info.coreConfigurations() & QBluetoothDeviceInfo::LowEnergyCoreConfiguration) {
auto devInfo = new DeviceInfo(info);
auto it = std::find_if(devices.begin(), devices.end(),
[devInfo](DeviceInfo *dev) {
return devInfo->getAddress() == dev->getAddress();
});
if (it == devices.end()) {
devices.append(devInfo);
} else {
auto oldDev = *it;
*it = devInfo;
delete oldDev;
}
emit devicesUpdated();
}
}La lista de dispositivos puede tener el aspecto que se muestra en la imagen siguiente.
Nota: Es un requisito previo que los dispositivos remotos anuncien activamente su presencia.

Conexión a los servicios
Una vez que el usuario ha seleccionado un dispositivo de la lista, la aplicación se conecta al dispositivo y analiza todos los servicios. Para conectarse al dispositivo se utiliza la clase « QLowEnergyController ». La función « QLowEnergyController::connectToDevice()» inicia el proceso de conexión, que dura hasta que se recibe la señal « QLowEnergyController::connected()» o se produce un error:
if (!controller) {
// Connecting signals and slots for connecting to LE services.
controller = QLowEnergyController::createCentral(currentDevice.getDevice(), this);
connect(controller, &QLowEnergyController::connected,
this, &Device::deviceConnected);
connect(controller, &QLowEnergyController::errorOccurred, this, &Device::errorReceived);
connect(controller, &QLowEnergyController::disconnected,
this, &Device::deviceDisconnected);
connect(controller, &QLowEnergyController::serviceDiscovered,
this, &Device::addLowEnergyService);
connect(controller, &QLowEnergyController::discoveryFinished,
this, &Device::serviceScanDone);
}
if (isRandomAddress())
controller->setRemoteAddressType(QLowEnergyController::RandomAddress);
else
controller->setRemoteAddressType(QLowEnergyController::PublicAddress);
controller->connectToDevice();La ranura activada por la señal connected() llama inmediatamente a QLowEnergyController::discoverServices() para iniciar la detección de servicios en el dispositivo periférico conectado.
controller->discoverServices();La lista resultante se muestra al usuario. La imagen siguiente muestra los resultados cuando se selecciona el dispositivo SensorTag. La vista muestra los nombres de los servicios, si son servicios primarios o secundarios, y el UUID que determina el tipo de servicio.

Tan pronto como se elige el servicio, se crea la instancia correspondiente de QLowEnergyService para permitir la interacción con él:
QLowEnergyService*service = controller->createServiceObject(serviceUuid);
if (!service) {
qWarning() << "Cannot create service for uuid";
return;
}El objeto de servicio proporciona las señales y funciones necesarias para conocer los detalles del servicio, leer y escribir características y descriptores, así como recibir notificaciones de cambios en los datos. Las notificaciones de cambio pueden activarse como resultado de escribir un valor o debido a una actualización en el dispositivo que podría haber sido activada por la lógica interna. Durante la búsqueda inicial de detalles, la función state() del servicio pasa de RemoteService a RemoteServiceDiscovering y, finalmente, termina en RemoteServiceDiscovered:
connect(service, &QLowEnergyService::stateChanged,
this, &Device::serviceDetailsDiscovered);
service->discoverDetails();
setUpdate(u"Back\n(Discovering details...)"_s);Lectura de datos del servicio
Al seleccionar un servicio, se muestran los detalles del mismo. Cada característica aparece en la lista junto con su nombre, UUID, valor, identificador y propiedades.

Es posible recuperar las características del servicio mediante QLowEnergyService::characteristics() y, a su vez, cada descriptor se puede obtener mediante QLowEnergyCharacteristic::descriptors().
const QList<QLowEnergyCharacteristic> chars = service->characteristics();
for (const QLowEnergyCharacteristic &ch : chars) {
auto cInfo = new CharacteristicInfo(ch);
m_characteristics.append(cInfo);
}Aunque la aplicación de ejemplo no muestra los descriptores, los utiliza para obtener el nombre de una característica concreta si dicho nombre no se puede deducir a partir de su UUID. La segunda forma de obtener el nombre es mediante la existencia de un descriptor del tipo QBluetoothUuid::DescriptorType::CharacteristicUserDescription. El código siguiente muestra cómo se puede lograr esto:
QString name = m_characteristic.name();
if (!name.isEmpty())
return name;
// find descriptor with CharacteristicUserDescription
const QList<QLowEnergyDescriptor> descriptors = m_characteristic.descriptors();
for (const QLowEnergyDescriptor &descriptor : descriptors) {
if (descriptor.type() == QBluetoothUuid::DescriptorType::CharacteristicUserDescription) {
name = descriptor.value();
break;
}
}© 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.