一、引言
在使用 Qt 开发串口调试工具的过程中，QSerialPort 是核心类之一，它封装了底层串口通信的所有逻辑，包括端口配置、数据读写、错误处理等功能。熟练掌握 QSerialPort 的用法，是开发高质量串口工具的关键。
本文将对 QSerialPort 类的结构与接口进行系统讲解，并穿插实际开发中常用技巧。
二、QSerialPort 的类结构概览
QSerialPort 继承自 QIODevice，因此可以像文件一样使用 read(), write(), open(), close()，这为串口通信提供了统一的接口封装。
类结构简要图如下：
QObject
└── QIODevice
└── QSerialPort
此外，它还配套了 QSerialPortInfo 类，用于扫描系统中可用串口。
三、核心属性与设置方法
1. 端口名设置
void setPortName(const QString &name);
QString portName() const;
设置串口名称，例如 "COM1"、"/dev/ttyUSB0" 等。
2. 波特率 BaudRate
enum BaudRate { Baud9600, Baud115200, ... };
bool setBaudRate(qint32 baudRate);
qint32 baudRate() const;
你可以使用常量，也可以设置任意自定义整数值。常用波特率如：
serial->setBaudRate(QSerialPort::Baud115200);
技巧：波特率设置失败通常不会报错，请结合 open() 的返回值进行判断。
3. 数据位 DataBits
enum DataBits { Data5, Data6, Data7, Data8 };
bool setDataBits(DataBits bits);
一般设置为 Data8，对应 8 个数据位。
4. 偶校验 Parity
enum Parity { NoParity, EvenParity, OddParity, SpaceParity, MarkParity };
bool setParity(Parity p);
NoParity：无校验（最常用）EvenParity：偶校验OddParity：奇校验
5. 停止位 StopBits
enum StopBits { OneStop, OneAndHalfStop, TwoStop };
bool setStopBits(StopBits stopBits);
6. 流控 FlowControl
enum FlowControl { NoFlowControl, HardwareControl, SoftwareControl };
bool setFlowControl(FlowControl fc);
通常选择 NoFlowControl，如果设备需要 RTS/CTS 需要选硬件流控。
7. 打开和关闭串口
bool open(QIODevice::OpenMode mode);
void close();
打开串口前需先设置好上述参数。典型用法：
serial->setPortName("COM3");
serial->setBaudRate(QSerialPort::Baud9600);
serial->open(QIODevice::ReadWrite);
四、数据收发接口
1. 发送数据
qint64 write(const QByteArray &data);
将数据写入串口。支持直接写字符串或字节数组：
serial->write("Hello");
2. 接收数据
使用信号槽机制接收数据：
connect(serial, &QSerialPort::readyRead, this, &YourClass::onReadyRead);
回调中：
QByteArray data = serial->readAll();
3. 同步阻塞方式（不推荐 GUI 用）
serial->waitForReadyRead(1000); // 阻塞 1 秒
五、错误处理机制
1. 错误类型枚举
enum SerialPortError {
NoError, DeviceNotFoundError, PermissionError, OpenError, ...
};
常见错误：
DeviceNotFoundError：设备不存在PermissionError：权限不足OpenError：打开失败ReadError/WriteError：IO 失败
2. 信号通知错误
connect(serial, &QSerialPort::errorOccurred, this, &YourClass::handleError);
配合 error() 获取错误类型。
六、附加功能接口
1. RTS / DTR 控制（调试时非常重要）
serial->setRequestToSend(true); // RTS
serial->setDataTerminalReady(true); // DTR
某些设备通信前需拉高 RTS/DTR，常见于 USB 转串口模块。
2. 清除缓冲区
serial->clear(QSerialPort::AllDirections);
serial->flush();
clear()：清除接收/发送缓冲flush()：立即写入发送缓冲
七、开发实用技巧与建议
1. 检查串口是否可用
if (!serial->open(QIODevice::ReadWrite)) {
qDebug() << "串口打开失败:" << serial->error();
}
2. 配合 QSerialPortInfo 获取可用串口
foreach (const QSerialPortInfo &info, QSerialPortInfo::availablePorts()) {
qDebug() << "发现串口：" << info.portName();
}
八、总结
QSerialPort 提供了 Qt 开发中几乎所有串口相关的功能，并通过信号槽机制与 Qt 主线程良好集成。掌握它可以帮助我们快速构建各种嵌入式调试工具、上位机界面等应用。
本节要点回顾：
- 串口初始化流程（设置端口名、波特率等）
- 数据读写接口与事件机制
- 错误类型及调试建议
- 高级功能如 RTS/DTR 控制
九、下节预告
《手动开发一个串口调试工具（二）：Qt 串口类基本认识与使用》