简介：这份资源面向STM32嵌入式开发学习者与以太网应用开发者，聚焦STM32F407平台下FreeRTOS与LwIP协议栈的整合实践。工程基于CubeMX生成原始框架，外接LAN8742A PHY芯片，通过添加任务线程完成网络协议栈移植，最终实现ping响应与TCP回响测试，适合已掌握STM32基础、希望进阶网络通信与实时操作系统的开发者参考。压缩包共674个文件，约46.13MB，以C源码与头文件为主体，包含HAL库驱动、LwIP协议栈源码、FreeRTOS内核文件，以及Keil工程配置、编译中间产物与说明文档，结构完整便于直接编译与二次开发。目前已有801人学习下载。读者可从中获取一套可运行的FreeRTOS+LwIP以太网工程模板，理解任务调度与网络数据收发的协同机制，掌握PHY驱动配置、协议栈裁剪及TCP回响调试思路，为后续物联网终端与工业以太网项目打下基础。
1. 从一块吃灰的 F407 板子说起：为什么我劝你先别急着烧 tcpecho
手头这块 STM32F407 开发板在抽屉里躺了小半年，网口、晶振、供电都齐，就是没跑起来过一个像样的网络例程。直到某天要做一个设备侧的数据上报 Demo，才不得不把 FreeRTOS 和 LwIP 这套组合重新捡起来。很多人第一次接触 STM32F407 + FreeRTOS + LwIP 的 tcpecho，都是被“跑通一个 TCP 回显服务器”这个目标吸引进来的——听起来简单，实际装环境的时候版本对不上、PHY 地址写错、堆栈给少了，板子要么 ping 不通，要么连上就死机。这套环境在工业网关、边缘采集盒、教学实验里出现频率极高，装不好就是一块只能点灯的板子。这篇笔记面向的是手里有 F407 类板子、想把 FreeRTOS 和 LwIP 真正跑起来的人，从选版本、配参数到验证回显，一步步走完。
2. 环境准备与版本选择：STM32F407 上 FreeRTOS 和 LwIP 怎么搭才不打架
2.1 先定芯片型号和网络外设，别拿 F103 的配置硬套
STM32F407 和 F103 最大的区别不只是主频，网络外设这块差得很远。F407 自带 10/100M 以太网 MAC，配合外部 PHY（常见的是 LAN8720 或 DP83848）走 RMII 接口。如果你手里是那种“核心板 + 底板”的组合，先确认底板上焊的是哪颗 PHY，因为 PHY 地址和复位引脚在代码里是要写死的。我一般会先翻原理图，把三个信息记下来：PHY 的 SMI 地址（LAN8720 通常是 0x00 或 0x01）、复位引脚接在哪个 GPIO、RMII 的 REF_CLK 是 PHY 提供还是 MCU 提供。这三项任何一项搞错，后面 LwIP 初始化都会卡在ethernetif_init里出不来。
常见做法是拿 ST 官方的STM32F4x7_ETH_LwIP例程或者 CubeMX 生成的工程做底子，但不要直接照搬 F107 的配置。F407 的 ETH 外设时钟来自 AHB1，而 F107 走的是 AHB，时钟使能位不一样。如果你用 CubeMX，在Connectivity -> ETH里选 RMII，然后到Clock Configuration里确认ETH_TX_CLK和ETH_RX_CLK都来自 50MHz 的 REF_CLK，否则 PHY 协商不出速率。
2.2 FreeRTOS 和 LwIP 的版本搭配，别追最新
FreeRTOS 和 LwIP 的版本兼容性是个老坑。LwIP 2.x 之后对sys_arch的接口做了一些调整，而 FreeRTOS 的FreeRTOSConfig.h里configTOTAL_HEAP_SIZE和 LwIP 的MEM_SIZE如果都开得很大，F407 的 192KB SRAM 根本不够分。我一般会选这套组合：
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| FreeRTOS Kernel | V10.4.6 | 稳定，CMSIS-RTOS v2 封装成熟 |
| LwIP | 2.1.3 | 对 STM32 以太网驱动适配好，bug 少 |
| STM32CubeF4 | V1.27.x | 里面带的 ETH 驱动和 LwIP 中间件版本匹配 |
| 工具链 | arm-none-eabi-gcc 10.3 | 或者 Keil MDK 5.36 |
不要用 LwIP 2.2.0 的 master 分支直接怼，那个版本对sys_mbox_t的实现改了，和 FreeRTOS 的xQueue对接时容易在sys_mbox_fetch里死等。FreeRTOS 这边，如果你用 CubeMX 生成，它会自动把 FreeRTOS 作为 CMSIS-RTOS v2 的 RTOS 塞进去，LwIP 的sys_arch.c会去调osMessageQueueNew这些 CMSIS 接口，所以 FreeRTOS 的FreeRTOSConfig.h里必须打开configSUPPORT_DYNAMIC_ALLOCATION和configUSE_COUNTING_SEMAPHORES。
2.3 工程目录怎么摆，头文件路径别漏
我习惯把 LwIP 的源码和 FreeRTOS 的源码放在工程根目录下的Middlewares文件夹里，和Drivers平级。CubeMX 生成的工程默认就是这个结构，但如果你手动移植，注意这几个路径必须加到编译器的 include 里：
# 假设工程根目录为 PROJECT_ROOT PROJECT_ROOT/Middlewares/Third_Party/LwIP/src/include PROJECT_ROOT/Middlewares/Third_Party/LwIP/src/include/lwip PROJECT_ROOT/Middlewares/Third_Party/LwIP/system PROJECT_ROOT/Middlewares/Third_Party/FreeRTOS/Source/include PROJECT_ROOT/Middlewares/Third_Party/FreeRTOS/Source/CMSIS_RTOS_V2 PROJECT_ROOT/Middlewares/Third_Party/FreeRTOS/Source/portable/GCC/ARM_CM4F漏掉system目录会报arch/cc.h找不到，漏掉CMSIS_RTOS_V2会报cmsis_os2.h找不到。GCC 下ARM_CM4F这个 port 目录必须对，F407 是 Cortex-M4 带 FPU，用ARM_CM3的 port 虽然能跑，但任务切换时浮点寄存器不会自动保存，遇到浮点运算就玄学了。
3. 从 CubeMX 到 Makefile：一步步把 FreeRTOS + LwIP 工程配出来
3.1 CubeMX 里勾选 ETH、FreeRTOS 和 LwIP 的顺序
打开 CubeMX 新建工程选 STM32F407ZGTx（或者你板子上的具体型号），然后按这个顺序操作：
System Core -> RCC：高速外部时钟选Crystal/Ceramic Resonator，F407 一般外挂 8MHz 晶振。Connectivity -> ETH：Mode 选RMII，然后到Parameter Settings里把PHY Address改成你原理图上的地址（LAN8720 通常是 0），Auto Negotiation勾上。Middleware -> FREERTOS：Interface 选CMSIS_V2，然后在Config parameters里把TOTAL_HEAP_SIZE改成 30720（30KB），MINIMAL_STACK_SIZE改成 256。Middleware -> LWIP：勾上Enabled，然后在General Settings里把LWIP_DHCP先关掉（调试阶段用静态 IP 更快），IP_ADDRESS设成192.168.1.100，NETMASK设成255.255.255.0，GATEWAY设成192.168.1.1。Clock Configuration：确认ETH_RX_CLK和ETH_TX_CLK都是 50MHz，HCLK跑到 168MHz。
生成代码的时候，Toolchain 选Makefile或者MDK-ARM，看你习惯。我一般用 Makefile，因为后面加自己的源文件方便。
3.2 改lwipopts.h：这几个参数不改，tcpecho 跑不起来
CubeMX 生成的lwipopts.h在Core/Inc目录下，里面有几个关键参数必须手动调：
// lwipopts.h 关键修改 #define MEM_SIZE (16 * 1024) // LwIP 堆大小，F407 给 16KB 够用 #define TCP_MSS 1460 // 以太网 MTU 1500 减去 IP/TCP 头 #define TCP_SND_BUF (4 * TCP_MSS) // 发送缓冲，太小会阻塞 #define TCP_WND (4 * TCP_MSS) // 接收窗口 #define PBUF_POOL_SIZE 16 // pbuf 池数量，网络流量大时加 #define LWIP_NETCONN 1 // 必须开，tcpecho 用 netconn API #define LWIP_SOCKET 0 // 不用 socket API 就关掉省空间 #define LWIP_STATS 0 // 调试完关掉，省 FlashMEM_SIZE和 FreeRTOS 的configTOTAL_HEAP_SIZE是两套独立的内存池，LwIP 自己管MEM_SIZE，FreeRTOS 管任务栈和队列。F407 的 192KB SRAM 里，MEM_SIZE给 16KB、FreeRTOS 堆给 30KB，剩下的给主栈和全局变量，刚好够。如果你把TCP_SND_BUF设成TCP_MSS的 2 倍以下，发大包时会频繁tcp_output失败，现象就是客户端收数据断断续续。
3.3 写 tcpecho 任务：用 netconn API 还是 raw API
LwIP 有三种编程接口：raw API（回调式，无 RTOS）、netconn API（阻塞式，需要 RTOS）、socket API（兼容 BSD，最占资源）。既然已经上了 FreeRTOS，用 netconn API 最顺手。在Core/Src下新建tcpecho.c：
// tcpecho.c #include "lwip/opt.h" #include "lwip/api.h" #include "cmsis_os.h" #define TCPECHO_PORT 7 void tcpecho_thread(void *arg) { struct netconn *conn, *newconn; err_t err; LWIP_UNUSED_ARG(arg); // 新建一个 TCP 连接结构 conn = netconn_new(NETCONN_TCP); if (conn == NULL) { printf("netconn_new failed\r\n"); return; } // 绑定到 7 端口 err = netconn_bind(conn, IP_ADDR_ANY, TCPECHO_PORT); if (err != ERR_OK) { printf("netconn_bind failed: %d\r\n", err); netconn_delete(conn); return; } // 进入监听状态 netconn_listen(conn); while (1) { // 阻塞等待客户端连接 err = netconn_accept(conn, &newconn); if (err == ERR_OK) { struct netbuf *buf; void *data; u16_t len; // 循环接收数据并原样发回 while ((err = netconn_recv(newconn, &buf)) == ERR_OK) { do { netbuf_data(buf, &data, &len); netconn_write(newconn, data, len, NETCONN_COPY); } while (netbuf_next(buf) >= 0); netbuf_delete(buf); } // 客户端断开，关掉这个连接 netconn_close(newconn); netconn_delete(newconn); } } }netconn_new(NETCONN_TCP)会从 LwIP 的MEM_SIZE里分配一个连接结构，如果MEM_SIZE太小，这里直接返回 NULL。netconn_bind的第二个参数用IP_ADDR_ANY表示监听所有本地地址。netconn_accept在没有客户端连接时会阻塞当前任务，所以这个任务必须跑在 FreeRTOS 里，不能裸机跑。netconn_write的最后一个参数NETCONN_COPY表示数据拷贝到 LwIP 内部缓冲再发，如果改成NETCONN_NOCOPY，调用者必须保证数据在发送完成前不被修改，新手用 COPY 更稳。
然后在main.c里创建任务：
// main.c 片段 osThreadAttr_t tcpecho_attr = { .name = "tcpecho", .stack_size = 1024, // 1KB 栈，netconn API 调用层次深，别给 512 .priority = osPriorityNormal, }; osThreadNew(tcpecho_thread, NULL, &tcpecho_attr);栈大小给 1024 字（4KB）比较保险，因为netconn_recv内部会调sys_arch_mbox_fetch，再往下还有tcpip_thread的通信，栈不够就会进 HardFault。
4. 避坑与排查：tcpecho 跑不通时先查这五个地方
4.1 ping 不通，但网口灯是亮的
现象：板子上电后网口 Link 灯亮，但 PC 上ping 192.168.1.100超时。 原因：PHY 地址写错，或者 RMII 的 REF_CLK 没配对。LAN8720 的地址由 PHYAD0 引脚决定，如果原理图上该引脚接地，地址就是 0，但 CubeMX 默认给的是 1。 解决：在ethernetif.c的low_level_init里找到heth.Init.PhyAddress，改成原理图上的实际值。改完重新编译烧录，用ping再试。如果还不通，拿示波器量 REF_CLK 引脚，正常应该是 50MHz 方波。
4.2 能 ping 通，但 tcpecho 连上就断
现象：PC 上telnet 192.168.1.100 7能建立连接，但发一个字符就断开。 原因：TCP_SND_BUF或PBUF_POOL_SIZE太小，netconn_write返回ERR_MEM，任务里没处理这个错误就直接退出了接收循环。 解决：把lwipopts.h里的TCP_SND_BUF改成(8 * TCP_MSS)，PBUF_POOL_SIZE改成 32。然后在netconn_write后面加错误判断：
err = netconn_write(newconn, data, len, NETCONN_COPY); if (err != ERR_OK) { printf("write err: %d\r\n", err); break; // 跳出接收循环，关连接 }4.3 跑几分钟后死机，串口打印 HardFault
现象：tcpecho 正常回显一段时间后，板子突然不响应，调试器显示进了 HardFault_Handler。 原因：FreeRTOS 堆不够，osThreadNew返回 NULL 但没检查，或者 LwIP 的tcpip_thread栈溢出。 解决：把FreeRTOSConfig.h里的configCHECK_FOR_STACK_OVERFLOW设为 2，并实现vApplicationStackOverflowHook，在里面打印出事的任务名。同时把configTOTAL_HEAP_SIZE从 30720 加到 40960，重新编译看xPortGetFreeHeapSize()的返回值，如果小于 4096 就继续加。
4.4 DHCP 拿不到 IP，静态 IP 却正常
现象：打开LWIP_DHCP后，串口一直打印dhcp state: SELECTING，拿不到地址。 原因：路由器没开 DHCP，或者网线接的是交换机的 uplink 口但没连到 DHCP 服务器。 解决：调试阶段先用静态 IP，等 tcpecho 跑通了再开 DHCP。开 DHCP 时注意lwipopts.h里LWIP_DHCP和LWIP_AUTOIP不要同时开，会冲突。另外dhcp_start要在netif添加之后调用，顺序错了也会卡在 SELECTING。
4.5 编译报sys_mbox_t未定义
现象：GCC 编译时sys_arch.c报unknown type name 'sys_mbox_t'。 原因：sys_arch.h里用了 FreeRTOS 的QueueHandle_t，但没包含FreeRTOS.h和queue.h。 解决：在sys_arch.h开头加：
#include "FreeRTOS.h" #include "queue.h" #include "semphr.h"如果用的是 CMSIS-RTOS v2 封装，还要加#include "cmsis_os2.h"。这个坑在手动移植 LwIP 时几乎必踩，CubeMX 生成的工程会自动处理好，但自己拼工程就容易漏。
5. 装完怎么验证：用 iperf 和 telnet 把 tcpecho 压到极限
5.1 先用 telnet 做基本回显验证
板子烧录后，串口应该打印出 IP 地址，比如192.168.1.100。PC 上打开终端：
telnet 192.168.1.100 7连上后随便敲几个字符，如果终端原样显示你敲的内容，说明 tcpecho 的基本收发通了。注意 telnet 默认是行缓冲，你敲完一行按回车才会发出去，所以看到的是整行回显。如果想测单字符回显，用nc：
echo "hello" | nc 192.168.1.100 7正常应该输出hello。如果nc卡住不返回，检查板子上的netconn_write是不是没加NETCONN_COPY，或者TCP_SND_BUF太小导致数据发不出去。
5.2 用 iperf 测吞吐，看 LwIP 配置有没有瓶颈
telnet 只能验证功能，吞吐得用 iperf。PC 上装 iperf2（注意不是 iperf3，LwIP 的 tcpecho 不支持 iperf3 的协议）：
iperf -c 192.168.1.100 -p 7 -t 10 -i 1因为 tcpecho 只是回显，不是标准的 iperf 服务端，所以 iperf 会把它当成一个普通的 TCP 连接，测出来的其实是“发出去再收回来”的往返吞吐。F407 跑 LwIP 2.1.3，TCP_SND_BUF给 4 个 MSS 时，单向吞吐大概在 8~12 Mbps；如果把TCP_SND_BUF和TCP_WND都加到 8 个 MSS，PBUF_POOL_SIZE加到 32，能跑到 20 Mbps 左右。再往上就受限于 F407 的 ETH 外设和内存带宽了。
验证的时候注意看串口有没有打印write err，如果有，说明ERR_MEM出现了，得继续加缓冲。另外 iperf 跑的时候 PC 的防火墙可能拦，先临时关掉防火墙再测。
5.3 长时间跑稳定性，看 FreeRTOS 剩余堆
功能验证完，别急着收工。让板子连续跑 30 分钟 tcpecho，期间用 PC 反复连接断开，然后通过串口打印xPortGetFreeHeapSize()和mem_get_free()（LwIP 的堆剩余）。我一般会在main.c里加一个低优先级任务，每 10 秒打印一次：
void monitor_thread(void *arg) { while (1) { printf("FreeRTOS heap free: %u\r\n", xPortGetFreeHeapSize()); printf("LwIP mem free: %u\r\n", mem_get_free()); osDelay(10000); } }如果FreeRTOS heap free持续下降不回升，说明有任务创建后没删除，或者netconn连接断开后没netconn_delete。如果LwIP mem free下降，检查netbuf_delete有没有漏调。我踩过一次坑：netconn_recv返回ERR_OK后，如果netbuf_data拿到的数据长度是 0，直接netbuf_delete就完了，但我在代码里写成了continue，导致 buf 没释放，跑十几分钟 LwIP 堆就耗尽了。
从那以后我每次移植完 LwIP，都强制让板子跑一晚上 tcpecho，第二天早上看串口打印的剩余堆有没有归零。这个习惯帮我提前发现了三次内存泄漏，省得在现场调试时抓瞎。希望帮到你。
本文还有配套的精品资源，点击获取
