从零到一：用 Qt + libmodbus 做一个靠谱的 Modbus RTU 小工具（实战总结）

这是一篇“拿来就能写”的总结。你读完、按文中套路，一般就能把 RTU 读写跑通，并把工具做得稳当、好用、易扩展。

---

你会得到什么

• 一张 Modbus 速查表（数据区、功能码、地址与字节序）
• 一个 Qt Widgets + libmodbus 的落地套路（连接三板斧、四类区读写）
• 可直接复用的 代码片段（解析输入、展示输出、错误处理、RAII）
• 一份 易错点清单 和 工程化升级建议

---

快速背景：为什么是 Modbus RTU？

• 现场设备（变频器、温控器、仪表、I/O 模块）几乎都会支持 Modbus。
• RTU 走串口（RS-485 常见），稳定、便宜、易调试。
• 用 Qt 做一个可视化小工具，能更快看数、改参、验线、定位问题。

---

协议速查（够用不啰嗦）

四类数据区

• 线圈 Coils（读写，位）→ 功能码 01 读、05/0F 写（单/多）
• 离散输入 Discrete Inputs（只读，位）→ 02
• 保持寄存器 Holding Registers（读写，16 位）→ 03 读、06/10 写（单/多）
• 输入寄存器 Input Registers（只读，16 位）→ 04

常见上限（经验值）

• 03/04 单次读寄存器 ≤ 125 个
• 10 写多寄存器 ≤ 123 个
• 01 读线圈 ≤ 2000 位
  （设备/库实现可能不同，以手册为准）

地址与字节序

• 地址从 0 开始（很多手册写 40001/30001 这类“人读编号”，实际通讯要减 1）
• 寄存器是 大端 16 位；32/64 位数值常跨多个寄存器，可能需 word/byte swap（按厂家文档）

---

工程结构与 UI 组织

UI 分四个 Tab： 线圈、离散输入、保持寄存器、输入寄存器。
每个 Tab 里统一放：起始地址、数量、读/写按钮、多值输入/输出框（QPlainTextEdit）、状态栏显示结果。

状态栏：始终显示「最近一次操作 + 简要结果 / 错误信息」。

---

连接“三板斧”（Windows 串口重点）

1. modbus_new_rtu("\\\\.\\COM40", 19200, 'N', 8, 1);

   • Windows 上 COM10+ 一定用 \\\\.\\COMx 形式

2. modbus_set_slave(ctx, slaveId);

3. modbus_connect(ctx);

   • 失败立刻提示并禁用全部读写按钮或直接返回

可选增强：
modbus_set_response_timeout(ctx, sec, usec)、modbus_set_byte_timeout(ctx, sec, usec) 调好超时更稳。

---

四类区的 API 一览（附最小代码）

线圈（位）

• 读：modbus_read_bits(ctx, addr, nb, uint8_t* dest)
• 写单：modbus_write_bit(ctx, addr, onOff)
• 写多：modbus_write_bits(ctx, addr, nb, const uint8_t* src)

寄存器（16 位）

• 读：modbus_read_registers(ctx, addr, nb, uint16_t* dest)
• 写单：modbus_write_register(ctx, addr, value)
• 写多：modbus_write_registers(ctx, addr, nb, const uint16_t* src)

判断成功的唯一标准：返回值 ret == 请求的点数（单写返回 1）。否则当失败处理，并用 modbus_strerror(errno) 给出底层原因。

示例：读保持寄存器

int nb = ui->spinCount->value();
std::vector<uint16_t> regs(nb);
int ret = modbus_read_registers(ctx, startAddr /*0-based*/, nb, regs.data());
if (ret != nb) {
    ui->status->setText(QString("读失败：%1").arg(modbus_strerror(errno)));
} else {
    QStringList out;
    for (auto v : regs) out << QString::number(v);
    ui->plainOutput->setPlainText(out.join('\t')); // 用 \t 便于复制
    ui->status->setText(QString("读成功：%1 个").arg(nb));
}

示例：写多个线圈

// 从文本框解析 0/1 序列，空格/逗号/分号/换行皆可
static std::vector<uint8_t> parseBits(const QString& s) {
    const QRegularExpression sep(R"([\s,;]+)");
    QStringList parts = s.split(sep, Qt::SkipEmptyParts);
    std::vector<uint8_t> out; out.reserve(parts.size());
    for (const auto& p : parts) out.push_back(p.toUInt() ? 1 : 0);
    return out;
}

