简介ESP32本地OTA升级参考实现基于ESP-IDF框架对应Arduino生态里的OTAWebUpdater思路但省去了远程OTA服务器适合在局域网内做产品固件迭代的开发者。demo覆盖AP与STA两种WiFi模式核心模块包括HttpServer的URI注册与请求处理原生JavaScript上传页面带进度与速度显示基于GPIO2电平检测的固件自检和失败自动回滚另有BuildVer.sh脚本按编译时间生成版本号。整个代码包共1116个文件压缩后35.37MB文件以ESP-IDF构建生成的obj、lib静态库、cmake工程文件为主附带elf/bin固件和中转产物同时也有易读的c/cpp源码、h头文件、html前端与sh工具脚本工程目录完整便于对照学习编译产物与源码的关系。对不熟悉ESP-IDF构建流程的读者来说可通过这些中间产物理解整个编译链路的组成对已具备基础的开发者则可直接复用HttpServer、OTA分区和回滚检测这几段核心逻辑快速为自己的ESP32设备接入本地OTA能力。目前已有3807人浏览学习。 有一次我拿着一块ESP32开发板去现场调设备发现业务逻辑里有个边界条件写错了。设备的USB口已经封在机柜里要更新固件就得拆外壳、拔线、带回办公室重新烧录。当时我就在想如果这设备能连上局域网我掏出手机打开浏览器选一个bin文件传上去它自己写完Flash、校验、切换分区、重启那该多省事。这个需求在ESP32上完全可行用ESP-IDF的HttpServer模式就能做出一套本地OTA升级功能体验上基本对标Arduino生态里那个经典的OTAWebUpdater例程。这篇文章我打算把整套方案完整拆开讲一遍重点放在三件事上OTA的分区与启动机制、HttpServer模式下固件上传的完整代码实现、以及我实际跑流程时踩过的坑和回滚策略。如果你正在用ESP-IDF做设备固件升级或者想把Arduino下的OTAWebUpdater移植到IDF工程里这篇内容可以直接照着实操。1. 为什么在ESP-IDF里做本地OTA是个刚需场景设备一旦部署出去升级手段就成了逃不开的话题。串口和JTAG适合开发阶段设备装在机柜、墙内、车上的时候根本不现实。云端OTA当然是大厂方案但涉及平台接入、设备认证、流量成本很多中小项目和私有化部署根本用不上。夹在中间最舒服的形态就是局域网内HTTP升级设备开一个Web服务浏览器或脚本把固件丢给它它自己完成后续一切。这种模式不需要额外服务器不需要公网IP也不依赖外部网络状态尤其适合产线批量刷新、现场售后维护和实验室设备更新。那为什么选ESP-IDF而不是ArduinoArduino下OTAWebUpdater确实几行代码就跑起来但到了产品化阶段我通常还是会切回ESP-IDF。原因很实际IDF的内存分配更透明组件化结构方便裁剪安全特性固件签名、Flash加密、回滚也更完整。Arduino库封得太死出问题排查起来不如直接看IDF源码来得痛快。另一方面ESP-IDF官方提供了esp_http_server和esp_ota_ops这两个组件组合起来正好实现一套不依赖任何第三方库的本地OTA和Arduino那个例程的交互逻辑几乎一一对应网页里选一个bin文件点升级进度走完自动重启。这里的“本地”两个字值得再强调一下。很多人一听说OTA就想到云端实际上本地OTA的适用范围比想象中广设备在产线上还没装箱用本地OTA批量写固件不用反复拔USB设备已经部署到客户内网售后人员连上同一个局域网就能远程操作一些对公网隔离有要求的系统本地升级甚至是唯一可选的更新通道。所以这篇文章的定位很明确就是做一套能在局域网里稳定跑、可复现、出问题能回滚的固件升级方案。2. OTA升级背后的完整工作链路从固件上传到分区切换想把这套代码写明白先得把OTA的运行机制吃透。我尽量用最直白的方式讲。2.1 Flash分区与启动顺序ESP32的Flash里不是只放一个固件而是划分成很多区域。做OTA至少需要两个app分区一个叫factory是出厂固件另一个叫ota_0用来放新固件。更稳妥的做法是再加一个ota_1形成三份固件的滚动布局。此外还有nvs存参数、phy_init射频校准、ota_data记录从哪个分区启动等数据分区。上电后引导流程是这样的ROM里的一级bootloader先执行然后二级bootloader读ota_data分区判断当前应该从factory还是ota_0还是ota_1启动。如果没有ota_data标记默认启动factory。这套机制的巧妙之处在于升级不需要覆盖旧固件而是把新固件写到另一个空白分区确认没问题后再切换启动标记这就为回滚留了后路。2.2 一次完整升级经历哪些阶段一次HTTP升级从代码角度拆开看其实是六个连续动作缺一个都不算完整接收固件数据流HTTP Server拿到POST请求后循环调用httpd_req_recv读取body内容。写入目标分区把读到的字节流通过esp_ota_write逐块写入ota_0或ota_1。固件校验写完后调用esp_ota_end内部会校验镜像头的magic、校验和以及固件末尾的MD5。提交启动标记校验通过后调用esp_ota_set_boot_partition把ota_data改成指向新分区。设备重启调用esp_restart让新固件生效。新固件健康确认新固件启动后调用esp_ota_mark_app_valid_cancel_rollback告诉bootloader“我已经跑起来了别回滚”。可以粗浅地类比成买鞋试穿新鞋先放在旁边鞋柜里不急着扔旧鞋穿上走两步觉得合适MD5校验通过、新固件能正常启动再留下不合适还能换回旧鞋回滚到上一个分区。2.3 分区状态与回滚是怎么发生的在没有启用回滚功能时升级后重启如果新固件崩溃大概率是不断重启甚至可能变砖。ESP-IDF提供了一套软回滚机制来兜底背后的核心是每个app分区都有状态记录存储在OTA Data区域。状态流转大致如下状态含义发生时机ESP_OTA_IMG_UNDEFINED初始/未知esp_ota_begin之后ESP_OTA_IMG_NEW新固件已写入且校验通过esp_ota_end成功ESP_OTA_IMG_PENDING_VERIFY正在等待健康确认新分区作为启动分区后ESP_OTA_IMG_VALID已确认健康新固件调用mark_app_validESP_OTA_IMG_ABORTED升级中止写入失败或调用abortESP_OTA_IMG_INVALID镜像非法校验不通过或审计失败启用回滚之后bootloader启动一个处于PENDING_VERIFY状态的新固件时如果新固件没有在预期时间内调用标记有效接口或者启动过程中反复复位bootloader就会自动把启动标记切回上一个有效分区。这个机制给OTA兜上了最后一道安全网后面讲代码和踩坑时你还会反复遇到这几个状态。3. ESP-IDF工程搭建分区表、sdkconfig与目录结构理论部分过了开始动手。我先说工程结构再说分区表怎么配最后列一下必须打开的menuconfig选项。3.1 准备工程与分区表文件创建一个ESP-IDF基础工程的方式不多讲了简单提一句用idf.py create-project local_ota即可创建干净模板。关键在于项目根目录下要放一个自定义分区表CSV文件命名随意我习惯叫partitions_ota.csv。以下是我在8MB Flash模块上用的方案# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 2M, ota_0, app, ota_0, 0x210000, 2M, ota_1, app, ota_1, 0x410000, 2M,三个app分区各2MB空间很宽裕。如果你用的还是最常见的4MB Flash开发板建议改成三个1MB分区再多就放不下了# Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, factory, app, factory, 0x10000, 1M, ota_0, app, ota_0, 0x110000, 1M, ota_1, app, ota_1, 0x210000, 1M,然后进入menuconfig把分区表指定成这个文件同时开启回滚支持idf.py menuconfig关键配置项Partition Table → Custom partition table CSV → 填partitions_ota.csvBoot ROM Behavior → Enable app rollback support → 勾选如果不需要回滚可以不勾但建议勾Component config → HTTP Server → 把Stack size从默认的4096改到8192以上避免处理上传时栈溢出3.2 编译时容易忽略的两个细节第一分区表里每个app分区的尺寸必须大于等于你实际编译出来的固件体积。如果固件超了编译过程可能不会报错但烧录或OTA写入时会失败或者运行时直接异常。我习惯在写完代码后看一眼编译日志末尾输出的binary大小确认离分区上限还有余量。第二OTA Data分区不需要手动写进CSVESP-IDF构建系统检测到有ota_0/ota_1时会自动预留位置。不用画蛇添足加错了反而报错。4. 核心代码实现HTTP Server注册与OTA升级回调工程结构就绪后看主程序代码。我的实现思路是设备连上局域网后启动HTTP Server访问根路径返回一个上传页面页面用application/octet-stream编码提交bin文件到/ota接口接口边收边写校验通过后重启整体等价于Arduino下OTAWebUpdater的交互流程。完整的主程序框架如下这段代码在ESP-IDF v5.x下直接编译可用。#include string.h #include freertos/FreeRTOS.h #include freertos/task.h #include esp_log.h #include esp_wifi.h #include esp_event.h #include esp_netif.h #include nvs_flash.h #include esp_ota_ops.h #include esp_http_server.h static const char *TAG local_ota; static int ota_progress 0; #define MIN(a, b) ((a) (b) ? (a) : (b)) /* 根路径页面浏览器访问设备IP时返回 */ static esp_err_t root_get_handler(httpd_req_t *req) { const char resp[] htmlheadmeta charsetutf-8/headbody h2ESP32 本地OTA/h2 form methodPOST action/ota enctypeapplication/octet-stream input typefile namefirmware accept.binbrbr input typesubmit value开始升级 /form/body/html; httpd_resp_set_type(req, text/html); return httpd_resp_send(req, resp, HTTPD_RESP_USE_STRLEN); } /* 进度查询接口前端可以轮询 */ static esp_err_t progress_get_handler(httpd_req_t *req) { char buf[16]; snprintf(buf, sizeof(buf), %d, ota_progress); httpd_resp_set_type(req, text/plain); return httpd_resp_send(req, buf, HTTPD_RESP_USE_STRLEN); } /* 核心OTA固件上传处理 */ static esp_err_t ota_post_handler(httpd_req_t *req) { char buf[1024]; esp_ota_handle_t ota_handle; const esp_partition_t *update_partition esp_ota_get_next_update_partition(NULL); int content_len req-content_len; int received_total 0; if (update_partition NULL) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, no OTA partition); return ESP_FAIL; } esp_err_t err esp_ota_begin(update_partition, OTA_WITH_SEQUENTIAL_WRITES, ota_handle); if (err ! ESP_OK) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, ota begin failed); return ESP_FAIL; } ota_progress 1; while (received_total content_len) { int remaining content_len - received_total; int to_read MIN(remaining, sizeof(buf)); int received httpd_req_recv(req, buf, to_read); if (received 0) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, recv failed); esp_ota_abort(ota_handle); return ESP_FAIL; } err esp_ota_write(ota_handle, buf, received); if (err ! ESP_OK) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, ota write failed); esp_ota_abort(ota_handle); return ESP_FAIL; } received_total received; ota_progress (received_total * 100) / content_len; } /* 这一步内部做完整固件校验MD5不对这里就会失败 */ err esp_ota_end(ota_handle); if (err ! ESP_OK) { ESP_LOGE(TAG, esp_ota_end failed: %s, esp_err_to_name(err)); httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, ota validate failed); return ESP_FAIL; } err esp_ota_set_boot_partition(update_partition); if (err ! ESP_OK) { httpd_resp_send_err(req, HTTPD_500_INTERNAL_SERVER_ERROR, set boot partition failed); return ESP_FAIL; } ota_progress 100; httpd_resp_set_type(req, text/plain); httpd_resp_sendstr(req, upgrade ok, rebooting...); vTaskDelay(pdMS_TO_TICKS(500)); esp_restart(); return ESP_OK; } static void start_http_server(void) { httpd_config_t config HTTPD_DEFAULT_CONFIG(); config.stack_size 10240; config.recv_wait_timeout 30; httpd_handle_t server NULL; if (httpd_start(server, config) ESP_OK) { httpd_uri_t root_uri { .uri /, .method HTTP_GET, .handler root_get_handler }; httpd_register_uri_handler(server, root_uri); httpd_uri_t progress_uri { .uri /progress, .method HTTP_GET, .handler progress_get_handler }; httpd_register_uri_handler(server, progress_uri); httpd_uri_t ota_uri { .uri /ota, .method HTTP_POST, .handler ota_post_handler }; httpd_register_uri_handler(server, ota_uri); } } static void wifi_init_sta(void) { ESP_ERROR_CHECK(nvs_flash_init()); ESP_ERROR_CHECK(esp_netif_init()); ESP_ERROR_CHECK(esp_event_loop_create_default()); esp_netif_create_default_wifi_sta(); wifi_init_config_t cfg WIFI_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_wifi_init(cfg)); wifi_config_t wifi_config { .sta { .ssid YOUR_SSID, .password YOUR_PASSWORD, }, }; ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, wifi_config)); ESP_ERROR_CHECK(esp_wifi_start()); } void app_main(void) { wifi_init_sta(); start_http_server(); ESP_LOGI(TAG, local OTA server started, visit device IP to upload firmware); }代码里有几个点我想专门拎出来说。第一处是HTML表单的enctypeapplication/octet-stream。如果你下意识用了multipart/form-data浏览器POST出去的body会带上boundary分隔线和文件名头写入分区的bin文件就全废了升级必失败。Arduino那个OTAWebUpdater用的也是这种少见但有效的表单编码目的就是让整个HTTP body就是裸的固件二进制。第二处是httpd_req_recv配合循环读取。固件可能几百KB甚至几MB不能一次性读入内存ESP32的可用RAM根本扛不住。我这里的做法是固定1KB缓冲区边读边用esp_ota_write写Flash内存占用恒定这是OTA实现的基本素养。第三处是esp_ota_end的作用。它不仅是收尾还负责把整包固件做最终校验包括镜像头、段表、MD5。很多人以为校验必须自己算一遍MD5其实不用esp_ota_end内部已经做了。如果你在上传过程中手动算一个额外的MD5也不是不行但至少别把这一步省略。我在调试过程中故意用损坏的bin测试过esp_ota_end会返回ESP_ERR_OTA_VALIDATE_FAILED此时旧固件完全不受影响这就是前面讲的状态机在实际代码里的表现。5. 编译烧录与实测验证网页上传、curl测试与升级闭环代码写完了验证环节才是真正暴露问题的地方。我建议你准备两个不同版本的固件用来测试升级比如v1打印app version: 1v2打印app version: 2。这样升级后看一眼串口日志就知道新固件到底有没有跑起来。5.1 编译烧录与首次启动工程根目录执行idf.py build flash monitor烧录完成后开发板会连接你配置的WiFi串口日志里会打印本地OTA服务已启动的提示。给设备分配到的IP做个记录比如192.168.1.100。在浏览器打开这个IP应该能看到一个非常朴素的升级页面一个文件选择框加一个“开始升级”按钮。5.2 用命令行模拟网页上传除了网页我更推荐你掌握curl的测试方式因为自动化回归的时候非常方便。注意这里不能用-F参数-F会强制走multipart必须用--data-binary把整个文件内容作为原始body发送curl --data-binary build/local_ota.bin \ -H Content-Type: application/octet-stream \ http://192.168.1.100/ota正常情况下串口会看到字节数累加的日志上传完成后等待几百毫秒设备自动重启新固件的版本号出现在串口输出里。从按回车到新固件跑起来整个过程大概十秒出头具体取决于固件大小和局域网质量。5.3 故意制造一次失败升级这一步我强烈建议你测试。随便找一个非bin文件或者把一个正常的bin文件改坏几个字节再执行一次上面的curl命令。这时候观察两个现象第一HTTP响应应该是一个500错误第二设备不会重启旧固件还在正常运行。这说明esp_ota_end的校验确实兜住了坏包。再加上你前面开了rollback支持即使遇到新固件启动就崩溃的极端情况设备也会在几次复位后自动回滚到上一个有效版本。这个测试过程很值它把整套升级机制最脆弱的一环提前暴露在了实验室里。6. 实战中的踩坑记录从固件损坏到回滚策略实操过程中有几个坑是高频出现的我把现象、原因和解决办法整理出来你可以拿来当排错手册用。6.1 升级后网页转圈很久才断线设备重启但浏览器报错这个严格来说不算bug。浏览器提交表单后一直在等服务端响应但OTA handler在返回响应前就调用了esp_restart连接被TCP层断掉浏览器表现就是“页面无响应/连接重置”。我在程序里特意做了500ms延时先把完整响应发出去再重启实测大多数浏览器能收到“upgrade ok”提示但偶尔还是会出现连接重置。不用担心看一眼串口日志就能确认升级是否成功。如果前端要做得更优雅可以让页面轮询/progress接口不要用同步表单提交。6.2 接收中途断线导致写入一半的“残废”固件如果你用curl上传时网络闪断httpd_req_recv会返回0或者-1这时代码走了esp_ota_abort分支。这个调用会把当前OTA会话标记为中止之前写入的半个分区数据基本不会影响系统运行。但要注意如果你没有调用abort而是直接返回那这个分区的状态会一直挂在未完成状态下次升级可能出现异常。所以代码里的每一个失败分支都不能省abort是OTA操作里对“半途而废”唯一正确的处理方式。6.3 esp_ota_end返回ESP_ERR_OTA_VALIDATE_FAILED但旧系统仍能启动这个现象第一次遇到可能吓一跳以为是升级把设备搞坏了。其实这正是分区机制的防护效果。校验失败意味着新分区不可用bootloader下次启动仍然依据ota_data里的旧标记所以旧系统安然无恙。印到日志里的esp_ota_end failed: ESP_ERR_OTA_VALIDATE_FAILED只是一个响亮的警报告诉你上传的固件有问题通常原因是不小心传了HTML页面内容、传了旧平台固件、或者网络传输被代理改写了body。6.4 启用了回滚但新固件每次启动都被回滚成旧版本如果你开启CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE有一个责任必须落到新固件身上新固件启动后明确告诉bootloader“我一切正常”。否则bootloader会认为新固件未确认健康一直回滚。解决办法是在新固件的app_main启动早期补上这段健康确认代码const esp_partition_t *running esp_ota_get_running_partition(); esp_ota_img_states_t state; if (esp_ota_get_state_partition(running, state) ESP_OK) { if (state ESP_OTA_IMG_PENDING_VERIFY) { ESP_LOGI(TAG, current app is pending verify, mark valid); esp_ota_mark_app_valid_cancel_rollback(); } }这段代码要放在功能初始化完成、确认系统能跑起来之后而不是放第一行。如果新固件在初始化早期就崩溃回滚机制反而成了救命稻草。7. 加固方向签名验签与安全远程升级到这里本地OTA的基本链路已经完整但如果你对着的是真实产品我建议再往前走一步加固件签名验证。用浏览器上传bin的裸HTTP方案放在可信内网没问题放在开放网络里风险很大任意一个能访问这个网页的人都能刷入自己的固件等于把你的设备完全暴露了。ESP-IDF里有一个比较成熟的组合方案开启Secure Boot后用idf.py signed-app对固件签名bootloader每次启动只认签名过的镜像。这样即使别人拿到你的bin文件没有私钥也无法伪造固件。还可以配合Flash Encryption做固件加密进一步防止Flash被物理读取。这两块配置起来要改不少menuconfig选项涉及密钥烧录和eFuse操作不当确实可能把芯片永久锁死我建议在开发板上先完整验证一遍流程再决定要不要上量产。如果你是打算做公网远程升级那就得把HTTP替换成HTTPS同时固件端做设备身份校验比如预置证书或token。这个方向已经超出本文范围但底层OTA写入和校验逻辑完全一样换的只是传输层。我个人的习惯是在OTA handler里把接收到的字节数、目标分区、最终校验结果全部打日志升级完成后还会在新固件启动日志里打印当前app版本号方便确认跳转成功。套用这个思路做任何固件升级方案过程都会透明很多。建议你先在小板子上把整套升级和回滚流程跑通一次再考虑上生产环境。本文还有配套的精品资源点击获取