ESP32 ModbusTCP 分片缓存：环形缓冲与状态机实战

1. 项目缘起与整体设计思路

1.1 这个标题到底在说什么

先把话说清楚：ESP32 ModbusTCP 分片缓存，本质上解决的是一个在工业物联网场景里非常常见、但很多人第一次踩坑时完全摸不着头脑的问题——当 ESP32 作为 ModbusTCP 从站（或者网关）时，一帧 ModbusTCP 报文被 TCP 协议拆成了多个网络包发过来，而你的代码却天真地以为“一次 recv 就能拿到一整帧”。

我最早接触这个问题是在一个模拟的采集网关项目里。设备端用 ESP32 跑 ModbusTCP 服务，上位机（模拟的组态软件）通过以太网读写保持寄存器。测试阶段一切正常，因为数据量小、网络干净、寄存器数量少，每次请求也就十几个字节，TCP 一次就送过来了。结果现场一上量，读 100 个连续寄存器，请求帧加上 MBAP 头也就 12 字节左右，但响应帧直接飙到 200 多字节，问题就来了——ESP32 的 lwIP 栈默认的 TCP 接收窗口和 MSS 限制，导致这 200 多字节被拆成了 2 到 3 个 TCP 段。我的代码只读了第一个段，解析出来的数据缺斤少两，上位机显示的值全是乱的。

所以这个项目的核心就一句话：在 ESP32 上实现一个能正确处理 TCP 分片（或者说 TCP 流式传输）的 ModbusTCP 缓存层，保证无论报文被拆成几段，都能完整、正确地拼出一帧 Modbus 数据。

它适合谁看？如果你正在用 ESP32 做 ModbusTCP 从站、Modbus 网关、或者任何基于 TCP 的自定义二进制协议，并且被“数据偶尔对、偶尔错”“读多了就乱”“跑一晚上就断”这类问题折磨过，那这篇内容就是写给你的。哪怕你用的是别的 MCU，只要涉及 TCP 流式协议解析，思路也是通的。

1.2 为什么不能“一次 recv 一帧”

很多人写 TCP 代码有个思维惯性：UDP 是面向报文的，一次收一个包；TCP 是面向流的，它只保证字节顺序，不保证边界。ModbusTCP 虽然叫“TCP”，但它的帧边界是靠 MBAP 头里的长度字段来界定的，而不是靠 TCP 的包边界。

ModbusTCP 的报文结构是这样的：

关键就在那个长度字段。它告诉你“从单元标识符开始，后面还有多少字节”。所以正确的解析逻辑是：先把 MBAP 头 6 个字节收全，读出长度 L，然后再收 L 个字节，凑齐一帧。

但 TCP 不会配合你。它可能把 6 字节的头拆成 4+2，也可能把整个帧一次性给你，还可能把两帧粘在一起给你（粘包）。所以你需要一个缓存区，把收到的零散字节先存起来，然后按状态机去判断“现在够不够一帧”。

1.3 方案选型：为什么用环形缓冲而不是动态内存

在 ESP32 上做这个缓存，我试过三种方案：

第一种是每次 malloc 一块新 buffer，收到数据就 realloc。这个方案在 PC 上跑没问题，但在 ESP32 上跑久了必然碎片化。ESP32 的堆本来就不大，默认也就 300 多 KB 可用，频繁 malloc/free 小块的后果就是某天突然 malloc 失败，设备死给你看。

第二种是固定大数组 + 手动 memmove。比如开一个 512 字节的数组，每次收完数据把剩余部分往前挪。这个方案简单，但 memmove 在数据量大时开销不可忽视，而且如果一帧超过 512 字节（ModbusTCP 理论上最大 260 字节左右，但自定义扩展可能更大），就直接溢出了。

第三种就是我现在用的：环形缓冲区（Ring Buffer）+ 状态机。环形缓冲的好处是读写指针独立移动，不需要搬数据，O(1) 写入，O(1) 读取。配合一个解析状态机，先找 MBAP 头，再按长度字段收满整帧。这个方案内存占用固定，不会碎片化，而且天然支持粘包处理——因为缓冲区里可能同时存在一帧半的数据，状态机可以连续解析。

