简介:面向嵌入式与网络通信开发者的轻量级上位机工具集,基于 Qt5.12.0 框架自制,将串口调试、TCP 客户端/服务器、UDP 客户端/服务器与 CAN 分析仪等功能集成于同一界面,适合需要同时验证串行通信与网络协议、又不想在多个工具间来回切换的工程师,也适合作为学习 Qt 界面与通信编程的入门参考。压缩包共 36 个文件,以 cpp 与 h 源码为主体,配合 7 个 ui 界面文件、pro 工程文件及 qrc 资源文件,另含 CAN 驱动库与工程配置,整体仅 57KB,结构紧凑、便于在 Linux 环境下编译运行与二次修改。目前已有 1392 人学习下载。读者可从中获得一套可直接编译的多协议调试框架,参考串口参数配置、TCP/UDP 收发与 CAN 帧监控的实现思路,并借助模块化目录快速定位所需功能代码,用于自身项目移植或功能扩展。
1. 一个工具箱式的上位机:串口、TCP、UDP、CAN 全塞进一个 Qt5.12 工程
手上只有一块开发板、一根 USB 转串口线、一个 CAN 分析仪,却要在同一台电脑上同时盯串口日志、发 UDP 指令、连 TCP 服务端、抓 CAN 帧——这种场景在嵌入式联调里太常见了。这个基于 QT5.12 的上位机集合项目就是冲着这件事来的:它把串口调试助手、UDP 收发、TCP 客户端/服务端、CAN 分析仪几个常用工具做进同一个 Qt Widgets 工程,界面简易、代码直白,适合刚接触 Qt 串口通信与 TCP/IP、UDP 编程的开发者拿来跑通、拆开、再按自己的协议改。它不是工业级成品,而是一份能编译、能上手改的上位机骨架,新手照着能点亮第一个串口,熟手能看到多协议模块怎么在一个 Qt 工程里共存。
2. 工程结构与技术选型:Qt Widgets + QSerialPort + QtNetwork 的三层分工
2.1 为什么是 Qt5.12 而不是更新的版本
Qt5.12 是 LTS 版本,QSerialPort、QTcpSocket、QUdpSocket这些模块在 5.12 上接口稳定,串口和网络相关的坑基本被社区踩平了。这个项目选它,核心原因是依赖少、编译快、跨平台:Windows 上装个 Qt 5.12.x 的 MinGW 或 MSVC 套件就能编,Linux 上装qtbase5-dev和libqt5serialport5-dev也能跑。相比 Qt6 需要额外处理 CMake 与模块拆分,5.12 的 qmake 工程对新手更友好,.pro文件里加两行就能把串口和网络模块拉进来。
常见做法是在.pro里显式声明模块,避免链接期报找不到符号:
QT += core gui serialport network greaterThan(QT_MAJOR_VERSION, 4): QT += widgets TARGET = HostToolBox TEMPLATE = app SOURCES += main.cpp \ mainwindow.cpp \ serialworker.cpp \ tcpworker.cpp \ udpworker.cpp \ canworker.cpp HEADERS += mainwindow.h \ serialworker.h \ tcpworker.h \ udpworker.h \ canworker.hserialport对应QSerialPort,network对应QTcpSocket/QTcpServer/QUdpSocket。少了任何一个,编译能过但链接会挂,这是新手第一个容易翻车的地方。TARGET是生成的可执行文件名,改成自己的项目名即可。
2.2 目录与模块划分
工程按“一个协议一个 worker 类”来切,主窗口只负责界面和信号转发,业务逻辑下沉到各 worker。典型结构如下:
| 文件 | 职责 | 关键类/接口 |
|---|---|---|
main.cpp | 程序入口,创建 QApplication 与主窗口 | QApplication、MainWindow |
mainwindow.* | 界面布局、按钮槽函数、日志显示 | MainWindow |
serialworker.* | 串口打开/关闭、参数配置、收发 | QSerialPort |
tcpworker.* | TCP 客户端连接、服务端监听、收发 | QTcpSocket、QTcpServer |
udpworker.* | UDP 绑定端口、单播/广播收发 | QUdpSocket |
canworker.* | CAN 帧封装、发送、接收解析 | 自定义帧结构 + 串口/驱动适配 |
这种切法的好处是:串口和网络互不干扰,某个模块出问题只影响自己那一块;坏处是主窗口要维护多个 worker 的生命周期。我一般会在MainWindow构造函数里统一new出来,析构时统一delete,避免野指针。
2.3 信号槽是这套架构的粘合剂
Qt 的信号槽机制在这里承担了“界面 ↔ 业务”的解耦。worker 收到数据后发一个信号,主窗口的槽函数负责把字节流格式化成十六进制或文本追加到日志框;界面上的“发送”按钮触发主窗口槽函数,再调用 worker 的发送方法。整条链路不跨线程时是直连,跨线程时自动排队,这也是为什么这套简易架构能撑住串口和网络同时收发的场景。
// mainwindow.cpp 片段:把串口收到的数据接到日志显示 connect(serialWorker, &SerialWorker::dataReceived, this, &MainWindow::appendSerialLog); connect(serialWorker, &SerialWorker::errorOccurred, this, &MainWindow::showError); // 界面发送按钮 -> worker 发送 connect(ui->btnSerialSend, &QPushButton::clicked, this, [this]() { QByteArray data = parseHexOrText(ui->editSerialSend->text()); serialWorker->sendData(data); });dataReceived携带QByteArray,appendSerialLog里做toHex(' ')或直接文本转换;parseHexOrText是自定义的解析函数,根据界面上的“HEX/文本”单选按钮决定按十六进制还是按字符串解析。参数说明:QByteArray是 Qt 的字节容器,串口和网络收发都用它,避免char*的长度歧义。
3. 串口调试助手核心实现:从打开端口到收发闭环
3.1 串口参数配置与打开流程
串口模块的第一件事是把波特率、数据位、校验位、停止位、流控配好再open。QSerialPort的接口很直白,但顺序不能乱:先setPortName,再设参数,最后open,打开成功后再去拿setDataTerminalReady之类的控制线状态。
bool SerialWorker::openPort(const QString &portName, int baudRate, QSerialPort::DataBits dataBits, QSerialPort::Parity parity, QSerialPort::StopBits stopBits) { if (serial->isOpen()) serial->close(); serial->setPortName(portName); serial->setBaudRate(baudRate); serial->setDataBits(dataBits); serial->setParity(parity); serial->setStopBits(stopBits); serial->setFlowControl(QSerialPort::NoFlowControl); if (!serial->open(QIODevice::ReadWrite)) { emit errorOccurred(serial->errorString()); return false; } connect(serial, &QSerialPort::readyRead, this, &SerialWorker::onReadyRead); return true; }逻辑说明:open(QIODevice::ReadWrite)是读写模式;readyRead信号在串口缓冲区有数据时触发,接到onReadyRead里统一readAll()。参数说明:baudRate常见 9600/115200/921600,dataBits一般Data8,parity常用NoParity,stopBits常用OneStop。如果打开失败,errorString()会给出“Permission denied”或“No such file”这类信息,直接显示到界面比弹窗更好排查。
3.2 接收与发送:字节流怎么变成可读日志
接收侧的核心是readAll()后按界面模式格式化。发送侧则要处理“用户输入的是 HEX 还是文本”这个分支,HEX 模式下要把"01 02 AB"这种字符串转成QByteArray。
void SerialWorker::onReadyRead() { QByteArray chunk = serial->readAll(); emit dataReceived(chunk); // 交给界面决定显示格式 } void SerialWorker::sendData(const QByteArray &data) { if (!serial->isOpen()) { emit errorOccurred(QStringLiteral("串口未打开")); return; } qint64 written = serial->write(data); if (written != data.size()) { emit errorOccurred(QStringLiteral("写入不完整")); } }readAll()一次可能只拿到半帧数据,这是串口的常态,不是 bug。界面层如果要做协议解析,得自己维护一个接收缓冲区,按帧头帧尾或长度字段拼包。发送侧write返回实际写入字节数,和data.size()不一致时说明底层缓冲满了,常见做法是等bytesWritten信号再继续发,简易版可以先提示用户。
3.3 十六进制与文本双模式解析
HEX 解析是串口助手的高频需求,写不好就会在空格、大小写、奇数位上翻车。下面这个实现去掉了空格和常见分隔符,再按两位一组转换:
QByteArray parseHexOrText(const QString &input, bool hexMode) { if (!hexMode) return input.toUtf8(); QString cleaned = input; cleaned.remove(QRegularExpression("[\\s,;:]")); // 去掉分隔符 if (cleaned.size() % 2 != 0) { cleaned.prepend('0'); // 奇数位补前导 0 } QByteArray out; out.reserve(cleaned.size() / 2); for (int i = 0; i < cleaned.size(); i += 2) { bool ok = false; out.append(static_cast<char>( cleaned.mid(i, 2).toUInt(&ok, 16))); if (!ok) return QByteArray(); // 非法字符返回空 } return out; }逻辑说明:先按正则去掉空白和分隔符,奇数长度补0保证两位一组,toUInt(&ok, 16)做十六进制转换,ok为 false 说明用户输入了G这类非法字符,直接返回空让上层提示。参数说明:hexMode由界面单选按钮决定;返回空QByteArray时调用方应判断并提示,而不是直接发出去。
4. TCP/UDP 与 CAN 模块:多协议共存的收发链路
4.1 TCP 客户端与服务端的双角色
TCP 模块要同时支持“连别人”和“被别人连”。客户端用QTcpSocket,服务端用QTcpServer,两者共用一套收发接口,界面用下拉框切换角色。
// 客户端连接 void TcpWorker::connectToHost(const QString &host, quint16 port) { socket->connectToHost(host, port); connect(socket, &QTcpSocket::connected, this, [this]() { emit statusChanged(QStringLiteral("TCP 已连接")); }); connect(socket, &QTcpSocket::readyRead, this, [this]() { emit dataReceived(socket->readAll()); }); connect(socket, &QTcpSocket::errorOccurred, this, [this](QAbstractSocket::SocketError) { emit errorOccurred(socket->errorString()); }); } // 服务端监听 bool TcpWorker::startListen(quint16 port) { if (!server->listen(QHostAddress::Any, port)) { emit errorOccurred(server->errorString()); return false; } connect(server, &QTcpServer::newConnection, this, [this]() { QTcpSocket *client = server->nextPendingConnection(); clients.append(client); connect(client, &QTcpSocket::readyRead, this, [this, client]() { emit dataReceived(client->readAll()); }); }); return true; }逻辑说明:客户端连接成功后挂readyRead;服务端在newConnection里取出nextPendingConnection()并保存到clients列表,否则 socket 对象没人管会泄漏。参数说明:QHostAddress::Any表示监听所有网卡,port要和对方约定一致;errorOccurred是 Qt5.15 之后的信号名,5.12 上对应error信号,移植时要注意这个差异。
4.2 UDP 单播与广播
UDP 模块比 TCP 简单,bind一个本地端口后就能readDatagram和writeDatagram。广播场景要把writeDatagram的目标地址设成QHostAddress::Broadcast。
bool UdpWorker::bindPort(quint16 localPort) { if (!socket->bind(QHostAddress::AnyIPv4, localPort, QUdpSocket::ShareAddress)) { emit errorOccurred(socket->errorString()); return false; } connect(socket, &QUdpSocket::readyRead, this, [this]() { while (socket->hasPendingDatagrams()) { QByteArray buf; buf.resize(int(socket->pendingDatagramSize())); QHostAddress sender; quint16 senderPort = 0; socket->readDatagram(buf.data(), buf.size(), &sender, &senderPort); emit datagramReceived(buf, sender.toString(), senderPort); } }); return true; }逻辑说明:hasPendingDatagrams循环处理,避免一次只读一个包导致积压;pendingDatagramSize拿到当前包长度再resize,这是 UDP 读包的标准写法。参数说明:ShareAddress允许多个进程绑同一端口,调试时有用;sender/senderPort回传给界面,方便看数据从哪来。
4.3 CAN 帧的封装与解析
CAN 模块在 PC 端通常依赖厂商驱动或 USB-CAN 适配器,项目里把它抽象成一个 worker,内部维护帧结构:ID、数据长度、数据字节、帧类型(标准帧/扩展帧/远程帧)。发送时按适配器协议打包,接收时解析回结构体再显示。
struct CanFrame { quint32 id; quint8 dlc; // 数据长度 0~8 quint8 data[8]; bool extended; // 是否扩展帧 bool remote; // 是否远程帧 }; void CanWorker::sendFrame(const CanFrame &frame) { QByteArray raw; raw.append(char(frame.extended ? 0x01 : 0x00)); raw.append(char(frame.remote ? 0x01 : 0x00)); raw.append(char((frame.id >> 24) & 0xFF)); raw.append(char((frame.id >> 16) & 0xFF)); raw.append(char((frame.id >> 8) & 0xFF)); raw.append(char(frame.id & 0xFF)); raw.append(char(frame.dlc)); raw.append(reinterpret_cast<const char*>(frame.data), frame.dlc); transport->write(raw); // transport 为串口或厂商 SDK 封装 }逻辑说明:这里用一个简单的自定义帧头把 CAN 帧序列化,transport可以是串口 worker,也可以是厂商 SDK 的封装,换适配器只改transport这一层。参数说明:id标准帧 11 位、扩展帧 29 位,dlc最大 8(经典 CAN),extended/remote决定帧类型。实际对接厂商设备时,帧格式要按设备手册改,别直接照搬。
5. 避坑与排查:编译、串口、网络、CAN 四类高频问题
5.1 编译期找不到 QSerialPort
现象:.pro里没写serialport,或者装了 Qt 但没装串口模块,编译报QSerialPort: No such file or directory。原因:Qt 安装时串口模块是可选项,MinGW 套件默认不一定带。解决:在 Qt Maintenance Tool 里补装Qt Serial Port,.pro里确认QT += serialport,然后执行qmake再构建,别只点构建。
5.2 串口打开失败但设备管理器能看到
现象:open返回 false,errorString提示 Permission denied。原因:端口被别的调试助手占用,或者 Linux 下当前用户不在dialout组。解决:先关掉其他串口工具;Linux 下sudo usermod -aG dialout $USER后重新登录。这个坑我踩过不止一次,血泪经验是打开前先判断isOpen()。
5.3 TCP 连不上但 ping 得通
现象:connectToHost后一直不触发connected,最后超时。原因:目标端口没监听、防火墙拦截,或者服务端只绑了127.0.0.1。解决:先用telnet host port或nc -vz host port确认端口通不通;服务端监听地址改成QHostAddress::Any;检查本机防火墙规则。别一上来就怀疑代码。
5.4 UDP 收不到广播包
现象:单播正常,广播收不到。原因:绑定时用了QHostAddress::LocalHost,或者没设ShareAddress,或者发送端广播地址不对。解决:绑定用AnyIPv4,加ShareAddress,发送端目标地址用QHostAddress::Broadcast并确认子网掩码匹配。
5.5 CAN 帧发出去设备没反应
现象:write返回成功,但分析仪上没帧。原因:帧格式和适配器协议不一致,或者波特率没配对。解决:对照设备手册逐字节核对帧头,先用厂商自带工具确认能发,再换到自己的代码;波特率、采样点这些参数两边必须一致。这个模块最容易变成黑匣子,建议在发送前把原始字节打到日志里。
6. 二次开发改造:把简易骨架变成自己的协议工具
这套代码的价值不在“功能全”,而在“结构清楚、改起来不疼”。真要拿去做项目,我一般按三步改:先换协议层,再补持久化,最后加自动化。
第一步,协议解析独立成类。现在收发逻辑和界面混在 worker 里,二次开发时把“拼包/拆包”抽成ProtocolParser,worker 只负责搬运字节。这样换一个 Modbus 或自定义帧格式,只改解析类,界面和传输层不动。验证方法是写一组固定字节的单元测试,喂进去看输出帧对不对。
第二步,配置持久化。串口参数、TCP 地址、UDP 端口这些每次重开都要重填很烦,用QSettings存起来,启动时读回。代码量很小:
QSettings settings("MyCompany", "HostToolBox"); settings.setValue("serial/baud", ui->comboBaud->currentText().toInt()); int baud = settings.value("serial/baud", 115200).toInt();QSettings在 Windows 写注册表、Linux 写~/.config,跨平台不用自己管路径。注意键名统一加前缀,别和别的工具撞。
第三步,加发送队列和定时发送。调试时经常要按固定周期发心跳帧,用QTimer驱动一个发送队列,比手动点按钮靠谱。队列里存QByteArray,定时器到期取一条发,发完再取,避免一次性灌爆底层缓冲。
| 改造点 | 改动位置 | 验证方式 |
|---|---|---|
| 协议解析抽离 | 新增ProtocolParser类 | 固定字节单测 |
| 配置持久化 | MainWindow构造/析构 | 重启后参数保留 |
| 定时发送 | 新增QTimer+ 队列 | 抓包看周期是否稳定 |
| CAN 适配器替换 | CanWorker::transport | 厂商工具对比帧 |
最后说个习惯:每次改完传输层,我都会先用回环(本机 TCP 连本机、UDP 发本机)跑一遍,确认收发闭环没问题,再接真实设备。这个顺序能挡掉大半“到底是代码问题还是设备问题”的扯皮。希望帮到你。
本文还有配套的精品资源,点击获取