电子产品世界 » 论坛首页 » 嵌入式开发 » MCU » 【AtomS3R-M12】网页登录与OTA固件升级项目

共1条 1/1 1 跳转至页

【AtomS3R-M12】网页登录与OTA固件升级项目

高工
2026-11-16 18:24:46     打赏

第一章 项目介绍

本项目基于 ESP32 开发板,使用 Arduino 框架完成一个带网页登录和 OTA 固件升级功能的小型 Web 服务器。设备启动后连接指定 Wi-Fi,监听 80 端口,访问根路径时弹出浏览器登录窗口,用户必须输入账号密码后才能查看页面内容。

系统保留多账号登录能力,但仅 admin 账号拥有固件升级权限,避免普通登录用户直接修改设备固件。除浏览器上传固件的 OTA 方式外,程序同时保留 Arduino IDE 的 ArduinoOTA 无线升级能力,便于开发阶段快速迭代固件。

项目当前采用多文件结构,主程序只负责 Wi-Fi 连接与模块调度,Web 服务、网页界面和 OTA 服务分别封装在不同文件中,方便后续维护和功能扩展。

第二章 设计思路与实现过程

OTA 概述

OTA 是 Over-The-Air 的缩写,中文叫空中下载或无线固件升级。简单说,就是设备不通过 USB 数据线,而是通过无线网络接收新的固件程序并完成自我更新。本项目中 ESP32 连接 Wi-Fi 后,支持两种 OTA 方式:一种是在 Arduino IDE 中选择设备的网络端口直接上传固件,另一种是通过浏览器打开设备的升级页面上传 .bin 固件文件。

OTA 是如何实现功能的

核心原理涉及双分区机制和固件切换。

1. 双分区结构

在采用双 OTA 分区方案时(例如 Default 4MB with spiffs),ESP32 的 Flash 中包含 ota_0、ota_1 两个应用分区,以及一个 otadata 分区,用于记录当前应从哪个应用分区启动。第一次 USB 烧录的固件写入第一个应用分区(ota_0);OTA 升级时,新固件写到另一个空闲分区(比如 ota_1);写入并校验成功后,Update 库会更新 otadata 指向新分区,随后设备重启,从新分区运行新固件。这样在写新分区的过程中即使失败,旧分区内容也不会被破坏,设备仍可运行旧固件;但需要说明的是,如果新固件已经切换为启动分区后无法正常运行,Arduino 默认不会自动回滚,此时仍需通过 USB 重新烧录恢复。

otadata 分区固定占用 8KB 空间,由两个 4KB 扇区组成,分别保存一个 esp_ota_select_entry_t 结构,对应 ota_0 与 ota_1 两个应用槽。每个条目包含 ota_seq(启动序号)、ota_state(分区状态)和 crc(校验值)。设备上电时,引导程序先校验两个条目的 CRC,只认可校验有效且状态正常的分区,再从有效分区中选择 ota_seq 较大的一个启动。OTA 升级时,Update 库会向目标分区的条目写入比当前序号大 1 的 ota_seq,并更新状态与 CRC;重启后引导程序按新序号选择新固件,两个槽位就这样交替递增,形成乒乓式切换。如果某个条目的 CRC 不匹配,会被视为无效,不参与启动选择;首次 USB 烧录时 otadata 被擦除,两个条目均无效,引导程序默认从第一个应用分区 ota_0 启动。

1.ArduinoOTA 库

ArduinoOTA 库封装了网络监听、固件接收、分区写入、校验和重启的完整流程。开发者只需要调用 begin() 和 handle() 即可。

2.Update 库(网页 OTA)

网页 OTA 使用 Update 库直接操作 Flash:

Update.begin():分配写入空间,指定写入类型为 U_FLASH。

Update.write(buf, size):把浏览器上传的固件分块写入 Flash。

Update.end(true):结束写入并校验,返回成功或失败。

Update.abort():失败时中止,避免写入不完整的固件。

4. 权限控制

本项目中,网页 OTA 只允许 admin 账号操作。上传开始前先用 authorizeAdmin() 校验身份,未授权则拒绝写入,防止普通用户随意刷固件。