我最终选的是第三种，缓冲区大小给了 1024 字节。为什么是 1024？因为 ModbusTCP 标准帧最大 260 字节左右，1024 足够容纳 3 到 4 帧，给粘包留了充足余量。同时 1024 在 ESP32 上也就占 1KB 内存，完全可接受。

提示：如果你的应用场景里单帧可能超过 1024 字节（比如自定义扩展协议），缓冲区要相应放大，但建议不要超过 4096，否则 ESP32 的 RAM 会紧张。

1.4 整体架构分层

整个实现我分了三层：

最底层是TCP 接收层，负责从 lwIP 的 socket 里读数据，读到多少算多少，直接塞进环形缓冲。这一层不关心协议内容，只做搬运。

中间是环形缓冲层，提供 write、read、peek、available 这几个基本操作。写入时如果空间不够就丢弃最旧的数据（或者返回错误，看策略），读取时支持“预读但不消费”，方便状态机判断。

最上层是ModbusTCP 解析状态机，它从环形缓冲里 peek 数据，先检查是否有 6 字节以上的数据，然后读长度字段，再检查是否有完整帧，够了就消费掉并交给业务处理函数。

这三层解耦之后，调试起来非常清晰。TCP 层的问题不会影响解析逻辑，解析逻辑的 bug 也不会污染缓冲实现。

2. 核心细节解析与实操要点

2.1 环形缓冲的实现细节与踩坑

环形缓冲听起来简单，但有几个细节不注意就会出问题。

第一个是读写指针的边界处理。我用的是head和tail两个索引，head指向下一个写入位置，tail指向下一个读取位置。判断空的条件是head == tail，判断满的条件是(head + 1) % size == tail。注意这里牺牲了一个字节的空间来区分空和满，这是经典做法。如果你不想浪费这个字节，就得额外维护一个count变量。

第二个是写入时的分段拷贝。当head接近缓冲区末尾时，一次写入可能会跨越边界，需要拆成两段 memcpy。我见过有人在这里偷懒，直接逐字节写，结果在 115200 波特率下还行，到了以太网全速跑的时候，逐字节拷贝成了性能瓶颈。所以一定要用 memcpy 分段处理。

第三个是线程安全。ESP32 上如果你用的是 FreeRTOS，TCP 接收任务和 Modbus 解析任务可能不在同一个任务里。这时候环形缓冲的读写就需要加锁，或者用无锁的单生产者单消费者模式。我一开始没加锁，跑测试没问题，因为接收和解析恰好在同一个任务里。后来把解析拆到独立任务，立刻就出现了数据错乱。加了一把互斥锁之后稳定了，但要注意锁的粒度——只在 write 和 read 操作时加锁，不要在锁里做耗时操作。

// 环形缓冲写入示例（简化版） bool ringbuf_write(ringbuf_t *rb, const uint8_t *data, size_t len) { if (ringbuf_free(rb) < len) { return false; // 空间不足 } size_t first = rb->size - rb->head; if (len <= first) { memcpy(rb->buf + rb->head, data, len); rb->head = (rb->head + len) % rb->size; } else { memcpy(rb->buf + rb->head, data, first); memcpy(rb->buf, data + first, len - first); rb->head = len - first; } return true; }

注意：ringbuf_free的计算要考虑空满判断的那个保留字节，实际可用空间是size - 1 - used。

2.2 ModbusTCP 长度字段的陷阱

MBAP 头里的长度字段是大端序（网络字节序），这个大家都知道。但有个坑很多人不知道：长度字段的值不包括 MBAP 头本身的 6 个字节。也就是说，如果长度字段是 6，那整帧长度是 6 + 6 = 12 字节。

我见过有人把长度字段直接当成整帧长度，结果永远少读 6 个字节，解析出来的功能码全是错的。这个错误在调试时特别隐蔽，因为如果你只读一个寄存器，响应帧的 PDU 部分很短，少读 6 字节可能刚好把下一帧的头给吞了，表现就是“偶尔对一次，然后连续错”。

正确的计算方式是：

