简介：面向嵌入式开发者的STM32+W5500 HTTP下载示例工程，基于STM32F103RC驱动W5500以太网控制器，实现通过HTTP GET从服务器下载文件并保存，适用于需要网络连接、远程固件升级或云端交互的物联网场景。资源共212个文件，压缩包5.62MB，以C源码和H头文件为主，包含39个.c与41个.h，以及Keil MDK工程配置、编译生成的.o/.d/.crf中间文件、Hex/Axf烧录文件、Map/Lst映射列表等，可直接打开工程查看完整实现，也可按需提取源码复用。已有764人学习下载。工程完整覆盖W5500 SPI初始化、网络参数配置、TCP连接建立、HTTP请求构造、响应接收解析、文件保存及关闭连接的全流程，并包含错误处理与状态检查代码。对希望掌握STM32硬件TCP/IP协议栈应用、理解HTTP客户端交互流程的开发者，是一份值得参考的实战模板。 前一阵从硬盘角落里翻出一个STM32_W5500_HTTPC_Download_File.rar，这种命名方式一看就是老工程师的习惯——芯片型号、外设方案、功能点全塞在文件名里。这个包要解决的事情很明确：STM32通过SPI驱动W5500以太网芯片，以HTTP Client的身份从远程服务器下载一个文件到本地存储。如果你正在做嵌入式联网升级、设备远程配网、或者从服务器拉取资源文件这类需求，这个例程包是非常典型的参考模板。
不过说实话，这种压缩包在网上一抓一大把，真正能一次跑通的没几个。问题往往不出在W5500本身，而是出在工程里那些“默认不解释”的细节上：SPI时序配置、Socket缓冲区分配、HTTP报文构造、数据分块落盘，任何一个环节理解不到位，下载就会卡在半路。这篇我就把整个工程拆开讲，从硬件连接、初始化时序、HTTP状态机到SD卡写文件策略，最后把几个容易踩的坑也一并说了。
1. 例程包解剖：先从文件结构判断工程的硬件基础
1.1 工程结构里的关键文件
解压之后，典型的工程目录会包含这样几块：
- 平台相关文件（
startup_stm32f10x.s、system_stm32f10x.c、标准外设库或HAL库） - W5500驱动层（
w5500.c/h、wizchip_conf.c/h、socket.c/h） - HTTP客户端逻辑（
httpc.c/h） - 应用入口（
main.c） - SD卡与文件系统（
ff.c/h、diskio.c、SPI或SDIO底层驱动）
判断一个例程是否靠谱，先看W5500驱动文件是哪种。如果是WIZnet官方移植的标准库结构，即保留了wizchip_conf、socket和socketlib这组文件，说明驱动层是完整可用的；如果驱动是有人自己改写的一坨w5500_reg.c，就得小心寄存器操作是否遗漏了。我建议拿到工程后先确认驱动文件里有没有实现reg_wizchip_cs_select、reg_wizchip_spi_readbyte、reg_wizchip_spi_writebyte这些回调，这是W5500库和MCU硬件之间的约定接口。
1.2 硬件连接与开发环境确认
再看硬件连接。W5500与STM32之间基本是标准的4线SPI加一个片选、一个复位、一个中断引脚，网口变压器和RJ45大多集成在模块上：
| 信号 | STM32引脚 | 说明 |
|---|---|---|
| SCLK | PA5（SPI1_SCK） | SPI时钟，例程一般跑10MHz以下 |
| MOSI | PA7（SPI1_MOSI） | 主机发送从机接收 |
| MISO | PA6（SPI1_MISO） | 主机接收从机发送 |
| SCS | PA4（GPIO） | 片选，低电平有效 |
| RSTN | PA3（GPIO） | W5500硬复位，低电平有效 |
| INTN | PA2（GPIO） | 中断输出，本例程可不用或接外部中断 |
这里面最容易忽略的是RSTN。很多模块在STM32复位后并不会自动复位，而W5500内部寄存器在上电后处于默认状态，如果你之前配置过IP和Socket信息，复位后这些寄存器会残留或者处于未知状态。所以初始化第一步必须对W5500做硬复位，拉低RSTN至少500us再释放。这个细节直接影响后面对0x0039版本寄存器的读取结果。
开发环境方面，这种工程大多数是Keil MDK的.uvprojx，打开前确认已安装对应STM32型号的芯片包。注意部分工程用了标准外设库（如STM32F10x_StdPeriph_Lib），这种老库在新版本Keil上容易报一堆重复定义或“找不到头文件”，通常需要额外添加StdPeriph_Driver/inc到Include路径。我之前就遇到过一个工程打开之后全是红色波浪线，折腾半天发现只是头文件路径没配对。
2. SPI链路与W5500初始化：为什么先读0x0039版本寄存器
2.1 W5500的SPI帧格式与读写时序
W5500的SPI接口和普通存储器不一样，它每次传输一帧定长控制帧，由三部分组成：16位地址段 + 8位控制段 + N字节数据段。开CS后一次性发完，然后关CS。控制段的高3位是块选择，决定是访问寄存器块、Socket寄存器块、发送缓冲区还是接收缓冲区；第4位是读写方向；低4位在可变长度模式下填0即可。
如果你要读版本寄存器0x0039，流程是：
uint8_t w5500_read_version(void) { uint8_t tmp; W5500_CS_LOW(); spi_write_byte(0x00); // 地址高8位 spi_write_byte(0x39); // 地址低8位 spi_write_byte(0x04); // 控制段：寄存器块 + 读 + VDM模式 tmp = spi_read_byte(); // 读回数据 W5500_CS_HIGH(); return tmp; }控制段0x04拆开来看：高三位000表示寄存器块，bit3的0表示读，低四位0000表示可变数据长度模式。W5500正确复位后，w5500_read_version()应当返回0x04。这个返回值是验证SPI链路是否打通、W5500是否正常工作的第一个信号。我习惯在初始化后加一个断言式检查，读到不是0x04就立刻打印错误，而不是继续往下跑。
2.2 初始化检查：PHY状态与版本寄存器
还有一个检查点是PHY链路状态。W5500内置了PHY，链路协商状态可以通过PHY寄存器读取。在main初始化末尾，可以读取PHY状态并判断网线是否插好。如果板子上网口LED不亮，或者打印出链路断开，先检查网络变压器、RJ45到W5500之间的线路，别急着调代码。这一点很多新手会忽略，看到连不上服务器就反复改IP，实际上网线都没通。
另外要留意MAC地址不能全零，IP、网关、子网掩码三项要匹配本地网段。假设你的开发板连接路由器的LAN口，路由器网段是192.168.1.1，那么给W5500设置的IP可以是192.168.1.50，掩码255.255.255.0，网关192.168.1.1。用固定IP最省事，因为例程一般不带DHCP客户端；如果你希望自动获取IP，需要额外移植DHCP逻辑，这已经超出下载例程本身的范围了。
2.3 关于SPI时钟频率的取舍
官方驱动默认的SPI速率并不苛刻，但实际工程里很多人直接把SPI分频调到最低，结果下载一段时间后数据偶尔错乱。W5500的SPI从机时序在设计上有一定余量，但飞线和面包板场景下高频很容易翻车。我的习惯是：开发板用PCB走线可以跑到10MHz或更高，用杜邦线连接时先降到1MHz到4MHz跑通功能，再逐步提频。反正HTTP下载的瓶颈通常不在SPI速率上，而是TCP窗口和SD卡写入速度，没必要为了SPI时钟好看引入稳定性风险。
3. HTTP GET请求怎么发：报文构造与Socket状态机的配合
3.1 Socket的数据结构：为什么下载只需要一个Socket
W5500内部有8个独立的Socket，每个Socket相当于一个独立的TCP或UDP通道。HTTP下载场景下只需要使用Socket 0即可。为了提高吞吐，可以重新分配缓冲区：把Socket 0的TX Buffer配到8KB、RX Buffer配到8KB，其余Socket关闭或保留最小缓冲。W5500总缓冲区是32KB，合理分配能明显提高单TCP连接的数据吞吐量。
用官方库设置Socket 0缓冲区的方法是通过setSn_RXBUF_SIZE(0, 8)和setSn_TXBUF_SIZE(0, 8)。注意这个设置必须在Socket关闭状态下进行，而且重新分配之后要再次打开Socket。网上很多例程为了省事没做这一步，默认每个Socket的缓冲只有2KB，也能用，但下载速度会差不少。
3.2 HTTP请求头：用HTTP/1.0规避chunked编码的坑
构造HTTP GET请求是这个工程的核心。以从服务器下载/download/upgrade.bin为例：
const char http_req[] = "GET /download/upgrade.bin HTTP/1.0\r\n" "Host: 192.168.1.100\r\n" "User-Agent: STM32-W5500/1.0\r\n" "Accept: */*\r\n" "Connection: close\r\n" "\r\n";这里我特意用了HTTP/1.0而不是HTTP/1.1，目的就是从协议层面避开Transfer-Encoding: chunked的麻烦。很多主流HTTP服务器在HTTP/1.1下如果不知道文件长度，会返回分块传输编码，正文被拆成多个“长度+数据”的块。如果客户端没有实现chunked解码，直接按普通数据写文件，出来的文件大概率是坏的。用HTTP/1.0并且声明Connection: close，服务器通常会直接按HTTP/1.0语义返回完整内容，并以关闭连接表示传输结束。这个技巧在MCU上非常实用，能省掉一整套chunked状态机。
3.3 响应解析：状态行、响应头和正文的边界
TCP是流式协议，没有消息边界。服务器返回的HTTP响应到达W5500时，可能一次收到几十个字节，也可能一次收到几百上千个字节，而且第一次收到的报文很可能只覆盖了状态行和部分响应头。所以接收逻辑必须设计成状态机，而不是简单判断“第一次recv返回的数据就是响应头”。
响应处理的三个状态是：
- 状态行解析：检查
HTTP/1.0 200 OK或类似行，确认返回码是200。 - 响应头解析：逐字节累积，直到找到
\r\n\r\n，表示头部结束。 - 正文接收：头部结束之后的所有数据都是文件内容，开始写盘。
我有一个习惯：准备一个两三百字节的接收环形缓冲区，先把TCP收到的原始数据全部送进这个缓冲区，再用状态机从缓冲区里逐个字节消费。这样不管底层怎么分包，逻辑上都不会乱。等找到\r\n\r\n后，缓冲区里剩余的数据就是文件开头的字节，要最先写入文件，别丢掉。
4. 下载文件怎么落盘：小内存芯片上的分块缓存设计
4.1 接收缓冲与写卡缓冲怎么配
STM32的内部RAM很有限，比如F103系列多数只有20KB到64KB，你不可能把整个文件装进内存再写SD卡。正确做法是“边收边写”，每次从W5500的RX Buffer里读出一块数据，立刻通过FATFS写入SD卡文件。
推荐的缓冲策略是应用程序维护一个1KB到4KB的download_buf，然后开一个循环：
- 查询Socket 0的接收数据大小
getSn_RX_RSR(0)。 - 如果大于0，调用
recv(0, download_buf, size)读取数据。 - 把读到的数据交给状态机解析，判断是头部还是正文。
- 正文数据调用
f_write(&file, buf, len, &bw)写入SD卡。 - 循环直到服务器关闭连接或收到Content-Length指定的字节数。
这里的关键是读取大小。recv一次读取的量可以不超过download_buf的长度，但要注意W5500的RX Buffer有8KB，应用程序必须及时把它们读走。如果单片机上还有其他主循环任务占用了太多时间，W5500 RX Buffer满了之后新数据会被丢弃，抓包能看到TCP窗口变成0，表现为下载卡顿甚至文件损坏。
4.2 FATFS写入的扇区对齐优化
FATFS的f_write接口对字节写入本身没有限制，但由于底层SD卡是按扇区（512字节）读写，频繁碎字节写入会造成严重的读写放大。优化办法是自己做一层扇区缓冲：攒满512字节再调f_write，这样SD卡每次写操作都是整扇区对齐，速度能快一个数量级。
具体实现就是维护一个align_buf和偏移计数器，正文数据先落入align_buf，满了就f_write一次，同时把文件指针推进。最后一小块不够512字节的数据在文件结束时单独写一次，然后调用f_close把FATFS内部缓存也刷出去。这个技巧在低速SPI模式的SD卡上特别管用，能直接决定下载速度是几十KB/s还是五百KB/s以上。
4.3 收尾工作：大小校验和失败续传
文件下载完成后，务必做两件事：确认实际写入字节数与服务器返回的Content-Length一致；如果下载过程中TCP连接异常断开，删除残次文件或者记录已下载的偏移量。断点续传在HTTP协议里可以用Range: bytes=已下载长度-实现，但需要服务器支持。我拿这个例程做固件升级时，就接了外部Flash记录当前下载进度，下次上电继续下载剩余部分，省去整包重传。对于资源紧张的设备，这个思路比一次性下载可靠得多。
5. 实测中的排查链路：从链接建立到文件校验，哪些坑我踩过
5.1 通信正常但下载卡死：排查TCP连接状态
最典型的故障是：W5500能ping通，服务器也能访问，但HTTP请求发出去之后就像石沉大海。这时候先别猜是HTTP报文格式的问题，先确认TCP连接是否真的建立了。检查Socket 0的状态寄存器getSn_SR(0)，正常连接建立后应该是SOCK_ESTABLISHED；如果一直是SOCK_SYNSENT，说明TCP三次握手都没完成。
这种问题八成出在静态IP配置和路由上。确认开发板的IP和服务器在同一网段；如果不在同一网段，必须保证网关配置正确，且路由器允许转发。还有一种情况是目标服务器域名没有解析，W5500的例程一般不内置完整DNS客户端，你如果直接填了一个域名而不是IP地址，TCP根本没法发起连接。能直接用IP就先用IP跑通整个流程，域名解析的坑单独处理。
5.2 数据错乱：SPI速率与缓冲区溢出的双重嫌疑
下载到一半文件内容错乱，先看SPI速率，再看接收节奏。
SPI错乱通常表现为偶发性的数据字节错误，而且出错位置不固定。如果工程是在杜邦线上调试的，把SPI预分频调大，降到4MHz以内，基本能消除大多数时序问题。飞线越长，信号边沿越差，高频下出现建立时间不足的概率就越高。
缓冲区溢出的表现则更规律：文件前半部分正常，到了一定大小后开始出现大段缺失或CRC校验失败。我遇到过一次，主循环里加了一个每秒刷一次OLED屏的任务，刷屏期间SPI SD卡写入被阻塞，W5500的RX Buffer瞬间被填满，后到数据直接被丢弃。解决办法是改成下载期间暂停其他重任务，或者把W5500的INTN引脚接到外部中断，在中断里快速清空RX Buffer，打断点量再决定怎么写盘。
5.3 下载速度上不去的瓶颈分析
明明局域网是千兆交换机，为什么HTTP下载速度只有一两百KB/s？瓶颈一般不在网络带宽，而在数据链路的“最短木板”。用SPI模式驱动SD卡时，4MHz SPI的写速率大约500KB/s，如果没做扇区对齐，实际写卡速度可能不到200KB/s，下载速度就被拖到200KB/s左右。用SDIO接口或者换高速SPI模式打开SD卡，写卡速度能到1MB/s以上，HTTP下载明显提速。
另外，TCP窗口本身也是限制。W5500的Socket 0如果只分了2KB RX Buffer，一次TCP确认窗口就很小，服务器每个往返只能发2KB数据，再加上HTTP请求-响应的握手开销，速度很难上去。把Socket 0的RX Buffer扩到8KB，同时确认服务器支持TCP扩展窗口，下载速度会明显改善。当然，如果服务器在互联网上而不是局域网，公网往返延迟和带宽抖动也会限制速度，这种场景就别纠结单机吞吐了。
我在实际项目里把这个例程改造成过“远程固件升级”和“配置文件下发”两个版本，一个用FATFS写SD卡，一个用内部Flash存储，核心都是这个HTTPC链路。每次有同事说“下载中途失败了”，我第一个问题永远是：先确认PHY灯亮不亮，再查Socket状态，最后才是看HTTP报文。排查顺序对了，问题就解决了一半。如果你也打算拿这个工程做产品原型，建议从一开始就把连接状态、SPI错误计数、下载进度这些调试信息全部通过串口打出来，后面会省非常多的时间。
本文还有配套的精品资源，点击获取
