【Qt实战】工业级多线程串口通信：从底层协议设计到完美收发闭环

前言

在开发电机上位机、PLC通讯或嵌入式控制系统时，Qt 的 QSerialPort 是最常用的工具。然而，很多开发者（包括曾经的我）在将其放入多线程（QThread）环境时，都会遭遇“诡异报错”、“数据发丢”、“界面卡死”的三大拦路虎。

本文将总结一套经过验证的工业级通信架构，详细拆解从对象依附性到字节对齐的每一个关键知识点。

---

第一章：多线程的“户口”问题（Thread Affinity）

这是 Qt 多线程开发中 90% 的崩溃根源。

1.1 核心概念：对象依附性

在 Qt 中，QObject 及其子类（如 QSerialPort）都有一个属性叫 Thread Affinity（依附性）。通俗来说，就是这个对象的“户口”在哪个线程。

• 规则：一个对象只能被它“户口”所在的线程操作。
• 禁忌：如果对象的户口在主线程，你决不能在子线程的 run() 函数里调用它的 write() 或 read() 方法。

1.2 经典错误：在构造函数里 new

// ❌ 错误写法
Send_receive_pack_thread::Send_receive_pack_thread() {
    // 构造函数是在【主线程】执行的
    // 这里传入 this，导致串口对象的户口落在了【主线程】
    serial = new QSerialPort(this); 
}

void Send_receive_pack_thread::run() {
    // run 是在【子线程】执行的
    // 报错：Cannot send events to objects owned by a different thread
    serial->write(...); 
}

1.3 工业级解法：Run 内实例化

最稳妥的办法是遵循 “在哪干活，就在哪出生” 的原则。

// ✅ 正确写法
void Send_receive_pack_thread::run() {
    // 1. 在子线程的栈空间或堆空间创建
    QSerialPort *serial = new QSerialPort(); 
    // 2. 此时 serial 的户口自动归属当前子线程
    
    // ... 执行业务 ...

    // 3. 离开前清理
    serial->close();
    delete serial;
}

---

第二章：协议封包的艺术（内存与类型）

串口传输的是纯粹的字节流，如何保证我们定义的 struct 发过去不会乱码？

2.1 字节对齐：#pragma pack

C++ 编译器为了 CPU 存取速度，默认会把结构体按照 4 字节或 8 字节对齐。

• 风险：你的 9 字节协议，可能被填充成 12 字节。
• 解法：强制 1 字节对齐。

#pragma pack(push, 1) // 保存当前对齐方式，并设置新对齐为 1 字节
struct ProtocolFrame {
    uint8_t  header = 0xEF;
    uint8_t  cmd;
    uint8_t  param;
    uint32_t data;     // 4字节
    uint8_t  checkSum;
    uint8_t  tail = 0xFE;
};
#pragma pack(pop)     // 恢复之前的对齐方式

2.2 数据类型铁律

• **拒绝 int**：int 在不同系统下长度不确定（32位/64位）。
• **拥抱 uint8_t / uint32_t**：使用 <cstdint> 库，明确规定变量占几个坑位。
• 强类型枚举：使用 enum class + static_cast。

enum class MotorCmd : uint8_t { Temp = 0x01 };
// 存入结构体时必须强转，防止隐式转换带来的不可控风险
frame.cmd = static_cast<uint8_t>(MotorCmd::Temp);

---

第三章：发送逻辑的“究极进化”

发送不仅仅是调用 write，而是一套严密的组合拳。

3.1 为什么需要 reinterpret_cast？

write 函数只接受 const char* 类型的参数。我们需要把结构体“伪装”成字节数组。

// 意思是：不管 frame 是啥，从它的首地址开始，往后数 sizeof(frame) 个字节，统统发走
serial->write(reinterpret_cast<const char*>(&frame), sizeof(frame));

3.2 同步发送三部曲（防止丢包的核心）

串口发送是异步的。数据写入缓冲区后，如果没有物理时间发送，线程就休眠了，数据就会积压甚至丢失。

标准发送模板：

// Step 1: 写入缓冲区
qint64 ret = serial->write((char*)&frame, sizeof(frame));

// Step 2: 【关键】督促硬件发送
// 阻塞当前线程，直到数据真正从物理引脚发出去，或者等待 100ms 超时
if (serial->waitForBytesWritten(100)) {
    // 发送成功
} else {
    // 硬件异常或超时
}