OTA 的优势

1. 无需拆机、无需连线:设备安装到现场后(比如装在盒子里、高处、户外),不需要拆下来接 USB,直接远程升级,维护成本极低。

2. 批量升级方便:如果有多台设备,可以同时或分批通过网络推送固件,比逐台 USB 烧录效率高得多。

3. 双分区安全可靠:升级失败不影响旧固件运行,设备可恢复,降低了升级变砖的风险。

4. 快速迭代:开发阶段改完代码直接无线上传,省去反复插拔数据线的麻烦,加快调试节奏。

5. 支持多种升级通道:本项目同时支持 IDE 网络端口和浏览器网页上传,开发者可以根据场景灵活选择。

注意事项

1. 首次必须通过 USB 烧录:设备内部必须已经运行一个包含 Wi-Fi 连接和 OTA 服务的固件,无线升级链路才成立。全新设备或固件被破坏的设备,只能先用 USB 串口烧录恢复。

2. 新固件必须保留 Wi-Fi 与 OTA 代码:每次上传的新固件都必须保留 WiFi.begin、ArduinoOTA.begin、ArduinoOTA.handle 以及网页上传路由。如果新固件删除了这些代码,或 Wi-Fi 名称密码写错,升级后设备将失去无线升级能力,只能重新用 USB 烧录

3. 只上传应用固件:网页升级只能选择 Arduino IDE 或 arduino-cli 导出的应用固件(如 07HttpAuthCallbackInline.ino.bin),不能上传 merged.bin、bootloader.bin、partitions.bin 或完整合并镜像,否则会写入失败或破坏分区。

4. 分区方案必须包含 OTA 分区:烧录基础固件时,要选择带有 ota_0、ota_1 和 otadata 分区的方案,例如 Default 4MB with spiffs 等常见双分区方案。若选择了 No OTA、Huge APP 等单分区方案,Update.begin 会直接失败。

5. 固件体积不能超过 OTA 分区容量:双分区方案下每个应用分区只有约一半 Flash 空间。若固件过大,编译阶段就可能报错,或上传时 Update.begin 返回空间不足。应精简库依赖或调整分区表。

6. 升级期间保持供电和网络稳定:上传、写入和重启过程中不要断开电源、拔掉网线、重启路由器或关闭浏览器页面。写 Flash 时掉电可能造成固件不完整:写新分区阶段失败时旧固件仍可运行,但若新固件已经切换为启动分区后无法正常运行,Arduino 默认不会自动回滚,只能通过 USB 重新烧录恢复,因此升级期间务必保证供电和网络稳定。

7. 主循环不能长时间阻塞:ArduinoOTA.handle 和 WebServer.handleClient 必须被频繁调用。若 loop 中存在长时间 delay、while 死循环或耗时任务,OTA 请求得不到及时处理,可能超时失败,甚至触发看门狗复位。

8. 电脑与设备必须在同一局域网:设备应连接 2.4GHz Wi-Fi。不要在设备与电脑之间使用不同网段、访客网络或开启 AP 隔离。若电脑启用了 VPN 或代理,也可能导致局域网地址无法访问,需要临时关闭或设置分流。

9. 防火墙需要放行局域网访问:Windows 防火墙或第三方安全软件可能拦截 80 端口访问和 Arduino IDE 的网络端口发现。测试时可先将当前网络设置为专用网络,并为 Arduino IDE 添加允许规则。

10. 网页 OTA 权限与安全:网页升级仅对 admin 账号开放,上传开始前必须完成认证与权限校验,未授权时不能调用 Update.begin。本项目使用 HTTP 明文传输且未设置 ArduinoOTA 密码,只适合可信局域网内测试。正式使用应增加 OTA 上传密码、HTTPS 加密和固件签名校验。

11. 升级后 IP 可能变化:设备重启后会重新向路由器申请地址,DHCP 环境下 IP 可能改变。若原地址无法访问,应重新通过串口日志(波特率 115200)或路由器设备列表确认新的 IP 地址。

