QT5.12.11 + QCustomPlot实战：手把手教你打造多通道串口虚拟示波器（附源码）

QT5.12.11 + QCustomPlot实战：手把手教你打造多通道串口虚拟示波器（附源码）

你是否也曾遇到过这样的场景：手头的嵌入式设备正在输出一串串数据，你想直观地观察这些数据的实时变化趋势，但手边没有昂贵的专业示波器，或者现有的串口调试工具绘图功能简陋、卡顿且功能受限？对于嵌入式开发者、电子爱好者或是工业数据监控的工程师来说，一个能够灵活定制、稳定可靠且能实时绘制多通道数据的虚拟示波器，无疑是提升开发效率和问题排查能力的利器。今天，我们就将深入实战，利用经典的QT5.12.11框架和强大的QCustomPlot绘图库，从零开始构建一个功能完备的多通道串口虚拟示波器。整个过程不仅仅是代码的堆砌，更会涉及开发环境搭建、核心架构设计、通信协议解析、性能优化以及最终的项目打包发布。无论你是QT的初学者，还是希望深化图形界面与硬件交互理解的开发者，这篇文章都将提供一条清晰的路径和可落地的源码参考。

1. 开发环境搭建与项目初始化

工欲善其事，必先利其器。一个稳定且熟悉的开发环境是项目成功的第一步。我们选择QT5.12.11 LTS版本，这是一个长期支持版本，在稳定性和社区支持方面都有很好的保障。QCustomPlot则是一个基于QT的轻量级绘图库，它功能强大、性能优异，特别适合用于需要实时绘制大量数据点的科学和工程图表。

1.1 安装QT与配置开发环境

首先，前往QT官网或国内镜像站点下载QT5.12.11的在线安装器。在安装组件选择时，确保勾选了与你编译器匹配的套件，例如MinGW 7.3.0 32-bit或MSVC 2017 64-bit。对于Windows平台，MinGW是一个简单易用的选择。

安装完成后，打开Qt Creator，我们需要创建一个基础项目。选择文件 -> 新建文件或项目，在Application类别下选择Qt Widgets Application。给项目起一个名字，例如SerialScopePro，并选择合适的构建套件。

在项目创建向导中，类信息页面保持默认（生成MainWindow、mainwindow.ui等文件）即可。创建完成后，你将得到一个最基本的QT窗口应用程序框架。

1.2 集成QCustomPlot库到项目

QCustomPlot的集成非常简便，它主要由两个文件组成：qcustomplot.h和qcustomplot.cpp。你可以从其官网下载最新源码包。

1. 下载与放置：解压下载的源码包，将qcustomplot.h和qcustomplot.cpp两个文件复制到你的项目根目录下。
2. 添加到项目：在Qt Creator的项目树视图中，右键点击项目名称，选择添加现有文件...，将这两个文件添加到项目中。
3. 界面设计引入：打开mainwindow.ui文件，在左侧的Widget Box中，你会发现多出了一个QCustomPlot控件。如果没有，可能需要重新启动Qt Creator。将它拖拽到主窗口的设计区域。
4. 提升为QCustomPlot：另一种更灵活的方式是，先拖入一个普通的QWidget，然后右键点击它，选择提升为...。在“提升的类名称”中填入QCustomPlot，在“头文件”中填入qcustomplot.h，然后点击“添加”和“提升”。这样，这个Widget就在代码中可以被当作QCustomPlot对象来使用了。

至此，基础环境与核心库的集成已经完成。你可以尝试编译并运行项目，如果一切顺利，一个空白的窗口将会出现，这标志着我们的“画布”已经准备就绪。

2. 构建软件核心骨架与用户界面

一个直观、易用的用户界面是软件的门面。对于虚拟示波器，我们需要将控制功能区与波形显示区清晰地区分开来。

2.1 主界面布局设计

我们采用经典的左右或上下布局。这里推荐使用水平分割（QSplitter）或垂直布局嵌套的方式。一个常见的设计是：左侧或上方为控制面板，右侧或下方为占据主要面积的绘图区域。

在mainwindow.ui中，我们可以这样操作：

