En esta página

Receptor de bloqueo

Muestra cómo utilizar la API síncrona de QSerialPort en un hilo que no sea de la interfaz gráfica de usuario.

El receptor de bloqueo muestra cómo crear una aplicación para una interfaz serie utilizando la API síncrona de QSerialPort en un hilo que no sea de interfaz gráfica de usuario.

Receptor de bloqueo de Qt Serial Port

QSerialPort Admite dos enfoques generales de programación:

  • El enfoque asíncrono (no bloqueante). Las operaciones se programan y se ejecutan cuando el control vuelve al bucle de eventos de Qt. QSerialPort emite una señal cuando finaliza la operación. Por ejemplo, QSerialPort::write() devuelve el resultado inmediatamente. Cuando los datos se envían al puerto serie, QSerialPort emite bytesWritten().
  • El enfoque síncrono (bloqueante). En aplicaciones sin interfaz gráfica de usuario y multihilo, se pueden invocar las funciones de waitFor...() (es decir, QSerialPort::waitForReadyRead()) para suspender el hilo que realiza la llamada hasta que la operación haya finalizado.

En este ejemplo se muestra el enfoque síncrono. El ejemplo «Terminal» ilustra el enfoque asíncrono.

El objetivo de este ejemplo es mostrar un patrón que puedes utilizar para simplificar tu código de programación en serie, sin perder la capacidad de respuesta de tu interfaz de usuario. El uso de la API de programación en serie con bloqueo de Qt suele dar lugar a un código más sencillo, pero, debido a su comportamiento de bloqueo, solo debe utilizarse en subprocesos que no sean de la interfaz gráfica de usuario para evitar que esta se cuelgue. Sin embargo, al contrario de lo que muchos piensan, el uso de subprocesos con « QThread » no añade necesariamente una complejidad inmanejable a la aplicación.

Esta aplicación es un «Receptor» que muestra su funcionamiento en combinación con la aplicación emisora del ejemplo «Blocking Sender».

La aplicación «Receiver» recibe la solicitud a través del puerto serie desde la aplicación «Sender» y le envía una respuesta.

Comenzaremos con la clase «ReceiverThread», que se encarga del código de programación en serie.

class ReceiverThread : public QThread
{
    Q_OBJECT

public:
    explicit ReceiverThread(QObject *parent = nullptr);
    ~ReceiverThread();

    void startReceiver(const QString &portName, int waitTimeout, const QString &response);

signals:
    void request(const QString &s);
    void error(const QString &s);
    void timeout(const QString &s);

private:
    void run() override;

    QString m_portName;
    QString m_response;
    int m_waitTimeout = 0;
    QMutex m_mutex;
    bool m_quit = false;
};

ReceiverThread es una subclase de QThread que proporciona una API para recibir solicitudes del emisor, y cuenta con señales para enviar respuestas y notificar errores.

Debes llamar a startReceiver() para iniciar la aplicación «Receiver». Este método transfiere a «ReceiverThread» los parámetros deseados para configurar e iniciar la interfaz serie. Cuando «ReceiverThread» recibe cualquier solicitud de «Sender», emite la señal request(). Si se produce algún error, se emiten las señales error() o timeout().

Es importante tener en cuenta que startReceiver() se invoca desde el hilo principal (el de la interfaz gráfica de usuario), pero se accederá a los datos de respuesta y a otros parámetros desde el hilo de ReceiverThread. Los miembros de datos de ReceiverThread se leen y escriben de forma concurrente desde diferentes hilos, por lo que es recomendable utilizar QMutex para sincronizar el acceso.

void ReceiverThread::startReceiver(const QString &portName, int waitTimeout, const QString &response)
{
    const QMutexLocker locker(&m_mutex);
    m_portName = portName;
    m_waitTimeout = waitTimeout;
    m_response = response;
    if (!isRunning())
        start();
}

La función `startReceiver()` almacena el nombre del puerto serie, el tiempo de espera y los datos de respuesta, y ` QMutexLocker ` bloquea el mutex para proteger estos datos. A continuación, iniciamos el hilo, a menos que ya se esté ejecutando. La función ` QWaitCondition::wakeOne()` se tratará más adelante.

