简介一份基于C实现的MODBUS TCP服务器端源码面向工业自动化开发者、嵌入式工程师及通信协议学习者。源码实现了MODBUS功能码03与16即读取保持寄存器和写多个保持寄存器并通过TCP 502端口与客户端通信覆盖请求解析、应答构造、错误处理等基本流程可快速构建设备接入TCP/IP网络的服务器框架。压缩包采用rar格式共22个文件以C头文件.h和实现文件.cpp为主另含Visual Studio工程配置、资源说明与辅助资源整体仅152KB结构紧凑便于逐行阅读和二次开发。已有2169人学习下载。开发者可在此基础上扩展线圈操作功能码01、05等更多能力并用于智能能源管理、环境监测、自动化生产线等工业场景的定制化调试既方便初学者理解MODBUS帧格式与事务处理流程也有助于在真实网络中快速验证设备通信逻辑是C网络编程与协议栈学习的良好实践样例。 前阵子做设备联网改造需要在Linux的嵌入式板子上跑一个MODBUS TCP Server网上找了一圈现成的源码不是依赖了一堆第三方库就是代码写得太抽象想在里面加自己的业务逻辑反而更费劲。后来干脆对照MODBUS协议文档自己从零写了一个精简的Server代码拢共几百行Linux和Windows都能编译运行后面还把核心模块移植到了资源有限的ARM板子上实测下来相当稳定。这篇就把整个实现过程、关键源码和调试阶段踩过的坑整理出来给准备自己实现MODBUS TCP Server的朋友做个参考。不管你是做PLC数据采集、网关协议转换还是想快速模拟一个从站来调试上位机这篇文章应该都能帮上忙。1. 动工之前MODBUS TCP和RTU的差异以及Server要解决的场景1.1 少了CRC多了MBAPMODBUS TCP的协议帧到底长什么样学习MODBUS TCP之前很多人会把RTU那套帧格式往TCP上硬套。其实两者虽然寄存器和功能码模型完全一致但在帧结构上有两个非常明显的区别。RTU走串口帧格式是“从站地址 功能码 数据 CRC”从站地址只有1个字节CRC16校验也是必须的因为串口链路没有可靠传输保证。而MODBUS TCP走的是TCP/IPTCP协议自己已经解决了可靠传输、乱序重排和校验问题所以MODBUS TCP帧里不再需要CRC校验取而代之的是一个MBAP报文头。MBAP头一共7个字节真正给MODBUS用到的只有前6个事务处理标识符2字节客户端发起的请求序号服务端原样返回用来匹配某个请求和对应的响应协议标识符2字节MODBUS TCP中固定为0x0000长度字段2字节表示后面“单元标识符 功能码 数据”的总字节数单元标识符1字节以前叫从站地址在TCP模式下一般填0x01如果需要通过网关桥接多个串口从站这个字段就能派上用场。所以如果你在解析MODBUS TCP报文时去第一帧数据里找CRC那方向就错了。这个区别最直接的后果是写代码时要看清楚TCP报文里那个“长度”字段才决定了你需要收多少字节才能凑齐一帧。1.2 三种典型场景模拟从站、协议转换、数据采集网关那么一个自定义实现的MODBUS TCP Server一般用来干嘛我做了几个项目之后发现归纳起来主要是三种场景。第一种是模拟从站。开发上位机或者组态软件时现场设备还没到位用自己写的Server在PC上跑起来填上模拟的寄存器数据上位机就能先调试逻辑。这个场景要求Server配置灵活、启动快最好双击就能跑。第二种是协议转换网关。很多工业现场的老设备只有RS485串口走MODBUS RTU而上位机要求走MODBUS TCP。这种情况下网关设备里跑一个TCP Server收到上位机的TCP请求之后解析出功能码和地址再通过串口转发给底层RTU从站拿到响应后转成TCP回给上位机。这个场景对实时性要求不算高但要做好超时处理和异常码映射。第三种是数据采集边缘网关。网关本身通过其他总线比如CAN、模拟量采集拿到数据要把数据开放给上位机或云平台时做一个标准的MODBUS TCP Server接口让任意支持MODBUS TCP协议的上位机都能直接读取。我在设计源码时就是围绕这三种场景来做抽象把“寄存器区”做成一个简单接口底层可以接内存数组也可以接真实硬件读取函数。这样一套代码三种场景全通。2. 架构设计与模块划分从socket到寄存器表怎么分2.1 自己写Server不管代码多少都要有的四个层次虽然MODBUS协议看起来简单但如果把所有逻辑都塞在一个大函数里调试起来会非常痛苦。我重构了几次之后固定成了四个层次。网络层管socket的创建、监听、accept和poll事件循环负责“有没有新连接、某个连接有没有数据可读”。协议层做的两件事一是从字节流里切出完整的一帧二是根据MBAP头把响应帧拼回去。帧解析层则负责校验功能码、解析地址和数量然后调用具体的数据读写函数。数据模型层就是你的寄存器表和线圈表或者对应的硬件操作函数。好处是编译期就隔离了关注点网络层怎么改都不会影响协议层协议层加功能码也不会动数据模型。比如你想把Server从socket换成epoll只改网络层想增加一个非标准的私有功能码只加帧解析层。我个人写协议栈的习惯是层与层之间通过函数指针或者简单的结构体传参不引入复杂框架以免在嵌入式上编译困难。2.2 线程模型怎么选单线程poll方案在小资源设备上最省心线程模型是写Server时第一个要做的决定。我在嵌入式板子上跑内存和CPU都紧张所以最终选择了“单线程事件循环”的方案用poll来管理所有socket。核心思路是把listen socket和每个已连接的client socket都放进一个pollfd数组有事件就处理没有事件就阻塞等待。单线程最大的优势是不用考虑锁。寄存器数组和连接列表全部在同一个线程里被访问不会出现并发修改问题代码自然就简单了。你可能会担心性能但实际上MODBUS TCP的请求频率一般不会超过数百毫秒一次单线程处理几十个客户端绰绰有余。如果哪天你需要更高的并发比如上千个客户端同时轮询再考虑改成多线程或者把IO改成epoll异步模型。但就绝大多数工业现场来说完全没必要一上来就上多线程。做嵌入式就是这句话性能够用就行可维护性远比花哨重要。2.3 数据模型设计直接用数组模拟寄存器区真实设备就换回调MODBUS协议里有四类数据对象线圈Coil可读可写、离散输入Discrete Input只读、保持寄存器Holding Register可读可写、输入寄存器Input Register只读。这四类数据区在源码里最直接的做法就是定义成全局数组。#define N_HOLDING_REGS 1000 #define N_INPUT_REGS 1000 #define N_COILS 1000 #define N_DISCRETE_IN 1000 static uint16_t holding_regs[N_HOLDING_REGS]; static uint16_t input_regs[N_INPUT_REGS]; static uint8_t coils[N_COILS]; static uint8_t discrete_inputs[N_DISCRETE_IN];用数组模拟的好处是代码简单、可运行、可测试。当你需要对接真实设备时只要在读写函数里加一个回调钩子读保持寄存器的函数从“读取数组”改成“调用你硬件的读取API”就完成接入了。我在网关项目里就是这么做的底层是串口数据采集线程上层协议处理时通过互斥锁拿最新快照既简单又不会卡住协议解析。3. 核心代码实现监听、拆帧与功能码分发3.1 服务端网络骨架创建socket必须开的SO_REUSEADDR服务端骨架不管在哪个平台流程都是固定的socket、bind、listen、accept。有一个细节我每次都会强调就是bind之前必须设置SO_REUSEADDR。int listen_fd socket(AF_INET, SOCK_STREAM, 0); if (listen_fd 0) { perror(socket); return -1; } int opt 1; setsockopt(listen_fd, SOL_SOCKET, SO_REUSEADDR, opt, sizeof(opt)); struct sockaddr_in addr; memset(addr, 0, sizeof(addr)); addr.sin_family AF_INET; addr.sin_addr.s_addr htonl(INADDR_ANY); addr.sin_port htons(502); if (bind(listen_fd, (struct sockaddr *)addr, sizeof(addr)) 0) { perror(bind); close(listen_fd); return -1; } listen(listen_fd, 8);没有这个选项时Server崩溃重启之后很可能报“Address already in use”因为TCP连接处于TIME_WAIT状态端口还没释放。加了SO_REUSEADDR之后重启就没这个问题了。端口方面标准MODBUS TCP端口是502但Linux下普通用户没有权限绑定1024以下的端口要么用root跑要么先换成1502测试等真正部署时再映射到502。3.2 半包粘包从字节流里准确切出一帧MODBUS报文TCP是字节流协议没有“帧”的概念。一次recv拿到的数据可能只是半帧也可能是好几帧粘在一起。处理的唯一正确姿势是先接收数据到一个缓冲区然后根据MBAP头里的长度字段来判断当前缓冲区里有没有完整的一帧。#define RX_BUF_SIZE 260 static uint8_t rx_buf[RX_BUF_SIZE]; static int rx_len 0; // recv返回n 0时执行 rx_len n; while (rx_len 6) { int pkt_len (rx_buf[4] 8) | rx_buf[5]; // MBAP长度 int frame_len pkt_len 6; // 帧总长 前6字节 长度字段 if (frame_len RX_BUF_SIZE) { // 明显是坏数据清空缓冲区 rx_len 0; break; } if (rx_len frame_len) { // 半包等后续数据 break; } // 收到完整一帧交给协议处理 process_modbus_frame(client_fd, rx_buf); // 移出已处理的数据 memmove(rx_buf, rx_buf frame_len, rx_len - frame_len); rx_len - frame_len; }这段代码是Server的核心也是我踩坑最多的地方。第一次实现时我用固定大小数组存“一帧”结果客户端请求一个响应慢的场景下数据粘包直接导致解析错位。后来改成“先收6字节头再收数据”的流程问题才彻底解决。实际项目里建议每个客户端独立分配一个rx缓冲区不要所有连接共享。3.3 功能码分发03读保持寄存器、06写寄存器等核心函数帧解析拿到完整报文后接下来就是最常用的几个功能码。一张表先列出常规Server需要支持的功能码名称作用0x01读线圈读取线圈状态按位返回0x02读离散输入读取离散输入状态0x03读保持寄存器读取可读写的16位寄存器0x04读输入寄存器读取只读的16位寄存器0x05写单个线圈写一个线圈的通断状态0x06写单个保持寄存器写一个保持寄存器值0x0F写多个线圈写多个线圈状态0x10写多个保持寄存器写多个保持寄存器值以03功能码为例请求数据部分由“起始地址2字节 寄存器数量2字节”组成响应则是“字节数 寄存器数据每个寄存器2字节高字节在前”。void handle_read_holding_regs(uint16_t addr, uint16_t count, uint8_t *resp, int *resp_len) { if (addr count N_HOLDING_REGS) { build_exception_resp(0x03, 0x02, resp, resp_len); return; } resp[0] 0x03; resp[1] (uint8_t)(count * 2); // 后续数据字节数 for (int i 0; i count; i) { resp[2 i * 2] holding_regs[addr i] 8; resp[3 i * 2] holding_regs[addr i] 0xFF; } *resp_len 2 count * 2; }有一点特别容易忽略MODBUS协议中寄存器地址是从0开始编号的比如文档里说“保持寄存器40001”实际请求地址就是0。很多设备说明书会写成人眼友好的地址实际网络报文中地址值要减去基地址。如果你用MODBUS Poll去测试自己的Server发现请求的地址总是和你预期的差一位多半就是这个基地址偏移问题。3.4 异常响应请求不合法时用功能码最高位置1回给客户端协议里规定了异常响应的格式将功能码最高位置1即请求功能码是0x03异常响应就是0x83后面跟一个异常码异常码由“功能码 异常码”组成。常用的三个异常码01非法功能码02非法数据地址03非法数据值。void build_exception_resp(uint8_t func, uint8_t code, uint8_t *resp, int *resp_len) { resp[0] func | 0x80; // 功能码置高位 resp[1] code; *resp_len 2; }写Server的时候最忌讳的是收到非法请求后直接把连接断开。正确做法是回一个异常响应让客户端明确知道“你请求的地址超范围了”或者“功能码不支持”。我在第一版实现时遇到非法地址直接不回复结果上位机那边超时重试日志刷得飞快后来加上异常码问题一下就清晰了。4. 用MODBUS Poll和Wireshark把Server跑起来验证4.1 MODBUS Poll配置要点IP、端口502、功能码03、地址范围写完了Server接下来就要验证它。这里我强烈建议用MODBUS Poll作为主站客户端来测试。关于MODBUS Poll网上流传的密钥文件版本很杂且经常失效其实官方试用版完全够用不用在这上面浪费时间。连接配置很简单Setup菜单里选择TCP/IP连接模式填上Server的IP地址和端口默认502其他参数暂时不用改。然后在“Read/Write Definition”里选择功能码03、起始地址0、数量10点OK后主界面就能看到寄存器值了。如果Server的逻辑正确这里应该稳定地周期性读出一条数据。测试写功能的时候可以双击任意寄存器输入新值然后观察Server端日志和MODBUS Poll状态栏。如果返回错误码优先去看是不是地址越界再去看字节序配置MODBUS TCP默认是大端传输如果上位机用了小端解释你会看到一个16位值高低字节对调比如写入0x1234读到的是0x3412这通常是客户端配置问题不是Server的问题。4.2 Wireshark抓包看MODBUS TCP报文对错一眼就能看出来MODBUS Poll能告诉你功能是否正常但要想知道报文细节必须上Wireshark。启动抓包后在过滤框输入“modbus”立刻就能看到完整的MODBUS请求和响应帧。抓包时重点看三样东西第一是MBAP头里的“长度”字段是否正确。我见过有人把长度写成了整个TCP payload长度导致客户端解析错位。第二是事务处理标识符是否一一对应Server必须原样返回请求的事务ID。第三是寄存器数据的字节序抓包面板中如果能看到数值以高字节在前的方式呈现说明Server处理正确。还有一个实践中经常用的技巧抓包看TCP层。如果MODBUS帧在应用层看起来完全正常但客户端时不时报超时检查是否为TCP粘包导致客户端一次性收到了两帧数据。这种情况在抓包面板里会非常明显——一个TCP Segment里出现了两个MODBUS请求。解决办法就是我在3.2节写的缓冲区分帧处理逻辑。5. 我把踩过的坑整理成了问题排查清单5.1 bind失败与端口不可用SO_REUSEADDR救不了所有情况最典型的报错是“bind: Address already in use”通常是因为上一个Server进程没完全退出或者有TCP连接处于TIME_WAIT状态。SO_REUSEADDR能解决大部分场景但如果是另一个进程正占着502端口那什么选项都不管用。排查时用lsof -i :502看看哪个进程占着端口或者用netstat -tlnp确认端口状态。另外还要注意很多Linux发行版默认防火墙策略会拦截外部访问502端口。我之前在Ubuntu上跑Server本机用MODBUS Poll连接一切正常换到另一台机器就连不上了排查半天发现是防火墙没放行。临时用iptables放行一下或者干脆在受控内网里把防火墙关掉这个坑一定要提前知道。5.2 Modbus Poll报02 Illegal Data Address多半是地址越界了用MODBUS Poll测试时如果请求读100个寄存器而Server内部数组实际只定义了50个Server会返回异常码02非法数据地址。这个问题不是MODBUS Poll的Bug而是请求的地址加数量确实超出了寄存器表的范围。解决方法有两个角度。从Server角度把寄存器表扩容到足够覆盖整个应用区域或者对越界请求回异常码后记日志。从客户端角度把读取数量改小或把起始地址改到有效范围内。我实际排查中还遇到过一种隐蔽情况请求地址本身在范围内但“地址数量”溢出了uint16_t导致地址回绕成一个很小或很大的数这种时候Server一定要用uint32_t做加法判断防止溢出。5.3 多客户端并发读写的安全单线程轮询其实最稳很多人在Server刚跑通时会纠结一个事多个客户端同时读同一个寄存器会不会乱单线程事件循环模型天然没有这个问题因为每个时刻只处理一个socket的事件寄存器数组不会同时被两个请求修改。但如果你的Server不止一个线程比如数据采集线程在驱动真实设备同时另一个线程在响应MODBUS请求这个时候寄存器的读写就要加锁了。我的做法是数据采集线程负责更新数据快照用一个互斥锁保护快照MODBUS协议线程读取快照前加锁读取之后立即解锁把锁持有的时间控制在最短。这样做实时性损失很小数据一致性有保证。记住一个原则不要在一个大事务里抱着锁不放尤其是涉及网络读写时。写到这里我回头看这段源码最有价值的其实不是那几行函数而是“如何用最直观的方式把协议变成代码”这个思考过程。我自己建项目的第一步永远是先写命令行日志把收到的每一帧原始字节打出来确认帧边界正确后再往下解析。这套“日志先行”的思路帮我省掉了至少一半的调试时间也建议你从开始就养成这个习惯。本文还有配套的精品资源点击获取