12. 失败优先查看串口日志:Update.printError 会把具体错误原因输出到串口,例如空间不足、写入失败、校验失败等。发现升级异常时应先以 115200 波特率连接串口,根据日志判断问题,而不是反复盲目重试。

网页登录采用 HTTP Basic Authentication 思路,由 WebServer 的 authenticate 接口读取浏览器提交的用户名,再在本地账号表中查找对应密码并完成校验。账号表使用以 NULL 结尾的结构体数组,便于扩展多个用户。认证成功后根据用户名决定显示内容,admin 用户额外显示固件升级入口,其他用户只显示普通登录成功信息。

固件升级采用 ESP32 的 Update 库。浏览器通过 multipart/form-data 上传 .bin 文件,服务端在上传开始阶段先进行 admin 权限校验,只有校验通过才调用 Update.begin 准备 OTA 分区。上传过程中分块调用 Update.write 写入数据,完成后调用 Update.end 校验并切换启动分区,最后重启设备使新固件生效。

为了使结构清晰,网页 HTML、CSS、JavaScript 全部放在 web_pages 模块;账号表、认证逻辑以及首页和升级页的 GET 路由放在 web_server 模块;ArduinoOTA、网页 OTA 状态机、Update 写入逻辑以及 /update 的 POST 上传路由放在 ota_service 模块。主 .ino 只做系统启动和循环调用,避免所有代码集中在一个文件中。

实现思路:USB 烧录与 Wi-Fi OTA 升级

本项目的固件烧录与升级分为两个阶段:第一次必须通过 USB 串口烧录,使设备运行包含 Wi-Fi 与 OTA 功能的基础固件;之后即可通过同一局域网内的 Wi-Fi 进行无线 OTA 升级,无需再次连接 USB 线。下面按第一次通过 USB 烧录、后续通过 Wi-Fi 进行 OTA 升级、常见问题排查三个部分说明。

一、第一次通过 USB 烧录

ESP32 出厂时内部没有可运行的应用固件,或者固件中不包含本项目的 OTA 能力,因此第一次必须使用 USB 数据线连接电脑与开发板,通过 Arduino IDE 或 arduino-cli 将编译好的固件烧录到 Flash 中。

烧录前需要在代码中填写正确的 Wi-Fi 名称和密码,选择与开发板匹配的型号和串口,并确认分区方案包含 OTA 分区。烧录成功后设备自动重启,连接 Wi-Fi 并通过串口输出当前 IP 地址。此时设备已经具备网页登录、浏览器上传固件和 Arduino IDE 网络 OTA 三种能力。

第一次 USB 烧录的目的,本质上是把一个“支持 OTA 的引导固件”写入设备。只有这个基础固件正常运行,后续的无线升级链路才成立。

二、后续通过 Wi-Fi 进行 OTA 升级

基础固件运行后,设备会在 loop 中持续调用 otaServiceHandle 和 webServerHandle 两个封装函数。前者内部调用 ArduinoOTA.handle,负责响应 Arduino IDE 的网络端口发现与固件推送;后者内部调用 server.handleClient,负责响应浏览器的网页访问与固件上传。

浏览器 OTA 的流程为:电脑与设备连接同一局域网,访问设备 IP 并使用 admin 账号登录,进入固件升级页面后选择 .ino.bin 应用固件并提交。服务端在上传开始阶段先校验 admin 权限和上传字段,通过后调用 Update.begin 预留 OTA 分区;上传过程中分块调用 Update.write 写入数据;上传完成后调用 Update.end 校验固件并切换启动分区,最后发送成功页面并调用 ESP.restart 重启设备。重启后设备从新分区启动,完成无线升级。

Arduino IDE OTA 的流程为:在 Arduino IDE 的端口列表中选择设备的网络端口,点击上传后 IDE 通过 Wi-Fi 将编译好的固件发送给设备,ArduinoOTA 库完成写入与重启。两种 OTA 方式共用同一套 OTA 分区和启动机制,只是上传通道不同。

实现过程

