Terminal serie
Muestra cómo utilizar diversas funciones de QSerialPort.
La sección «Terminal» explica cómo crear un terminal para una interfaz serie sencilla utilizando Qt Serial Port.

Este ejemplo muestra las principales características de la clase ` QSerialPort `, como la configuración, la implementación de E/S, etc. Además, se invoca la clase ` QSerialPortInfo ` para mostrar información sobre los puertos serie disponibles en el sistema.
QSerialPort Admite dos enfoques generales de programación:
- El enfoque asíncrono (sin bloqueo). 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 un resultado inmediatamente. Cuando se envían datos al puerto serie, QSerialPort emite bytesWritten().
- El enfoque síncrono (bloqueante). En aplicaciones sin interfaz gráfica de usuario y multihilo, se pueden llamar las funciones `
waitFor...()` (es decir, ` QSerialPort::waitForReadyRead()`) para suspender el hilo de llamada hasta que la operación haya finalizado.
En este ejemplo se muestra el enfoque asíncrono. El ejemplo «Blocking Receiver » ilustra el enfoque síncrono.
Nuestro ejemplo contiene algunos controles de interfaz gráfica de usuario:
MainWindow(terminal/mainwindow.cpp) —es la ventana principal de la aplicación que contiene toda la lógica de funcionamiento para la programación del puerto serie, incluida la configuración, el procesamiento de E/S, etc., al tiempo que hereda de QMainWindow.Console(terminal/console.cpp): es el widget central de la ventana principal, que muestra los datos transmitidos o recibidos. El widget deriva de la clase QPlainTextEdit.SettingsDialog(terminal/settingsdialog.cpp) — es un cuadro de diálogo para configurar el puerto serie, así como para mostrar los puertos serie disponibles y la información sobre ellos.
El puerto serie se instancía en el constructor de MainWindow. El widget principal se pasa como padre, por lo que la eliminación del objeto se produce automáticamente según el mecanismo de padres e hijos de Qt:
MainWindow::MainWindow(QWidget *parent) :
QMainWindow(parent),
m_ui(new Ui::MainWindow),
m_serial(new QSerialPort(this))
{
...Este ejemplo muestra las siguientes señales de QSerialPort:
- readyRead() - indica que se han recibido nuevos datos y que, por lo tanto, están disponibles
- bytesWritten() - se utiliza para comprobar que todos los datos se han escrito correctamente
...
connect(m_serial, &QSerialPort::readyRead, this, &MainWindow::readData);
connect(m_serial, &QSerialPort::bytesWritten, this, &MainWindow::handleBytesWritten);
...
}Al hacer clic en el botón «Conectar» se invoca la ranura « openSerialPort() »:
void MainWindow::openSerialPort()
{
const SettingsDialog::Settings p = m_settings->settings();
m_serial->setPortName(p.name);
m_serial->setBaudRate(p.baudRate);
m_serial->setDataBits(p.dataBits);
m_serial->setParity(p.parity);
m_serial->setStopBits(p.stopBits);
m_serial->setFlowControl(p.flowControl);
if (m_serial->open(QIODevice::ReadWrite)) {
m_console->setEnabled(true);
m_console->setLocalEchoEnabled(p.localEchoEnabled);
m_ui->actionConnect->setEnabled(false);
m_ui->actionDisconnect->setEnabled(true);
m_ui->actionConfigure->setEnabled(false);
showStatusMessage(tr("Connected to %1 : %2, %3, %4, %5, %6")
.arg(p.name, p.stringBaudRate, p.stringDataBits,
p.stringParity, p.stringStopBits, p.stringFlowControl));
} else {
QMessageBox::critical(this, tr("Error"), m_serial->errorString());
showStatusMessage(tr("Open error"));
}
}En esta ranura, se leen los ajustes de « SettingsDialog » y se intenta abrir e inicializar el puerto serie en consecuencia. Si se realiza correctamente, la barra de estado muestra un mensaje indicando que la apertura se ha realizado con éxito con la configuración dada; de lo contrario, se muestra un cuadro de mensaje con el código de error y el mensaje correspondientes. Si nunca se han llamado los ajustes del puerto serie, el terminal intenta abrir el puerto con la configuración por defecto: 9600 8N1.
Al hacer clic en el botón «Desconectar» se invoca la ranura « closeSerialPort() »:
void MainWindow::closeSerialPort()
{
if (m_serial->isOpen())
m_serial->close();
m_console->setEnabled(false);
m_ui->actionConnect->setEnabled(true);
m_ui->actionDisconnect->setEnabled(false);
m_ui->actionConfigure->setEnabled(true);
showStatusMessage(tr("Disconnected"));
}En este caso, se gestiona mediante el cierre del puerto serie.
Al hacer clic en el botón «Configurar» se invoca el slot « show() », que pertenece al widget « SettingsDialog ».
Este método (terminal/settingsdialog.cpp) muestra el cuadro de diálogo « SettingsDialog », en el que el usuario puede seleccionar el puerto serie deseado, consultar la información sobre el puerto seleccionado y establecer los parámetros deseados para dicho puerto serie.
Escritura de datos
Al escribir caracteres en la consola se invoca la ranura « writeData() »:
void MainWindow::writeData(const QByteArray &data)
{
const qint64 written = m_serial->write(data);
if (written == data.size()) {
m_bytesToWrite += written;
m_timer->start(kWriteTimeout);
} else {
const QString error = tr("Failed to write all data to port %1.\n"
"Error: %2").arg(m_serial->portName(),
m_serial->errorString());
showWriteError(error);
}
}Esta ranura envía los caracteres escritos en el widget «Console» al puerto serie; véase « terminal/console.cpp ». También inicia un temporizador para comprobar si la escritura se ha realizado correctamente o no. Utilizamos la señal « bytesWritten()» para asegurarnos de que todos los bytes se han escrito realmente. Está conectada a la ranura « MainWindow::handleBytesWritten() »:
void MainWindow::handleBytesWritten(qint64 bytes)
{
m_bytesToWrite -= bytes;
if (m_bytesToWrite == 0)
m_timer->stop();
}Lectura de datos
Cuando el puerto serie recibe nuevos datos, se emite la señal readyRead(), y dicha señal está conectada a la ranura MainWindow::readData():
void MainWindow::readData()
{
const QByteArray data = m_serial->readAll();
m_console->putData(data);
}Esta ranura lee los datos del puerto serie y los muestra en el widget «Consola».
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.
Véase también «Receptor 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.