STM32F407 FreeRTOS+LwIP以太网通信实战：从tcpecho到自定义协议-育师

简介：这份资源面向STM32嵌入式开发学习者与工程师，聚焦STM32F407平台下FreeRTOS与LwIP协议栈的联合移植与调试。工程基于CubeMX生成原始框架，外接LAN8742A PHY模块，在FreeRTOS多线程环境下完成LwIP网络协议栈的适配，最终实现ping响应与TCP回响（tcpecho）测试，适合想掌握RTOS下以太网通信、TCP/IP协议栈移植与线程调度的中高级开发者参考。压缩包共674个文件，约46.13MB，以C源码与头文件为主体，包含HAL库驱动、LwIP协议栈源码、FreeRTOS内核文件，以及Keil工程文件、编译中间产物、map映射文件、hex固件与ioc配置等，完整保留了从工程配置到编译输出的全过程。目前已有801人学习下载。读者可从中获得可直接编译运行的完整工程，理解PHY驱动、ETH外设初始化、LwIP网卡接口对接及TCP回响线程的编写思路，并借助map与hex文件对照验证运行结果，快速搭建自己的网络通信实验环境。

1. 拿到一份 STM32F407 的 FreeRTOS+LwIP 工程，先别急着点编译

有个做工业网关的朋友跟我吐槽，说他手上这份 STM32F407 的 FreeRTOS+LwIP 工程，编译能过、下载能跑，但网口插上网线后 ping 不通，tcpecho 也连不上，折腾两天没找到入口。我拿过来一看，问题不在代码，而在他没搞清楚这套东西的分层关系——FreeRTOS 管任务调度，LwIP 管 TCP/IP 协议栈，STM32F407 的 ETH 外设管物理收发，三者靠一个叫ethernetif的网卡驱动层粘在一起。这份工程的价值就在这儿：它把裸机 LwIP 移植里最烦人的几个环节——PHY 初始化、DMA 描述符、sys_arch信号量和邮箱对接——都替你搭好了，还带一个 tcpecho 示例，能直接验证 TCP 收发链路是否打通。适合谁？适合正在做以太网通信、想从裸机 LwIP 过渡到 RTOS 多任务架构的嵌入式开发者，也适合拿它当 FreeRTOS 任务划分和 LwIP 回调机制的参考模板。

2. 工程架构拆解：从 main 到网卡驱动的四层链路

2.1 目录结构与各层职责

拿到工程先别翻代码，先看目录。这类 STM32F407 + FreeRTOS + LwIP 的工程，目录一般长这样：

project/ ├── Core/ │ ├── Inc/ │ │ ├── main.h │ │ ├── FreeRTOSConfig.h // FreeRTOS 裁剪配置 │ │ ├── lwipopts.h // LwIP 裁剪配置 │ │ └── stm32f4xx_hal_conf.h // HAL 外设开关 │ └── Src/ │ ├── main.c // 入口，创建任务 │ ├── freertos.c // 任务定义与创建 │ ├── ethernetif.c // 网卡驱动，LwIP 与 ETH 的桥 │ └── stm32f4xx_hal_msp.c // 外设底层初始化 ├── Drivers/ │ ├── STM32F4xx_HAL_Driver/ // HAL 库 │ └── CMSIS/ // 内核头文件 ├── Middlewares/ │ ├── Third_Party/FreeRTOS/ // FreeRTOS 源码 │ └── Third_Party/LwIP/ // LwIP 源码 └── LWIP/ ├── Target/ │ └── ethernetif.c // 部分工程放这里 └── App/ └── lwip.c // LwIP 初始化与任务

四层职责要分清：应用层是 tcpecho，跑在独立任务里；协议栈层是 LwIP，负责 TCP/IP 状态机；RTOS 层是 FreeRTOS，给 LwIP 提供信号量和邮箱；驱动层是ethernetif.c，负责把 ETH DMA 收到的帧交给 LwIP，把 LwIP 要发的帧塞进 DMA。很多人调不通，就是没分清哪层出问题。

2.2 FreeRTOS 任务划分与优先级

打开freertos.c，核心是任务创建。典型划分是三个任务：

/* freertos.c 任务创建片段 */ osThreadId_t defaultTaskHandle; osThreadId_t tcpEchoTaskHandle; osThreadId_t lwipTaskHandle; const osThreadAttr_t defaultTask_attributes = { .name = "defaultTask", .stack_size = 512 * 4, .priority = (osPriority_t) osPriorityNormal, }; const osThreadAttr_t tcpEchoTask_attributes = { .name = "tcpEchoTask", .stack_size = 1024 * 4, .priority = (osPriority_t) osPriorityNormal, }; const osThreadAttr_t lwipTask_attributes = { .name = "lwipTask", .stack_size = 1024 * 4, .priority = (osPriority_t) osPriorityHigh, }; void MX_FREERTOS_Init(void) { defaultTaskHandle = osThreadNew(StartDefaultTask, NULL, &defaultTask_attributes); tcpEchoTaskHandle = osThreadNew(TcpEchoTask, NULL, &tcpEchoTask_attributes); lwipTaskHandle = osThreadNew(LwipTask, NULL, &lwipTask_attributes); }

