简介：这是一份纯C语言实现的跨平台Modbus RTU协议通信库，面向工业控制、嵌入式开发及物联网领域的工程师与学习者，用于在Windows、Linux、macOS及RTOS等平台上快速搭建稳定可靠的主从通信机制。压缩包共收录2000个文件，以926个h头文件与838个c源文件为核心，辅以94个md说明文档、54个py脚本、36个txt配置及少量cpp、xml、sh、json等，整体约81.7MB，目录结构清晰，便于按模块检索与移植。目前已有65人学习下载。库内覆盖自定义地址映射、数据校验、错误处理等关键环节，代码结构化、易调试、运行时开销小，在资源受限的嵌入式系统中表现突出，可直接用于智能建筑、农业自动化、环境监测与智能电网等场景，也可作为理解Modbus协议原理与实现技术的教学实践素材。

1. 一份纯 C 写的 Modbus RTU 库，为什么工控现场还在用它

如果你在工控现场待过，大概率见过这样的场景：一台跑了七八年的数控机床，PLC 只留了一个 RS485 口，协议是 Modbus RTU，上位机却要从 Linux 网关、Windows 调试机、甚至一块 ARM 板子上同时把运行状态读出来。这时候你需要的不是某个大而全的组态软件，而是一个能塞进任何工程、不挑编译器、不依赖第三方运行时的通信库。modbus-rt纯C实现的跨平台modbus协议通信库.zip就是冲着这个需求来的——它把 Modbus RTU 的主站/从站逻辑用纯 C 写了一遍，不绑操作系统，不绑框架，编译进你的工程就能收发帧。

它解决的核心问题很具体：串口字节流怎么切成一帧一帧的 Modbus 报文、CRC 怎么算、超时怎么判、异常码怎么回。适合谁？做设备数据采集的嵌入式工程师、写上位机网关的后端、以及需要把 Modbus 协议嵌进自己采集程序里的从业者。如果你只是想找个现成软件点点鼠标读 PLC，那这份资源不是给你准备的；但如果你要自己写采集逻辑，它省掉的是最烦的那层协议解析。

2. 拆开这个库：纯 C 的 Modbus RTU 到底由哪几块拼成

2.1 帧结构决定了整个库的骨架

Modbus RTU 的帧没有起始符和结束符，靠的是 3.5 个字符时间的静默间隔来断帧。这个特性直接决定了库的设计：它必须有一个字节级的接收状态机，而不是像 Modbus TCP 那样先读长度字段。一份合格的纯 C 实现，通常会把帧拆成「地址 + 功能码 + 数据 + CRC」四段，CRC 是低字节在前。库内部一般会维护一个接收缓冲区和一个发送缓冲区，接收侧靠定时器或轮询判断帧是否结束。

我一般会先看这个库有没有把「帧间隔」这件事交给调用方处理。因为纯 C 库不绑操作系统，它没法自己开线程做超时，常见做法是暴露一个poll或receive接口，让调用方在循环里喂字节、传时间戳。这样设计的好处是移植性极强，坏处是你得自己管时序。下面是一个典型的接收状态机骨架，很多纯 C 库都是这个思路：

/* 简化的 RTU 接收状态机：按字节喂入，靠时间戳断帧 */ typedef enum { STATE_IDLE, /* 等待帧起始 */ STATE_RECV, /* 正在收字节 */ STATE_COMPLETE /* 一帧收完 */ } rtu_state_t; typedef struct { rtu_state_t state; uint8_t buf[256]; /* RTU 单帧最大 256 字节 */ uint16_t len; uint32_t last_tick; /* 上一个字节到达的时间 */ } rtu_rx_t; /* 每收到一个字节调用一次，tick 为毫秒级时间戳 */ int rtu_rx_byte(rtu_rx_t *rx, uint8_t byte, uint32_t tick) { /* 距上一字节超过 3.5 字符时间，认为上一帧结束 */ if (rx->state == STATE_RECV && (tick - rx->last_tick) > FRAME_GAP_MS) { rx->state = STATE_COMPLETE; return 1; /* 通知调用方：可以取帧了 */ } if (rx->len < sizeof(rx->buf)) { rx->buf[rx->len++] = byte; } rx->last_tick = tick; rx->state = STATE_RECV; return 0; }

这段代码的关键参数是FRAME_GAP_MS。在 9600 波特率下，一个字符约 1.04ms，3.5 个字符约 3.6ms，工程上常取 4ms 左右；115200 波特率下这个值要缩到 0.3ms 量级。取大了会把两帧粘在一起，取小了会把一帧切断。这是纯 C 库最容易被误用的地方，也是后面避坑章节要重点说的。