auto bits = parseBits(ui->plainInput->toPlainText());
int ret = modbus_write_bits(ctx, startAddr, (int)bits.size(), bits.data());
ui->status->setText(ret == (int)bits.size()
    ? QString("写成功：%1 位").arg(bits.size())
    : QString("写失败：%1").arg(modbus_strerror(errno)));

---

字符串 ↔ 数组：输入/输出的“通用套路”

• 输入（批量写）：多分隔符切分 → 转为 vector<uint8_t/uint16_t> → 调用 write_*
• 输出（批量读）：读到 vector → 用 \t 连接 → 回填只读的 QPlainTextEdit

static std::vector<uint16_t> parseU16List(const QString& s) {
    const QRegularExpression sep(R"([\s,;]+)");
    QStringList parts = s.split(sep, Qt::SkipEmptyParts);
    std::vector<uint16_t> out; out.reserve(parts.size());
    for (const auto& p : parts) out.push_back(p.toUShort());
    return out;
}

---

易错点 Checklist（上线前过一遍）

• COM 路径：Windows 用 \\\\.\\COMx（尤其 COM10+）
• 地址偏移：手册编号 ≠ 实际地址（请求从 0 开始）
• 数量上限：别超过设备/库允许的单次点数
• 返回值：必须等于请求点数才算成功
• 资源释放：析构里 modbus_close + modbus_free（或用 RAII）
• 线程阻塞：串口 IO 放到工作线程，UI 不要卡
• 485 布线：总线拓扑、两端 120Ω、A/B 极性、必要的偏置电阻
• 字节序/字序：32/64 位数据要按手册做 swap

---

工程化升级（让工具更耐用）

1) RAII 封装：不怕 early return 泄漏

class ModbusCtx {
public:
    ~ModbusCtx() { reset(nullptr); }
    bool connectRtu(const QString& com, int baud, char parity, int data, int stop, int slave) {
        reset(modbus_new_rtu(com.toUtf8().constData(), baud, parity, data, stop));
        if (!ctx_) return false;
        modbus_set_slave(ctx_, slave);
        modbus_set_response_timeout(ctx_, 1, 0);
        modbus_set_byte_timeout(ctx_, 0, 200000);
        if (modbus_connect(ctx_) == -1) { reset(nullptr); return false; }
        return true;
    }
    modbus_t* get() const { return ctx_; }
    bool ok() const { return ctx_ != nullptr; }
    void reset(modbus_t* n) { if (ctx_) { modbus_close(ctx_); modbus_free(ctx_); } ctx_ = n; }
private:
    modbus_t* ctx_ = nullptr;
};

2) 错误信息更有用

• 统一使用 modbus_strerror(errno)
• 失败时把关键参数带上：端口、波特率、站号、功能码、地址、数量、期望/实际返回点数

3) 线程模型建议

• 用 QThread 或 QtConcurrent::run 跑读写；UI 用 signal/slot 收结果
• 连续轮询时加节流（如 100–200ms）与重试（上限次数 + 指数退避）

4) 设置持久化 & 日志

• QSettings 记住最近的 COM、波特率、站号
• 把每次操作写一行日志：时间戳、操作类型、参数、结果/错误

---

调试与验收流程（按这个顺序最省心）

1. 先用第三方工具（QModMaster / Modbus Poll）验证设备是否通、站号/寄存器是否对
2. 最小读：先读 1 个寄存器/1 位线圈，确认地址偏移正确
3. 批量读：逐步放大数量，确认上限 & 性能
4. 写入：先写 1 个，再写多个；同时盯住设备侧是否生效
5. 异常测试：拔线、改站号、改波特率，看看错误提示是否清晰

---

附：几个常用片段

把“手册编号”转为 0 基地址（示例）

// 仅示意：具体偏移应按手册分类（如 40001/30001/00001/10001 各自对应 0 起）
static int toZeroBased_4xxxx(int human) { return human - 40001; }

析构清理（若不用 RAII）

MainWindow::~MainWindow() {
    if (ctx) { modbus_close(ctx); modbus_free(ctx); }
    delete ui;
}

统一的失败提示

auto fail = [&](const char* what, int expect, int got){
    ui->status->setText(QString("%1 失败：期望 %2 实得 %3，原因：%4")
        .arg(what).arg(expect).arg(got).arg(modbus_strerror(errno)));
};

---