En esta página

Qt Bluetooth Descripción general

Con la API « Qt Bluetooth », los casos de uso habituales son:

  • Recuperar información sobre el dispositivo Bluetooth local.
  • Buscar otros dispositivos Bluetooth dentro del alcance y obtener información sobre ellos.
  • Enviar archivos a dispositivos remotos mediante el perfil OBEX Object Push Profile (OPP).
  • Conectarse a dispositivos remotos a través de un canal RFCOMM utilizando el perfil de puerto serie (SPP).
  • Crear un servidor RFCOMM que permita conexiones entrantes mediante SPP.
  • Obtener especificaciones sobre un dispositivo Bluetooth de bajo consumo.
  • Conectarse a un dispositivo Bluetooth de bajo consumo.
  • Recibir anuncios de un dispositivo Bluetooth Low Energy.

Ten en cuenta que el perfil Object Push no es compatible con Android ni con Windows.

Nota: Qt no permite configuraralgunas funciones de RFCOMM en Windows. Los campos « ServiceClassIds » y « ProtocolDescriptorList » de un servicio se rellenan automáticamente. Por lo tanto, registrar un servicio con valores personalizados para estos campos podría no dar el resultado esperado en Windows.

Nota: El indicador de intensidad de señal recibida (RSSI), así como los datos específicos del fabricante anunciados por los dispositivos Bluetooth LE, no son compatibles con el backend Win32. Además, solo es posible encontrar dispositivos que se hayan emparejado previamente a través de la configuración de Windows.

En las siguientes secciones se describe cómo utilizar las clases de la API de C++ de Qt Bluetooth para los casos de uso mencionados anteriormente.

Recuperación de información de dispositivos locales

La API de Qt Bluetooth tiene tres funciones principales. La primera es obtener información sobre dispositivos locales y remotos. Los primeros pasos para recuperar información del dispositivo consisten en comprobar si Bluetooth está disponible en el dispositivo y leer la dirección y el nombre del dispositivo local. La clase ` QBluetoothLocalDevice ` proporciona toda esta información. Además, se puede utilizar para activar o desactivar Bluetooth, configurar la visibilidad del dispositivo y determinar las conexiones actuales.

QBluetoothLocalDevice localDevice;
QString localDeviceName;

// Check if Bluetooth is available on this device
if (localDevice.isValid()) {

    // Turn Bluetooth on
    localDevice.powerOn();

    // Read local device name
    localDeviceName = localDevice.name();

    // Make it visible to others
    localDevice.setHostMode(QBluetoothLocalDevice::HostDiscoverable);

    // Get connected devices
    QList<QBluetoothAddress> remotes;
    remotes = localDevice.connectedDevices();
}

Búsqueda de dispositivos Bluetooth

De forma similar a la clase « QBluetoothLocalDevice », la API ofrece la clase « QBluetoothDeviceInfo », que proporciona información similar sobre dispositivos remotos. Aunque puedes crear objetos « QBluetoothDeviceInfo » por tu cuenta y rellenarlos con datos, la forma más sencilla es utilizar el método « QBluetoothDeviceDiscoveryAgent » para iniciar una búsqueda automática de dispositivos Bluetooth visibles dentro del alcance de conexión.

void MyClass::startDeviceDiscovery()
{

    // Crear un agente de detección y conectarse a sus señales
    QBluetoothDeviceDiscoveryAgent*discoveryAgent = new QBluetoothDeviceDiscoveryAgent(this);
    connect(discoveryAgent, SIGNAL(deviceDiscovered(QBluetoothDeviceInfo)),
            this, SLOT(deviceDiscovered(QBluetoothDeviceInfo)));

    // Iniciar un proceso de detección
    discoveryAgent->start();

    //...
}

// En tu slot local, lee la información sobre los dispositivos encontrados
void MyClass::deviceDiscovered(const QBluetoothDeviceInfo&device)
{
    qDebug() << "Found new device:" << device.name() << '(' << device.address().toString() << ')';
}

Intercambio de datos entre dispositivos

El método más flexible para la comunicación entre dos dispositivos con Bluetooth es crear una conexión de puerto serie virtual e intercambiar datos libremente a través de ella. Esto se puede hacer mediante el perfil de puerto serie (SPP). El perfil de puerto serie emula una conexión serie a través del protocolo de transporte Bluetooth RFCOMM.

Para poder recibir conexiones SPP entrantes, es necesario escuchar las conexiones entrantes utilizando ` QBluetoothServer`.

rfcommServer = new QBluetoothServer(QBluetoothServiceInfo::RfcommProtocol, this);
connect(rfcommServer, &QBluetoothServer::newConnection,
        this, QOverload<>::of(&ChatServer::clientConnected));
bool result = rfcommServer->listen(localAdapter);
if (!result) {
    qWarning() << "Cannot bind chat server to" << localAdapter.toString();
   return;
}

Conéctate a este servidor desde otro dispositivo que actúe como cliente utilizando un QBluetoothSocket:

void ChatClient::startClient(const QBluetoothServiceInfo&remoteService)
{
    if (socket)
        return;

    // Conectarse al servicio
    socket = new QBluetoothSocket(QBluetoothServiceInfo::RfcommProtocol);
    qDebug() << "Create socket";
    socket->connectToService(remoteService);
    qDebug() << "ConnectToService done";

    connect(socket, &QBluetoothSocket::readyRead, this, &ChatClient::readSocket);
    connect(socket, &QBluetoothSocket::connected, this, QOverload<>::of(&ChatClient::connected));
    connect(socket, &QBluetoothSocket::disconnected, this, &ChatClient::disconnected);
    connect(socket, &QBluetoothSocket::errorOccurred, this, &ChatClient::onSocketErrorOccurred);
}

El uso de este tipo de conexión permite intercambiar cualquier tipo de datos en ambas direcciones. Es ideal para juegos o para sincronizar el estado entre dos instancias de una aplicación en dos dispositivos. Para obtener descripciones más detalladas sobre cómo configurar el servidor y el cliente, consulta las secciones de descripción detallada de las clases QBluetoothServer y QBluetoothSocket. Un buen ejemplo para iniciarse en SPP es el ejemplo «Bluetooth Chat ».

Bluetooth de baja energía

Bluetooth de bajo consumo, también conocido como Bluetooth Smart, es una nueva tecnología que permite que los dispositivos con bajo consumo energético se comuniquen entre sí. Se puede encontrar más información sobre esta tecnología y las API de Qt relacionadas en la Descripción general de Bluetooth de bajo consumo.

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