树莓派 RS485 串口调试工具 · Modbus RTU 纯标准库实现

这个项目解决什么问题

一个典型的场景：用树莓派 + RS485 扩展板控制实验室仪器，官方示例代码跑不通，项目时间紧。串口打不开、指令发出去石沉大海、收到数据 CRC 报错——问题可能出在协议层、链路层或系统配置的任何一层，却很难定位。本项目把"调试一台 RS485 仪器"要做的事集成到一个工具里，并提供一个能在 Windows 上零硬件跑通的演示模式，先把代码逻辑验证对，再上真机排查物理链路。

核心亮点

• 零硬件演示模式：--mock 模式内置一台虚拟 Modbus RTU 从机（模拟工业温湿度变送器）。它不是"打印假数据"——CRC 错的请求会被静默丢弃（真机就是这样，主机侧表现为超时），非法功能码返回标准异常响应，写寄存器后复读能验证生效，还能顺带演示超时的错误诊断。课程汇报现场没有树莓派也能完整演示。
• 协议层纯标准库手写：Modbus RTU 帧构造、CRC16（0xA001 算法）与响应解析不依赖任何第三方库，带经典测试向量自检（python modbus_utils.py），方便逐行讲清协议字节格式。
• 收发日志双显落盘：每条收发都带毫秒时间戳、十六进制 + ASCII 双显，自动写入 logs/，事后可回溯比对。
• 结构化排错：出错不只是抛异常——按错误信息自动匹配故障类别，给出排查建议清单；diagnose.py 另有 4 类故障的交互式问答排查（dialout 权限、控制台占用、A/B 接反、波特率不匹配、共地……），都是这类调试最常踩的坑。

效果预览

串口扫描与配置检测——插上 USB 转 485 即可枚举端口：

模拟模式的收发日志——TX/RX 字节流、CRC 校验通过、超时自动给出排查建议：

预览图为控制台输出示意图，实际运行输出格式一致。

你将学到

• Modbus RTU 的帧格式与 CRC16 校验算法（读保持寄存器 0x03、写单寄存器 0x06 等）
• RS485 半双工通信的常见坑：A/B 接反、DE/RE 收发方向控制、共地与终端电阻
• 树莓派串口配置全流程：启用串口硬件、关闭控制台占用、dialout 用户组
• 主机-从机协议代码的"模拟先行"开发/调试方法：先 mock 验证逻辑，再上真机查链路

适合谁

需要在树莓派/PC 上调试 RS485 仪器（Modbus 协议）、或正在做串口通信方向毕业设计、又被"代码跑不通"卡住的学习者。难度 ★★☆，代码中文注释齐全，--mock 模式无需任何硬件即可上手。

交付内容：完整可运行源码、README.md（逐步运行方法与实现说明）、requirements.txt。

许可：个人使用，可用于自己的学习、课程实验与研究报告，请勿转售或公开传播。

环境与步骤

pip install -r requirements.txt

python serial_tool.py --list          # 扫描可用串口
python serial_tool.py --mock --demo   # 模拟模式跑一组读写事务
python demo_modbus.py                 # 读寄存器并解析温湿度数值

python serial_tool.py --port /dev/ttyUSB0 --baud 9600 --timeout 1.0

注意事项

• Windows 上 --mock 模式即可跑通全部逻辑；接真机需要 pyserial 与树莓派。

Q：没有树莓派和 485 板子能跑吗？

A：能，这是刻意做的。python serial_tool.py --mock --demo 会启动内置的虚拟 Modbus RTU 从机（模拟工业温湿度变送器）：CRC 校验错的请求被静默丢弃（真机就是这样，主机侧表现为超时）、非法功能码返回标准异常响应、写寄存器后复读能验证生效。Windows 上即可完整演示。

Q：接真机需要装什么？

A：pyserial>=3.5。树莓派侧的串口硬件启用、关闭控制台占用、加入 dialout 用户组这些步骤，rpi_setup.md 里逐条列了命令。

Q：Modbus 协议是调库吗？

A：帧构造、CRC16（0xA001 多项式）与响应解析都是纯标准库手写，不依赖第三方库；python modbus_utils.py 自带经典测试向量自检，能逐行讲清每个字节。

Q：报错了从哪里查起？

A：diagnose.py 是 4 类故障的问答式排查（打不开串口、无应答、CRC 报错、数据异常），按错误信息自动匹配故障类别并给出排查清单，覆盖 A/B 接反、波特率不匹配、共地、DE/RE 收发方向这些常见坑。