2.2 功能码支持范围决定了它能接什么设备

Modbus RTU 常用功能码就那么几个：01 读线圈、02 读离散输入、03 读保持寄存器、04 读输入寄存器、05 写单线圈、06 写单寄存器、15 写多线圈、16 写多寄存器。一份能落地的库，至少要把 03/04/06/16 做扎实，因为读 PLC、传感器、数控机床的运行状态数据，绝大多数走的是 03 和 04。

拿到这个库之后，我建议先翻它的功能码分发逻辑，看是不是用一张表或者 switch 把功能码映射到处理函数。好的实现会把「请求解析」和「响应组装」分开，这样主站和从站可以复用同一套编解码。下面是一个功能码分发的典型写法：

/* 功能码分发：根据请求帧的功能码调用对应处理函数 */ int modbus_dispatch(const uint8_t *req, uint16_t req_len, uint8_t *resp, uint16_t *resp_len) { uint8_t func = req[1]; /* 功能码在第二个字节 */ switch (func) { case 0x03: /* 读保持寄存器 */ return handle_read_holding(req, req_len, resp, resp_len); case 0x04: /* 读输入寄存器 */ return handle_read_input(req, req_len, resp, resp_len); case 0x06: /* 写单寄存器 */ return handle_write_single(req, req_len, resp, resp_len); case 0x10: /* 写多寄存器，即 16 */ return handle_write_multi(req, req_len, resp, resp_len); default: /* 不支持的功能码，回异常码 0x01（非法功能） */ return build_exception(req[0], func, 0x01, resp, resp_len); } }

这里要注意异常响应的格式：异常帧的功能码是「原功能码 | 0x80」，后面跟一个异常码。很多新手自己写解析时忘了这一位，结果设备回了异常，上位机却当成正常数据解析，读出来的寄存器值全是乱的。这个库如果处理对了，说明作者是踩过坑的。

2.3 跨平台靠的是抽象层而不是条件编译堆砌

「跨平台」这三个字在纯 C 库里不是靠一堆#ifdef _WIN32堆出来的，而是靠把串口操作、时间获取这两件事抽象成接口。库本身只做协议编解码，串口打开、波特率设置、读写字节这些交给调用方或者一个薄薄的移植层。常见做法是库提供send_bytes和get_tick两个回调，你在 Windows 上用CreateFile+ReadFile，在 Linux 上用open+termios+read，在裸机上直接操作 UART 寄存器。

/* 移植层接口：库只依赖这两个回调，不关心底层是哪个 OS */ typedef struct { int (*send)(const uint8_t *data, uint16_t len); /* 发送原始字节 */ int (*recv)(uint8_t *data, uint16_t max_len); /* 非阻塞收字节，返回收到数量 */ uint32_t (*tick_ms)(void); /* 毫秒时间戳 */ } modbus_port_t; /* Linux 下用 termios 配置串口的典型片段 */ int linux_serial_open(const char *dev, int baud) { int fd = open(dev, O_RDWR | O_NOCTTY | O_NDELAY); struct termios opt; tcgetattr(fd, &opt); cfsetispeed(&opt, baud); /* 波特率，如 B9600 / B115200 */ cfsetospeed(&opt, baud); opt.c_cflag |= (CLOCAL | CREAD); opt.c_cflag &= ~PARENB; /* 无校验，Modbus RTU 常用 8N1 */ opt.c_cflag &= ~CSTOPB; /* 1 位停止位 */ opt.c_cflag &= ~CSIZE; opt.c_cflag |= CS8; /* 8 位数据位 */ tcsetattr(fd, TCSANOW, &opt); return fd; }

参数上要留意：Modbus RTU 标准推荐 8 位数据、1 位停止位，校验位可选无/奇/偶。现场设备五花八门，有的默认偶校验，你按 8N1 去读就是一堆乱码。所以移植层最好把数据位、停止位、校验位都做成可配置，而不是写死。

3. 从零跑通一次读寄存器：接线、配置、发帧、验帧

3.1 硬件接线和串口参数先对齐

动手之前先把物理层搞定。RS485 是差分信号，A 接 A、B 接 B，很多现场翻车是因为 A/B 接反了——接反不一定完全不通，有时能收到但误码率极高，表现为偶尔能读、偶尔超时。如果是 USB 转 485 的转换器，注意转换器本身的收发方向控制，有些便宜模块需要手动控制 RTS，有些自动切换。用万用表量一下 A/B 之间有没有 120 欧姆终端电阻，长距离总线两端各一个，短距离可以不加。