uint16_t mbap_len = (buf[4] << 8) | buf[5]; // 大端 uint16_t total_len = mbap_len + 6; // 加上 MBAP 头

还有一个边界情况：长度字段的合法范围。ModbusTCP 规范里，长度字段最大是 253 + 1 = 254（PDU 最大 253 字节，加上单元标识符 1 字节）。如果你读出来的长度超过 260，那基本可以判定是脏数据或者协议错误，应该丢弃当前缓冲重新同步。我在状态机里加了这个检查，超过 260 就直接 reset，避免因为一个坏帧把整个缓冲区堵死。

2.3 状态机的设计：三状态还是四状态

解析状态机我最初设计的是三个状态：找头、读长度、收数据。后来发现不够，因为“找头”这个动作本身需要区分“完全没头”和“头收了一半”。所以最终是四个状态：

这里有个优化点：在 WAIT_MBAP 状态，如果缓冲区里的数据不够 6 字节，就直接返回，等下次 TCP 收到数据再进来。不要在这里阻塞等待，否则会卡住整个任务。

在 CHECK_LEN 状态，读完长度后不要急着消费数据，因为可能 PDU 还没收全。这时候应该转到 WAIT_PDU，等 available 够了再处理。

在 PROCESS 状态，处理完一帧后，消费掉 total_len 个字节，然后立即回到 WAIT_MBAP，因为缓冲区里可能还有下一帧（粘包）。这个循环要一直跑到 available 不够一帧为止。

