简介基于STM32F103与W5500以太网控制器的HTTPS访问方案工程面向嵌入式开发者和物联网应用场景用于解决单片机设备通过网页进行远程访问与参数配置的问题。压缩包共102个文件包含45个头文件、42个C源文件以及启动文件、编译脚本、bin/hex固件和Keil工程配置整体仅406KB结构紧凑便于直接导入开发环境使用。代码中提供两套协议组合出厂默认程序采用“HTTP Server NetBIOS 固定IP”并内嵌“梦想版”网页另一套例程采用“HTTP Server NetBIOS DHCP”并内置常规配置页面方便对比学习HTTP Server的两种工作模式掌握DHCP、NetBIOS与固定IP等协议在STM32平台上的实际应用。已有1271人学习下载尤其适合具备一定STM32基础、希望快速搭建网络通信功能的开发者移植参考。1. STM32W5500 做 HTTPS 访问难的不是 HTTP 是 TLS把 HTTPS 客户端跑在 STM32 上和跑在 Linux 板子上完全是两个量级的问题。Linux 上有 OpenSSL、有完整的文件系统、有足够的 RAM而一颗 STM32F407 只有 192KB RAMW5500 又把 TCP/IP 协议栈固化在了芯片内部这意味着你要在应用层手写 HTTP 报文还要在 MCU 上完成 TLS 握手、证书校验、加密通信。很多人第一步就倒在了“W5500 只负责 TCPTLS 握手必须由 MCU 自己算”这个认知上。这篇文章要解决的就是用 STM32 W5500 的硬件协议栈做底搭配 mbedTLS 软件加密库打通一条完整的 HTTPS 访问链路。适合做物联网设备上报、工控数据采集、远程配置下发这几类项目的工程师。读完你能得到一条可复现的移植路径以及那些在调试器里才能看到的坑。2. W5500 的 Socket 层先打通HTTPS 的传输地基2.1 硬件协议栈和 MCU 的分工边界W5500 内部集成了 TCP/IP 协议栈但它只覆盖到传输层。也就是说TCP 的三次握手、四次挥手、ACK 重传、分片重组这些都在 W5500 内部完成MCU 只需要通过 SPI 读写 Socket 的发送/接收缓冲区。但 TLS 层位于 TCP 之上W5500 完全不认识 TLS 记录层的数据格式它只会把 TLS 握手报文当成普通的 TCP 负载原样收发。这个分工决定了代码结构MCU 侧跑 mbedTLSmbedTLS 需要底层提供两个回调函数——send 和 recv这两个函数的内部实现就是去读写 W5500 的某个 Socket 缓冲区。因此移植的第一步不是碰加密库而是先把 W5500 的 Socket 收发调通用裸 TCP 做一次回环测试。我用的是 W5500 的标准驱动库官方提供了 ioLibrary但那是面向通用平台的。实际工程里我习惯自己封装一层 SPI 接口这样能控制片选时序和中断响应。W5500 的 SPI 最高支持 40MHz 左右但 STM32 的 SPI 外设跑到 18MHz 比较稳再高就得看布线质量了W5500 原理图里常用的 SPI 接线是 PA5、PA6、PA7 对应 SCK、MISO、MOSI片选单独用一个 GPIO 控制RST 引脚接 MCU 的普通输出口。2.2 初始化与 Socket 打开的最小代码下面是 W5500 驱动初始化和打开一个 TCP Socket 的代码这一版我直接操作寄存器不引第三方库方便你对照数据手册排查。// SPI 写 W5500 寄存器 void w5500_write_reg(uint16_t addr, uint8_t data) { W5500_CS_LOW(); spi_transfer((uint8_t)(addr 8)); // 地址高字节 spi_transfer((uint8_t)(addr 0xFF)); // 地址低字节 spi_transfer(0x04); // 写模式VDM0RWB1 spi_transfer(data); W5500_CS_HIGH(); } // 打开 Socket 0连接到目标服务器 uint8_t w5500_socket_open(uint8_t *ip, uint16_t port) { // 设置 Socket 0 的目标 IP 和端口 w5500_write_reg(0x0004, ip[0]); // SIPR0 w5500_write_reg(0x0005, ip[1]); w5500_write_reg(0x0006, ip[2]); w5500_write_reg(0x0007, ip[3]); w5500_write_reg(0x0008, (uint8_t)(port 8)); // SPORT0 w5500_write_reg(0x0009, (uint8_t)(port 0xFF)); // Socket 0 模式寄存器TCP w5500_write_reg(0x0400, 0x01); // Sn_MR, 0x01 TCP // Socket 0 命令寄存器OPEN w5500_write_reg(0x0401, 0x01); // Sn_CR, 0x01 OPEN // 等待 OPEN 完成 uint16_t timeout 0; while (w5500_read_reg(0x0401) ! 0) { HAL_Delay(1); if (timeout 200) return 1; // 超时 } // 发送 CONNECT 命令 w5500_write_reg(0x0401, 0x04); // Sn_CR, 0x04 CONNECT timeout 0; while (1) { uint8_t status w5500_read_reg(0x0403); // Sn_SR if (status 0x17) break; // SOCK_ESTABLISHED if (status 0x1D) return 2; // SOCK_CLOSED连接被拒 HAL_Delay(1); if (timeout 5000) return 3; // 连接超时 } return 0; }这段代码开了 Socket 0 并阻塞等待连接建立。注意0x0401是 Sn_CR 命令寄存器写入后需要轮询到它自动清零表示命令执行完毕。0x0403是 Sn_SR 状态寄存器TCP 建立成功后的状态值是0x17SOCK_ESTABLISHED如果变成0x1DSOCK_CLOSED说明对端拒绝了连接。W5500 的寄存器地址是 16 位的高字节是 Socket 基地址偏移Socket 0 的寄存器从0x0400开始Socket 1 从0x0500开始这个规律可以帮你快速定位问题寄存器。2.3 Socket 收发缓冲区怎么设才够用W5500 的 TX/RX 缓冲区大小由寄存器 S0_TX_RX_SIZE地址0x001E和0x001F控制单位是 1KB。数据手册上 2K 是默认值但 HTTPS 场景下这个值不够——TLS 握手阶段一次要发出去几百字节的 ClientHello加上 TCP 头、IP 头2K 勉强能过但到了应用层一次 HTTPS GET 请求的响应头就能超过 2K接收缓冲区太小会直接丢包。我一般把 Socket 0 的 RX 和 TX 都设成 8K。计算方法W5500 的总缓冲区是 64KB8 个 Socket 共享你用几个 Socket 就怎么分。代码上改两个字节w5500_write_reg(0x001E, 0x08); // S0_TX_RX_SIZE, TX 8K w5500_write_reg(0x001F, 0x08); // S0_RX_RX_SIZE, RX 8K缓冲区大小寄存器设置后必须在打开 Socket 之前写入否则不生效。另外Sn_RXBUF_SIZE和Sn_TXBUF_SIZE的地址偏移分别是0x001E socket_num * 0x100这类规律实际驱动代码里直接查数据手册的表最快。3. mbedTLS 移植把 TLS 握手压进 STM32 的内存预算3.1 选 mbedTLS 而不是其他加密库的理由STM32 上能跑的 TLS 实现有几个选择mbedTLSARM 维护、wolfSSL、BearSSL。mbedTLS 在 MCU 生态里最普及因为 STM32CubeMX 直接支持生成带 mbedTLS 的工程而且它的配置宏体系允许你裁剪掉用不到的算法。HTTPS 访问场景只需要 TLS 1.2 客户端、RSA 证书校验、AES-GCM 对称加密这三样全开的话编译后 ROM 占用大约 40-60KBRAM 占用看握手中的临时缓冲通常在 15-30KB 之间。wolfSSL 更省内存但 API 风格和 OpenSSL 差得远调试时资料少BearSSL 的优点是实现精简但它的 API 设计偏底层对 STM32 的硬件随机数、RTC 时钟接入不如 mbedTLS 顺手。做产品我选 mbedTLS出问题能搜到的案例多而且 STM32Cube 的例程就是拿它做的。需要说明的是mbedTLS 是一个软件实现它不依赖 STM32 的硬件加密外设。如果你的 MCU 带 CRYP 或 AES 硬件加速mbedTLS 可以配置成使用硬件加速但移植复杂度会上升。先跑通软件版本再考虑性能优化这是最稳的路径。3.2 裁剪配置关闭不需要的算法mbedTLS 的裁剪在mbedtls_config.h里做重点是关掉你不用的东西。下面是 HTTPS 客户端场景我常用的配置开关// 只用 TLS 1.2不要 TLS 1.0/1.1减小代码体积 #define MBEDTLS_SSL_PROTO_TLS1_2 // 证书校验需要 RSA 和 SHA-256 #define MBEDTLS_RSA_C #define MBEDTLS_SHA256_C // 对称加密只用 AES-GCM握手效率高、安全性好 #define MBEDTLS_AES_C #define MBEDTLS_GCM_C // 关闭调试输出能省 10KB 以上 ROM // #define MBEDTLS_DEBUG_C // 用标准 C 库的 calloc/freeSTM32 的堆要开够 #define MBEDTLS_PLATFORM_C #define MBEDTLS_PLATFORM_MEMORY #define MBEDTLS_MEMORY_BUFFER_ALLOC_C这些宏不是随便关的。MBEDTLS_MEMORY_BUFFER_ALLOC_C这个开关要注意它会让 mbedTLS 自己管理一块静态内存池而不是直接调malloc。好处是内存分配的确定性高坏处是你得提前算好内存池大小。HTTPS 握手期间mbedTLS 需要一块连续的缓冲区做握手消息缓存我算过RSA 2048 位证书校验加 AES-GCM 握手的峰值需求大约是 24KB。你可以在mbedtls_memory_buffer_alloc_init里传入一个 40KB 的静态数组留出冗余。3.3 三个必须实现的底层回调mbedTLS 的 SSL 层不直接接触你的网络接口它通过mbedtls_ssl_set_bio注册两个回调发送函数和接收函数。这两个函数的实现要对接 W5500 的 Socket 读写。同时还需要一个时间函数TLS 握手时校验证书有效期要用。// 发送函数把 buf 里的数据通过 W5500 Socket 0 发出去 static int net_send(void *ctx, const unsigned char *buf, size_t len) { (void)ctx; return w5500_socket_send((uint8_t *)buf, (uint16_t)len); } // 接收函数从 W5500 Socket 0 读取数据 static int net_recv(void *ctx, unsigned char *buf, size_t len) { (void)ctx; return w5500_socket_recv(buf, (uint16_t)len); } // 时间函数返回 Unix 时间戳用于证书有效期校验 static time_t mbedtls_time_cb(void *ctx) { (void)ctx; // 从 RTC 读取时间换算成 Unix 时间戳 return get_unix_timestamp_from_rtc(); } // 在 SSL 初始化后绑定回调 mbedtls_ssl_set_bio(ssl, NULL, net_send, net_recv, NULL); mbedtls_ssl_set_timer_cb(ssl, NULL, mbedtls_timing_set_delay, mbedtls_timing_get_delay);net_recv这里有一个关键点W5500 的recv函数返回的是实际读取的字节数如果 Socket 缓冲区没有数据应该返回MBEDTLS_ERR_SSL_WANT_READ值是-0x6900而不是 0。mbedTLS 的错误处理逻辑会把非负返回值当成有效数据长度返回 0 会触发MBEDTLS_ERR_SSL_CONN_EOF握手会直接中断。这个坑我在调试时卡了两天排查方法是在net_recv里加日志打印每次调用的返回值和当前 Socket 状态。时间回调如果返回 0mbedTLS 会认为证书已过期握手直接失败。STM32 上一般用 RTC 维持时间但掉电后 RTC 会清零所以要么在设备联网后先做 SNTP 对时要么在调试阶段把证书校验的时间检查临时关掉MBEDTLS_SSL_VERIFY_NONE等调通了再打开。3.4 内存预算表你的 STM32 型号够不够资源最小需求推荐配置说明Flash (ROM)60KB100KB 以上含 mbedTLS 库加 W5500 驱动加应用层RAM40KB64KB 以上含 8K Socket 缓冲区加 mbedTLS 内存池堆空间10KB20KBmbedTLS 的证书解析需要动态分配SPI 速率10MHz18-30MHz太低会导致握手超时表格里最容易被忽略的是堆空间。如果你用了MBEDTLS_PLATFORM_MEMORY就绕过了 C 库的堆直接用静态数组如果没开这个宏就要检查startup_stm32f4xx.s里的Heap_Size。默认的0x200512 字节肯定不够调到0x500020KB起步。STM32F103C820KB RAM跑 HTTPS 会非常紧张MBEDTLS_MEMORY_BUFFER_ALLOC_C的静态数组加握手缓冲就占了将近 40KB建议用 STM32F407VG192KB RAM或以上型号。4. 证书与密钥的嵌入式处理从烧写到校验4.1 证书转 C 数组的正确姿势HTTPS 客户端要做两件事校验证书验证服务器身份和提供自己的身份如果服务器要求双向认证。在嵌入式设备里没有文件系统证书必须编译进固件。最常见的做法是用xxd -i之类的工具把 PEM 格式的证书转成 C 数组。但直接用xxd转出来的数组是unsigned char而 mbedTLS 的mbedtls_pk_parse_key需要以字符串形式传入 PEM 数据所以转的时候要在字符串末尾补\0。# 把 CA 证书转成 C 字符串数组注意 -i 选项的输出格式 xxd -i ca_cert.pem ca_cert.c # 编辑 ca_cert.c在数组末尾手工加一个 0x00拿到数组之后初始化证书解析的代码是这样的#include ca_cert.c // 或直接 extern 声明 extern const unsigned char ca_cert_pem[]; extern const unsigned int ca_cert_pem_len; mbedtls_x509_crt ca_cert; mbedtls_x509_crt_init(ca_cert); // 注意最后一个参数是解析剩余长度填 0 表示解析完整数据 int ret mbedtls_x509_crt_parse(ca_cert, ca_cert_pem, ca_cert_pem_len 1); if (ret ! 0) { // 解析失败用 mbedtls_strerror 打印错误码 char err_buf[128]; mbedtls_strerror(ret, err_buf, sizeof(err_buf)); printf(cert parse failed: %s\n, err_buf); }ca_cert_pem_len 1这个细节要特别注意。xxd -i生成的数组是包含末尾换行符的但mbedtls_x509_crt_parse需要你传入包含\0终结符的长度否则解析会失败错误码通常是MBEDTLS_ERR_X509_BAD_INPUT_DATA-0x0080。如果你不用xxd直接在代码里用字符串字面量定义证书内容编译器会自动加\0反而没这个问题。4.2 SSL 配置与握手流程的关键代码证书解析完之后配置 SSL 上下文并发起握手。这块代码我把每一步的错误处理都留了日志输出方便定位具体是哪个环节失败mbedtls_ssl_config conf; mbedtls_ssl_init(ssl); mbedtls_ssl_config_init(conf); // 客户端模式TLS 1.2 mbedtls_ssl_config_defaults(conf, MBEDTLS_SSL_IS_CLIENT, MBEDTLS_SSL_TRANSPORT_STREAM, MBEDTLS_SSL_PRESET_DEFAULT); // 设置证书校验模式需要校验服务器证书 mbedtls_ssl_conf_authmode(conf, MBEDTLS_SSL_VERIFY_REQUIRED); mbedtls_ssl_conf_ca_chain(conf, ca_cert, NULL); // 对接底层收发函数 mbedtls_ssl_set_bio(ssl, NULL, net_send, net_recv, NULL); mbedtls_ssl_set_hostname(ssl, api.example.com); // 用于 SNI 和证书域名校验 // 开始握手 int ret; int timeout 0; while ((ret mbedtls_ssl_handshake(ssl)) ! 0) { if (ret ! MBEDTLS_ERR_SSL_WANT_READ ret ! MBEDTLS_ERR_SSL_WANT_WRITE) { char err_buf[128]; mbedtls_strerror(ret, err_buf, sizeof(err_buf)); printf(handshake failed: %s\n, err_buf); break; } if (timeout 20) { // 最多等 20 次重试 printf(handshake timeout\n); break; } HAL_Delay(100); }mbedtls_ssl_set_hostname不是可选项。即使你的服务器 IP 是固定的只要证书里的 CN 或 SAN 包含域名就必须在握手前把这个函数调了否则证书域名校验会失败返回MBEDTLS_ERR_X509_CERT_VERIFY_FAILED。另外MBEDTLS_SSL_VERIFY_REQUIRED模式下如果设备本地时间不对差得久同样会报证书校验失败。调试阶段可以先用MBEDTLS_SSL_VERIFY_NONE确认握手能通再打开校验查时间问题。4.3 SNTP 对时证书校验里最容易踩的隐藏依赖HTTPS 的证书有效期检查依赖本地时钟。W5500 工程里很多开发者只做 TCP 通信从来没初始化过 RTC结果一接 HTTPS 就报CERT_VERIFY_FAILED排查半天以为是证书没烧对。其实只要用date命令看一眼设备时间就知道问题。解决方法是在 W5500 链路建好后、发起 HTTPS 请求前先走一次 SNTP// 用 W5500 的 UDP Socket 发送 SNTP 请求从时间服务器取回时间戳 uint8_t sntp_request(uint32_t *unix_time) { // 构造 SNTP 请求包48 字节使用 Socket 1 的 UDP // 发送到 ntp.aliyun.com (203.107.6.88) 端口 123 static uint8_t packet[48]; memset(packet, 0, 48); packet[0] 0x1B; // LI0, VN3, Mode3 (client) // 通过 W5500 Socket 1 发送后等等响应 // 收到后取第 40-43 字节的时间戳减去 2208988800UL 得到 Unix 时间戳 }SNTP 请求包的构造很简单0x1B是标准的客户端请求标识。DNS 解析这里不提因为 W5500 不自带 DNS 客户端你需要把 NTP 服务器的 IP 直接硬编码进固件或者自己实现一个简化版 DNS 查询。Wi-Fi 模块场景里一般都有现成的 DNS 解析但纯 W5500 没有。别名 IP 写死之后设备时间就能在每次上电后快速校准。5. HTTPS 请求怎么发把裸 HTTP 报文包进 TLS 记录层5.1 处理 mbedTLS 的 SSL_write 和 W5500 的发送缓冲握手完成后HTTPS 的请求和普通 HTTP 的报文字段完全一样只是经过mbedtls_ssl_write加密后再交给 W5500 发送。但这里有一个性能陷阱W5500 的 Socket 发送缓冲区是 8KB而一次 HTTPS GET 请求的报文可能只有 200-300 字节直接写进去没问题。但如果你的 HTTP 报文头很大比如带了很长的 Cookie 或者自定义 Header超过 8KB 就得分包发送。// 构造 HTTP GET 请求 char request[512]; int req_len snprintf(request, sizeof(request), GET /api/v1/status HTTP/1.1\r\n Host: api.example.com\r\n User-Agent: STM32-W5500/1.0\r\n Connection: close\r\n \r\n); // 通过 TLS 加密发送 int ret mbedtls_ssl_write(ssl, (unsigned char *)request, req_len); if (ret 0) { char err_buf[128]; mbedtls_strerror(ret, err_buf, sizeof(err_buf)); printf(ssl_write failed: %s\n, err_buf); }mbedtls_ssl_write的返回值是实际写入的字节数。如果返回MBEDTLS_ERR_SSL_WANT_WRITE说明底层的 W5500 发送缓冲区暂时满了应该延时重试而不是直接重发整个报文。重发会导致 TLS 记录层出现重复数据服务器会返回解密失败或直接断开连接。5.2 接收响应的分片处理逻辑TLS 记录层的最大长度是 16KB但服务器的响应可能分多个 TLS 记录发过来。W5500 的接收缓冲区是 8KB一次net_recv最多返回 8KB 数据。所以接收循环必须以“读完所有 TLS 记录”为目标而不是读完一次缓冲就算完。uint8_t response[4096]; int total_received 0; while (1) { int ret mbedtls_ssl_read(ssl, response total_received, sizeof(response) - total_received); if (ret 0) { total_received ret; if (total_received sizeof(response)) break; // 防止缓冲区溢出 // 检查 HTTP 报文是否结束找到 \r\n\r\n 并且 Content-Length 已读完 if (http_response_complete(response, total_received)) break; } else if (ret MBEDTLS_ERR_SSL_WANT_READ) { continue; // 底层暂时没数据继续读 } else { break; // 连接关闭或出错 } }这里http_response_complete是你自己写的函数用来检查 Header 里的Content-Length和已经接收到的 Body 长度。如果服务器返回的是Connection: close那读文件到mbedtls_ssl_read返回MBEDTLS_ERR_SSL_CONN_EOF就算结束不需要解析 Content-Length。建议在请求头里强制加Connection: close省去判断报文边界的麻烦。5.3 HTTP 状态码和响应体解析的轻量实现嵌入式设备上没必要引入完整的 HTTP 解析库我一般用两个轻量函数一个找状态码一个从响应体里按 JSON 键值对取值。上代码// 解析 HTTP 状态码例如 HTTP/1.1 200 OK - 200 int http_get_status_code(uint8_t *response) { // 跳过 HTTP/1.1 的前 9 个字符 return atoi((char *)response 9); } // 从响应体里查找 key:value 模式的第一个值 // 适用于服务器返回纯 JSON 的场景 int http_get_json_value(uint8_t *response, const char *key, char *value, int max_len) { char pattern[64]; snprintf(pattern, sizeof(pattern), \%s\, key); char *pos strstr((char *)response, pattern); if (pos NULL) return -1; // 跳过 key 和一个冒号 pos strchr(pos strlen(pattern), :); if (pos NULL) return -1; pos; // 跳过冒号 while (*pos || *pos \t) pos; // 跳过空白字符 if (*pos ) { pos; char *end strchr(pos, ); if (end NULL || end - pos max_len) return -2; memcpy(value, pos, end - pos); value[end - pos] \0; } else { // 处理数字或布尔值读到逗号或右花括号 char *end strpbrk(pos, ,}); if (end NULL || end - pos max_len) return -2; memcpy(value, pos, end - pos); value[end - pos] \0; } return 0; }这段代码能覆盖绝大多数物联网云端接口的返回格式。如果你的服务器返回的是 XML 或者自定义二进制协议把http_get_json_value替换成对应的解析逻辑即可。不建议在 STM32 上跑复杂的 JSON 解析库比如 cJSON纯内存开销就要 4-8KB而且中断安全性和重入性需要额外注意。字符串匹配的方式在响应体小于 4KB 的场景下性能完全够用。6. HTTPS 访问的最小可跑路径与错误码排查清单6.1 从头到尾的最小工程结构按下面的顺序在 STM32CubeMX 生成的工程上逐步叠加代码能最快跑通 HTTPS步骤操作验证方法1初始化 SPI W5500配置静态 IPping 通网关2用 Socket 0 连接服务器的 443 端口服务器日志看到 TCP SYN3移植 mbedTLS配置最小算法集编译通过ROM 占用 120KB4实现 net_send / net_recv / 时间回调握手日志出现 ClientHello5导入 CA 证书开启证书校验握手成功无错误码6SNTP 对时后发 HTTPS GET收到 HTTP 200 响应6.2 mbedTLS 常见错误码一览错误码值含义排查方向MBEDTLS_ERR_SSL_WANT_READ-0x6900底层无数据需重试检查 W5500 接收状态MBEDTLS_ERR_SSL_CONN_EOF-0x6100连接被对端关闭抓 TCP 报文看 RSTMBEDTLS_ERR_X509_CERT_VERIFY_FAILED-0x2780证书校验失败时间是否同步CA 是否完整MBEDTLS_ERR_SSL_ALLOC_FAILED-0x7F00内存不足增大内存池或堆空间MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE-0x7400TLS 报文顺序不对检查 net_recv 是否返回 06.3 一个可以抄走的 openssl 命令调试期间建议在 PC 上用 Wireshark 抓包对比。抓包时同时跑一个 macOS 或 Linux 上的openssl s_client对比正常握手的报文顺序openssl s_client -connect api.example.com:443 -servername api.example.com -state -msg这个命令能看到完整的握手过程包括 ClientHello、ServerHello、Certificate、KeyExchange、Finished。对照 STM32 侧的日志能快速定位是第几帧出了问题。比如 STM32 侧的 ClientHello 发出后服务器没回 ServerHello大概率是 TLS 版本不匹配——mbedTLS 配置成 TLS 1.2但服务器只支持 TLS 1.3这时候要改MBEDTLS_SSL_PROTO_TLS1_2为MBEDTLS_SSL_PROTO_TLS1_3或者同时打开两个版本。HTTPS 访问的调试就是这样的报错信息会精确到错误码关键是顺着错误码往下追不要靠猜。本文还有配套的精品资源点击获取