Complete Guide to Modpoll Modbus Debugging Tool: Command Line Master Simulator from Beginner to Proficient

What is Modpoll?

Modpoll 是一款开源的命令行 Modbus 主站模拟器，由 proconX 公司基于其 FieldTalk™ 协议栈开发。它可以在 Windows、Linux、QNX 等操作系统上运行，是工程师进行 Modbus 设备调试、协议测试和批量数据采集时的利器。与带 GUI 的 Modbus Poll 不同，Modpoll 完全通过命令行参数控制，非常适合集成到自动化测试脚本和 CI/CD 流程中。

官方下载地址：http://www.focus-sw.com/fieldtalk/modpoll.html

Modpoll 支持的功能

• 传输模式：Modbus RTU（串口）和 Modbus TCP（以太网），同时支持通过 RTU-over-TCP 网关通信
• 功能码覆盖：FC01（读线圈）、FC02（读离散输入）、FC03（读保持寄存器）、FC04（读输入寄存器）、FC05（写单线圈）、FC06（写单寄存器）、FC15（写多线圈）、FC16（写多寄存器）、FC23（读/写多寄存器）
• 数据格式：支持 HEX、十进制无符号、十进制有符号、32 位浮点数（Float）等多种显示格式
• 字节序配置：支持 Big-Endian 和 Little-Endian 两种字节序，适配不同厂商的 PLC 设备
• 轮询模式：支持单次读取和连续轮询，可自由指定轮询间隔
• 输出格式：支持标准文本输出和十六进制 raw 输出两种模式

安装 Modpoll

Windows 平台安装

从官网下载 Windows 版本的 ZIP 压缩包，解压后即可获得 modpoll.exe 可执行文件。建议将解压目录添加到系统的 PATH 环境变量中，方便在任意目录下调用。Windows 10/11 用户也可以直接通过 WSL 使用 Linux 版本的 Modpoll。

Linux 平台安装

# 下载 Linux 版本（以 3.10 版本为例）
wget http://www.focus-sw.com/fieldtalk/modpoll-3.10-linux-x86_64.tar.gz

# 解压
tar -xzf modpoll-3.10-linux-x86_64.tar.gz

# 进入目录
cd modpoll-3.10-linux-x86_64

# 测试运行
./modpoll --version

# 可选：创建软链接方便全局调用
sudo ln -s $(pwd)/modpoll /usr/local/bin/modpoll

ARM / 嵌入式 Linux 安装

如果需要在树莓派等 ARM 设备上运行，可以从官网选择对应的 ARM 版本，或从源码交叉编译。proconX 提供了 armhf 和 aarch64 等架构的预编译包。

Modpoll 命令行参数详解

常用实战命令

1. Modbus TCP 读取保持寄存器（FC03）

从 IP 地址 192.168.1.100、端口 502 的设备，读取从站地址 1 的保持寄存器 0-9（共 10 个）：

modpoll -m tcp -a 1 -r 1 -c 10 192.168.1.100

输出示例：

-- Polling slave 1...
[1]: 1234
[2]: 5678
[3]: 0
[4]: 100

2. Modbus RTU 串口通信

# Linux Platform（/dev/ttyUSB0）
modpoll -m rtu -a 1 -r 1 -c 10 -b 9600 -p none /dev/ttyUSB0

# Windows Platform（COM3）
modpoll -m rtu -a 1 -r 1 -c 10 -b 9600 -p none COM3

3. 持续轮询模式（监控用）

# each 500 Millisecond polling once，infinite loop
modpoll -m tcp -a 1 -r 1 -c 20 -1 192.168.1.100 500

# Output polling data with timestamp
modpoll -m tcp -a 1 -r 1 -c 5 -1 192.168.1.100 1000 | while read line; do
    echo "$(date '+%H:%M:%S') $line"
done

4. 读线圈状态（FC01）

# Read address 0 start 8 A coil
modpoll -m tcp -a 1 -r 1 -c 8 -t 0 192.168.1.100

注意：-t 0 表示线圈类型，-t 1 表示离散输入，-t 3 表示输入寄存器，-t 4 表示保持寄存器。

5. 写入单寄存器（FC06）

# Address of the agreement 0 Write the register value of 1234
modpoll -m tcp -a 1 -r 1 192.168.1.100 1234

6. 读取 32 位浮点数（Float）

很多工业仪表（如温度变送器、流量计）使用两个连续的 16 位保持寄存器存储一个 IEEE 754 32 位浮点数：

# From address 0 Start reading 2 A register，press float Format display
modpoll -m tcp -a 1 -r 1 -c 2 -t 4:float 192.168.1.100

7. 批量写入多寄存器（FC16）

# From the protocol address 0 Start，Write sequentially 100, 200, 300, 400
modpoll -m tcp -a 1 -r 1 192.168.1.100 100 200 300 400