void modbus_parse(ringbuf_t *rb) { while (1) { size_t avail = ringbuf_available(rb); if (avail < 6) return; uint8_t header[6]; ringbuf_peek(rb, header, 6); uint16_t len = (header[4] << 8) | header[5]; if (len > 254) { ringbuf_reset(rb); // 脏数据，重置 return; } uint16_t total = len + 6; if (avail < total) return; uint8_t frame[260]; ringbuf_read(rb, frame, total); handle_modbus_frame(frame, total); } }

提示：ringbuf_peek是不消费数据的读取，ringbuf_read会移动 tail 指针。这两个操作要区分清楚，否则会把没处理完的数据吃掉。

2.4 缓冲区大小的权衡

前面说了我选了 1024 字节，这里展开讲讲为什么。

ModbusTCP 单帧最大长度：MBAP 头 6 字节 + 单元标识符 1 字节 + PDU 最大 253 字节 = 260 字节。这是标准上限。但实际应用中，读 125 个寄存器（功能码 0x03 的最大值）的响应是 1 + 1 + 1 + 250 = 253 字节左右，加上头就是 259 字节。

如果缓冲区只有 260 字节，那么当一帧刚好收完但还没处理时，如果 TCP 又送来下一帧的开头，就会溢出。所以缓冲区至少要能容纳“一帧完整 + 下一帧的头”。260 + 6 = 266，取整到 512 其实就够了。

但我选了 1024，原因是：给粘包留余量，减少状态机循环次数。如果缓冲区是 512，可能一次只能处理一帧多一点；1024 的话可以连续处理 3 到 4 帧，减少了 peek/read 的调用频率。在 ESP32 上，这点性能差异其实不大，但调试时缓冲区大一点，抓到的数据更完整，方便分析问题。

当然，如果你同时跑多个 ModbusTCP 连接，每个连接都要一个独立的环形缓冲，那内存就要乘以连接数。ESP32 默认的 lwIP 最大 socket 数是 10 左右，如果全开，10 × 1024 = 10KB，还在可接受范围。但如果你的应用还有其他内存大户（比如 TLS、JSON 解析），就要适当缩小到 512。

3. 实操过程与核心环节实现

3.1 环境搭建与基础配置

我用的开发环境是 ESP-IDF，版本 4.4 以上。lwIP 是 ESP-IDF 自带的，不需要额外移植。创建工程后，先配置几个关键参数：

在menuconfig里，Component config → LWIP → Max number of open sockets我设成了 8，够用就行。TCP receive window保持默认的 5744 字节，这个值影响的是 TCP 层的接收窗口，不是我们的应用缓冲，不用改。

Wi-Fi 或者以太网初始化这部分不是本文重点，假设你已经能正常 ping 通 ESP32。我测试时用的是内置以太网 PHY 的模组，IP 设为静态 192.168.1.100，端口 502。

然后定义一个 ModbusTCP 服务任务：

void modbus_server_task(void *pvParameters) { int listen_sock = socket(AF_INET, SOCK_STREAM, 0); struct sockaddr_in addr = { .sin_family = AF_INET, .sin_port = htons(502), .sin_addr.s_addr = htonl(INADDR_ANY), }; bind(listen_sock, (struct sockaddr *)&addr, sizeof(addr)); listen(listen_sock, 4); while (1) { int client = accept(listen_sock, NULL, NULL); if (client < 0) continue; handle_client(client); // 每个连接一个处理循环 close(client); } }

注意：ESP32 上不要在主任务里跑这个循环，否则看门狗会咬。我单独开了一个任务，栈大小给了 4096，优先级设成 5。

3.2 TCP 接收与环形缓冲的对接

handle_client里就是核心循环：recv 收数据，塞进环形缓冲，调用解析状态机。

void handle_client(int sock) { ringbuf_t rb; ringbuf_init(&rb, 1024); uint8_t tmp[256]; while (1) { int n = recv(sock, tmp, sizeof(tmp), 0); if (n <= 0) break; // 连接关闭或错误 if (!ringbuf_write(&rb, tmp, n)) { // 缓冲区满，说明对端发太快或者有脏数据 ringbuf_reset(&rb); continue; } modbus_parse(&rb); } ringbuf_free(&rb); }

这里有个细节：recv的缓冲区我给了 256 字节。为什么不给 1024？因为 lwIP 的 TCP 接收窗口默认就 5744，但实际每次 recv 返回的数据量取决于 MSS 和当前窗口。给 256 是为了让 recv 尽快返回，不要等太久。如果给太大，recv 可能会阻塞到收满才返回，反而增加了延迟。

实测下来，在局域网环境下，一次 recv 通常返回 100 到 200 字节，正好是一帧 ModbusTCP 的大小。但偶尔会返回 40 多字节（分片），或者 400 多字节（粘包）。环形缓冲都能正确处理。

3.3 解析状态机的完整实现

把前面的状态机思路落地成代码，我写了一个modbus_parse函数，它被handle_client在每次 recv 之后调用。

typedef enum { STATE_WAIT_MBAP, STATE_CHECK_LEN, STATE_WAIT_PDU, } parse_state_t; void modbus_parse(ringbuf_t *rb) { static parse_state_t state = STATE_WAIT_MBAP; static uint16_t expected_len = 0; while (1) { size_t avail = ringbuf_available(rb); switch (state) { case STATE_WAIT_MBAP: if (avail < 6) return; uint8_t hdr[6]; ringbuf_peek(rb, hdr, 6); expected_len = ((hdr[4] << 8) | hdr[5]) + 6; if (expected_len > 260) { ringbuf_reset(rb); state = STATE_WAIT_MBAP; return; } state = STATE_WAIT_PDU; break; case STATE_WAIT_PDU: if (avail < expected_len) return; uint8_t frame[260]; ringbuf_read(rb, frame, expected_len); handle_modbus_frame(frame, expected_len); state = STATE_WAIT_MBAP; break; } } }

注意这里我把state和expected_len定义成了static，这意味着这个函数不可重入。如果你有多个连接，每个连接需要独立的解析状态，那就得把这两个变量封装到一个结构体里，每个连接一个实例。我一开始就是用了 static，结果两个客户端同时连的时候数据串了，排查了半天才发现是状态共享的问题。

提示：多连接场景下，把解析状态和环形缓冲打包成一个modbus_conn_t结构体，每个 accept 出来的 socket 分配一个，这样最干净。

3.4 业务处理与响应发送

handle_modbus_frame里就是真正的 Modbus 逻辑了。解析功能码，读或者写寄存器，然后组响应帧发回去。

void handle_modbus_frame(uint8_t *frame, uint16_t len) { uint16_t trans_id = (frame[0] << 8) | frame[1]; uint8_t unit_id = frame[6]; uint8_t func = frame[7]; if (func == 0x03) { // 读保持寄存器 uint16_t start = (frame[8] << 8) | frame[9]; uint16_t count = (frame[10] << 8) | frame[11]; // 校验 start 和 count 的合法性... uint8_t resp[260]; resp[0] = frame[0]; resp[1] = frame[1]; // 事务ID resp[2] = 0; resp[3] = 0; // 协议ID uint16_t pdu_len = 3 + count * 2; resp[4] = (pdu_len >> 8) & 0xFF; resp[5] = pdu_len & 0xFF; resp[6] = unit_id; resp[7] = func; resp[8] = count * 2; for (int i = 0; i < count; i++) { uint16_t val = get_holding_reg(start + i); resp[9 + i*2] = (val >> 8) & 0xFF; resp[10 + i*2] = val & 0xFF; } send(client_sock, resp, 9 + count * 2, 0); } // 其他功能码... }

这里有个性能注意点：send的时候不要一字节一字节发，要一次性把整帧发出去。TCP 虽然有 Nagle 算法会合并小包，但显式地一次 send 更可控。另外，如果send返回值小于期望长度，说明发送缓冲区满了，需要循环发送剩余部分。我在测试时遇到过发送 200 多字节只发出去 100 多的情况，后来加了循环发送才稳定。

3.5 实测数据与性能观察

我用一个模拟的 Modbus 主站工具，每秒发 100 次读请求，每次读 100 个寄存器（响应约 209 字节）。连续跑了 2 小时，统计结果如下：

分片率 30% 说明这个问题真的不是偶发，而是常态。如果没有分片缓存，三分之一的请求都会出错。粘包率 10% 也验证了状态机循环处理的必要性。

延迟方面，3.2ms 的平均值在工业场景完全够用。最大 18ms 出现在网络抖动时，但也没有超过 Modbus 典型的超时阈值（通常 100ms 到 1s）。

4. 常见问题与排查技巧实录

4.1 问题速查表

4.2 三个我踩过的坑

第一个坑：以为 TCP 会按帧送达。这个前面说了，是最根本的认知错误。我一开始用recv的返回值当帧长度，结果在实验室跑了一周都没事，一到现场就崩。后来用 Wireshark 抓包才发现，现场的网络设备多，交换机负载高，TCP 分片概率大幅上升。所以永远不要假设 TCP 的包边界等于应用层帧边界。

第二个坑：环形缓冲的满判断写错。我最初写的满判断是head == tail表示满，空也是head == tail，结果缓冲区一满就死循环。后来改成保留一个字节，(head + 1) % size == tail表示满，才正确。这个 bug 很隐蔽，因为只有缓冲区快满时才触发，平时测试根本遇不到。

第三个坑：多连接状态共享。前面提过，static变量导致两个客户端的数据串了。这个问题的表现是：单个客户端测试完全正常，两个客户端同时测试时，A 的请求收到了 B 的响应。排查时我一度怀疑是 TCP 连接搞混了，后来才意识到是解析状态没隔离。每个连接必须有独立的缓冲和状态，这是铁律。

4.3 调试技巧：怎么看到分片

很多人说“我怎么知道有没有分片”，其实很简单，在 recv 后面加一行打印：

ESP_LOGI(TAG, "recv %d bytes", n);

如果 n 的值有时候是 12（刚好一帧请求），有时候是 6（半帧），有时候是 200 多（完整响应），有时候是 400 多（两帧粘一起），那就说明分片和粘包都存在。

更进一步，你可以把每次 recv 的数据用十六进制打印出来，对照 ModbusTCP 的帧结构看。我调试时就是靠这个办法，一眼就看出第一段只有 MBAP 头的前 4 个字节，长度字段都没收全。

提示：ESP32 的日志输出用ESP_LOGI，不要用printf，因为printf在多任务环境下可能重入导致崩溃。日志级别在 menuconfig 里可以调，调试时开 Info，发布时关掉。

4.4 性能优化的两个小技巧

第一个是减少 peek 次数。在状态机里，每次循环都 peek 6 字节读头，其实可以在第一次读到完整头之后，把长度缓存起来，后续循环直接用缓存值，不用重复 peek。这个优化在高速请求下能减少约 15% 的 CPU 占用。

第二个是批量处理粘包。如果缓冲区里有多帧，不要每帧都调用一次handle_modbus_frame再回到循环，而是可以在一次循环里连续处理，直到剩余数据不够一帧。这个前面代码里已经体现了，while(1)循环会一直跑到avail < 6才返回。

4.5 什么情况下需要扩大缓冲区

如果你的应用场景满足以下任意一条，建议把缓冲区从 1024 扩大到 2048 或 4096：

• 单帧超过 260 字节（自定义扩展协议）
• 网络延迟高，TCP 窗口大，一次 recv 可能返回 500 字节以上
• 同时处理多个连接，且每个连接都可能粘包
• 主站发送频率极高，超过 1000 次/秒

但扩大缓冲区之前，先确认 ESP32 的剩余 heap 够不够。可以用esp_get_free_heap_size()打印一下，如果剩余小于 50KB，就要谨慎了。

5. 从单连接到多连接的扩展思路

5.1 连接结构体的设计

单连接跑通之后，扩展到多连接是自然而然的事。核心就是把之前static的状态变量全部收进一个结构体：

typedef struct { int sock; ringbuf_t rb; parse_state_t state; uint16_t expected_len; } modbus_conn_t;

每个 accept 出来的 socket 分配一个modbus_conn_t，然后开一个独立任务或者用 select 多路复用。我选的是每个连接一个任务，因为 ESP32 是双核的，任务多一点反而能利用双核优势。但任务栈要控制好，每个任务 4096 字节，8 个连接就是 32KB，加上其他任务，内存还是够的。

5.2 资源回收与异常处理

多连接场景下，最怕的是连接断了但资源没释放。我的做法是在handle_client的循环退出后，确保close(sock)和ringbuf_free都被调用。另外加了一个看门狗，如果某个连接超过 30 秒没有数据往来，就主动断开，防止僵尸连接占着内存。

异常处理方面，recv返回 0 表示对端正常关闭，返回负数要区分EAGAIN（非阻塞模式下无数据）和其他错误。我用的阻塞模式，所以recv返回负数基本就是连接异常，直接退出循环清理资源。

5.3 实际部署中的观察

在一个模拟的 4 连接并发测试中，每个连接每秒 50 次请求，连续跑 24 小时，结果如下：

这个结果说明，在合理配置下，ESP32 跑 4 路 ModbusTCP 从站是完全可行的。CPU 占用 35% 还有余量，heap 剩余 120KB 也足够应对突发。

注意：这个测试是在局域网有线环境下做的。如果是 Wi-Fi 环境，延迟和丢包率会高一些，分片概率也会上升，缓冲区可以适当加大到 2048。

6. 一些个人体会与后续可扩展的方向

这个项目从最初的“一次 recv 一帧”到最终的环形缓冲加状态机，中间踩的坑比我预想的多。最大的体会是：TCP 编程里，任何“想当然”都会在某个时刻变成 bug。你以为一次能收全，它偏要分片；你以为一帧处理完就没了，它偏要粘包；你以为单连接没问题，多连接就串数据。

环形缓冲加状态机这个组合，我后来也用在其他协议上，比如自定义的二进制协议、MQTT 的变长报文、甚至 HTTP 的 chunked 编码解析。思路都是一样的：先缓存，再按协议规则找边界，边界完整了再处理。这个模式一旦掌握，TCP 流式协议解析就不再是难题。

后续如果要扩展，我觉得有几个方向值得做：一是把环形缓冲改成无锁的，用原子操作替代互斥锁，进一步降低多任务切换开销；二是加一个统计模块，记录分片率、粘包率、错误帧数，方便现场诊断；三是支持 ModbusTCP 和 ModbusRTU 的自动转换，做成一个通用的协议网关。

不过这些都是后话了。眼下这套实现已经在几个模拟项目里稳定跑了几个月，没再出现过数据错乱的问题。如果你也在被 TCP 分片折磨，不妨按这个思路试试，应该能少走不少弯路。