1:先连接 Wi-Fi

setup() 中的 WiFi.begin() 让 ESP32 接入局域网,这是无线升级的前提。

2:初始化 OTA 服务

ArduinoOTA.begin() 启动 OTA 服务,使 ESP32 能够接收 Arduino IDE 发来的固件。

3:循环处理升级请求

loop() 中的 ArduinoOTA.handle() 会持续检查并处理 OTA 连接、固件接收等操作,因此必须反复执行。

4:从 Arduino IDE 上传

ESP32 连上 Wi-Fi 后,Arduino IDE 通常会发现对应的网络端口。选择该端口并点击“上传”,IDE 就会通过 Wi-Fi 将编译后的固件发送给 ESP32。

5:写入并重启

ESP32 接收到完整固件后,将其写入专用的 OTA 分区,校验成功后自动重启,运行新固件。

简单来说就是:连接 Wi-Fi → 启动 OTA 服务 → 循环接收请求 → IDE 无线发送固件 → ESP32 写入并重启。

当前代码没有调用 ArduinoOTA.setPassword(),因此也没有设置 OTA 上传密码,适合在可信的局域网内测试。

需要注意,新上传的固件也必须保留 Wi-Fi 连接和 OTA 相关代码,否则升级后设备将失去无线升级能力,只能重新通过 USB 烧录恢复。

三、常见问题排查

问题一,浏览器无法打开设备页面。首先查看串口输出的 IP 地址,确认电脑与设备在同一局域网;其次检查路由器是否开启 AP 隔离或访客网络隔离;最后确认防火墙没有拦截局域网访问。

问题二,网页升级失败。确认上传的是 .ino.bin 应用固件而非 merged.bin、bootloader.bin 或 partitions.bin;确认分区方案支持 OTA;检查上传期间是否断电、断网或关闭页面;查看串口输出的 Update 错误信息判断具体原因。

问题三,Arduino IDE 看不到网络端口。确认设备已成功连接 Wi-Fi 且基础固件包含 ArduinoOTA.begin;确认电脑与设备在同一网段;尝试重启 Arduino IDE、设备或路由器;检查防火墙是否允许 Arduino IDE 的网络发现。

问题四,升级后设备无法启动或无法再次 OTA。这通常是因为新固件 Wi-Fi 配置错误、缺少 OTA 代码或程序崩溃。此时只能通过 USB 重新烧录一个正常的基础固件来恢复。

第三章 程序流程图与代码编写步骤

3.1 程序流程

上电启动 → 初始化串口 → 连接 Wi-Fi → Wi-Fi 失败则延时重启 → Wi-Fi 成功则初始化 OTA 服务 → 注册首页和升级页 GET 路由 → 注册固件上传 POST 路由 → 启动 WebServer → 循环调用 otaServiceHandle(内部执行 ArduinoOTA.handle)与 webServerHandle(内部执行 server.handleClient)。

访问 / 根页面时,程序先执行 HTTP 认证;认证失败返回 401;认证成功后,如果是 admin 显示带 iOS 风格升级入口的首页,其他账号显示相同登录信息但不显示升级按钮。

访问 GET /update 时,程序要求 admin 权限;普通账号返回 403。进入升级页面后选择 .bin 固件并提交,表单通过 POST /update 上传。上传开始再次校验 admin 权限和字段名,通过后 Update.begin;上传过程 Update.write;上传结束 Update.end。成功后返回成功页面并重启,失败则返回错误提示,不重启设备。

各接口的 HTTP 状态码对应关系为:访问首页 / 时,认证失败返回 401 并要求重新认证;访问 GET /update 时,未认证返回 401,已认证但不是 admin 返回 403;提交 POST /update 时,未认证返回 401,已认证但不是 admin 返回 403,admin 上传但未收到文件返回 400,上传字段不是 firmware、写入失败或校验失败返回 500 并在响应体中给出具体错误原因;升级成功返回 200 并显示成功页面,随后设备自动重启。授权校验在固件写入之前完成,因此未通过校验的请求不会写入 Flash。

3.2 代码编写步骤