// Step 3: 刷新缓冲区（双重保险）
serial->flush();

// Step 4: 节奏控制
// 给下位机 20ms 的喘息时间去处理数据
QThread::msleep(20);

---

第四章：数据校验与组包（Burstification）

4.1 偶校验算法（Even Parity）

原理：确保传输的一组二进制数中，“1”的个数是偶数。

uint8_t calculateEvenParity(const ProtocolFrame& frame) {
    // 1. 提取所有有效载荷字节
    QByteArray data;
    data.append(frame.cmd);
    data.append(frame.param);
    // 将 32位 data 拆解为 4个 8位字节 (小端序)
    data.append(static_cast<uint8_t>(frame.data & 0xFF));
    data.append(static_cast<uint8_t>((frame.data >> 8) & 0xFF));
    data.append(static_cast<uint8_t>((frame.data >> 16) & 0xFF));
    data.append(static_cast<uint8_t>((frame.data >> 24) & 0xFF));

    // 2. 统计算法
    uint8_t count = 0;
    for (char byte : data) {
        uint8_t val = static_cast<uint8_t>(byte);
        while (val > 0) {
            if (val & 0x01) count++; // 如果最低位是1，计数+1
            val >>= 1;               // 右移一位
        }
    }
    // 如果1的个数是偶数，校验位填0；否则填1
    return (count % 2 == 0) ? 0 : 1;
}

---

第五章：完美的 run() 循环架构

结合以上所有点，这就是一个永远不会崩溃、可随时停止、且收发稳定的线程函数。

void Send_receive_pack_thread::run() {
    // 1. 现场创建，户口归子线程
    QSerialPort *serial = new QSerialPort();
    serial->setPortName("COM3");
    serial->setBaudRate(19200);
    
    if (!serial->open(QIODevice::ReadWrite)) {
        emit errorOccurred("无法打开串口");
        delete serial;
        return;
    }

    // 2. 循环条件：使用 isInterruptionRequested 替代 while(1)
    // 这样主线程调用 requestInterruption() 时，子线程能优雅退出
    while (!isInterruptionRequested()) {
        
        for (const auto &task : TASK_LIST) {
            // A. 清除旧缓存，防止粘包
            serial->clear();

            // B. 组包与发送
            ProtocolFrame frame;
            // ... 填充 frame ...
            serial->write(reinterpret_cast<const char*>(&frame), sizeof(frame));

            // C. 【核心】同步等待发送完成
            if (!serial->waitForBytesWritten(100)) {
                qDebug() << "发送超时，跳过本次";
                continue;
            }

            // D. 【核心】同步等待接收反馈 (一问一答)
            // 等待 50ms 看有没有数据回来
            if (serial->waitForReadyRead(50)) {
                QByteArray resp = serial->readAll();
                // ... 解析 resp ...
            }

            // E. 频率控制
            QThread::msleep(20);
        }
        
        // F. 长轮询休眠
        QThread::msleep(1000);
    }

    // 3. 资源释放
    serial->close();
    delete serial; // 必须要删，否则内存泄漏
    qDebug() << "线程安全退出";
}

---

第六章：容易忽视的“坑”与经验清单

1. 数据位初始化：结构体里的 data 即使不用（比如查询指令），也必须初始化为 0 (data = 0x00000000)。否则发送出去的是内存里的随机垃圾值，可能导致校验失败。
2. 指针野指针：如果在类成员里定义了 QSerialPort *serial，记得在构造函数初始化为 nullptr，在 run 里 new，在 run 结束前 delete 并置回 nullptr。
3. 调试技巧：不要用 qDebug() << data; 看乱码。要用 qDebug() << data.toHex(' ').toUpper();，这样能看到 EF 01 02 ... 这样清晰的十六进制流。
4. 波特率匹配：代码写的再好，波特率跟电机对不上也是白搭。务必确认 BaudRate、DataBits、Parity、StopBits 四大参数。
5. 信号槽连接：主线程与子线程交互（比如更新UI），必须用信号槽（Signal-Slot）。不要在子线程直接操作 UI 控件（Label, LineEdit），必崩！

---

结语

串口通信看似简单，实则暗藏玄机。从内存对齐到底层驱动时序，再到多线程模型，每一个环节都需要严谨对待。掌握了这套逻辑，你不仅能搞定电机上位机，以后遇到任何 Modbus、TCP/IP 协议开发都能游刃有余。