STM32F407+lwIP+HTTPD嵌入式Web服务器搭建实战

做嵌入式开发久了就会发现一个特别现实的问题很多设备根本不需要跑完整操作系统但非常需要上网。我自己在STM32F407上折腾网络功能时首先想到的就是lwIP这个圈子里版权友好、资源占用可控的轻量级协议栈。协议栈能跑通只是第一步真正让项目出效果的是挂在它上面的应用所以我这次直接在lwIP上把自带的HTTPD服务器也搭了起来让浏览器输入板子的IP就能看到实时数据还能远程控制IO口。这篇是这个系列的第二篇上一篇把开发环境、时钟、串口这些基础底子打好了这一节就专门讲协议栈移植和HTTPD服务器搭建。如果你手里是F407或者同系列带以太网MAC的芯片跟着这个流程走基本能复现不管你是刚开始接触网络协议栈还是已经在裸机上写过几个TCP样例这里面的经验和坑应该都能用得着。1. 整体方案为什么是“F407lwIPHTTPD”1.1 硬件底子F407自带MACPHY要外挂STM32F407这颗芯片最大的优势之一就是内置了10/100M以太网MAC控制器配合DMA可以自动完成网络报文和内存之间的搬运CPU只在必要的时候参与处理。但MCU内部只有MAC物理层的PHY芯片还是需要外部挂一颗常见搭配是LAN8720、DP83848、KSZ8081这几种。选PHY的时候有一个特别容易忽略的问题RMII接口的50MHz参考时钟到底由谁产生。以LAN8720为例它可以用外部25MHz晶振内部PLL把时钟倍频到50MHz后从REF_CLK引脚输出给MCU这种方案完全不用动MCU的MCO。而有些PHY则要求MCU的MCO1直接供给50MHz时钟这时候去调STM32F407的PLL配置会很痛苦因为系统主频168MHz和精确50MHz的MCO输出在普通分频比下很难同时满足。我做板子的时候干脆选了LAN8720这种自带REFCLK输出的方案少了一个时钟源绕来绕去的麻烦。引脚分配上RMII接口只需要TXD0/1、RXD0/1、TX_EN、MDC、MDIO和REF_CLK这七个信号相比MII接口省了一半多的引脚对F407这种100pin封装非常友好。具体引脚号要根据你的板子原理图来CubeMX里面配置时会自动检查冲突但要确认板上MCU和PHY的实际连接。1.2 软件分层CubeMX生成底层、lwIP跑协议、HTTPD管交互软件上我把它想成三层结构。最底层是STM32CubeMX生成的HAL以太网驱动负责处理MAC、DMA描述符、中断这些寄存器级别的操作中间层是lwIP协议栈负责把TCP/IP报文解析、重传、路由这些复杂逻辑包装成简单接口最上层才是我们真正要写的应用代码比如HTTPD服务器、MQTT客户端或者自定义的TCP/UDPSocket逻辑。CubeMX的好处在于它会帮你生成ethernetif.c和lwip.c前者是以太网驱动的接口适配层后者是协议栈的初始化流程。HTTPD则属于lwIP官方applications目录下的一个组件它的核心是一个小型的Web服务器支持静态页面、CGI接口和SSI动态注入。有了这层东西之后浏览器访问板子上的HTML页面就和访问一个小网站没有本质区别。这种三层结构最舒服的地方是每一层都可以独立调试。如果你发现自己改的HTTPD代码崩了可以先确认不是底层驱动的问题如果ping不通也不用怀疑是应用层写错了。分层清晰之后定位Bug的时间能省一半。1.3 方案对比裸写协议栈、Linux和lwIP怎么选谈嵌入式网络方案我见过最多的三条路一是自己写TCP/IP协议栈二是跑Linux系统三是在MCU上移植lwIP这样的开源轻量协议栈。自己写TCP/IP协议栈这种事写个UDP收发还算简单但要做到TCP的可靠传输、超时重传、滑动窗口、状态机管理工作量直接爆炸而且很难保证兼容性和稳定性。除非你是为了教学或者去面试秀肌肉否则真没必要重复造这个轮子。Linux倒是功能强大但F407没有MMU跑完整的Linux内核非常别扭外设驱动适配也是个大工程最基本的Flash和RAM容量就不太够。相比之下lwIP专为资源受限的嵌入式设备设计几KB内存就能跑起来而且它提供RAW API、netconn API和BSD Socket API三种开发接口从裸机到RTOS都能用。F407跑lwIP属于杀鸡用牛刀空间很充裕。另外说一句lwIP的BSD Socket接口写起来几乎和PC端socket编程一样这一点对很多从上位机转过来的开发者非常友好。你要是以后想把代码迁移到Linux或Windows平台逻辑部分改动很小这就是选成熟协议栈的红利。2. CubeMX工程配置关键参数与避坑点2.1 使能ETH外设RMII接口与PHY地址打开CubeMX工程在Pinout Configuration面板里找到Connectivity下的ETH勾选激活。接口模式选RMII然后ETH的底层配置里最关键的两个参数一个是PHY地址一个是MAC地址。PHY地址这个坑我踩过好几次。LAN8720的地址通常是0x00DP83848在官方评估板上是0x01甚至0x1F具体要看PHY芯片的地址引脚怎么接。如果地址填错HAL_ETH_Init阶段可能看似成功但后面读PHY的链接状态寄存器永远失败表现就是网线插上去了、link灯也亮了但ping死活不通。建议在初始化后主动读一次PHY的ID寄存器来验证比如LAN8720读到的ID应该是0x0007读不到就说明地址不对或者MDIO时序有问题。MAC地址不能全是00只要不跟局域网内其他设备冲突可以随便设一个自己局域网内的唯一地址。CubeMX默认有一个值我一般改成00:80:E1:00:00:01这种格式方便后面做MAC过滤和调试。配置完成后打开System Core里的RCC确认外部高速晶振HSE已经启用然后把时钟树自动解算一遍。F407的PCLK1和PCLK2不直接影响以太网但DMA和RAM的时钟要正常主频尽量跑在168MHz这样整体系统性能才够。2.2 lwIP中间件参数IP、内存和协议特性在Middleware and Software Packs里找到LWIP先Enabled再设置OS Mode。这个选项我强烈建议选FreeRTOS只要你没有特殊原因必须裸奔。裸机模式下lwIP的定时器需要自己在主循环调用MX_LWIP_Process()来驱动否则TCP超时重传、ARP老化这些功能都不会工作做HTTPD这种多并发任务会很吃力。选了FreeRTOS之后lwIP会创建一个tcpip_thread协议栈的收发处理都在这个线程里应用层用Socket接口就能直接阻塞等待数据。IP地址配置上刚开始调试建议用静态IP比如192.168.1.10子网掩码255.255.255.0网关192.168.1.1。DHCP虽然也能用但每次板子上电可能拿到不同IP串口打印IP又搞不好容易在第一步就卡住排查方向。内存相关参数我通常会这样改MEM_SIZE协议栈堆大小CubeMX默认可能给得比较小跑HTTPD加上多个TCP连接会吃紧建议加到16000以上。TCP_SND_BUF发送缓冲和TCP_WND接收窗口直接决定了单条TCP连接传输速度HTTPD页面大的话窗口太小会导致页面加载明显变慢我一般放到2048甚至更大。TCP_MSS以太网标准MTU是1500字节减去TCP/IP头MSS默认1460就行不要乱加。LWIP_HTTPD相关选项在Middleware配置页里把HTTPD使能并且打开SSI和CGI支持。这些开关最终会反映到lwipopts.h的宏定义里比如LWIP_HTTPD_CGI、LWIP_HTTPD_SSI。如果你用的是lwIP 1.x这部分源码路径和API命名会有些差异建议直接上2.x用起来顺手得多。2.3 时钟、中断和FreeRTOS的协同问题ETH外设本身不依赖系统主频做协议计算但RMII的时钟要求必须满足。如果你用的是LAN8720这类PHY输出50MHz REF_CLK给MCU的方案只需要在CubeMX里确认ETH_RMII_REF_CLK引脚配置正确。如果你用的PHY需要MCU输出50MHz那就要查MCO1的分频配置而这颗料在168MHz主频下要精确得到50MHz并不容易所以我前面才反复强调选PHY时优先考虑能够独立输出REFCLK的型号。中断方面ETH的中断开启后我建议把它的抢占优先级设置在5左右不要设成比FreeRTOS的configMAX_SYSCALL_INTERRUPT_PRIORITY更高。原理其实很简单FreeRTOS的API在临界区受保护高优先级中断如果调用了会触发系统错误的函数莫名其妙死机就是从这里来的。CubeMX生成代码后手工检查一下NVIC配置把ETH和ETH_WKUP的中断优先级设到一个合理的值。还有一个很多人忽略的点如果工程里同时跑FreeRTOS需要在CubeMX默认生成的FreeRTOS配置里给TCP/IP操作留下足够的内存比如在FreeRTOS的heap size上适当加大。lwIP的pbuf、TCP连接控制块都是动态分配的每个连接会吃几十字节到上百字节页面并发连接一多内存耗尽的表现很诡异可能不是崩溃而是响应变慢排查起来很折磨人。3. 底层驱动对接ethernetif.c与数据通路3.1 生成代码里必须调整的PHY驱动逻辑CubeMX生成工程后会有一个ethernetif.c它把lwIP的netif操作函数和HAL库的ETH驱动桥接起来。这个文件里low_level_init()函数是整个以太网驱动初始化的核心里面有MAC地址设置、DMA描述符初始化和PHY地址配置。生成代码默认的PHY处理逻辑比较通用但实际用起来要动几个地方。首先确认PhyAddress填了正确的值这个前面已经强调过。然后是PHY芯片的自动协商处理LAN8720和DP83848对寄存器地址的定义基本兼容但有些PHY需要额外配置芯片的工作模式比如RMII模式选择寄存器。拿LAN8720来说它有一个PHY Special Control/Status寄存器bit15是RMII模式选择位如果芯片被误配成MII模式RMII接口的通信就会失败。我在low_level_init末尾加了一段PHY自检逻辑读取PHY的基础状态寄存器打印出link状态和速度模式。调试信息用printf发到串口这样一上电就能立刻看到PHY有没有正常协商成千兆百兆、双工是否正常。这个动作花不了几行代码但它能让你在后续排查网络问题时省下大量时间。3.2 数据收发路径从浏览器到PHY再到协议栈理解lwIP的收发路径能帮你少踩很多坑。发送方向是应用层写数据到Socket、lwIP把数据切包封装成TCP/IP头然后调用netif-linkoutput函数也就是ethernetif.c里的low_level_output()和HAL_ETH_TransmitFrame()。发送完成后HAL库通过发送描述符知道数据已经被DMA拿走lwIP就会释放对应的pbuf内存。接收方向是PHY收包后通过RMII接口给MACDMA自动把数据搬运到内存里的接收描述符缓冲区然后触发接收中断或轮询。ethernetif.c在eth_rx()里调用HAL_ETH_GetReceivedFrame和HAL_ETH_ReadData把DMA缓冲区里的数据拷贝到lwIP的pbuf里最后通过netif-input交给tcpip_thread处理。这里有个很重要的性能点以太网DMA描述符和缓冲区必须放在4字节对齐、并且能被DMA访问的内存区域。CubeMX生成的代码一般默认放在内部SRAM但如果后续你用了外部SDRAM需要特别注意这个DMA地址范围的问题。零拷贝这个事儿在lwIP里主要说的是驱动层尽量直接操作pbuf避免不必要的拷贝但HAL库默认实现还是有一份拷贝对大多数嵌入式Web服务器来说性能完全够用不追求极限速率的话不用过度优化。3.3 lwIP与FreeRTOS线程模型的配合当lwIP的OS Mode设为FreeRTOS之后协议栈会启动几个核心线程。tcpip_thread负责处理协议栈的输入输出tcpip_timeout线程管理各种超时定时器。应用程序发起的Socket读写最终就是通过邮箱IPC机制投递到tcpip_thread执行的。这种模型的好处是协议栈内部所有数据结构都有锁保护多个线程可以安全地同时访问Socket。实际使用时要注意你自己创建的多个业务线程如果频繁创建和关闭TCP连接可能因为内存池耗尽或者长时间占用锁导致tcpip_thread处理不及时。最简单的规避方式就是别在一秒内并发创建几十个连接HTTPD的默认并发连接数在8个左右足够日常页面轮询使用比这个高反而容易出问题。如果遇到网络卡死80%的情况是某个线程在回调里做了阻断操作比如在CGI回调里直接等待串口打印完成或者延时几百毫秒这会卡住整个TCP/IP线程页面当然就刷不出来了。4. HTTPD服务器落地网页、SSI与CGI4.1 fsdata静态网页打包makefsdata的使用lwIP的HTTPD不像PC服务器那样依赖文件系统和磁盘它默认的页面存储方式叫fsdata机制简单说就是把HTML页面、CSS文件这些静态资源通过工具转成C语言数组编译进单片机固件里。这么做的好处是零文件系统开销、不会碎片化、也不存在Flash磨损问题。转换工具叫makefsdata位于lwIP的contrib源码目录下的apps/httpd/makefsdata。使用方式也很粗暴把一个文件夹里的所有网页文件都放进去在命令行执行makefsdata它会自动扫描文件夹并生成fsdata.c和fsdata.h。生成的fsdata.c里每一个文件都对应一个HTTPD_FS_DATA_ENTRY结构体里面保存了文件名、内容指针和长度。我在工程里新建一个fs文件夹把index.shtml、style.css这些文件都放进去然后用工具生成fsdata.c替换掉CubeMX默认生成的同名文件再重新编译就可以了。有一点要特别注意HTTPD处理文件名是区分大小写的而且CGI重定向要跳转的页面名必须和fsdata里的文件名完全一致否则会404。我第一次就栽在这个问题上页面文件名写成了“Index.shtml”FS里存的是“index.shtml”调试了半天才反应过来。4.2 设计一个Led控制台页面HTML骨架为了让页面不只是显示“hello world”我设计了一个简单的设备控制台页面功能包括显示ADC采样值、显示LED当前状态、两个按钮控制LED开关。页面代码如下!DOCTYPE html html head meta charsetutf-8 titleF407 Web Console/title style body { font-family: Arial, sans-serif; margin: 40px; } button { padding: 10px 24px; margin-right: 12px; font-size: 16px; } .status { background: #eee; padding: 12px; display: inline-block; min-width: 200px; } /style script function refresh() { var xhr new XMLHttpRequest(); xhr.open(GET, /data.shtml, true); xhr.onreadystatechange function() { if (xhr.readyState 4 xhr.status 200) { document.getElementById(adc).innerHTML xhr.responseText; } }; xhr.send(); } setInterval(refresh, 1000); /script /head body h2STM32F407 Web Console/h2 pADC Value: span idadc classstatus--/span/p pLED State: !--#led_state--/p p a href/led?stateonbuttonLED ON/button/a a href/led?stateoffbuttonLED OFF/button/a /p /body /html这个页面里有两个动态点!--#led_state--是SSI占位符服务器返回页面时会替换成LED当前状态data.shtml是一个极简的动态接口它只有一个数字JavaScript定时器每秒去拉一次更新到页面上。这样不用整页刷新就能拿到实时数据交互体验比刷新整个页面好很多流量上也更友好。4.3 SSI动态数据注入让ADC值“活”起来SSI全称是Server Side IncludelwIP实现里就是扫描HTML模板中的特殊注释标签例如!--#tag_name--发现之后调用我们注册的SSI回调函数生成内容。它的触发点在服务端发送页面之前所以浏览器拿到的已经是替换后的最终HTML。注册SSI标签和处理函数代码如下#include lwip/apps/httpd.h /* SSI标签列表顺序要和回调里case对应 */ static const char *ssi_tags[] { adc_value, led_state }; static uint16_t read_adc_value(void) { /* 这里换成你自己读取ADC的函数即可 */ return 1234; } u16_t ssi_handler(int iIndex, char *pcInsert, int iInsertLen) { uint16_t len 0; switch (iIndex) { case 0: /* adc_value */ len (uint16_t)snprintf(pcInsert, iInsertLen, %u, read_adc_value()); break; case 1: /* led_state */ if (get_led_status()) { len (uint16_t)snprintf(pcInsert, iInsertLen, ON); } else { len (uint16_t)snprintf(pcInsert, iInsertLen, OFF); } break; default: break; } return len; } void httpd_custom_init(void) { http_set_ssi_handler(ssi_handler, ssi_tags, LWIP_ARRAYSIZE(ssi_tags)); }注意这里的iIndex对应的是ssi_tags数组的下标所以回调里switch的case顺序必须和标签数组一一对应。pcInsert缓冲区的大小受限于HTTPD内部配置建议单次注入内容不要超过几百字节。snprintf一定要带上长度参数防止溢出踩踏内存。注册这个回调函数的时机是httpd_init()之后我在main函数里做了类似的事情int main(void) { /* HAL初始化、MX_LWIP_Init等省略 */ httpd_init(); httpd_custom_init(); /* 启动RTOS后 osKernelStart(); */ }不同lwIP版本API名称会变旧的1.4里可能是httpd_set_ssi_handler2.x以后是http_set_ssi_handler如果编译报错去httpd.h里确认一下当前版本的函数原型就行。4.4 CGI命令处理浏览器远程控制LEDCGI是lwIP HTTPD处理动态请求的主要方式通常用于处理URL带参数的GET请求。点击页面上的LED ON按钮其实就是在浏览器地址栏发起/led?stateon。HTTPD会把URL路径匹配到我们注册的CGI表然后调用对应的处理函数。注册CGI处理器如下static const char *cgi_led(int iIndex, int iNumParams, char *pcParam[], char *pcValue[]) { uint8_t i; for (i 0; i iNumParams; i) { if (strcmp(pcParam[i], state) 0) { if (strcmp(pcValue[i], on) 0) { set_led_status(1); } else if (strcmp(pcValue[i], off) 0) { set_led_status(0); } } } /* 返回的字符串是HTTP重定向页面名告诉浏览器跳回主页面 */ return /index.shtml; } static const tCGI cgi_handlers[] { { /led, cgi_led }, }; void httpd_custom_init(void) { /* ...SSI注册代码... */ http_set_cgi_handlers(cgi_handlers, LWIP_ARRAYSIZE(cgi_handlers)); }iNumParams是参数个数pcParam[i]和pcValue[i]分别是对应的参数名和参数值。我这里只解析了state参数。需要注意的是CGI处理函数返回值是一个字符串它代表跳转的页面名注意千万不能用局部字符串数组去返回因为函数结束后那段内存就失效了处理函数返回的字符串默认是静态的页面路径常量。如果你需要在CGI里生成动态响应内容就得用我前面设计的data.shtml接口思路用SSI标签生成。4.5 用“假接口”实现AJAX轮询每秒刷新实时数据真正的Web服务器很轻松就能做一个返回JSON的API接口但lwIP HTTPD默认框架下返回动态纯文本内容比较绕。如果你直接用CGI返回一段字符串它只会被当成页面名去查找FS里的文件并不会把字符串内容直接发送给浏览器。所以不做FS层深度定制的话最优雅的取巧方案就是建一个只有一个SSI标签的页面叫它data.shtml内容就一行!--#adc_value--当JavaScript请求/data.shtml时HTTPD会正常返回这个页面并且在返回之前把SSI标签替换成实际的ADC值于是浏览器拿到的响应正文就是类似1234这样的纯文本。响应头里虽然带着text/html但XMLHttpRequest读取responseText完全没问题。这个方案我用了很多次效果很稳定而且不用改lwIP底层逻辑。浏览器端代码就是前面HTML里的refresh()函数setInterval(refresh, 1000)定时每秒拉取一次数据。如果你需要更复杂的数据结构可以让这个data页面里包含多个SSI标签然后用文本处理去解析或者调整FS层做真正的动态JSON输出但大多数内部调试和Demo场景这样已经足够。5. 现场排查与调优记录5.1 ping不通时的五步检查法HTTPD页面打不开第一个动作永远是Ping而不是打开浏览器。Ping不通就说明网络层都有问题HTTPD肯定也好不了。我给自己整理了一套固定的排错顺序看PHY的link状态串口打印读到的PHY基本状态寄存器bit0为1表示有网线连接且协商完成。如果link都不通优先查网线、对方交换机端口、PHY供电。确认RMII时钟LAN8720的REF_CLK引脚有没有50MHz波形没有就查晶振和芯片供电有才继续。确认IP配置板子和电脑是否在同一网段网卡IP和板子IP不能冲突。检查PHY地址用读PHY ID寄存器的方式确认MDIO总线能正常访问PHY这一步不会骗人。关掉防火墙PC端防火墙偶尔会拦ICMP裸板调试时直接关掉或者加一个Ping放行规则。有一次我卡在第四步原因是LAN8720的地址引脚有个上拉电阻没焊导致地址变来变去MDIO通信时好时坏。这个例子说明硬件细节和软件配置必须放在一起查。5.2 页面打开但数据异常的处理思路Chip能通、页面也能出来但显示的数据不对这是另一个典型的坑。首先是SSI标签没有替换页面上直接显示原始的!--#adc_value--。这种情况多半是LWIP_HTTPD_SSI这个宏没开或者SSI标签字符串和回调里注册的不一致。其次是CGI点击后跳转404这个大概率是CGI返回的页面名在fsdata里不存在可以对比一下返回字符串和FS中实际文件名。另外我遇到过一种很隐蔽的情况FS里页面内容被压缩了HTTPD对某些类型的文件默认启用了压缩特性而页面文件里又包含中文字符解码后出现乱码。简单做法是避免在FS里存大体积文件以及确保文件编码和Content-Type匹配。最后还有一种情况是页面打开很慢极有可能是DHCP没生效而你又用了自动获取IP或者ARP缓存没刷新。固定IP情况下通常是TCP窗口太小MTU设置又偏大导致分片重传可以按照2.2节里的参数调整。如果还是慢检查一下全局中断是否被人为关闭了那会拖累整个协议栈的响应。5.3 常见问题速查表我把实际项目中遇到比较多的现象和原因整理成了表格方便你遇到问题时快速对号入座。现象可能原因处理办法PING不通PHY link灯灭网线/PHY供电/变压器问题查PHY寄存器link bit短接测试网口PING不通link灯亮PHY地址配置错误读PHY ID寄存器确认地址PING不通串口无打印lwIP初始化失败或MAC地址全0检查ethernetif.c和硬件复位页面打开404fsdata缺少对应文件或文件名不匹配用makefsdata重新生成检查大小写页面显示原始SSI标签未使能LWIP_HTTPD_SSI或标签不匹配检查lwipopts.h和ssi_tagsCGI点击无反应CGI表未注册或URL路径不匹配对比tCGI表中的路径和实际URL页面奇慢无比TCP窗口太小或内存不足调大TCP_WND、MEM_SIZE运行一段时间断网内存泄漏或定时器没跑开启lwIP stats统计检查超时线程FreeRTOS下偶尔死机中断优先级问题导致API不安全降低ETH中断优先级释放锁检查这个表格是我在调试新板子时的第一参考很多问题其实不需要看代码对照现象就能缩小范围。5.4 让HTTPD更稳的几点调优调试阶段跑通和产品阶段稳定运行之间还有一段路我通常会在功能正常后做这几件事。第一打开lwIP自带的统计功能LWIP_STATS_DISPLAY宏置1状态页或者串口就能输出内存池使用量、TCP连接状态、丢包重传统计。这个能帮你直观看出内存够不够用、有没有泄漏。第二固定IP改为DHCP获取然后在串口打印分配到的IP这样生产环境插上路由就能用不用每台改配置。第三HTTPD并发连接数默认8个左右一般够用但如果你在页面上开了多个定时轮询任务可以考虑适当调高HTTPD_MAX_CONNECTIONS同时注意内存开销。最后一件事如果你决定在HTTPD之外再挂MQTT或者TLS这类更重的应用一定要提前规划内存分配调大MEM_SIZE之外还要看FreeRTOS的堆大小。协议栈吃内存很凶别等到功能叠加到一半才想起来看内存余量那会儿查起来会很痛苦。我个人在实际操作中最深的体会是lwIP移植这件事配置和代码只占三成剩下的七成都在排查连接、时钟、内存这些“看不到”的环节。把ethernetif.c和lwipopts.h这些关键文件里的每个参数吃透再遇到问题就会从容很多。做完HTTPD这个Demo之后下一步可以往MQTT、CoAP或者TLS方向扩展思路和这次完全一样希望这篇能让你少走几段弯路。