8. 读写组合操作（FC23）

# Read address 0-4（5A register)，Simultaneously provide the address 10-11 write 99, 88
modpoll -m tcp -a 1 -r 1 -c 5 -w 11 -q 2 192.168.1.100 99 88

集成到自动化测试脚本

Modpoll 的命令行特性使其成为自动化测试的理想选择。以下是一个完整的设备验收测试脚本：

#!/bin/bash
# Modbus 设备寄存器读写验收测试
# 用法: ./modbus_test.sh <设备IP>

DEVICE_IP=${1:-"192.168.1.100"}
PASS=0
FAIL=0

echo "=== Modbus 设备验收测试 ==="
echo "目标设备: $DEVICE_IP"
echo ""

# 测试1: TCP 连接性
echo "[TEST 1] TCP 端口 502 连通性"
if timeout 3 bash -c "echo > /dev/tcp/$DEVICE_IP/502" 2>/dev/null; then
    echo "  [PASS] 端口 502 可达"
    PASS=$((PASS+1))
else
    echo "  [FAIL] 端口 502 不可达"
    FAIL=$((FAIL+1))
fi

# 测试2: 读取保持寄存器 FC03
echo "[TEST 2] 功能码 FC03 - 读保持寄存器"
result=$(modpoll -m tcp -a 1 -r 1 -c 5 -o 1 $DEVICE_IP 2>&1)
if echo "$result" | grep -qE '[[0-9]+]:'; then
    echo "  [PASS] FC03 功能正常"
    PASS=$((PASS+1))
else
    echo "  [FAIL] FC03 读取失败: $result"
    FAIL=$((FAIL+1))
fi

# 测试3: 写入保持寄存器 FC06
echo "[TEST 3] 功能码 FC06 - 写单寄存器"
# 先读当前值
before=$(modpoll -m tcp -a 1 -r 1 -c 1 -o 1 $DEVICE_IP 2>&1 | grep -oP '(? /dev/null 2>&1
# 验证写入
after=$(modpoll -m tcp -a 1 -r 1 -c 1 -o 1 $DEVICE_IP 2>&1 | grep -oP '(? /dev/null 2>&1
if [ "$after" = "9999" ]; then
    echo "  [PASS] FC06 写入功能正常"
    PASS=$((PASS+1))
else
    echo "  [FAIL] FC06 写入失败: 预期9999, 实际$after"
    FAIL=$((FAIL+1))
fi

echo ""
echo "=== 测试结果: $PASS 通过, $FAIL 失败 ==="

Modpoll 与其他 Modbus 工具对比

• Modbus Poll：Windows GUI 工具，可视化操作，适合手动调试。官网 www.modbustools.com。
• Modpoll：纯命令行工具，跨平台，适合脚本自动化和远程部署，完全免费。
• pymodbus：Python 库，需要编程，灵活性最高，适合构建自定义测试框架。
• QModMaster：Qt 写的跨平台 GUI 工具，开源免费，功能较简单。

常见问题排查指南

连接超时

首先用 ping 确认网络层连通。对于 Modbus TCP，默认使用 502 端口，用 telnet 192.168.1.100 502 测试。如果连接立即断开（而非超时），说明服务器拒绝连接，可能端口未开放。如果一直等待无响应，可能是防火墙拦截。

读取值全为零

可能原因：从站地址 -a 设置与实际设备不匹配；起始地址 -r 的 PLC 地址到协议地址转换错误（如 PLC 地址 40001 对应协议地址 0）；该段寄存器确实未被配置或未写入过数据。

RTU 模式返回异常/错误

逐一确认：波特率（-b）、数据位（固定8位）、校验位（-p：none/even/odd）和停止位是否与从站设备一致。RS-485 接线特别注意 A（+）/B（-）线序不能接反。建议先用示波器或逻辑分析仪观察总线上信号质量。

浮点数读数异常

32 位浮点数涉及两个 16 位寄存器的排列顺序（字节序/字序）。不同厂商可能使用 ABCD、CDAB、BADC、DCBA 等不同顺序。Modpoll 默认使用 Big-Endian 浮点格式。如果读数明显异常（如 NaN 或数量级完全不对），尝试用 modpoll -t 4:hex 先看原始十六进制值，手动计算确认字节序后再调整配置。

总结

Modpoll 是 Modbus 协议调试工具链中不可或缺的"瑞士军刀"。它的最大优势在于轻量、跨平台、命令行驱动，可以无缝融入 Shell 脚本、Python 测试框架和 CI/CD 流水线。无论是嵌入式工程师验证单片机 Modbus 从站、自动化工程师调试 PLC 通信配置，还是 QA 工程师编写自动化的 Modbus 设备验收测试，掌握 Modpoll 都能显著提高工作效率。