• 删除默认的centralWidget中的所有内容。
• 拖入一个Horizontal Layout（水平布局）到centralWidget中。
• 在水平布局中，先拖入一个Widget作为控制面板容器，再拖入一个QCustomPlot控件（或提升后的Widget）作为绘图区域。
• 为控制面板容器设置一个合适的固定宽度（例如250像素），并为它设置一个垂直布局（Vertical Layout），以便于排列内部的按钮、下拉框等控件。

控制面板需要包含以下核心控件：

• 串口选择：QComboBox，用于列出可用串口。
• 波特率选择：QComboBox，预置常用波特率（9600, 19200, 38400, 57600, 115200, 230400等）。
• 打开/关闭串口按钮：QPushButton。
• 通道控制：一组QCheckBox，用于勾选显示/隐藏第1到第10通道。
• 图形控制：暂停/继续按钮、Y轴自动缩放复选框、清空图形按钮。
• 数据点/页设置：QSpinBox，用于设置X轴一屏显示的数据点数，控制波形滚动速度。
• 保存功能：保存为图片、保存数据为文本按钮。

提示：合理使用QGroupBox对功能相关的控件进行分组，可以使界面更加整洁，例如“串口设置”、“通道控制”、“图形操作”等分组框。

2.2 核心类的设计与数据流

在代码层面，我们需要规划好数据流向和类职责。在mainwindow.h中，我们至少需要声明以下关键成员：

#include "qcustomplot.h" #include <QSerialPort> #include <QSerialPortInfo> namespace Ui { class MainWindow; } class MainWindow : public QMainWindow { Q_OBJECT public: explicit MainWindow(QWidget *parent = nullptr); ~MainWindow(); private slots: void onSerialReadyRead(); // 串口数据到达槽函数 void refreshSerialPortList(); // 刷新串口列表 void onOpenCloseSerialClicked(); // 打开/关闭串口 void updatePlot(); // 定时更新曲线 // ... 其他槽函数，如各个按钮的点击事件 private: Ui::MainWindow *ui; QSerialPort *m_serialPort; QTimer *m_dataTimer; // 用于定时刷新绘图的定时器 // 数据缓冲区 QVector<QVector<double>> m_channelData; // 存储各通道数据 QVector<double> m_timeData; // 存储时间轴数据 int m_dataPointCount; // 当前已接收的数据点索引 void setupPlot(); // 初始化图表样式、坐标轴、曲线 void parseProtocol(const QByteArray &data); // 解析自定义通信协议 void saveSettings(); // 保存配置 void loadSettings(); // 加载配置 };

这个设计清晰地划分了界面（Ui）、硬件交互（QSerialPort）、数据存储（QVector）和图形显示（QCustomPlot）的界限。m_dataTimer是动态曲线的“心脏”，它以固定的频率（如50ms）触发updatePlot()函数，将缓冲区中的数据绘制到屏幕上。

3. 实现串口通信与自定义协议解析

串口通信是虚拟示波器与下位机（如STM32、Arduino等）对话的桥梁。可靠的数据接收和高效的协议解析是软件稳定的基石。

3.1 串口模块的初始化与数据读取

在MainWindow的构造函数中，我们需要初始化串口对象，并连接信号与槽。

MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent), ui(new Ui::MainWindow), m_serialPort(new QSerialPort(this)), m_dataPointCount(0) { ui->setupUi(this); // 初始化数据缓冲区，假设最多10个通道 m_channelData.resize(10); m_timeData.reserve(10000); // 预分配空间以提高性能 // 连接串口数据可读信号 connect(m_serialPort, &QSerialPort::readyRead, this, &MainWindow::onSerialReadyRead); // 初始化定时器，用于动态绘图 m_dataTimer = new QTimer(this); connect(m_dataTimer, &QTimer::timeout, this, &MainWindow::updatePlot); m_dataTimer->start(50); // 20Hz刷新率 setupPlot(); // 设置图表 loadSettings(); // 加载保存的配置 refreshSerialPortList(); // 刷新串口下拉列表 }

onSerialReadyRead()槽函数是数据入口。这里有一个关键点：readyRead信号并非在完整的一帧数据到达时触发，而是在串口缓冲区有任意新数据时就会触发。因此，我们需要一个缓冲区来累积数据，并从中解析出完整的帧。

void MainWindow::onSerialReadyRead() { static QByteArray rawDataBuffer; // 静态变量，用于累积数据 rawDataBuffer.append(m_serialPort->readAll()); // 循环解析，直到缓冲区中没有完整帧 while (rawDataBuffer.size() > 0) { int frameStart = rawDataBuffer.indexOf(0xAA); // 假设帧头为0xAA if (frameStart == -1) { // 没有找到帧头，清空无效数据 rawDataBuffer.clear(); break; } // 移除帧头之前的所有无效数据 rawDataBuffer.remove(0, frameStart); // 检查缓冲区长度是否足够包含一帧最小长度（例如帧头+1个数据+帧尾） if (rawDataBuffer.size() < MIN_FRAME_LENGTH) { break; // 数据不够，等待下次接收 } // 尝试解析一帧数据 bool parseSuccess = false; int frameLength = parseProtocol(rawDataBuffer, parseSuccess); if (parseSuccess && frameLength > 0) { // 解析成功，移除已处理的数据 rawDataBuffer.remove(0, frameLength); } else { // 解析失败（可能是数据错误），丢弃第一个字节（帧头），继续寻找下一帧头 rawDataBuffer.remove(0, 1); } } }

3.2 设计并解析灵活的数据帧协议

一个健壮且灵活的协议是双向可靠通信的关键。我们设计一个可变长度的协议帧，以支持1到10个通道的数据传输。

协议帧格式示例：

parseProtocol函数的核心任务就是从原始字节流中，按照上述格式提取出各个通道的浮点数值。

int MainWindow::parseProtocol(const QByteArray &data, bool &success) { success = false; if (data.size() < 5) return 0; // 帧头2+通道数1+帧尾2=5 // 检查帧头 if ((quint8)data[0] != 0xAA || (quint8)data[1] != 0x55) { return 0; } quint8 channelCount = (quint8)data[2]; if (channelCount < 1 || channelCount > 10) { return 0; // 通道数非法 } int expectedFrameLen = 2 + 1 + channelCount * 4 + 2; // 头+通道数+数据+尾 if (data.size() < expectedFrameLen) { return 0; // 数据不完整 } // 检查帧尾 int tailIndex = expectedFrameLen - 2; if ((quint8)data[tailIndex] != 0x55 || (quint8)data[tailIndex+1] != 0xAA) { return 0; // 帧尾错误 } // 解析数据 QVector<float> frameData(channelCount); const char *ptr = data.constData() + 3; // 指向第一个数据的指针 for (int i = 0; i < channelCount; ++i) { // 注意字节序问题！下位机通常是小端，QT在x86上也是小端。 // 如果平台字节序不同，需要转换。 float value; memcpy(&value, ptr + i * 4, 4); frameData[i] = value; } // 将解析到的数据存入对应的通道缓冲区 for (int i = 0; i < channelCount; ++i) { m_channelData[i].append(frameData[i]); } // 更新时间轴（简单递增索引） m_timeData.append(m_dataPointCount++); // 限制缓冲区大小，防止内存无限增长（例如只保留最近5000个点） const int maxDataPoints = ui->spinBoxPointsPerPage->value() * 5; // 保留5页数据 if (m_timeData.size() > maxDataPoints) { int removeCount = m_timeData.size() - maxDataPoints; m_timeData.remove(0, removeCount); for (auto &channel : m_channelData) { if (channel.size() > removeCount) { channel.remove(0, removeCount); } } m_dataPointCount = m_timeData.size(); // 调整索引 } success = true; return expectedFrameLen; }

这个解析器包含了帧头帧尾校验、长度验证、数据提取和缓冲区管理，是一个相对完整的实现。在实际项目中，你可能还需要加入CRC校验来提高数据可靠性。

4. 动态曲线绘制与高级交互功能

有了稳定的数据源，接下来就是让数据“动”起来，并赋予用户强大的图表交互能力。这正是QCustomPlot大显身手的地方。

4.1 初始化图表与创建动态曲线

在setupPlot()函数中，我们配置图表的视觉样式并创建多条曲线（Graph）。

void MainWindow::setupPlot() { QCustomPlot *customPlot = ui->customPlot; // 1. 设置背景和网格 customPlot->setBackground(QBrush(QColor(48, 48, 48))); // 深色背景 customPlot->xAxis->setBasePen(QPen(Qt::white, 1)); customPlot->yAxis->setBasePen(QPen(Qt::white, 1)); customPlot->xAxis->setTickPen(QPen(Qt::white, 1)); customPlot->yAxis->setTickPen(QPen(Qt::white, 1)); customPlot->xAxis->setSubTickPen(QPen(Qt::white, 1)); customPlot->yAxis->setSubTickPen(QPen(Qt::white, 1)); customPlot->xAxis->setTickLabelColor(Qt::white); customPlot->yAxis->setTickLabelColor(Qt::white); customPlot->xAxis->grid()->setPen(QPen(QColor(140, 140, 140), 1, Qt::DotLine)); customPlot->yAxis->grid()->setPen(QPen(QColor(140, 140, 140), 1, Qt::DotLine)); // 2. 创建10条不同颜色的曲线 QVector<QColor> colors = {Qt::red, Qt::green, Qt::blue, Qt::cyan, Qt::magenta, Qt::yellow, Qt::gray, QColor(255,165,0), Qt::darkGreen, QColor(148,0,211)}; for (int i = 0; i < 10; ++i) { customPlot->addGraph(); customPlot->graph(i)->setPen(QPen(colors[i], 2)); customPlot->graph(i)->setName(QString("通道 %1").arg(i+1)); // 初始化为空数据 customPlot->graph(i)->setData(QVector<double>(), QVector<double>()); } // 3. 设置坐标轴标签和范围 customPlot->xAxis->setLabel("时间/点数"); customPlot->yAxis->setLabel("幅值"); customPlot->xAxis->setLabelColor(Qt::white); customPlot->yAxis->setLabelColor(Qt::white); customPlot->xAxis->setRange(0, 500); // 初始显示500个点 customPlot->yAxis->setRange(-1, 1); // 初始范围，后续可自动缩放 // 4. 显示图例 customPlot->legend->setVisible(true); customPlot->legend->setBrush(QColor(255, 255, 255, 150)); // 半透明白色背景 customPlot->legend->setBorderPen(QPen(Qt::white)); customPlot->legend->setTextColor(Qt::white); customPlot->axisRect()->insetLayout()->setInsetAlignment(0, Qt::AlignTop|Qt::AlignRight); // 5. 启用交互 (在下一小节详细说明) setupPlotInteractions(customPlot); }

4.2 实现数据的实时更新与滚动

updatePlot()函数由定时器周期性调用，负责将缓冲区中的数据更新到图表上，并实现类似示波器的滚动效果。

void MainWindow::updatePlot() { if (m_timeData.isEmpty()) return; QCustomPlot *customPlot = ui->customPlot; int pointsToShow = ui->spinBoxPointsPerPage->value(); // 用户设置的一屏点数 // 为每条可见的曲线设置数据 for (int i = 0; i < m_channelData.size(); ++i) { if (ui->checkBoxChannel[i]->isChecked()) { // 假设每个通道对应一个复选框 // 只取最后 pointsToShow 个点进行显示 int startIdx = qMax(0, m_channelData[i].size() - pointsToShow); QVector<double> xData = m_timeData.mid(startIdx, pointsToShow); QVector<double> yData = m_channelData[i].mid(startIdx, pointsToShow); customPlot->graph(i)->setData(xData, yData); customPlot->graph(i)->setVisible(true); } else { customPlot->graph(i)->setVisible(false); } } // 设置X轴范围，实现滚动效果 double currentMaxTime = m_timeData.last(); customPlot->xAxis->setRange(currentMaxTime - pointsToShow + 1, currentMaxTime); // Y轴自动缩放 if (ui->checkBoxAutoScaleY->isChecked()) { customPlot->yAxis->rescale(true); // true表示只缩放可见的曲线 } // 重绘图表 customPlot->replot(); }

4.3 集成强大的图表交互功能

QCustomPlot内置了丰富的交互功能，我们只需简单地启用和配置它们。

void MainWindow::setupPlotInteractions(QCustomPlot *customPlot) { // 1. 鼠标拖动轴范围 customPlot->setInteractions(QCP::iRangeDrag | QCP::iRangeZoom | QCP::iSelectPlottables); // 2. 鼠标滚轮缩放 connect(customPlot, &QCustomPlot::mouseWheel, this, [customPlot](QWheelEvent *event) { double factor = 1.0 + event->angleDelta().y() / 1200.0; // 缩放因子 customPlot->axisRect()->rangeZoom(Qt::Horizontal | Qt::Vertical, factor); customPlot->replot(); }); // 3. 右键框选放大 customPlot->setSelectionRectMode(QCP::srmZoom); customPlot->setSelectionRect(new QCPSelectionRect(customPlot)); // 框选后，可以通过双击图表快速回到自动缩放状态 connect(customPlot, &QCustomPlot::mouseDoubleClick, this, [this, customPlot]() { if (ui->checkBoxAutoScaleY->isChecked()) { customPlot->yAxis->rescale(true); } // 重置X轴到显示一屏点数 int pointsToShow = ui->spinBoxPointsPerPage->value(); double currentMaxTime = m_timeData.isEmpty() ? 0 : m_timeData.last(); customPlot->xAxis->setRange(currentMaxTime - pointsToShow + 1, currentMaxTime); customPlot->replot(); }); // 4. 显示鼠标位置处的数值（在状态栏或图上显示） connect(customPlot, &QCustomPlot::mouseMove, this, [this, customPlot](QMouseEvent *event) { double x = customPlot->xAxis->pixelToCoord(event->pos().x()); double y = customPlot->yAxis->pixelToCoord(event->pos().y()); ui->statusBar->showMessage(QString("X: %1, Y: %2").arg(x, 0, 'f', 2).arg(y, 0, 'f', 2)); }); }

通过这些设置，用户就可以像操作专业软件一样，通过鼠标拖拽平移波形、滚轮缩放、右键框选局部放大，极大地提升了数据分析的体验。

5. 功能完善、优化与项目发布

核心功能完成后，我们需要打磨细节，提升软件的实用性和健壮性，最后将其打包成一个可以独立分发的应用程序。

5.1 实现数据保存与配置持久化

保存波形图片：利用QCustomPlot的savePng、saveJpg或savePdf方法可以轻松将当前视图保存为图片。

void MainWindow::onSaveImageClicked() { QString fileName = QFileDialog::getSaveFileName(this, "保存图片", "", "PNG文件 (*.png);;JPEG文件 (*.jpg)"); if (!fileName.isEmpty()) { QFileInfo fi(fileName); if (fi.suffix().isEmpty()) fileName += ".png"; // 默认PNG格式 bool success = ui->customPlot->saveRastered(fileName, 0, 0, 1.0, fi.suffix()); if (success) { ui->statusBar->showMessage("图片保存成功: " + fileName, 3000); } else { QMessageBox::warning(this, "错误", "图片保存失败！"); } } }

保存原始数据到文本：将内存缓冲区中的数据导出为CSV或TXT格式，便于后续在MATLAB、Excel等工具中分析。

void MainWindow::onSaveDataClicked() { QString fileName = QFileDialog::getSaveFileName(this, "保存数据", "", "文本文件 (*.txt);;CSV文件 (*.csv)"); if (fileName.isEmpty()) return; QFile file(fileName); if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) { QMessageBox::warning(this, "错误", "无法创建文件！"); return; } QTextStream out(&file); // 写入表头 out << "Index"; for (int i = 0; i < m_channelData.size(); ++i) { out << QString(", Ch%1").arg(i+1); } out << "\n"; // 写入数据 int dataCount = m_timeData.size(); for (int i = 0; i < dataCount; ++i) { out << m_timeData[i]; for (int ch = 0; ch < m_channelData.size(); ++ch) { double value = (i < m_channelData[ch].size()) ? m_channelData[ch][i] : 0.0; out << QString(", %1").arg(value, 0, 'f', 6); // 保留6位小数 } out << "\n"; } file.close(); ui->statusBar->showMessage("数据保存成功: " + fileName, 3000); }

保存与加载软件配置：使用QT的QSettings类可以方便地将界面状态（如串口名、波特率、窗口大小、各通道显示状态等）保存到系统注册表（Windows）或配置文件（ini格式）中。

void MainWindow::saveSettings() { QSettings settings("MyCompany", "SerialScopePro"); settings.setValue("geometry", saveGeometry()); settings.setValue("windowState", saveState()); settings.setValue("serialPortName", ui->comboBoxPort->currentText()); settings.setValue("baudRate", ui->comboBoxBaud->currentText()); // ... 保存其他控件状态 } void MainWindow::loadSettings() { QSettings settings("MyCompany", "SerialScopePro"); restoreGeometry(settings.value("geometry").toByteArray()); restoreState(settings.value("windowState").toByteArray()); // ... 加载其他控件状态 }

在窗口的closeEvent中调用saveSettings()，在构造函数末尾调用loadSettings()，即可实现关闭记忆和启动恢复。

5.2 性能优化与常见问题处理

当数据量很大或刷新率很高时，性能可能成为瓶颈。以下是一些优化建议：

• 限制重绘区域：对于动态曲线，每次更新时，只有新增的数据部分需要重绘。但QCustomPlot的replot()默认会重绘整个图表。对于简单的动态追加，性能通常足够。如果遇到卡顿，可以尝试使用QCustomPlot::replot(QCustomPlot::rpQueuedReplot)进行异步重绘，或者精细控制QCPGraph::addData并只更新数据范围。
• 数据缓冲区管理：如前文代码所示，务必限制存储的历史数据长度，避免内存无限增长。采用环形缓冲区（FIFO）是更高效的策略。
• 降低刷新频率：并非所有应用都需要50Hz（20ms）的刷新率。根据数据速率调整m_dataTimer的间隔，在流畅性和CPU占用率之间取得平衡。
• 解析算法优化：parseProtocol函数中的memcpy和循环是性能关键点。确保其简洁高效。对于固定格式的协议，使用reinterpret_cast可能比memcpy稍快，但要注意内存对齐和可读性。

常见问题：

• 串口无法打开：检查端口是否被其他程序占用，用户是否有权限访问（在Linux/macOS上常见）。
• 数据解析乱码：首先检查波特率、数据位、停止位、校验位是否与下位机严格一致。其次，检查协议帧的字节序（大端/小端）是否匹配。
• 曲线不更新：检查串口是否成功打开并接收到数据（可通过打印rawDataBuffer到控制台调试）。检查m_dataTimer是否启动，以及updatePlot槽函数是否被正确连接和调用。
• 内存占用持续增长：检查数据缓冲区是否被正确裁剪，没有内存泄漏。

5.3 项目编译与发布

在Qt Creator中完成开发和调试后，我们需要生成一个可以独立运行的发布版本。

1. 切换构建模式：在Qt Creator左下角，将构建套件从Debug切换到Release。
2. 清理并重新构建：点击构建 -> 清理所有项目，然后点击构建 -> 构建项目“SerialScopePro”。
3. 定位可执行文件：构建成功后，在项目构建目录（通常是build-项目名-Release或release文件夹）中找到生成的.exe文件（Windows）。
4. 使用windeployqt打包（Windows）：这是最关键的一步，用于收集所有依赖的QT动态库。
   • 打开开始菜单，找到与你构建套件对应的Qt 5.12.11 (MinGW 7.3.0 32-bit)或类似的命令行工具。
   • 使用cd命令切换到上一步找到的包含.exe文件的目录。
   • 执行命令：windeployqt serialscopepro.exe（请将serialscopepro.exe替换为你的实际可执行文件名）。
   • 该命令会自动扫描.exe文件的依赖，并将所有必要的DLL、插件等复制到当前目录。
5. 测试发布包：将整个目录复制到另一台没有安装QT和编译环境的电脑上，直接运行.exe文件，看是否能正常启动。如果提示缺少某些特定的系统库（如msvcp140.dll,vcruntime140.dll），可能需要安装对应的Visual C++ Redistributable运行时。

完成以上所有步骤，一个功能完整、界面友好、交互流畅的多通道串口虚拟示波器就诞生了。它不仅是一个工具，更是一个深入理解QT图形编程、串口通信和实时数据可视化的绝佳实践项目。你可以在此基础上继续扩展，比如增加FFT频谱分析、数据滤波、协议自定义、网络传输等功能，让它更加强大。