En esta página

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 APIAndroidiOSLinux (BlueZ 5.x)macOSWindows
Bluetooth clásicoxxxx
Bluetooth LE Centralxxxxx
Periférico Bluetooth LExxxx

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 += bluetooth

Permisos

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.

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 registroDescripción
Qt BluetoothHabilita el registro de la ruta de código multiplataforma en QtBluetooth
qt.bluetooth.androidHabilita el registro de la implementación de Android
qt.bluetooth.bluezHabilita el registro de la implementación de BLuez/Linux
qt.bluetooth.iosHabilita el registro de la implementación de iOS
qt.bluetooth.osxHabilita el registro de la implementación de macOS
qt.bluetooth.windowsHabilita 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

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.

BlueZ

Ú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.