逻辑说明：lwipTask优先级给osPriorityHigh，因为它要周期性调用MX_LWIP_Process()处理网卡收发，优先级低了会被其他任务饿死，导致 ping 丢包。tcpEchoTask优先级 Normal 即可，它只负责建连和收发数据。栈大小别抠，LwIP 里tcp_write、pbuf分配都吃栈，1024 字（4KB）是常见起步值。

参数说明：stack_size单位是字节，不是字，1024 * 4就是 4KB。priority用 CMSIS-RTOS2 的枚举，数值越大优先级越高。改任务优先级时注意：LwIP 的tcpip_thread如果被映射成独立任务，它的优先级必须高于应用任务，否则 TCP 握手会超时。

2.3 LwIP 初始化与 tcpip_thread 对接

LwIP 在 RTOS 模式下有两种跑法：一是NO_SYS=0且用tcpip_thread，二是把MX_LWIP_Process()塞进自己的任务轮询。这份工程用的是后者，简单直接：

/* lwip.c 初始化片段 */ void MX_LWIP_Init(void) { lwip_init(); // 协议栈初始化 netif_add(&gnetif, &ipaddr, &netmask, &gw, NULL, &ethernetif_init, &tcpip_input); netif_set_default(&gnetif); if (netif_is_link_up(&gnetif)) { netif_set_up(&gnetif); } else { netif_set_down(&gnetif); } } void LwipTask(void *argument) { MX_LWIP_Init(); for (;;) { MX_LWIP_Process(); // 处理网卡收发 osDelay(1); // 让出 CPU } }

逻辑说明：netif_add把网卡注册进 LwIP，ethernetif_init是驱动层入口，tcpip_input是收到帧后的回调。MX_LWIP_Process()内部会调ethernetif_input，把 DMA 里的帧取出来喂给 LwIP。osDelay(1)不能省，否则这个任务会独占 CPU，其他任务跑不起来。

参数说明：ipaddr、netmask、gw是ip4_addr_t类型，用IP4_ADDR(&ipaddr, 192, 168, 1, 100)赋值。改 IP 就改这三个。netif_set_up和netif_set_down要根据 PHY 链路状态调用，链路没起来就set_up，LwIP 会一直发 ARP 但发不出去。

2.4 ethernetif.c 网卡驱动关键点

这是最容易翻车的地方。ethernetif.c要干三件事：初始化 ETH 和 PHY、实现low_level_output发送、实现low_level_input接收。

/* ethernetif.c 发送片段 */ static err_t low_level_output(struct netif *netif, struct pbuf *p) { struct pbuf *q; uint8_t *buffer = (uint8_t *)(ETH_TX_DESC[tx_idx].Buffer1); uint32_t framelen = 0; for (q = p; q != NULL; q = q->next) { memcpy(buffer + framelen, q->payload, q->len); framelen += q->len; } if (framelen < 60) { // 以太网最小帧 60 字节 memset(buffer + framelen, 0, 60 - framelen); framelen = 60; } ETH_TX_DESC[tx_idx].ControlBufferSize = framelen; ETH->DMASR |= ETH_DMASR_TBUS; // 触发发送 tx_idx = (tx_idx + 1) % ETH_TXBUFNB; return ERR_OK; }

逻辑说明：LwIP 的pbuf是链式的，一个帧可能拆成多个pbuf，所以要遍历q->next拼成完整帧。拼完后检查最小帧长，不够 60 字节要补零，否则 PHY 会丢帧。最后置DMASR_TBUS触发 DMA 发送。

参数说明：ETH_TXBUFNB是发送缓冲区个数，常见 4 或 8。tx_idx是当前发送描述符索引，发完要循环回绕。ETH_TX_DESC是 DMA 描述符数组，每个描述符的Buffer1指向数据缓冲区。

接收侧类似，low_level_input从ETH_RX_DESC取帧，用pbuf_alloc分配pbuf，再pbuf_take拷贝数据，最后返回给ethernetif_input。

3. 跑通 tcpecho：从编译到验证的完整步骤

3.1 编译前必须检查的三个配置

别急着点编译，先查三个文件，这三个地方错一个就跑不通。

第一，FreeRTOSConfig.h里的堆大小。configTOTAL_HEAP_SIZE至少给 30KB，LwIP 的pbuf池和任务栈都从这里出。给 16KB 大概率在tcp_new时返回 NULL。

第二，lwipopts.h里的MEM_SIZE和PBUF_POOL_SIZE。MEM_SIZE给 16KB 以上，PBUF_POOL_SIZE给 16 个以上。tcpecho 回显数据时，如果PBUF_POOL_SIZE太小，pbuf_alloc失败，数据就丢了。

第三，stm32f4xx_hal_conf.h里的HAL_ETH_MODULE_ENABLED。这个宏没开，ETH 初始化直接跳过，网口灯都不亮。

/* lwipopts.h 关键配置 */ #define MEM_SIZE (16 * 1024) #define PBUF_POOL_SIZE 16 #define PBUF_POOL_BUFSIZE 1524 #define TCP_MSS 1460 #define TCP_SND_BUF (4 * TCP_MSS) #define TCP_WND (4 * TCP_MSS)

逻辑说明：TCP_MSS是最大报文段，以太网 MTU 1500 减去 IP 头 20 和 TCP 头 20，得 1460。TCP_SND_BUF和TCP_WND给 4 倍 MSS，保证发送窗口够用。PBUF_POOL_BUFSIZE给 1524，能装下一个完整以太网帧。

3.2 tcpecho 服务端代码逐段讲

tcpecho 的逻辑很简单：监听一个端口，收到连接后把收到的数据原样发回去。但 LwIP 的 API 是回调式的，得按它的套路写。

/* tcpecho.c 核心片段 */ static err_t echo_recv(void *arg, struct tcp_pcb *tpcb, struct pbuf *p, err_t err) { if (p == NULL) { // 对端关闭连接 tcp_close(tpcb); return ERR_OK; } tcp_recved(tpcb, p->tot_len); // 通知协议栈已收数据 tcp_write(tpcb, p->payload, p->tot_len, TCP_WRITE_FLAG_COPY); tcp_output(tpcb); // 立即发送 pbuf_free(p); // 释放 pbuf return ERR_OK; } static err_t echo_accept(void *arg, struct tcp_pcb *newpcb, err_t err) { tcp_recv(newpcb, echo_recv); // 注册接收回调 return ERR_OK; } void TcpEchoTask(void *argument) { struct tcp_pcb *pcb = tcp_new(); tcp_bind(pcb, IP_ADDR_ANY, 7); // 监听 7 端口 pcb = tcp_listen(pcb); tcp_accept(pcb, echo_accept); // 注册连接回调 for (;;) { osDelay(100); } }

逻辑说明：tcp_recv注册接收回调，有数据来就调echo_recv。tcp_recved必须调，告诉协议栈窗口可以往前推，不调的话对端发几次就不发了。tcp_write的TCP_WRITE_FLAG_COPY表示拷贝数据，这样pbuf_free后数据还在发送队列里。tcp_output触发立即发送，不调的话要等协议栈自己攒够再发。

参数说明：tcp_bind的端口号 7 是 echo 协议标准端口，改成别的也行，客户端要对应。IP_ADDR_ANY表示监听所有网卡地址。tcp_listen返回新的pcb，原来的pcb被释放，别搞混。

3.3 用网络调试工具验证收发

代码跑起来后，用网络调试工具（比如常见的 TCP 调试助手）验证。步骤：

板子上电，网线接路由器或直连电脑，串口打印 IP 地址。
电脑和板子在同一网段，先ping板子 IP，通的话说明 ARP 和 ICMP 链路 OK。
打开 TCP 客户端工具，目标 IP 填板子 IP，端口填 7，点连接。
连接成功后发一段字符串，比如hello，看是否原样返回。

如果 ping 通但 TCP 连不上，先查tcp_listen的端口对不对，再查echo_accept有没有被调用。如果连上但发数据没回显，查echo_recv里的tcp_recved和tcp_output有没有漏。

提示：ping 通只说明 IP 层和 ICMP 层 OK，不代表 TCP 层 OK。TCP 连不上优先查tcp_listen和tcp_accept的注册顺序。

4. 避坑与排查：五个让工程跑不起来的常见问题

4.1 ping 不通，网口灯不亮

现象：板子上电后网口灯不亮，ping 板子 IP 无响应。

原因：PHY 初始化失败，或者 ETH 的 RMII/MII 时钟没配。STM32F407 的 ETH 需要 25MHz 或 50MHz 参考时钟，如果外部晶振没起振，PHY 不工作。

解决：查HAL_ETH_MspInit里的 GPIO 和时钟配置，确认ETH_RMII_REF_CLK引脚有信号。用示波器量 PHY 的晶振引脚，没波形就换晶振或查负载电容。

4.2 ping 通但丢包严重

现象：ping 能通，但丢包率 30% 以上，或者时通时不通。

原因：lwipTask优先级太低，被其他任务抢占，MX_LWIP_Process()调用不及时，DMA 接收缓冲区溢出。

解决：把lwipTask优先级提到osPriorityHigh，或者把MX_LWIP_Process()放到SysTick中断里调用（注意中断里不能调osDelay）。另外查ETH_RXBUFNB和ETH_TXBUFNB，给 4 以上。

4.3 tcp_write 返回 ERR_MEM

现象：tcp_write返回ERR_MEM，数据发不出去。

原因：TCP_SND_BUF太小，或者PBUF_POOL_SIZE不够，发送队列满了。

解决：把TCP_SND_BUF调到8 * TCP_MSS，PBUF_POOL_SIZE调到 32。如果还不行，查MEM_SIZE是不是被其他模块吃光了，用mem_trim或增大堆。

4.4 连接建立后立刻断开

现象：TCP 客户端显示连接成功，但马上断开。

原因：echo_accept里没注册tcp_recv，或者echo_recv里p == NULL时没调tcp_close，协议栈状态机卡死。

解决：确认tcp_recv(newpcb, echo_recv)被调用。p == NULL表示对端关闭，必须调tcp_close释放pcb，否则pcb泄漏，后续连接建不起来。

4.5 改 IP 后 ping 不通

现象：改了IP4_ADDR里的 IP，编译下载后 ping 不通。

原因：netif_set_up在链路没起来时被调用，或者 IP 和网关不在同一网段。

解决：确认 IP、掩码、网关三者匹配。比如 IP 是192.168.1.100，掩码255.255.255.0，网关192.168.1.1。如果直连电脑，网关可以设成电脑 IP 或留空。另外netif_set_up要在netif_is_link_up返回真之后调。

注意：改lwipopts.h后必须全量重编译，LwIP 很多配置是编译期宏，增量编译可能不生效。

5. 二次开发：从 tcpecho 到自定义协议服务的改造思路

tcpecho 只是个验证 Demo，真正做项目要改成自定义协议。改造分三步：换协议解析、加任务间通信、做连接管理。

第一步，把echo_recv里的回显逻辑换成协议解析。比如自定义一个「长度 + 命令字 + 数据」的帧格式：

/* 自定义协议解析片段 */ typedef struct { uint16_t len; uint8_t cmd; uint8_t data[256]; } my_proto_t; static err_t proto_recv(void *arg, struct tcp_pcb *tpcb, struct pbuf *p, err_t err) { if (p == NULL) { tcp_close(tpcb); return ERR_OK; } tcp_recved(tpcb, p->tot_len); /* 把 pbuf 数据拷到环形缓冲区，交给解析任务 */ ringbuf_write(&g_rx_ring, p->payload, p->tot_len); osSemaphoreRelease(g_rx_sem); // 唤醒解析任务 pbuf_free(p); return ERR_OK; }

逻辑说明：接收回调里不做解析，只把数据塞进环形缓冲区，然后释放信号量唤醒解析任务。这样接收回调执行时间短，不会阻塞协议栈。解析任务在独立任务里跑，慢慢解析、慢慢处理。

参数说明：ringbuf_write是自定义的环形缓冲区写入函数，要保证线程安全，可以用关中断或互斥量保护。g_rx_sem是二值信号量，解析任务osSemaphoreAcquire等它。

第二步，加任务间通信。解析任务解析出命令后，可能要控制 GPIO、读 ADC、发串口，这些操作通过消息队列发给对应的任务：

/* 消息队列发送片段 */ typedef struct { uint8_t cmd; uint8_t data[64]; } msg_t; msg_t msg = { .cmd = parsed_cmd }; osMessageQueuePut(g_cmd_queue, &msg, 0, osWaitForever);

第三步，做连接管理。tcpecho 只支持一个连接，实际项目要支持多连接。用tcp_accept回调里维护一个连接链表，每个连接分配独立的接收缓冲区和状态机。连接断开时从链表摘除，释放资源。

改造完怎么验证？我的习惯是分三层测：先用 ping 测链路，再用 TCP 调试工具测协议解析，最后用压力测试工具发大量数据测稳定性。压力测试时重点看pbuf有没有泄漏——跑一小时，看memr里的PBUF_POOL剩余数是不是稳定，一直降就是泄漏。

从那以后我每次改 LwIP 相关代码，都强制走一遍「ping → 单连接 → 多连接 → 压力测试」四步，少一步都可能在上线后翻车。希望帮到你。

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