简介这是一份基于STM32CubeMX构建的STM32H750LAN8720以太网完整工程面向使用FreeRTOS与lwIP协议栈做TCP socket开发的工程师。工程已成功实现掉线自动重连与KeepAlive保活机制适合正在调试网络通信、或基础移植后始终无法稳定维持连接的场景可对照工程快速定位配置问题。压缩包为RAR格式大小约2.21MB共403个文件以250个.h头文件和137个.c源文件为主覆盖HAL驱动、lwIP协议栈、FreeRTOS任务调度及socket接口另有.ioc、json、cfg、ld、makefile等工程文件便于导入CubeMX重新生成或命令行编译。目前已有5100人学习下载。工程核心价值在于提供一套可直接对照验证的掉线重连与KeepAlive组合配置并清晰展示任务、socket、网卡中断的协同方式帮助理顺TCP长连接生命周期读者可调整参数或直接抽取相关模块集成到自研项目中显著减少底层排错与方案验证时间。 搞过一阵子嵌入式网络通信的朋友应该都有体会以太网这东西硬件只要十几块钱的PHY芯片一焊理论上就能让板子联网但真正把协议栈跑稳、跑不丢包、断开还能自己抢回来才是最磨人的地方。这次要聊的这个工程正好就是一套完整的参考实现基于CubeMX生成的STM32H750工程外接LAN8720做以太网PHY内部跑FreeRTOS和lwip并且把掉线检测、重连、TCP KeepAlive这套机制全部移植好了。如果你正准备用H7系列做联网产品或者刚用CubeMX点开过lwip但面对一堆配置一脸懵这份工程值得好好拆一拆。1. 工程是什么硬件平台与整体架构拆解1.1 为什么是STM32H750LAN8720这套组合STM32H750这颗料很有意思它是H7里定位比较特殊的一个型号。内核是Cortex-M7跑满能到480MHz这个性能对跑lwip FreeRTOS来说可以说是“杀鸡用牛刀”协议栈开销根本不需要担心。真正的槽点在于它的内部Flash只有128KB代码稍大一点就得考虑外部存储。但反过来想正因为主频高、外设全、Flash小它反而成了很多网络产品做“小系统协议处理”的首选尤其适合把网络协议栈这层活全包下来。LAN8720则是这颗MCU的好搭档。它是Microchip原SMSC出的低功耗10/100M以太网PHYRMII接口3.3V供电引脚少价格便宜在很多开发板上都能看到它的身影。和MCU之间就7根信号线板级设计很省事。H750内部自带了MAC控制器所以MCU负责跑MAC层和上层协议LAN8720负责物理层的编码、协商、收发两个芯片各干各的活配合起来正好是一套标准“MACPHY”架构。这套组合在国内开发圈出镜率极高网上能找到的参考工程、原理图、调试笔记都很多遇到问题也容易搜到答案对入门和量产来说都是比较稳妥的选择。1.2 FreeRTOS与lwip各自承担什么很多新手容易把FreeRTOS和lwip混在一起理解其实它们完全是两个层面的东西。FreeRTOS是操作系统干的任务是任务调度、信号量、消息队列、内存管理它让单片机有了“同时做几件事”的能力。lwip是网络协议栈负责把TCP/IP的IPv4、UDP、TCP、ICMP这些协议跑起来它只关心“数据包怎么封装、怎么路由、怎么应答”不关心跑在什么样的OS上。这两个东西组合起来标准的做法是让lwip跑在FreeRTOS之上。具体来说lwip里有一个“操作系统的抽象层”sys_archCubeMX生成代码时会自动对接到FreeRTOS的线程和消息邮箱机制上。这样lwip本身在网络收发的中断里只做最简单的数据搬运复杂的TCP状态机、重传、分片等逻辑全部交给一个专用的tcpip_thread线程去处理不会因为网络数据量大而把MCU的中断处理时间拖死。所以这个工程里用户应用任务和lwip协议栈任务是分离的。用户的业务逻辑只管调socket或者netconn接口协议栈内部怎么分包重传应用层根本不用管丢包重发这些事情由lwip替我们扛。1.3 移植工程的目录结构与产出这个工程的价值在于“开箱即用”它把CubeMX生成的工程往下推进了很多不仅仅是跑通ping而是面对真实网络环境时能保持连接不崩溃。工程内主要包含这几块内容CubeMX生成的初始化代码时钟、ETH、FreeRTOS、lwip基础配置应用层网络任务负责主动连接远端服务器链路检测逻辑周期性查询PHY状态感知网线断开和恢复TCP KeepAlive配置让长时间没有数据交互的连接能自动发现对端是否“假死”重连状态机当链路断开、对端异常或连接失败时自动进入重连流程。也就是说这套工程拿去做参考你看完之后不仅能会配CubeMX还能把“连接断了怎么自动恢复”这个问题彻底解决掉。2. CubeMX配置实操四个关键环节2.1 时钟树配置LAN8720的50MHz REF_CLK从哪来很多人在CubeMX里第一步就翻车往往不是ETH没配好而是时钟树上根本没有给以太网留出正确的时钟来源。先说结论RMII接口的PHY必须要一个50MHz的参考时钟。这个时钟可以由两条路径产生第一种PHY自己产生。原理是在LAN8720的XI和XO引脚之间接一个25MHz的晶振PHY内部有PLL会把这个25MHz倍频到50MHz然后从REF_CLK引脚输出给STM32。这是开发板最常见的做法CubeMX里ETH的RMII配置中选择“REF_CLK由PHY提供”即可。第二种主控产生。如果LAN8720的外部晶振电路省掉了可以直接用STM32的MCO引脚输出50MHz给PHY的REF_CLK。这个工程在CubeMX里的标准做法是第一种外接25MHz晶振PHY把50MHz时钟源送回给MCU。注意CubeMX中ETH配置的那个“User PHY”选项卡里需要把PHY的地址和时钟源方向配置正确否则后面驱动初始化PHY时会一直读不到正确的芯片ID。提示如果你用的是自己的板子先翻原理图确认REF_CLK的方向。方向搞反了PHY寄存器读不出来ping也永远不通这是新手最容易忽视的问题。2.2 ETH外设与RMII引脚对照原理图逐个核对在CubeMX里勾选ETH外设之后Pinout视图会出现一套默认的RMII引脚配置。H750VBT6这类的封装下标准的RMII引脚映射是下面这张表信号引脚ETH_RMII_TXD0PB12ETH_RMII_TXD1PB13ETH_RMII_TX_ENPB11ETH_RMII_RXD0PC4ETH_RMII_RXD1PC5ETH_RMII_CRS_DVPD8ETH_RMII_REF_CLKPA1ETH_RESET自定义GPIO一般接PC3或任意空闲引脚这里要特别提醒几个点。第一RMII接口没有单独的RX_CLK它把接收时钟和载波侦听合到一根CRS_DV线上所以引脚映射要是错了数据收发就直接废掉。第二REF_CLK这个引脚在H7上是PA1如果原理图上LAN8720的50MHz输出没有接到PA1那就得改CubeMX里的Alternate功能或者直接改硬件。第三LAN8720的复位脚不能悬空复位时序也很讲究CubeMX里虽然不会自动给PHY复位但工程初始化代码里专门做了拉低-延时-拉高的复位动作这块在移植的时候一定不能省。另外LAN8720那个PHYAD0引脚的上下拉决定了PHY的I2C/MDIO访问地址。绝大多数模块出厂时把PHY地址配置为0如果在CubeMX或者驱动代码里填的是1那MDIO通信会一直失败。这个等到后面章节再展开讲排查方法。2.3 FreeRTOS参数任务栈与堆的分配CubeMX里启用FreeRTOS之后系统会自动创建一些内部任务比如定时器任务、空闲任务。我们自己的网络业务任务也需要在这里定义网络任务主要做三件事初始化网络连接、周期检测链路状态、在断开后触发重连。这个任务不能给它太小的栈。lwip的socket接口里面有一些局部缓冲区如果栈深度不够很容易在调用send/recv时触发栈溢出。工程里网络任务栈大小我建议配置到1024 words也就是4KB字节起步如果后续业务里还要处理JSON解析、加解密等再往上加。同时注意FreeRTOS的堆大小configTOTAL_HEAP_SIZECubeMX默认可能只给了4096或者8192字节这个数值在跑lwip时通常不够。因为lwip内部也会从FreeRTOS的heap里分配内存给PBUF、PCB等数据结构尤其是开启了DHCP、TCP连接较多的情况下堆太小会直接导致协议栈初始化失败或者运行一段时间后随机死机。这套工程里建议堆至少给到4万字节以上网络任务栈维持1024 words同时留出一定余量。2.4 lwip参数协议栈内存与KeepAlive开关CubeMX在Middleware里选中lwip后可以配置协议栈的全局参数。这里面有几个关键点直接影响内存占用和可用性MEM_SIZE堆的大小默认给的1600字节偏小建议调到几万字节地址空间便宜但MCU的RAM要撑得住。H750有512KB以上的RAM这部分绰绰有余。MEMP_NUM_PBUF和MEMP_NUM_TCP_SEG控制PBUF和TCP分段缓冲区的数量任务并发量大时尽量给大。TCP_MSS默认1460一次TCP报文携带的最大数据长度结合网口MTU 1500来理解不需要改。TCP_WND接收窗口默认应该够用太小会限制传输速度。LWIP_TCP_KEEPALIVE这个宏必须开启不开的话即使代码里设置了SO_KEEPALIVElwip也不会真正定时发送探测包。TCP_KEEPIDLE_DEFAULT、TCP_KEEPINTVL_DEFAULT、TCP_KEEPCNT_DEFAULT这三个参数控制KeepAlive探测的具体行为等下单独讲。CubeMX图形界面上能改的KeepAlive参数不一定全很多关键宏要手动去lwipopts.h里改。工程里特意把需要改的宏都标注了注释方便查阅。3. lwip与FreeRTOS协同运行的关键细节3.1 结合模式选择NO_SYS0跑在tcpip线程上lwip有两种运行模式裸机模式和OS模式。裸机模式NO_SYS1下协议栈不依赖操作系统需要在主循环里不断轮询调用lwip的service函数所有网络逻辑都串行执行适合简单场景。而这个工程采用的是NO_SYS0模式即lwip跑在FreeRTOS的多任务环境下。NO_SYS0模式会额外创建两个核心线程。第一个是tcpip_thread它是协议栈的主线程负责TCP/IP协议处理、数据包上抛、ARP处理等耗时操作第二个是eth_rx_thread负责从以太网DMA接收描述符里把收到的数据包取出来封装成PBUF后投递给tcpip_thread。这两个线程的优先级很关键tcpip_thread应该比普通应用任务优先级高一些否则高优先级应用任务持续占用CPU时协议栈时钟和处理会被饿死。CubeMX生成的ETH中断回调里实际只会发送一个信号量唤醒eth_rx_thread避免在中断上下文里做大量工作。这种设计是lwip在RTOS环境下的标准做法好处是中断响应快不会因为网络流量大导致中断延迟超高。3.2 数据收发链路从MAC中断到应用socket整个数据路径可以这么理解网线收到数据帧以后LAN8720通过RMII接口把数据传进STM32内部的MACMAC的DMA控制器自动把数据搬进指定的内存缓冲区DMA描述符然后触发ETH中断。中断服务函数里判断一下是不是接收事件如果是就把一个信号量交给eth_rx_thread。eth_rx_thread被唤醒之后从DMA接收描述符中取出数据将数据头封装成lwip的PBUF结构然后发送到tcpip_thread的mbox中。tcpip_thread从mbox里取到数据包根据以太网类型做判断如果是ARP就进入ARP模块处理如果是IPv4就进入IP层再由协议类型分发到TCP或UDP模块。最终应用层通过recv()调用拿到数据。发送链路则相反应用层调用send()把数据放进lwip的内核缓冲由tcpip_thread根据流控算法决定是否立即发送需要发的时候把数据交给MAC的DMA发送描述符MAC自动把数据帧发到PHY最终送上网线。这套链路里最需要注意的就是DMA描述符内存的对齐问题。lwip的PBUF分配和DMA描述符如果不对齐在高优化级别下容易出现数据错乱。CubeMX生成的代码默认会处理好但如果你自己改了堆配置或者把lwip用的内存区搬了位置一定要检查描述符是否在32字节对齐的地址上。3.3 调试小技巧串口打印与断点定位跑网络任务时最怕的就是系统在半空中死掉但连死在哪儿都不知道。这套工程里在三个位置加了串口日志PHY初始化完成后打印一次芯片ID和连接状态任务连接服务器成功或失败时打印对应错误码KeepAlive触发断开时打印一条告警。别小看这三行打印实际调试重连问题时90%的定位线索都来自这种关键节点的输出。如果需要更细的调试也可以在lwip内部开DEBUG宏。比如LWIP_DEBUGF配合LWIP_TCP_DEBUG、LWIP_ETHARP_DEBUG等开关可以看到协议栈内部的收发包过程。但注意在FreeRTOS环境下开这些调试宏会大幅拖慢协议栈性能不建议长时间开着跑业务定位完问题就关掉。4. 掉线重连与KeepAlive保障长连接稳定4.1 TCP KeepAlive原理与参数设置TCP连接建立之后如果很长一段时间没有实际数据交互中间链路可能早就断了但两端的协议栈还傻傻地维护着这个连接。这时候如果应用直接发数据可能收到超时或RST如果不发数据这个连接会一直占着资源假死一样。TCP KeepAlive机制就是用来解决这个问题的协议栈在连接空闲一段时间后周期性地发送一个长度为0的探测包对端正常会回复ACK。如果一个或多个探测包都没有得到响应协议栈就能确认连接已经失效进而主动关闭socket返回错误给应用层。比如在lwip的lwipopts.h里配置#define LWIP_TCP_KEEPALIVE 1 #define TCP_KEEPIDLE_DEFAULT 10000 /* 空闲10秒后开始探测 */ #define TCP_KEEPINTVL_DEFAULT 3000 /* 每3秒探测一次 */ #define TCP_KEEPCNT_DEFAULT 3 /* 连续3次没回应则断开 */这三个参数的意思是连接空闲满10秒协议栈发出第一个KeepAlive探测包之后每隔3秒发一个连续发出3个都没有得到任何ACK响应就判定连接已断开。从开始探测到最终判定大约耗时9秒也就是说一个假死连接最多让你等待19秒就能被识别出来。4.2 物理链路检测与状态机设计TCP层的KeepAlive能发现对端假死但发现不了“网线拔了又插上”这种物理层的瞬时中断。因为网线断开时TCP未必能在第一时间收到任何信号只有等到下次收发数据时才会暴露问题。所以工程里单独加一个链路检测任务周期性地去读PHY的状态寄存器。LAN8720的状态寄存器地址1的bit2就是Link Status0表示链路断开1表示链路已建立。CubeMX的驱动里可以通过HAL_ETH_ReadPHYRegister来读取。启动后每隔500ms读一次一旦发现链路从1变成0立刻标记一个“链路丢失”状态。链路恢复后LAN8720会自动重新协商等协商完成link状态再次为1任务就可以触发重连流程。如果把整个连接管理改成状态机会更清晰IDLE尚未开始连接。CONNECTING正在发起TCP连接等待服务器响应。CONNECTED连接正常收发数据都在这里进行。LINK_LOST物理层断开停止发送数据等待链路恢复。RECONNECTING链路已恢复但服务器连接还没建立进入重连循环。应用代码里用switch就行每次状态变化时打印一行日志这样子后期就算业务复杂了也好定位。4.3 重连步骤与代码流程重连流程其实不复杂但有几个细节决定了它能不能稳定工作。第一步关闭旧socket再重建。不要拿着旧的fd继续connectlwip在高负载下容易出现状态残留必须先close确保协议栈把那个连接占用的PCB、PBUF等都释放干净。第二步connect时不能阻塞等待结果。正常情况下lwip的connect是非阻塞的基于select或者poll来判断是否连接上否则连接一个不可达的服务器地址时应用线程会一直卡死整个任务就废了。工程里连接超时时间设定在5秒左右超时没连上就close掉等待下一轮重试。第三步加退避逻辑。假设服务器宕机了如果应用每500ms就尝试连一次不仅浪费CPU还会给对端造成压力。工程里退避策略是失败后先等3秒累计失败次数越多等待时间递增最多30秒封顶每成功连接一次就把失败计数清零。简化后的伪代码如下void net_task(void *arg) { while (1) { switch (net_state) { case STATE_IDLE: net_state STATE_CONNECTING; break; case STATE_CONNECTING: if (tcp_client_connect(server_ip, server_port) 0) { net_state STATE_CONNECTED; fail_count 0; } else { fail_count; vTaskDelay(pdMS_TO_TICKS(backoff(fail_count))); } break; case STATE_CONNECTED: if (phy_link_detect() LINK_DOWN) { net_state STATE_LINK_LOST; } else { /* 收发业务数据 */ tcp_client_poll(); } break; case STATE_LINK_LOST: if (phy_link_detect() LINK_UP) { tcp_client_close(); net_state STATE_CONNECTING; } else { vTaskDelay(pdMS_TO_TICKS(500)); } break; } vTaskDelay(pdMS_TO_TICKS(10)); } }这样设计的好处是网络任务永远在跑不会因为某次连接失败而退出或卡死。不管是网线断了、服务器重启、还是长时间无数据导致的假死最终都能回到CONNECTED状态。5. 移植过程中踩过的坑5.1 PHY地址错位导致ping不通这是最常见的移植问题没有之一。LAN8720的PHY地址由引脚PHYAD0的上下拉决定绝大多数模块默认地址是0但有些开发板为了区分不同PHY会把地址配置成1。如果你的代码里读PHY寄存器一直读到0xFFFF或者读出来的芯片ID不对先确认PHY地址再查其他原因。CubeMX里可以在ETH配置的“Advanced Parameters”中设置PHY Address然后在HAL_ETH_Init后的代码里加一行打印把读到芯片ID打出来。LAN8720的芯片ID一般是0x0007C0F0含版本字段看到这个值就说明PHY通信正常了。5.2 网口协商失败与link灯不亮如果初始化看起来正常但网口link灯不亮第一步检查是不是把网口插到交换机/路由器上了而不是插到电脑后直连电口都不亮。第二步查硬件LAN8720的复位脚、时钟源、REF_CLK方向。第三步用万用表量PHY供电3.3V和1.2V都是必须有的。如果外接的是25MHz晶振却不起振那问题大概率出在晶振负载电容或焊锡上。软件层面还有一个原因ETH外设时钟没有使能。H750的ETH使用的是AHB1上面的时钟CubeMX里如果外设时钟忘记勾选PHY寄存器读写虽然不报错但收发完全不通。5.3 PBUF和堆栈溢出导致的随机死机网络任务用着用着就死机而且死机时机完全没有规律这通常不是逻辑bug而是内存问题。排查方法也比较直白如果开了FreeRTOS的栈溢出检测钩子函数先加上栈溢出打印如果lwip还开着串口调试观察打印有没有MEMP分配失败的告警。这两个方向的概率最大。实际踩过的场景是TCP收到大量数据时lwip一次性需要分配多个PBUF如果MEMP_NUM_PBUF或MEM_SIZE设置得太小分配失败后协议栈会丢弃数据包极端情况下会进入死循环。H750的RAM已经很大了在这个工程里把MEM_SIZE调到几万字节、MEMP_NUM_TCP_SEG调到16以上没有再出现过随机死机的问题。5.4 重连失败或假死问题重连逻辑写得没问题但多次重连之后发现连接不上了而且串口没有任何报错。这种属于比较隐蔽的坑关闭socket后lwip的时钟仍被后续的KeepAlive周期事件占用而新建socket在非阻塞connect时如果没做好超时清理连接状态就卡在SYN_SENT上。解决办法有两个第一重连前先把旧的PCB释放干净用lwip自带的stats接口打印创建的TCP PCB数量确保每次close后数量能降下来第二在非阻塞connect之后必须用select做超时判断超时后立即close而不是盲目等待。这些坑如果不实际踩一轮很难意识到问题会在哪里。其实做网络这块环境复杂、场景多种多样稳定的关键并不是某一行代码写得有多神而是把边界情况都考虑进去给每个环节都留好退路。写在最后我自己的体会是这种带网络协议的工程能“ping通”只是一个起点真正难的是让它在恶劣网络环境下长期活着。这套工程带来的最大启发就是把物理链路检测和TCP层的KeepAlive结合起来再加上重连状态机基本上能覆盖掉90%的异常场景网线被踢了、对端服务器重启了、长时间无流量被中间设备超时踢掉这些都能在几十秒内恢复。如果你后续要用H750做更复杂的业务比如对接云平台、做OTA升级这个框架也完全可以直接作为底子继续往上面堆功能。本文还有配套的精品资源点击获取