串口参数必须和设备手册一致。以读一台支持 Modbus RTU 的温控仪表为例，手册上写的是「9600, 8, N, 1，从站地址 1」。那你的配置就是波特率 9600、8 数据位、无校验、1 停止位、从站地址 1。这几个参数错一个，要么完全没响应，要么响应超时。

3.2 手工构造一帧读保持寄存器请求

在写代码之前，我强烈建议先用串口助手手工发一帧，确认设备会回。读从站地址 1 的保持寄存器，起始地址 0x0000，读 2 个寄存器，请求帧是：

01 03 00 00 00 02 C4 0B

拆开看：01是从站地址，03是功能码读保持寄存器，00 00是起始地址，00 02是寄存器数量，C4 0B是 CRC16 校验（低字节在前）。CRC 算错的话设备直接不理你，这是最常见的「发了没反应」原因。用库里的 CRC 函数算一遍，或者用在线工具核对，确认无误再往下走。

正常响应应该是01 03 04 XX XX YY YY CRC，其中04是字节数（2 个寄存器 = 4 字节），后面 4 个字节是两个寄存器的值。如果回的是01 83 02 CRC，说明功能码被置了 0x80，异常码 02 表示「非法数据地址」，也就是你请求的寄存器地址设备不支持。

3.3 用库把请求发出去并解析响应

手工验证通过后，把逻辑搬进代码。下面是一个完整的主站读寄存器流程，假设库已经提供了modbus_build_request和modbus_parse_response两个接口：

/* 主站读保持寄存器完整流程 */ uint8_t req[8]; uint8_t resp[256]; uint16_t req_len, resp_len; uint16_t regs[2]; /* 1. 组帧：从站地址 1，功能码 03，起始 0，数量 2 */ req_len = modbus_build_read_holding(1, 0x0000, 2, req, sizeof(req)); /* 2. 通过移植层发送 */ port.send(req, req_len); /* 3. 等待响应，带超时。超时时间一般取 100~300ms */ uint32_t start = port.tick_ms(); resp_len = 0; while ((port.tick_ms() - start) < 300) { int n = port.recv(resp + resp_len, sizeof(resp) - resp_len); if (n > 0) { resp_len += n; /* 尝试解析，收够了就退出 */ if (modbus_parse_read_holding(resp, resp_len, regs, 2) == 0) { break; } } } /* 4. 使用结果：regs[0] 和 regs[1] 就是两个寄存器的值 */ printf("reg0=%u reg1=%u\n", regs[0], regs[1]);

参数说明：超时时间 300ms 是个经验值，波特率低、总线长、设备响应慢的时候要适当放大；modbus_parse_read_holding的返回值要区分「数据不够继续收」和「校验失败直接丢弃」两种情况，否则会把半帧当完整帧解析。这一步是纯 C 库落地时最容易写错的地方——很多人只判断收到字节就解析，结果 CRC 对不上还硬用。

3.4 验证响应正确性的三个检查点

收到响应后别急着用数据，先过三道检查。第一，从站地址是否和请求一致，总线上多个从站时可能串帧；第二，功能码最高位是不是 0x80，是的话就是异常响应，要去查异常码；第三，CRC 是否匹配，不匹配直接丢帧重发。这三步做完，数据才可信。

如果设备支持，可以故意发一个非法地址，看它回不回异常帧。能正确回异常帧的设备，说明它的 Modbus 实现是完整的，后续采集稳定性会好很多。这一步相当于给设备做个体检。

4. 避坑与排查：纯 C Modbus RTU 落地时最常翻车的五件事

4.1 现象：偶尔能读到数据，大部分时间超时

原因通常是帧间隔时间设错了。前面说过，RTU 靠 3.5 字符静默断帧，如果你的接收逻辑用固定延时或者错误的间隔值，会把一帧切成两半，或者把两帧粘成一帧。波特率越高，这个时间窗口越窄，越容易出问题。

解决办法是把帧间隔做成跟波特率联动的计算值，而不是写死一个常数。9600 波特率取 4ms，19200 取 2ms，115200 取 0.3ms 左右。更稳妥的做法是用「收到字节后启动一个定时器，超时即认为帧结束」，而不是在字节流里数时间。

4.2 现象：CRC 校验一直失败，但手工算是对的

