Qt Bluetooth
La API de Bluetooth proporciona conectividad entre dispositivos compatibles con Bluetooth.
Actualmente, la API es compatible con las siguientes plataformas:
| Características de la API | Android | iOS | Linux (BlueZ 5.x) | macOS | Windows |
|---|---|---|---|---|---|
| Bluetooth clásico | x | x | x | x | |
| Bluetooth LE Central | x | x | x | x | x |
| Periférico Bluetooth LE | x | x | x | x |
Descripción general
Bluetooth es una tecnología inalámbrica de corto alcance (menos de 100 metros). Tiene una velocidad de transferencia de datos de 2,1 Mbps, lo que la hace ideal para transferir datos entre dispositivos. La conectividad Bluetooth se basa en funciones básicas de gestión de dispositivos, como la búsqueda de dispositivos, la recopilación de información sobre ellos y el intercambio de datos entre ellos.
Qt Bluetooth Admite el desarrollo de Bluetooth Low Energy para casos de uso en los que el dispositivo actúa como cliente o como central. Se puede encontrar más información en la sección «Descripción general de Bluetooth Low Energy ».
Uso del módulo
Para utilizar la API de C++ de un módulo Qt es necesario vincularla a la biblioteca del módulo, ya sea directamente o a través de otras dependencias. Varias herramientas de compilación ofrecen soporte específico para ello, entre ellas CMake y qmake.
Compilación con CMake
Utilice el comando « find_package() » para localizar el componente del módulo necesario en el paquete « Qt6 »:
find_package(Qt6 REQUIRED COMPONENTS Bluetooth)
target_link_libraries(mytarget PRIVATE Qt6::Bluetooth)Para obtener más detalles, consulta la descripción general de «Compilación con CMake ».
Compilación con qmake
Para configurar el módulo para la compilación con qmake, añade el módulo como valor de la variable ` QT ` en el archivo `.pro` del proyecto:
QT += bluetoothPermisos
A partir de Qt 6.6, el módulo « Qt Bluetooth » utiliza la nueva API « QPermission » para gestionar los permisos de « Bluetooth ». Esto significa que Qt ya no solicita estos permisos por sí mismo, por lo que esto debe hacerse directamente desde la aplicación cliente.
Consulta la página Permisos de la aplicación para ver un ejemplo de cómo integrar la nueva API de QPermission en la aplicación.
Información relacionada
Compilación Qt Bluetooth
Aunque el módulo se puede compilar para todas las plataformas de Qt, no está adaptado a todas ellas. Las plataformas no compatibles utilizan un backend ficticio que se selecciona automáticamente cuando la plataforma no es compatible. El backend ficticio muestra los mensajes de error y los valores adecuados, lo que permite detectar en tiempo de ejecución que la plataforma actual no es compatible. El backend ficticio también se selecciona en Linux si no se encuentran los encabezados de desarrollo de BlueZ durante la compilación o si Qt se ha compilado sin compatibilidad con Qt D-Bus.
El uso del backend ficticio se señala mediante una advertencia adecuada durante la compilación y la ejecución.
Especifico de Linux
Desde Qt 6.5, la compatibilidad con periféricos en Linux cuenta con dos alternativas de backend: BlueZ DBus y la API del núcleo de Bluetooth. El backend DBus es el predeterminado desde Qt 6.7.
BlueZ DBus es la pila BlueZ más reciente y, posiblemente, la sucesora definitiva de la antigua API del kernel. Es un poco más limitada en cuanto a funcionalidades, pero en un uso típico esto no debería suponer ningún problema. Una ventaja destacable del uso del backend DBus es que el proceso de usuario ya no necesita tener la capacidad CAP_NET_ADMIN (por ejemplo, al ejecutarse como un usuari root ).
El backend DBus requiere la versión 5.56 o superior de BlueZ, y que esta proporcione las API de DBus necesarias. Si no se cumplen estos requisitos, Qt recurre automáticamente al backend de la API del núcleo de Bluetooth.
El backend del núcleo más antiguo también se puede seleccionar manualmente configurando la variable de entorno QT_BLUETOOTH_USE_KERNEL_PERIPHERAL.
Específico de macOS
La API de Bluetooth en macOS requiere un tipo concreto de distribuidor de eventos que, en Qt, genera una dependencia de QGuiApplication. Sin embargo, puedes establecer la variable de entorno QT_EVENT_DISPATCHER_CORE_FOUNDATION=1 para sortear este problema.
Las aplicaciones que no utilicen Bluetooth clásico dispondrán de un subconjunto de QtBluetooth, ya que CoreBluetooth (Bluetooth LE) no requiere QApplication ni QGuiApplication.
Artículos y guías
Referencia
Categorías de registro
El módulo « QtBluetooth » exporta las siguientes categorías de registro ( logging categories):
| Categoría de registro | Descripción |
|---|---|
| Qt Bluetooth | Habilita el registro de la ruta de código multiplataforma en QtBluetooth |
| qt.bluetooth.android | Habilita el registro de la implementación de Android |
| qt.bluetooth.bluez | Habilita el registro de la implementación de BLuez/Linux |
| qt.bluetooth.ios | Habilita el registro de la implementación de iOS |
| qt.bluetooth.osx | Habilita el registro de la implementación de macOS |
| qt.bluetooth.windows | Habilita el registro de la implementación de Windows |
Las categorías de registro permiten generar mensajes adicionales de advertencia y depuración para QtBluetooth. Encontrarás información más detallada sobre el registro en QLoggingCategory. Una forma rápida de habilitar todo el registro de QtBluetooth es añadir la siguiente línea a la función main():
QLoggingCategory::setFilterRules(QStringLiteral("qt.bluetooth* = true"));Ejemplos
- QML
- C++
Evolución del módulo
La sección « Qt Bluetooth » enumera loscambios importantes realizados en la API y la funcionalidad del módulo para la serie Qt 6 de Qt.
Licencias y atribuciones
Qt Bluetooth está disponible bajo licencias comerciales de The Qt Company. Además, está disponible bajo la Licencia Pública General Reducida de GNU, versión 3, o la Licencia Pública General de GNU, versión 2. Consulte Licencias de Qt para obtener más detalles.
En Linux, Qt Bluetooth utiliza un ejecutable independiente, sdpscanner, para integrarse con la pila de protocolos Bluetooth oficial de Linux, BlueZ. BlueZ está disponible bajo la Licencia Pública General de GNU, versión 2.
Únicamente Licencia Pública General de GNU v2.0 (esto no obliga a que el código del usuario esté bajo la GPL. Para más información, consulta los detalles). |
© 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.