当前位置：首页 > news >正文

用QSerialPortInfo和QSerialPort打造一个跨平台的串口调试助手（Qt/C++）

news 2026/4/16 10:05:26

用QSerialPortInfo和QSerialPort打造跨平台串口调试助手

在嵌入式开发、工业控制和物联网应用中，串口通信是最基础也最常用的通信方式之一。无论是调试单片机程序、与传感器交互还是监控设备状态，一个功能完善的串口调试工具都能极大提升开发效率。本文将带你使用Qt框架中的QSerialPortInfo和QSerialPort类，从零开始构建一个跨平台的串口调试助手。

1. 项目准备与环境搭建

首先确保你已经安装了Qt开发环境（建议使用Qt 5.15或更高版本）。创建一个新的Qt Widgets Application项目，并在.pro文件中添加串口模块支持：

QT += core gui serialport

在mainwindow.h中引入必要的头文件：

#include <QMainWindow> #include <QSerialPort> #include <QSerialPortInfo>

2. 串口设备发现与列表

现代操作系统可能连接了多个串口设备，我们需要先扫描并列出所有可用串口。使用QSerialPortInfo可以轻松实现这一功能：

void MainWindow::refreshSerialPorts() { ui->comboBoxPort->clear(); const auto infos = QSerialPortInfo::availablePorts(); for (const QSerialPortInfo &info : infos) { QString portInfo = info.portName(); if (!info.description().isEmpty()) portInfo += " - " + info.description(); ui->comboBoxPort->addItem(portInfo, info.portName()); } }

这段代码会扫描系统所有可用串口，并将它们添加到下拉框中，同时显示设备描述信息（如果有）。

3. 串口参数配置界面设计

一个完整的串口调试工具需要支持各种通信参数的配置。我们在UI中放置以下控件：

波特率选择框（常见值：9600, 19200, 38400, 57600, 115200等）
数据位选择（5,6,7,8）
校验位选择（无校验、奇校验、偶校验）
停止位选择（1,1.5,2）
流控选择（无流控、硬件流控、软件流控）

在Qt Designer中创建这些控件后，我们可以通过代码设置默认值：

// 波特率 ui->comboBoxBaudRate->addItem("9600", QSerialPort::Baud9600); ui->comboBoxBaudRate->addItem("19200", QSerialPort::Baud19200); ui->comboBoxBaudRate->addItem("38400", QSerialPort::Baud38400); ui->comboBoxBaudRate->addItem("57600", QSerialPort::Baud57600); ui->comboBoxBaudRate->addItem("115200", QSerialPort::Baud115200); ui->comboBoxBaudRate->setCurrentIndex(4); // 默认115200 // 数据位 ui->comboBoxDataBits->addItem("5", QSerialPort::Data5); ui->comboBoxDataBits->addItem("6", QSerialPort::Data6); ui->comboBoxDataBits->addItem("7", QSerialPort::Data7); ui->comboBoxDataBits->addItem("8", QSerialPort::Data8); ui->comboBoxDataBits->setCurrentIndex(3); // 默认8位 // 校验位 ui->comboBoxParity->addItem("无校验", QSerialPort::NoParity); ui->comboBoxParity->addItem("奇校验", QSerialPort::OddParity); ui->comboBoxParity->addItem("偶校验", QSerialPort::EvenParity);

4. 串口连接与断开

有了参数配置界面后，我们需要实现串口的打开和关闭功能。首先在MainWindow类中添加一个QSerialPort成员变量：

private: QSerialPort *serial;

然后在构造函数中初始化：

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui->setupUi(this); serial = new QSerialPort(this); connect(serial, &QSerialPort::readyRead, this, &MainWindow::readData); }

连接按钮的槽函数实现：