原因多半是字节序或者数据类型搞错了。CRC16 在 Modbus 里是低字节在前，有些实现按高字节在前发，设备自然不认。还有一种情况是接收缓冲区里混进了上一帧的残留字节，导致 CRC 计算范围不对。

解决办法是每次组帧前清空发送缓冲，每次解析前确认帧长度和功能码声明的字节数一致。CRC 计算函数单独写个测试用例，用标准帧01 03 00 00 00 02验证结果是不是C4 0B，对不上就先修 CRC 函数，别往下查。

4.3 现象：多从站轮询时，某个从站总是抢答或不应答

原因是轮询间隔太短，上一个从站的响应还没收完就发了下一个请求。RS485 是半双工，同一时刻只能有一个设备发。如果你的主站发完请求不等响应就发下一帧，总线会冲突。

解决办法是严格「一问一答」：发完请求必须等到响应或超时，才能发下一帧。轮询多个从站时，从站地址要逐个切换，中间留够帧间隔。有些库提供了轮询调度接口，如果没有，自己在应用层写一个状态机。

4.4 现象：Linux 下能跑，Windows 下收不到数据

原因是串口读写的阻塞模式不同。Linux 下read默认阻塞，Windows 下ReadFile的行为受超时参数影响。纯 C 库把串口操作交给移植层，移植层没处理好阻塞和非阻塞，就会出现「Linux 正常、Windows 卡死」或者反过来。

解决办法是移植层的recv统一做成非阻塞或带短超时，让库的上层循环去控制总超时。Windows 下用SetCommTimeouts把读超时设成 1~5ms，Linux 下用O_NONBLOCK或者select。两边行为对齐了，跨平台才算真的跨过去。

4.5 现象：读上来的寄存器值明显不对，但帧是对的

原因是寄存器地址的「协议地址」和「设备地址」差了 1。Modbus 协议里寄存器地址从 0 开始，但很多设备手册写的是 40001、40002 这种「PLC 地址」，40001 对应协议地址 0x0000。你按 40001 去发，实际请求的是 0x9C41，设备当然回异常或者错值。

解决办法是拿到手册先确认它给的是协议地址还是 PLC 地址。如果是 4xxxx 格式，减 40001 得到协议地址；如果是 3xxxx，减 30001。这个坑几乎每个做 Modbus 的人都踩过，属于血泪经验。

5. 进阶：把库用稳的三个技巧和一套自检方法

5.1 用重试加退避应对现场干扰

工控现场电磁干扰大，偶发 CRC 错误很正常。我的习惯是在应用层加一层重试：同一帧连续失败 3 次再报错，每次重试之间隔 50~100ms。不要一失败就疯狂重发，那样只会让总线更乱。重试次数和间隔做成可配置，现场调试时方便调整。

/* 带重试的读寄存器封装 */ int read_holding_with_retry(uint8_t slave, uint16_t addr, uint16_t count, uint16_t *out, int max_retry) { for (int i = 0; i < max_retry; i++) { if (modbus_read_holding(slave, addr, count, out) == 0) { return 0; /* 成功 */ } port.delay_ms(80); /* 退避，给总线恢复时间 */ } return -1; /* 连续失败，上报错误 */ }

参数上，max_retry一般取 3，delay_ms取 50~100。如果某个从站重试率特别高，先查接线和终端电阻，别一味加大重试次数掩盖硬件问题。

5.2 用回环测试验证库本身

怀疑库有问题时，先做回环测试：把串口的 TX 和 RX 短接，发什么收什么。这样能排除设备和接线因素，单独验证库的组帧、CRC、解析逻辑。回环下如果都收不对，那就是库或者移植层的问题，跟现场设备无关。

回环测试还能验证帧间隔逻辑。连续发几帧不同的请求，看接收侧能不能正确切分。如果回环下都粘帧，现场只会更糟。

5.3 用异常码反查设备能力

异常码是设备在告诉你它为什么不干活。01 非法功能、02 非法数据地址、03 非法数据值、04 从站故障。采集程序里把异常码打出来，比只报「读取失败」有用得多。比如你请求读 10 个寄存器，设备回异常码 02，说明它只支持更少的寄存器数量或者地址范围不对，改小数量再试。

我一般会在采集日志里把「从站地址 + 功能码 + 异常码」一起记下来，现场排查时一眼就能看出是哪个设备、哪个操作出的问题。这套习惯是从无数次现场返工里攒出来的——从那以后我每次接新设备，都强制先手工发一帧、再回环测一遍、最后才上采集程序，三步走完再谈稳定性。希望帮到你。

本文还有配套的精品资源，点击获取