void ReceiverThread::run()
{
    bool currentPortNameChanged = false;

    m_mutex.lock();
    QString currentPortName;
    if (currentPortName != m_portName) {
        currentPortName = m_portName;
        currentPortNameChanged = true;
    }

    int currentWaitTimeout = m_waitTimeout;
    QString currentRespone = m_response;
    m_mutex.unlock();

En la función run(), se comienza adquiriendo el bloqueo del mutex, se obtienen el nombre del puerto serie, el tiempo de espera y los datos de respuesta de los datos de miembro, y a continuación se libera de nuevo el bloqueo. Bajo ninguna circunstancia debe llamarse al método startReceiver() simultáneamente con un proceso que esté obteniendo estos datos. QString es reentrante pero no seguro para subprocesos, y no se recomienda leer el nombre del puerto serie de un inicio, ni los datos de llamada, tiempo de espera o respuesta de otro. ReceiverThread solo puede gestionar un inicio a la vez.

El objeto ` QSerialPort ` lo construimos en la pila dentro de la función `run()` antes de entrar en el bucle:

    QSerialPort serial;

    while (!m_quit) {

Esto nos permite crear un objeto una sola vez, mientras se ejecuta el bucle, y también significa que todos los métodos del objeto se ejecutarán en el contexto del hilo de run().

Dentro del bucle, comprueba si el nombre del puerto serie de la sesión de inicio actual ha cambiado o no. Si ha cambiado, vuelve a abrir y reconfigura el puerto serie.

        if (currentPortName.isEmpty()) {
            emit error(tr("Port not set"));
            return;
        } else if (currentPortNameChanged) {
            serial.close();
            serial.setPortName(currentPortName);

            if (!serial.open(QIODevice::ReadWrite)) {
                emit error(tr("Can't open %1, error code %2")
                           .arg(m_portName).arg(serial.error()));
                return;
            }
        }

        if (serial.waitForReadyRead(currentWaitTimeout)) {

El bucle continuará esperando datos de solicitud:

            // read request
            QByteArray requestData = serial.readAll();
            while (serial.waitForReadyRead(10))
                requestData += serial.readAll();

Advertencia: El método waitForReadyRead() debe utilizarse antes de cada llamada a read() en el enfoque de bloqueo, ya que procesa todas las rutinas de E/S en lugar del bucle de eventos de Qt.

Se emite la señal timeout() si se produce un error al leer los datos.

        } else {
            emit timeout(tr("Wait read request timeout %1")
                         .arg(QTime::currentTime().toString()));
        }

Tras una lectura correcta, intenta enviar una respuesta y espera a que finalice la transferencia:

            // write response
            const QByteArray responseData = currentRespone.toUtf8();
            serial.write(responseData);
            if (serial.waitForBytesWritten(m_waitTimeout)) {
                const QString request = QString::fromUtf8(requestData);
                emit this->request(request);

Advertencia: El método waitForBytesWritten() debe utilizarse tras cada llamada a write() en el enfoque bloqueante, ya que procesa todas las rutinas de E/S en lugar del bucle de eventos de Qt.

Se emite la señal timeout() si se produce un error al escribir datos.

            } else {
                emit timeout(tr("Wait write response timeout %1")
                             .arg(QTime::currentTime().toString()));
            }

Una vez emitida la señal de escritura correcta, se emite la señal request() que contiene los datos recibidos de la aplicación emisora:

                emit this->request(request);

A continuación, el hilo pasa a leer los parámetros actuales de la interfaz serie, ya que pueden haberse actualizado, y ejecuta el bucle desde el principio.

        m_mutex.lock();
        if (currentPortName != m_portName) {
            currentPortName = m_portName;
            currentPortNameChanged = true;
        } else {
            currentPortNameChanged = false;
        }
        currentWaitTimeout = m_waitTimeout;
        currentRespone = m_response;
        m_mutex.unlock();
    }

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Proyecto de ejemplo en code.qt.io

Véase también «Terminal serie » y «Remitente bloqueante».

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