1. 为什么我劝你先把 SPI 时序搞明白再碰 W5500很多人拿到 W5500 模块的第一反应是找现成库Ethernet.init()一调能 ping 通就收工。但真到了现场设备跑几天掉线、数据发不出去、DHCP 拿不到地址回头翻库源码又看不懂最后只能重启大法。我踩过这个坑所以这篇东西不打算给你一个能跑就行的例程而是把 ESP32 的 SPI 主机驱动和 W5500 的寄存器操作掰开揉碎讲清楚让你知道每一行代码在干什么。ESP32 的 SPI 外设和 STM32 那套完全不是一个思路。STM32 你配好 CR1、CR2、DR 就能收发ESP32 在 ESP-IDF 里走的是spi_master驱动事务transaction是核心概念一次 CS 拉低到拉高之间可以塞多个收发阶段。W5500 恰好就是这种一次片选内多段传输的典型器件——它的地址段、控制段、数据段是分开的中间 CS 不能抬起来。你要是用 Arduino 的SPI.transfer()一个字节一个字节发中间没有事务概念W5500 根本不会理你。所以这篇内容的定位很明确适合已经会点 ESP32、但被 SPI 和 W5500 组合卡住的嵌入式开发者也适合从 STM32 转过来、想搞懂 ESP-IDF SPI 驱动模型的人。看完你应该能做到三件事——自己写 W5500 的读写函数、看懂官方 ioLibrary 的底层在干嘛、遇到 ping 不通时知道从哪几个点下手排查。提示本文所有代码基于 ESP-IDF v5.xW5500 模块是市面上最常见的 SPI 转以太网小板晶振 25MHz带 3.3V 稳压。2. 先搞清楚 ESP32 SPI 驱动模型和 W5500 的脾气2.1 ESP-IDF 的 SPI 主机驱动到底怎么组织ESP-IDF 的 SPI 主机驱动分四层总线bus、设备device、事务transaction、收发transmit/receive。这个分层不是摆设理解它才能理解为什么初始化要分两步。总线初始化用spi_bus_initialize()你告诉它用哪个 SPI 控制器SPI2_HOST 或 SPI3_HOST、引脚怎么映射、DMA 通道用哪个。注意 ESP32 的 SPI1 是给 Flash 用的你不能碰能用的只有 SPI2 和 SPI3。总线初始化只做一次多个设备可以挂在同一条总线上。设备初始化用spi_bus_add_device()这一步才是配置时钟频率、SPI 模式CPOL/CPHA、CS 引脚、队列深度的地方。每个设备有自己的句柄收发时用句柄区分。W5500 支持 SPI 模式 0CPOL0CPHA0时钟最高 80MHz但实际跑 30MHz 左右比较稳后面会讲为什么。事务用spi_transaction_t结构体描述关键字段是length比特数不是字节数这个坑很多人踩、tx_buffer、rx_buffer、flags。W5500 的读写需要发地址、发控制、再收发数据三段所以要么用spi_device_transmit()分多次调用每次 CS 会抬起不行要么用spi_device_polling_transmit()配合手动控制 CS要么把三段拼成一个 buffer 一次发。我选的是手动控制 CS 加多次spi_device_polling_transmit()逻辑最清晰。2.2 W5500 的 SPI 帧格式为什么不能一个字节一个字节发W5500 的 SPI 帧结构是这样的前 2 字节是地址段第 3 字节是控制段包含读写位和 BSB 块选择位之后才是数据段。地址段和控制段必须在同一次 CS 有效期内连续发出中间 CS 抬起就作废。控制字节的位定义很关键bit7 是读写标志1 读 0 写bit6-3 保留bit2-0 是 BSBBlock Select Bits用来选 W5500 内部的哪个寄存器块。比如选通用寄存器 BSB0x00选 Socket0 寄存器 BSB0x01选 Socket0 的 TX 缓冲 BSB0x02RX 缓冲 BSB0x03。这个 BSB 设计是 W5500 比 W5100 进步的地方W5100 要发完整的 16 位地址W5500 用 BSB 加偏移就能定位省了字节。所以一次完整的读操作是CS 拉低 → 发 2 字节地址高字节在前→ 发 1 字节控制0x80 | (BSB3)→ 读 N 字节数据 → CS 拉高。写操作类似控制字节最高位是 0。2.3 硬件连接与引脚选择W5500 模块和 ESP32 的接线我用的是下面这套实测最稳W5500 引脚ESP32 引脚说明VCC3V3模块自带稳压供 3.3VGNDGND共地必须接CSGPIO5片选可换其他 GPIOSCKGPIO18SPI2 默认 SCKMISOGPIO19SPI2 默认 MISOMOSIGPIO23SPI2 默认 MOSIINTGPIO4中断可选但建议接RSTGPIO2复位建议接ESP32 的 IO MUX 允许 SPI2 映射到任意 GPIO但默认引脚性能最好非必要别乱改。INT 引脚我强烈建议接上W5500 收到数据会拉低 INT用中断比轮询省 CPU后面讲 Socket 编程时会用到。注意W5500 模块的晶振是 25MHzSPI 时钟不要超过 33MHz否则模块内部时序可能跟不上。我实测 30MHz 稳定40MHz 偶发丢包。3. 从零写 W5500 驱动寄存器读写函数逐行拆解3.1 初始化 SPI 总线和设备先看总线初始化。spi_bus_config_t里把四个引脚填好max_transfer_sz设成 4096因为 W5500 的 Socket 缓冲一次最多读 2KB留点余量。DMA 通道用SPI_DMA_CH_AUTO让驱动自动分配。spi_bus_config_t buscfg { .miso_io_num PIN_MISO, .mosi_io_num PIN_MOSI, .sclk_io_num PIN_SCK, .quadwp_io_num -1, .quadhd_io_num -1, .max_transfer_sz 4096, }; ESP_ERROR_CHECK(spi_bus_initialize(SPI2_HOST, buscfg, SPI_DMA_CH_AUTO));设备初始化里clock_speed_hz我设 30MHzmode设 0spics_io_num设 -1 表示手动控制 CS。为什么手动控制因为 W5500 一次操作要分三段发如果用驱动自动控制 CS每次spi_device_transmit()都会抬 CSW5500 就懵了。手动控制就是自己拉 GPIO把 CS 当成普通 IO 用。spi_device_interface_config_t devcfg { .clock_speed_hz 30 * 1000 * 1000, .mode 0, .spics_io_num -1, .queue_size 7, }; ESP_ERROR_CHECK(spi_bus_add_device(SPI2_HOST, devcfg, spi_handle));CS 引脚单独配置成输出初始拉高gpio_config_t cs_cfg { .pin_bit_mask (1ULL PIN_CS), .mode GPIO_MODE_OUTPUT, }; gpio_config(cs_cfg); gpio_set_level(PIN_CS, 1);3.2 写寄存器函数三段式传输的实现写寄存器的流程是拉低 CS → 发地址高字节 → 发地址低字节 → 发控制字节写BSB 左移 3 位→ 发数据 → 拉高 CS。每一段用spi_device_polling_transmit()发这个函数是阻塞的适合这种短传输。void w5500_write(uint16_t addr, uint8_t bsb, const uint8_t *data, size_t len) { spi_transaction_t t; uint8_t ctrl (bsb 3) 0x38; // 写操作 bit70 gpio_set_level(PIN_CS, 0); // 地址高字节 memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ((uint8_t[]){addr 8})[0]; spi_device_polling_transmit(spi_handle, t); // 地址低字节 memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ((uint8_t[]){addr 0xFF})[0]; spi_device_polling_transmit(spi_handle, t); // 控制字节 memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ctrl; spi_device_polling_transmit(spi_handle, t); // 数据 if (len 0) { memset(t, 0, sizeof(t)); t.length len * 8; t.tx_buffer data; spi_device_polling_transmit(spi_handle, t); } gpio_set_level(PIN_CS, 1); }这里有个细节t.length是比特数不是字节数。我第一次写的时候填了字节数结果只发了 1/8 的数据W5500 收到的全是错位。这个坑在 ESP-IDF 文档里写得很清楚但很多人不看文档直接抄例程就会中招。3.3 读寄存器函数注意 MISO 的时序读操作和写操作的区别在控制字节的 bit7 置 1然后数据段是接收而不是发送。接收时tx_buffer设 NULLrx_buffer指向接收缓冲。ESP32 的 SPI 驱动在接收时会自动发 0xFF 填充不用你手动准备。void w5500_read(uint16_t addr, uint8_t bsb, uint8_t *data, size_t len) { spi_transaction_t t; uint8_t ctrl 0x80 | ((bsb 3) 0x38); // 读操作 bit71 gpio_set_level(PIN_CS, 0); memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ((uint8_t[]){addr 8})[0]; spi_device_polling_transmit(spi_handle, t); memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ((uint8_t[]){addr 0xFF})[0]; spi_device_polling_transmit(spi_handle, t); memset(t, 0, sizeof(t)); t.length 8; t.tx_buffer ctrl; spi_device_polling_transmit(spi_handle, t); if (len 0) { memset(t, 0, sizeof(t)); t.length len * 8; t.rx_buffer data; spi_device_polling_transmit(spi_handle, t); } gpio_set_level(PIN_CS, 1); }读的时候有个容易忽略的点地址段和控制段发完之后MISO 线上可能还有残留数据所以数据段的第一个字节要丢弃吗不用W5500 的时序是控制字节发完的下一个时钟沿就开始输出有效数据ESP32 的驱动会在数据段开始时采样所以直接读就行。我实测读版本号寄存器0x0039BSB0返回 0x04说明 W5500 芯片正常。3.4 常用寄存器封装与版本验证有了读写函数就可以封装常用操作了。比如写通用寄存器void w5500_write_reg(uint16_t addr, uint8_t val) { w5500_write(addr, BSB_COMMON, val, 1); } uint8_t w5500_read_reg(uint16_t addr) { uint8_t val; w5500_read(addr, BSB_COMMON, val, 1); return val; }上电后第一件事是读版本号验证 SPI 通路。W5500 的版本号寄存器地址是 0x0039BSB0正常值 0x04。如果读出来是 0x00 或 0xFF说明 SPI 没通检查接线、CS 电平、时钟极性。我遇到过读出来 0xFF 的情况最后发现是 MISO 和 MOSI 接反了这种低级错误在面包板上很常见。实操心得调试 SPI 时先用示波器或逻辑分析仪抓 CS、SCK、MOSI 三根线看 CS 拉低后有没有 3 个字节的输出控制字节是不是 0x80 开头。没有仪器的话把 SPI 时钟降到 1MHz用万用表测 MISO 在 CS 拉低后有没有跳变也能判断个大概。4. 网络配置与 Socket 编程让 W5500 真正跑起来4.1 网络参数寄存器配置W5500 要联网得先配好 IP、子网掩码、网关、MAC。这些都在通用寄存器块里地址分别是寄存器地址长度GAR网关0x00014 字节SUBR子网掩码0x00054 字节SHARMAC0x00096 字节SIPR本机 IP0x000F4 字节写 IP 的时候注意字节序W5500 期望的是网络字节序大端而 ESP32 是小端所以要把 IP 数组按顺序写进去。比如 192.168.1.100 就是{192, 168, 1, 100}直接写。uint8_t ip[4] {192, 168, 1, 100}; uint8_t mask[4] {255, 255, 255, 0}; uint8_t gw[4] {192, 168, 1, 1}; uint8_t mac[6] {0xDE, 0xAD, 0xBE, 0xEF, 0x01, 0x02}; w5500_write(SHAR, BSB_COMMON, mac, 6); w5500_write(SIPR, BSB_COMMON, ip, 4); w5500_write(SUBR, BSB_COMMON, mask, 4); w5500_write(GAR, BSB_COMMON, gw, 4);配完之后要发一个命令让 W5500 应用这些参数命令寄存器 MR0x0000的 bit7 是复位bit4 是 PPBping 阻塞bit3 是 PBping 使能。一般先软复位再配置配置完清掉复位位。4.2 Socket 初始化与 TCP 客户端W5500 有 8 个 Socket每个 Socket 有独立的寄存器块BSB 从 0x01 到 0x08 对应 Socket0 到 Socket7。每个 Socket 的寄存器偏移是一样的比如 Sn_MR模式寄存器偏移 0x00Sn_CR命令寄存器偏移 0x01Sn_SR状态寄存器偏移 0x03。开一个 TCP 客户端流程是设 Sn_MR 为 TCP 模式0x01→ 发 OPEN 命令0x01→ 等 Sn_SR 变成 SOCK_INIT0x13→ 发 CONNECT 命令0x04→ 等 Sn_SR 变成 SOCK_ESTABLISHED0x17。每一步都要轮询状态不能发完命令就往下走。void socket_open_tcp(uint8_t sn, uint16_t port) { uint8_t bsb BSB_SOCKET(sn); w5500_write_reg_bsb(bsb, Sn_MR, 0x01); // TCP 模式 w5500_write_reg_bsb(bsb, Sn_PORT, port 8); w5500_write_reg_bsb(bsb, Sn_PORT 1, port 0xFF); w5500_write_reg_bsb(bsb, Sn_CR, 0x01); // OPEN while (w5500_read_reg_bsb(bsb, Sn_SR) ! 0x13) { vTaskDelay(pdMS_TO_TICKS(1)); } }连接目标服务器时先把目标 IP 和端口写进 Sn_DIPR 和 Sn_DPORT再发 CONNECT 命令。这里有个坑CONNECT 命令发出去后如果目标不可达Sn_SR 会变成 SOCK_CLOSED0x00不会一直停在 INIT。所以轮询时要加超时不然死循环。4.3 数据收发与缓冲管理W5500 每个 Socket 有 2KB 的 TX 缓冲和 2KB 的 RX 缓冲通过 Sn_TX_FSR 和 Sn_RX_RSR 寄存器查看剩余空间和已收数据量。发数据前先读 Sn_TX_FSR确认空间够然后写 Sn_TX_WR 指针把数据写进 TX 缓冲最后发 SEND 命令。uint16_t tx_free w5500_read_tx_fsr(sn); if (tx_free len) { uint16_t ptr w5500_read_tx_wr(sn); w5500_write_tx_buffer(sn, ptr, data, len); w5500_write_tx_wr(sn, ptr len); w5500_write_reg_bsb(bsb, Sn_CR, 0x20); // SEND }收数据是反过来的读 Sn_RX_RSR 看有多少数据然后读 Sn_RX_RD 指针从 RX 缓冲读出来最后把 Sn_RX_RD 指针加上读出的长度发 RECV 命令。注意TX 缓冲的写指针是环形回绕的写到 2KB 边界要回到 0。W5500 内部自动处理回绕但你传的地址要按 2KB 取模。我一开始没取模数据写到一半就乱了。4.4 中断处理与轮询的取舍W5500 的 INT 引脚在收到数据、连接建立、连接断开时会拉低。用中断的好处是 CPU 不用一直轮询 Sn_RX_RSR省电也省 CPU。但中断处理里不能做 SPI 读写SPI 事务可能阻塞所以中断里只发个信号量任务里再处理。static void IRAM_ATTR w5500_isr(void *arg) { BaseType_t hp pdFALSE; xSemaphoreGiveFromISR(sock_sem, hp); portYIELD_FROM_ISR(hp); }如果项目简单轮询也能用就是每 10ms 查一次 Sn_RX_RSR有数据就处理。我实测轮询在 100Mbps 网络下 CPU 占用大概 5%可以接受。中断方式 CPU 占用降到 1% 以下但代码复杂度上去了看项目需求选。5. 常见问题排查ping 不通、掉线、数据错位怎么破5.1 上电后读不到版本号这是最常见的问题现象是w5500_read_reg(0x0039)返回 0x00 或 0xFF。排查顺序先查供电W5500 模块要 3.3V5V 会烧芯片再查接线MISO/MOSI 别接反然后查 CS上电时 CS 必须是高电平如果 CS 一直低W5500 会一直以为在通信最后查 SPI 模式W5500 只支持模式 0CPOL0、CPHA0设成模式 3 就读不到。我遇到过一次读不到版本号查了半天发现是 ESP32 的 GPIO5 默认有内部上拉但 W5500 模块的 CS 有下拉电阻两个打架CS 电平不稳定。解决办法是在gpio_config里把 CS 引脚的上拉关掉或者换一个没有默认上拉的 GPIO。5.2 ping 通但 TCP 连不上ping 通说明 IP 层没问题TCP 连不上通常是 Socket 没开对。检查 Sn_MR 是不是 0x01TCPSn_PORT 是不是目标端口Sn_SR 有没有到 SOCK_INIT。如果 Sn_SR 一直是 0x00说明 OPEN 命令没生效可能是 BSB 算错了。BSB 的计算是0x01 snSocket0 是 0x01Socket1 是 0x02别搞混。还有一种情况是目标服务器有防火墙只允许特定源端口。W5500 的本地端口是 Sn_PORT如果设成 0W5500 会自动分配一个但有些服务器不认随机端口要设成固定值。5.3 跑几天后掉线、ping 断断续续这是 W5500 的经典问题根源通常是 SPI 时钟太快或者电源不稳。W5500 内部有 PLLSPI 时钟超过 33MHz 时 PLL 可能失锁导致寄存器读写错乱。把时钟降到 25MHz 或 20MHz 试试我实测 20MHz 跑一周不掉线。电源方面W5500 的峰值电流能到 150mA如果 ESP32 开发板的 3.3V LDO 只有 200mA加上 ESP32 自己的功耗很容易掉压。解决办法是给 W5500 单独供 3.3V或者在模块的 VCC 和 GND 之间并一个 100uF 电解电容加 0.1uF 陶瓷电容。还有一个隐藏问题是网线质量。劣质网线的差分阻抗不匹配W5500 的 PHY 会频繁重连。换一根好网线问题可能就没了。5.4 数据收发错位或丢包数据错位一般是 SPI 传输的 length 设错了或者 TX/RX 缓冲指针没取模。检查t.length是不是字节数乘 8检查 Sn_TX_WR 和 Sn_RX_RD 有没有按 2KB 取模。丢包的话先看 Sn_TX_FSR 和 Sn_RX_RSR 的轮询频率。如果发送任务优先级太低TX 缓冲满了没及时发 SEND 命令数据就丢了。把网络任务的优先级设高一点或者用中断触发发送。下面这张表是我整理的问题速查表遇到问题按表排查能省不少时间现象可能原因排查方法读版本号返回 0x00/0xFF接线错、CS 电平不对、SPI 模式错查 MISO/MOSI、测 CS 上电电平、确认模式 0ping 不通IP/掩码/网关配错、网线没插读回寄存器确认、换网线TCP 连不上Socket 没 OPEN、BSB 算错、端口被防火墙挡查 Sn_SR、确认 BSB0x01sn跑几天掉线SPI 时钟太快、电源不稳、网线差降时钟到 20MHz、加电容、换网线数据错位length 没乘 8、指针没取模检查 t.length、检查 2KB 回绕丢包轮询太慢、TX 缓冲满提高任务优先级、用中断避坑指南W5500 的 RST 引脚不要悬空上电时要给一个至少 500us 的低电平复位否则内部寄存器状态不确定。我习惯在初始化最开始拉低 RST延时 10ms再拉高延时 50ms然后再读版本号。6. 从能跑到跑稳我的调试顺序和几个私藏技巧调试 W5500 我有一套固定顺序按这个来基本不会卡住。第一步不接网线只读版本号确认 SPI 通路。第二步接网线配 IPping 通。第三步开 Socket连服务器发一条数据。第四步跑压力测试连续发 1MB 数据看有没有丢包。第五步挂机 24 小时看会不会掉线。每一步过了再进下一步别跳。几个私藏技巧。第一个W5500 的 Sn_IR 寄存器记录了中断标志收数据、发送完成、超时、连接断开都有对应位轮询时读这个寄存器比读 Sn_SR 更及时。第二个W5500 支持硬件 TCP 校验和Sn_MR 的 bit0 是校验和使能位开了之后 CPU 不用算校验和省不少事。第三个如果项目里同时用 WiFi 和以太网注意 ESP32 的 SPI2 和 WiFi 有引脚冲突SPI2 默认的 GPIO18/19/23 和某些 WiFi 天线配置会打架换 SPI3 或者改引脚映射。最后说个实际体会。W5500 这颗芯片出来很多年了资料多、坑也多但它的硬件 TCP/IP 栈确实省 CPU在 ESP32 上跑个 Web 服务器或者 Modbus TCP 网关很合适。我有个项目用 W5500 做 Modbus TCP 转 RTU 网关ESP32 只负责搬运数据TCP 握手、重传、校验全交给 W5500CPU 占用不到 3%跑了一年多没重启过。关键就是把 SPI 时序搞对、电源搞稳、时钟别贪快。你要是刚开始搞先把时钟设 20MHz等跑稳了再往上加别一上来就 40MHz那是给自己找麻烦。