第一步,编写主程序,完成串口、Wi-Fi 连接和模块初始化顺序。第二步,编写网页模块,封装首页、升级页和成功页的 HTML 与 iOS 按钮样式。第三步,编写 Web 服务模块,实现账号表、密码查找、请求认证、admin 授权和 GET 路由。第四步,编写 OTA 服务模块,封装 ArduinoOTA 以及固件上传、写入、结束、取消和结果处理。第五步,编译固件并烧录,分别测试普通账号、admin 账号和固件上传流程。

第四章 程序代码

07HttpAuthCallbackInline.ino

#include <WiFi.h>
#include <ESPmDNS.h>

#include "ota_service.h"
#include "web_server.h"

const char *ssid = "航天科宇";
const char *password = "88888888";

void setup() {
  Serial.begin(115200);

  WiFi.mode(WIFI_STA);
  WiFi.begin(ssid, password);
  if (WiFi.waitForConnectResult() != WL_CONNECTED) {
    Serial.println("WiFi Connect Failed! Rebooting...");
    delay(1000);
    ESP.restart();
  }

  otaServiceBegin();
  webServerRegisterRoutes();
  otaServiceRegisterRoutes();
  webServerBegin();

  Serial.print("Open http://");
  Serial.print(WiFi.localIP());
  Serial.println("/ in your browser to see it working");
  Serial.println("/ OTA congconggege");
}

void loop() {
  otaServiceHandle();
  webServerHandle();
  delay(2);  //allow the cpu to switch to other tasks
}

软件操作截图如下所示:

08-1 软件截图.png

08-2 网页截图.png

08-4 网页上传界面截图.png

08-3 上传成功截图.png

第五章 调试注意事项

第一次使用时需要通过 USB 烧录包含 OTA 功能的程序,之后才能通过浏览器或 Arduino IDE 进行无线升级。上传固件时应选择应用固件 .ino.bin,不要上传 merged.bin、bootloader.bin 或 partitions.bin,否则可能写入失败。

设备、电脑必须处于同一局域网,且路由器不能开启 AP 隔离。如果浏览器无法打开页面,应先查看串口输出的 IP 地址,并确认 Wi-Fi 名称和密码正确。如果网页升级失败,需要检查固件格式、分区方案是否支持 OTA、上传字段是否为 firmware,以及升级期间是否断开电源或网络。

网页 OTA 和 Arduino IDE OTA 都依赖正常运行的当前固件。如果新固件删除了 ArduinoOTA.handle、Update 上传逻辑或 Wi-Fi 连接错误,可能导致下一次无法继续 OTA,此时只能重新使用 USB 烧录。

本项目仅用于个人测试,账号密码和 OTA 上传未设置高强度安全保护,不建议直接用于商用或不受信任的网络环境。正式使用时应增加 HTTPS、OTA 密码、固件校验和更严格的访问控制。

第六章 调试心得

通过本项目可以直观理解 ESP32 的 Wi-Fi 联网、WebServer 认证和 OTA 升级流程。HTTP Basic 认证实现简单,但只适合测试环境;多账号认证的核心是根据用户名在账号表中查找密码,admin 权限判断则是在认证成功后再限制具体用户。

网页 OTA 的关键点是上传开始前必须先鉴权,未授权时不能调用 Update.begin,否则会带来安全风险。上传过程中要处理写入失败、文件错误和用户取消等情况,避免设备误重启。多文件拆分后,虽然代码总量增加,但网页、认证和 OTA 逻辑边界更清楚,后续修改页面或 OTA 流程时更加方便。

本次调试也说明,OTA 功能对网络稳定性和当前固件完整性依赖较强。调试时应先保证 Wi-Fi 连接稳定、串口日志正常,再逐步测试登录权限、网页上传和固件重启。整个项目功能已通过编译验证,实际硬件调试时还需结合串口信息判断具体问题。




关键词: AtomS3R-M12     网页     OTA升级    

共1条 1/1 1 跳转至页

回复

匿名不能发帖!请先 [ 登陆 注册 ]