從零到一：用 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)));
};

---