1. 串口曲线工具,为什么要自己用 Qt 写
上周帮同事看一台采集板:每 20ms 吐一行 ASCII 数值,串口助手只能刷滚动文本,想回看趋势得先存文件、再导进表格画图,中间隔着十几分钟。这类「看得到数、看不到趋势」的活,我一般直接用 Qt 这套代码开发工具写个桌面小工具:QSerialPort 把字节收进来,QCustomPlot 把点画成随时间滚动的曲线,几百行代码就能替掉串口助手加导出加画图的三段流程。
它适合两类人。一类是手上有设备、需要盯着某一路数值连续变化的人,关心的是端口参数怎么配、字节怎么拆成数据点;另一类是已经能把串口打开、但曲线一多界面就卡、拖窗口迟滞的人,关心的是线程和刷新节奏。下面按「能打开、能收到、能画动、不翻车」的顺序,把我自己踩过的路铺一遍。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 串口打开与参数设定:Qt 代码开发工具的第一道关
真正让人卡住的往往不是绘图,而是第一步:程序跑起来了,串口没打开,窗口一片空白,也没有任何提示。Qt 的串口能力都收在 QSerialPort 这个类里,打开、读写、设置波特率和校验位都由它提供,但它不会替你检查返回值,配置错了也不会主动弹窗。这一章把打开动作拆成配置、检查、验证三段,先把「能通信」这件事钉死。
2.1 工程准备:模块、头文件与绘图控件的落位
新建工程后第一件事是把模块加全。QSerialPort 不在默认的 core/gui 里,QCustomPlot 又依赖打印导出相关的模块,漏一个就是一堆 undefined reference。
pro复制# .pro 里一次性加齐,缺 serialport 会找不到 QSerialPort 头文件
QT += core gui serialport printsupport
逻辑说明:serialport 是 QSerialPort 所在的模块,printsupport 是 QCustomPlot 导出图片、打印时用到的依赖。用 CMake 的工程就在 find_package 里把 SerialPort 和 PrintSupport 两个组件一起写上,再链接到目标上。
参数说明:不需要把整个 Qt 的模块都堆进去,模块越多编译越慢,排查链接错误时干扰也越大。QCustomPlot 不是靠包管理器装的,qcustomplot.h 和 qcustomplot.cpp 两个文件直接拖进工程目录,在 .pro 的 HEADERS 和 SOURCES 里登记,主窗口里 #include "qcustomplot.h" 即可。放好之后先编译一次空工程,确认能过再写业务代码;我见过不少人把链接错误和逻辑错误混在一起查,最后发现只是少了一行 QT +=。
2.2 从 setPortName 到 open:顺序别颠倒
打开串口的代码很短,但每一步都有它的位置。我习惯把参数一次性配完再 open,而不是打开之后回头改。
cpp复制QSerialPort serial;
serial.setPortName("/dev/ttyUSB0"); // Windows 下换成 COM3 这类名字
serial.setBaudRate(115200); // 与设备端保持一致
serial.setDataBits(QSerialPort::Data8);
serial.setParity(QSerialPort::NoParity);
serial.setStopBits(QSerialPort::OneStop);
serial.setFlowControl(QSerialPort::NoFlowControl);
if (!serial.open(QIODevice::ReadWrite)) {
qDebug() << "无法打开串口:" << serial.errorString();
}
逻辑说明:setPortName 只是把端口名记进对象内部,setBaudRate 等一连串 set 也只是填写配置,真正向系统申请句柄的是 open。open 返回 bool,失败时必须读 errorString(),它会给出「设备不存在」「权限不足」「被占用」这类可定位的原因,比一个沉默的 false 有用得多。打开模式用 QIODevice::ReadWrite,只收不发可以退化成 ReadOnly,但调试阶段建议保持读写,方便做回环自测。
参数说明:端口名在 Linux 上通常形如 /dev/ttyUSB0、/dev/ttyACM0,Windows 上是 COM3 这种形式,两边不能混写;漏掉 /dev/ 前缀是最常见的打开失败原因之一。波特率没有默认值可用,必须和设备端一致。open 之后再改参数,部分平台的驱动会重新配置端口,行为不如前置配置稳定,所以顺序上我始终坚持「先配完,再打开」。
2.3 五个参数怎么定:一张表说清
串口参数看着多,实际决定通信成败的就那几个,定错了表现也不一样,对照着查比盲试快。
| 参数 | 常见取值 | 定错了的现象 |
|---|---|---|
| 端口名 | /dev/ttyUSB0、/dev/ttyACM0、COM3 |
open 失败,errorString 报设备不存在或无法打开 |
| 波特率 | 9600、115200,按设备说明书 | 收到成片乱码,或全是 0x00 / 0xFF 这类固定字节 |
| 数据位 | Data8 | 字节错位,数值整体偏移 |
| 校验位 | NoParity | 高位被吃掉,超过某个范围的数值全部异常 |
| 停止位 | OneStop | 偶发丢字节,帧尾对不齐 |
| 流控 | NoFlowControl | 发几包之后彻底卡住,写不出去也收不进来 |
逻辑说明:表格里最容易被忽略的是流控。设备端没启用硬件流控而主机端开了,或者反过来,表现是前一秒还正常、几包之后彻底停摆,因为一端在等对端的 CTS 信号。除非设备手册明确要求,我默认都设 NoFlowControl。
参数说明:波特率是唯一必须逐个设备确认的项,同一块板子换个固件都可能改。校验位和数据位在多数传感器场景是 8N1,即 Data8 + NoParity + OneStop,但不要把它当默认值照抄,先看设备端的协议说明,再回来填。
2.4 先用 write 做一次回环:把问题锁在打开阶段
打开成功不等于链路通。我习惯在写解析逻辑之前,先验证一次发送,用一根杜邦线把 USB-TTL 的 TX 和 RX 短接,做本地回环。
cpp复制qint64 n = serial.write("Hello, Serial Port!");
if (n == -1) {
qDebug() << "写入失败:" << serial.errorString();
} else {
qDebug() << "已提交字节数:" << n;
}
逻辑说明:write 返回的是实际提交到发送队列的字节数,返回 -1 表示失败,失败的详细原因同样在 errorString() 里。回环短接后,这一串字节会原样回到接收缓冲区,触发 readyRead,此时在槽函数里打印 readAll() 的结果,就能确认「打开、参数、发送、接收」四件事同时成立。
参数说明:write 成功返回不代表对方已经收到,它只表示数据进了本机的发送缓冲。回环测试的意义在于把范围缩小,如果回环收不到,问题一定在参数配置或端口本身,而不是你的解析代码;如果回环能收到、接上真实设备却收不到,再去查波特率和接线,能省掉大量来回。
3. 收数、拆包与时间戳:readyRead 里该做和不该做的事
串口能打开之后,接下来的问题是「收到的到底是什么」。串口是字节流,不是消息队列:设备端可能一次发半行、也可能连发三行粘在一起,你收到 readyRead 只说明缓冲区里有新字节,不说明一帧已经完整。这一章把字节流变成一个个带时间戳的数据点。
3.1 readyRead 与 readAll:信号只说「有」,不说「够」
接收的入口是 readyRead 信号,它在串口有新数据可读时触发。标准写法是连接到自己的槽函数,在槽里一次性把当前可用数据取走。
cpp复制connect(&serial, &QSerialPort::readyRead, this, &YourClass::readData);
void YourClass::readData() {
QByteArray data = serial.readAll(); // 取走当前缓冲区全部可用字节
// 交给后续解析
}
逻辑说明:readAll() 取走当前缓冲区里所有已到达的字节并清空它,下一次触发再取新的。不要在槽里只读固定长度,除非协议是严格定长的;也不要在槽里做耗时操作,这个槽运行在串口对象所属的线程,做重活会阻塞后续数据的到达。
参数说明:readyRead 可能一秒钟触发几十次,也可能一次带上好几帧,频率完全由设备端决定,不能拿它当帧同步信号。真正的帧边界要由协议自己定义,下一节处理。
3.2 行缓冲拆包:半包、粘包与脏数据一起解决
ASCII 协议最常见的是换行分隔,一行一个数。处理方式是自己维护一个缓冲区,把新到的字节追加进去,再从头找分隔符,找到一个就切一行。
cpp复制void YourClass::readData() {
m_rxBuffer.append(serial.readAll()); // 先追加,不做假设
int idx;
while ((idx = m_rxBuffer.indexOf('\n')) >= 0) {
QByteArray line = m_rxBuffer.left(idx).trimmed(); // 去掉 \r 和空格
m_rxBuffer.remove(0, idx + 1); // 从缓冲区移走已消费部分
if (line.isEmpty()) continue;
handleLine(line);
}
if (m_rxBuffer.size() > 4096) { // 长期没有分隔符时兜底
m_rxBuffer.clear();
}
}
逻辑说明:这段代码同时解决了三个问题。半包——一次只到了半行,找不到 \n,循环不执行,字节留在缓冲区等下一批;粘包——一次到了三行,循环连切三次;脏数据——空行直接跳过,不会进解析。末尾的容量保护是后悔药:如果设备端中途重启、发了一段不带换行的调试信息,缓冲区会一直涨,超过 4096 字节直接清掉,避免内存被慢慢啃光。
参数说明:trimmed() 去掉首尾空白,包括 Windows 风格的 \r,这一步不能省,否则 toDouble 会因为尾部回车解析失败。4096 这个上限按你单帧最大长度调,只要明显大于正常帧长、又不至于吞掉一整批数据就行。
3.3 时间戳打在解析处,不打在绘图处
一行文本要变成曲线上的一个点,需要一个横坐标。我的做法是在解析完成的瞬间取系统时间,而不是等到绘图时再取。
cpp复制void YourClass::handleLine(const QByteArray &line) {
bool ok = false;
double v = line.toDouble(&ok);
if (!ok) {
++m_badLineCount; // 记一笔,便于排查协议不匹配
return;
}
qint64 ms = QDateTime::currentMSecsSinceEpoch();
m_latest = QPointF(ms / 1000.0, v); // x 轴用秒,便于设范围
m_hasNew = true; // 只标记,不在这里画
}
逻辑说明:时间戳在解析处打,反映的是数据到达的真实时刻;如果拖到绘图时再打,界面按固定频率刷新,所有点会被压到同一条垂直线上,曲线形状就失真了。解析失败的行直接丢弃并计数,不要让非数值文本进曲线,否则一个异常值会把 y 轴量程瞬间撑爆,后面几十秒的曲线都被压成一条直线。
参数说明:toDouble 的第二个参数是成功标志,必须传,不能靠返回值判断。x 轴存的是秒为单位的浮点数,绘图时直接用它设范围;如果你需要显示成可读时间,在刻度格式化那一层处理,不要在数据层存字符串。
3.4 收不到数时,先分清是链路问题还是解析问题
排查的第一步是区分层次。在 readData 里加一句 qDebug() << data.size() << data.toHex();,能看到字节就说明链路通了,问题在解析;一个字节都看不到,问题在端口参数或接线。这一步花十秒钟,能省掉半小时的盲猜。
第二步看计数。解析成功数和失败数都记下来,成功数一直是 0 而字节数在涨,多半是分隔符不对或者波特率偏差导致内容本身就是乱码;成功数正常但曲线不动,问题就跑到下一章的刷新环节去了。把这三层分开,排查路径才不会绕圈。
4. CustomPlot 实时绘图:代码开发工具选型与刷新节流
曲线画不出来,一半原因在数据没到,另一半在绘制时机。QCustomPlot 的用法本身不复杂,加曲线、加数据、重绘三步,但把这三步放进一个每秒触发上百次的槽里,界面就会肉眼可见地变卡。这一章讲清楚配置、绘制和刷新节奏分别该放在哪。
4.1 addGraph 与坐标轴:配置只做一次
曲线对象由 addGraph() 创建,返回的指针要存成成员变量,后续所有加点操作都用它。轴标签、量程这类外观配置也是一次性的。
cpp复制QCPGraph *graph = customPlot.addGraph(); // 只调用一次,指针存成员
graph->setName("Realtime Data");
customPlot.xAxis->setLabel("Time");
customPlot.yAxis->setLabel("Value");
customPlot.xAxis->setRange(0, 60); // 初始 60 秒窗口
逻辑说明:addGraph 每次调用都会新建一条空曲线,放在刷新函数里就等于每帧多一条线,跑几分钟之后图上是几百条重叠曲线,内存也跟着涨。轴标签同理,setLabel 一次即可,重复设置除了浪费没有收益。
参数说明:setRange 的初值只影响启动时的视野,后续滚动由刷新逻辑接管。如果同一张图要画多路数据,就 addGraph 多次并各自保存指针,不要让它们共用一条曲线;颜色和线宽在创建后设置,避免每次刷新重设。
4.2 addData 加 replot:为什么不能每来一帧就画
最直观的写法是收到数据就加点、加点就重绘:
cpp复制void YourClass::updatePlot(qreal time, qreal value) {
graph->addData(time, value); // 追加一个数据点
customPlot.replot(); // 立即整图重绘
}
逻辑说明:这段代码逻辑正确,性能上却是灾难。replot() 是一次同步的整图重绘,坐标轴刻度、网格、所有曲线都要重新算一遍、重新画一遍。串口每秒来一百帧就调用一百次,主线程的时间几乎全花在重绘上,鼠标拖动、窗口缩放都会明显迟滞,数据量大之后更严重。
参数说明:addData 本身很轻,问题全在 replot。所以正确的拆分是「加点可以频繁,重绘必须节流」,两者不在同一个频率上。
4.3 定时器节流:50ms、20Hz 与采集频率解耦
把重绘交给定时器,采集频率和界面刷新频率就分开了。
cpp复制m_timer.setInterval(50); // 50ms 一次,约 20Hz
connect(&m_timer, &QTimer::timeout, this, &YourClass::onRefresh);
m_timer.start();
void YourClass::onRefresh() {
if (!m_hasNew) return; // 没有新数据就什么都不做
m_hasNew = false;
graph->addData(m_latest.x(), m_latest.y());
customPlot.xAxis->setRange(m_latest.x() - 60, m_latest.x()); // 滚动 60 秒窗口
customPlot.replot();
}
逻辑说明:串口按设备节奏收,解析在收到时完成,界面按固定 20Hz 从「最新结果」里取一次。人眼对 20Hz 以上的刷新差异基本无感,但 CPU 占用能省下一大半,这是整套方案里性价比最高的一处改动。m_hasNew 标记让没有新数据的周期直接返回,避免空转重绘。
参数说明:50ms 是刷新间隔,可按需下调到 33ms 左右;再快意义不大,反而挤占主线程。setRange 里减去的 60 是可视窗口宽度,单位是秒,和 x 轴的时间单位保持一致。窗口宽度决定了你能一眼看到多长的趋势,太窄看不出周期,太宽则每帧要处理的点变多。
4.4 窗口滚动与数据裁剪:别让点无限堆
x 轴滚动只是改变了视野,旧数据点仍然留在曲线对象里。跑一晚上之后,曲线里有几十万个点,每次重绘都要遍历一遍,内存也一路涨。
| 策略 | 做法 | 代价 |
|---|---|---|
| 只滚视野 | 只调 setRange,不删点 | 实现最简单,长时间运行后重绘变慢、内存上涨 |
| 按范围裁剪 | 每次滚动后删掉窗口左侧之外的点 | 视野外无法回看,需要额外记录 |
| 固定点数 | 只保留最近 N 个点,超出即淘汰 | 时间跨度随采样率浮动,需按场景定 N |
逻辑说明:我更常用第二种,在 onRefresh 里滚动完范围之后,把横坐标小于窗口左边界的数据点从曲线里移除,内存和重绘成本都是常数级。如果业务上需要回看历史,就把完整数据另外落到文件或环形缓冲里,绘图只负责显示窗口内的部分,两件事分开做。
参数说明:裁剪的阈值要和窗口宽度对齐,窗口 60 秒就删 60 秒之前的点,不要多删也不要少删。用固定点数策略时,N 取得太小曲线会跳动,太大又失去意义,一般按「窗口宽度乘以采样率」估算一个上限。
5. 常见问题排查:串口加绘图最容易翻车的五处
这套组合的故障点很集中,几乎都落在「打开、收到、画动」三个环节的交界处。下面五条是我自己和身边人反复遇到的现场,每条按现象、原因、解决三段记,照着对一遍通常能定位到具体那一行。
5.1 现象:open 返回 false,界面上什么都没有
原因:代码里调用了 open 但没有检查返回值,或者检查了却只写一个 qDebug,发布版本里被关掉,用户端就表现为「点了没反应」。也有相当一部分是端口名写错,比如把 /dev/ttyUSB0 写成 ttyUSB0。
解决:open 之后立刻判断返回值,失败时把 errorString() 的内容显示到界面上,不要只写日志。把端口名的来源改成可配置项,让使用者自己填或者从系统里枚举出来选,而不是硬编码在代码里。
5.2 现象:串口指示灯在闪,曲线纹丝不动
原因:readyRead 没连上,或者连上了但槽函数里没把数据存到绘图能取到的地方。还有一种常见情况是数据全被解析丢了,toDouble 一直失败,m_hasNew 永远是 false。
解决:先在 readData 里打印收到的字节数和十六进制内容,确认字节确实进来了;再在 handleLine 里打印解析成功与失败计数。字节有、成功数为零,就去查分隔符和数值格式;成功数正常、曲线不动,问题就在刷新逻辑,检查定时器是否真的启动了。
5.3 现象:数据一到上百 Hz,窗口拖动就迟滞,风扇开始转
原因:把 replot() 放在了数据到达的槽里,每来一帧重绘一次整图。如果解析里还混着 QString 转换和写日志,主线程被拖得更狠。
解决:加点和重绘拆开,重绘交给定时器,按 50ms 一次触发;解析里的字符串转换、写文件这类操作移出主线程,或者至少改成批量处理。判断标准很直接:拖动窗口边框,如果迟滞跟着数据频率变化,就一定是刷新节奏的问题。
5.4 现象:曲线像锯齿,尖峰被削平
原因:刷新频率低于数据频率时,如果每次都只取「最新一个点」,中间的点就被丢掉了。采样率 100Hz、界面 20Hz,就意味着五分之四的数据没进曲线。
解决:定时器回调里不要只取一个点,把这一周期内累积的所有点一次性 addData 进去,或者用批量加点的接口一次提交。绘制频率可以低,数据不能丢,这两件事本来就该分开设计。
5.5 现象:跑一晚上内存涨到几个 G,或者程序突然退出
原因:接收缓冲区没有上限,遇到不带分隔符的数据就一直追加;曲线里的点只增不减,重绘成本随时间线性上升。
解决:给行缓冲加容量上限,超过就清空并记一次异常;给曲线做窗口裁剪,只保留可视范围内的点,历史数据另存。这两处保护都很短,加起来不到十行,但决定了这个工具能不能连续跑过一夜。
6. 双线程装配与验证:把采集和界面彻底隔开
数据量再往上走,光靠节流不够,因为解析本身也开始占主线程。我的做法是把接收和解析整体挪到数据线程:UdpReceiver 或串口对象只负责收包发信号,Parser 在数据线程里把字节解析成结构体,结果放进缓存,再通过队列信号通知界面。
cpp复制// 线程装配:对象 move 到线程,而不是继承 QThread 写业务
auto *ioThread = new QThread;
auto *receiver = new UdpReceiver(QHostAddress("239.10.1.20"), 7200);
receiver->moveToThread(ioThread);
connect(ioThread, &QThread::finished, receiver, &QObject::deleteLater);
connect(ioThread, &QThread::started, receiver, &UdpReceiver::start);
ioThread->start();
// 解析对象也放进同一线程,结果用队列连接送回界面
auto *parser = new DataParser;
parser->moveToThread(ioThread);
connect(receiver, &UdpReceiver::frameReceived, parser, &DataParser::parseFrame);
connect(parser, &DataParser::frameReady, uiManager, &UiManager::updateFromFrame,
Qt::QueuedConnection);
逻辑说明:用 moveToThread 而不是继承 QThread 再在里面写业务,是为了把「线程控制」和「业务逻辑」解耦,换数据源时只改业务类。connect 默认的 AutoConnection 在跨线程时会自动退化成队列连接,槽函数在接收者所在线程执行;但 frameReady 到 updateFromFrame 这一处我仍然显式写 Qt::QueuedConnection,避免有人后来把对象 move 回主线程,导致更新直接跨线程操作控件。
参数说明:界面刷新频率和网络帧率必须解耦,收 100Hz、界面 20Hz 就够了,用 QTimer 按 50ms 从「最新解析结果缓存」里取快照,而不是每来一帧刷一次。缓存用有界队列,上限 512 包,满了丢旧帧保新帧,防止消费端跟不上时内存无限增长。
验证也简单:在解析线程里打一行每帧的时间间隔,在界面线程里打一行刷新间隔,两组数字应该是独立的,前者随设备频率变,后者稳定在 50ms 附近;再拖动窗口,如果不再迟滞,说明搬运确实隔开了。血泪经验是别在数据线程里碰任何控件,哪怕只是 setText 一行日志,偶发崩溃往往就出在这种「看起来没问题」的顺手操作上。从那以后我每次接新的数据源,都先把这两行间隔日志加上再写业务,希望帮到你。