void MainWindow::on_pushButtonConnect_clicked() { if (serial->isOpen()) { serial->close(); ui->pushButtonConnect->setText("连接"); ui->statusBar->showMessage("串口已断开"); } else { QString portName = ui->comboBoxPort->currentData().toString(); serial->setPortName(portName); // 设置串口参数 serial->setBaudRate(ui->comboBoxBaudRate->currentData().toInt()); serial->setDataBits(static_cast<QSerialPort::DataBits>( ui->comboBoxDataBits->currentData().toInt())); serial->setParity(static_cast<QSerialPort::Parity>( ui->comboBoxParity->currentData().toInt())); serial->setStopBits(static_cast<QSerialPort::StopBits>( ui->comboBoxStopBits->currentData().toInt())); serial->setFlowControl(static_cast<QSerialPort::FlowControl>( ui->comboBoxFlowControl->currentData().toInt())); if (serial->open(QIODevice::ReadWrite)) { ui->pushButtonConnect->setText("断开"); ui->statusBar->showMessage("串口已连接: " + portName); } else { QMessageBox::critical(this, "错误", "无法打开串口: " + serial->errorString()); } } }

5. 数据收发功能实现

串口通信的核心功能是数据的发送和接收。我们先实现数据发送功能：

void MainWindow::on_pushButtonSend_clicked() { if (!serial->isOpen()) { QMessageBox::warning(this, "警告", "请先连接串口"); return; } QString text = ui->textEditSend->toPlainText(); if (text.isEmpty()) return; QByteArray data; if (ui->checkBoxHexSend->isChecked()) { // 处理16进制发送 data = QByteArray::fromHex(text.toLatin1()); } else { // 文本模式发送 data = text.toUtf8(); if (ui->checkBoxNewLine->isChecked()) { data.append("\r\n"); } } qint64 bytesWritten = serial->write(data); if (bytesWritten == -1) { QMessageBox::critical(this, "错误", "发送失败: " + serial->errorString()); } else if (bytesWritten < data.size()) { QMessageBox::warning(this, "警告", "数据未完全发送"); } }

接收数据的功能通过readyRead信号触发：

void MainWindow::readData() { QByteArray data = serial->readAll(); if (ui->checkBoxHexDisplay->isChecked()) { // 16进制显示 QString hexString; for (char c : data) { hexString += QString("%1 ").arg(static_cast<quint8>(c), 2, 16, QLatin1Char('0')); } ui->textEditReceive->insertPlainText(hexString.toUpper()); } else { // 文本模式显示 QString text = QString::fromUtf8(data); ui->textEditReceive->insertPlainText(text); } // 自动滚动到底部 QTextCursor cursor = ui->textEditReceive->textCursor(); cursor.movePosition(QTextCursor::End); ui->textEditReceive->setTextCursor(cursor); }

6. 高级功能实现

6.1 接收数据统计

添加接收字节计数功能可以方便调试：

// 在MainWindow类中添加成员变量 private: qint64 bytesReceived; // 在构造函数中初始化 MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) , bytesReceived(0) { // ... } // 修改readData函数 void MainWindow::readData() { QByteArray data = serial->readAll(); bytesReceived += data.size(); ui->labelBytesReceived->setText(QString("接收: %1 字节").arg(bytesReceived)); // 原有显示逻辑... }

6.2 发送历史记录

实现发送历史记录功能可以提升使用效率：

void MainWindow::on_pushButtonSend_clicked() { // ...原有发送逻辑... // 添加到历史记录（去重） QString text = ui->textEditSend->toPlainText(); if (!text.isEmpty() && (ui->comboBoxHistory->count() == 0 || ui->comboBoxHistory->itemText(0) != text)) { ui->comboBoxHistory->insertItem(0, text); if (ui->comboBoxHistory->count() > 10) { ui->comboBoxHistory->removeItem(10); } } } void MainWindow::on_comboBoxHistory_activated(const QString &text) { ui->textEditSend->setPlainText(text); }

6.3 定时发送功能

定时发送对于某些测试场景非常有用：

// 添加定时器成员 private: QTimer *sendTimer; // 在构造函数中初始化 MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) , bytesReceived(0) { // ... sendTimer = new QTimer(this); connect(sendTimer, &QTimer::timeout, this, &MainWindow::on_pushButtonSend_clicked); } // 定时发送控制 void MainWindow::on_checkBoxTimedSend_toggled(bool checked) { if (checked) { int interval = ui->spinBoxInterval->value(); sendTimer->start(interval); } else { sendTimer->stop(); } }

7. 跨平台注意事项

Qt的串口模块虽然是跨平台的，但在不同系统上仍有一些差异需要注意：

串口命名规则：
- Windows: COM1, COM2等
- Linux: /dev/ttyS0, /dev/ttyUSB0等
- macOS: /dev/cu.usbserial, /dev/cu.Bluetooth-Incoming-Port等
权限问题：
- 在Linux系统上，普通用户可能需要权限才能访问串口设备
- 可以通过以下命令添加用户到dialout组：
```
sudo usermod -a -G dialout $USER
```
特殊功能支持：
- 某些高级串口功能（如硬件流控）在不同平台上的支持程度可能不同
- 建议在程序启动时检查功能支持情况
编码问题：
- 不同平台对文本编码的处理可能不同
- 建议在发送和接收文本数据时明确指定编码（如UTF-8）

8. 界面优化与用户体验

8.1 状态指示灯

添加连接状态指示灯可以提升用户体验：

// 在UI中添加一个QLabel作为指示灯 // 在连接/断开时更新状态 void MainWindow::updateConnectionStatus(bool connected) { QLabel *statusLed = ui->labelStatusLed; if (connected) { statusLed->setStyleSheet("QLabel { background-color: green; border-radius: 8px; }"); statusLed->setToolTip("串口已连接"); } else { statusLed->setStyleSheet("QLabel { background-color: red; border-radius: 8px; }"); statusLed->setToolTip("串口未连接"); } }

8.2 接收数据高亮

对于特定协议的数据，可以添加高亮显示功能：

void MainWindow::highlightReceivedData(const QString &data) { // 简单示例：高亮错误消息 if (data.contains("ERROR", Qt::CaseInsensitive)) { QTextCharFormat format; format.setForeground(Qt::red); QTextCursor cursor(ui->textEditReceive->document()); cursor.movePosition(QTextCursor::End); cursor.movePosition(QTextCursor::Left, QTextCursor::KeepAnchor, data.length()); cursor.mergeCharFormat(format); } }

8.3 自动滚动控制

添加自动滚动开关，让用户可以根据需要控制：

void MainWindow::on_checkBoxAutoScroll_toggled(bool checked) { if (checked) { connect(ui->textEditReceive, &QTextEdit::textChanged, this, &MainWindow::scrollToBottom); } else { disconnect(ui->textEditReceive, &QTextEdit::textChanged, this, &MainWindow::scrollToBottom); } } void MainWindow::scrollToBottom() { QTextCursor cursor = ui->textEditReceive->textCursor(); cursor.movePosition(QTextCursor::End); ui->textEditReceive->setTextCursor(cursor); }

9. 错误处理与日志记录

健壮的错误处理是串口应用的关键：

void MainWindow::handleSerialError(QSerialPort::SerialPortError error) { if (error == QSerialPort::NoError) return; QString errorString = serial->errorString(); QString errorMsg; switch (error) { case QSerialPort::DeviceNotFoundError: errorMsg = "设备未找到"; break; case QSerialPort::PermissionError: errorMsg = "没有访问权限"; break; case QSerialPort::OpenError: errorMsg = "设备已打开"; break; // 其他错误类型处理... default: errorMsg = "未知错误"; } QMessageBox::warning(this, "串口错误", QString("%1: %2").arg(errorMsg).arg(errorString)); if (serial->isOpen()) { serial->close(); updateConnectionStatus(false); } }

添加日志记录功能可以帮助调试：

void MainWindow::logMessage(const QString &message) { QString timestamp = QDateTime::currentDateTime().toString("hh:mm:ss.zzz"); ui->textEditLog->append(QString("[%1] %2").arg(timestamp).arg(message)); // 可选：保存到文件 QFile logFile("serial_debug.log"); if (logFile.open(QIODevice::Append)) { QTextStream stream(&logFile); stream << QString("[%1] %2\n").arg(timestamp).arg(message); logFile.close(); } }

10. 性能优化技巧

对于高频数据通信，可以考虑以下优化：

缓冲处理：

// 设置合适的读取缓冲区大小 serial->setReadBufferSize(1024 * 1024); // 1MB

批量处理接收数据：

void MainWindow::readData() { while (serial->bytesAvailable() > 0) { QByteArray data = serial->read(1024); // 每次读取1KB // 处理数据... } }

减少UI更新频率：

// 使用定时器批量更新UI QTimer *updateTimer = new QTimer(this); connect(updateTimer, &QTimer::timeout, this, [this]() { if (!receiveBuffer.isEmpty()) { ui->textEditReceive->append(receiveBuffer); receiveBuffer.clear(); } }); updateTimer->start(100); // 每100ms更新一次UI

使用二进制协议处理：对于高频数据传输，建议使用二进制协议而非文本协议，可以显著提高效率。

11. 扩展功能思路

协议解析：
- 添加常见协议（如Modbus）的解析功能
- 实现自定义协议模板
数据可视化：
- 将接收到的数据绘制成实时曲线图
- 支持多种图表类型（折线图、柱状图等）
脚本支持：
- 集成Lua或JavaScript引擎
- 支持自动化测试脚本
多串口支持：
- 同时监控多个串口设备
- 实现串口数据转发功能
云连接：
- 将串口数据转发到MQTT等物联网协议
- 支持远程监控和控制

12. 项目打包与分发

完成开发后，我们需要将应用程序打包以便分发：

Windows平台：
- 使用windeployqt工具打包依赖：
```
windeployqt --release SerialTool.exe
```
- 可以使用Inno Setup或NSIS创建安装程序
Linux平台：
- 可以打包为AppImage或deb/rpm包
- 确保包含必要的运行时依赖
macOS平台：
- 创建.app bundle
- 可以使用macdeployqt工具：
```
macdeployqt SerialTool.app
```