电子产品世界 » 论坛首页 » 嵌入式开发 » MCU » 【AtomS3R-M12】ESP32Web中间件与串口网页同步项目

共1条 1/1 1 跳转至页

【AtomS3R-M12】ESP32Web中间件与串口网页同步项目

高工
2026-11-19 18:41:25     打赏

一、项目概述

本项目用 M5AtomS3R 开启 SoftAP 热点,跑一个基于 WebServer 的 HTTP 服务,用来演示 Middleware(中间件)机制:CORS 中间件负责跨域响应头,Digest 认证中间件保护 /protected 路由,日志中间件可按需挂载输出 curl 风格请求日志。

在中间件演示的基础上,叠加了一个”串口—网页”同步的实时数据链路:设备每秒从串口打印一行带时间戳的计数文本 ESP32 WiFi test !! count N,同时把这行文本写入内存缓存,网页端每秒轮询一次,把缓存内容渲染在一个 iOS 风格的卡片里,支持手指滑动查看历史和一键清除。

网络形态:设备工作在 AP 模式,热点名 ESP32_Demo,无密码,默认网关 192.168.4.1,电脑或手机连上热点后直接用浏览器访问即可,不依赖路由器与外网。

二、中间件资料与原理

2.1 Middlewares 库特性

中间件是”请求前的公共处理 + 响应后的公共处理”,可以对全局所有路由生效,也可以只挂在某个路由上。

好处是公共逻辑只写一份,避免在每个 handler 里重复写 CORS 头、鉴权判断、日志代码。

中间件按添加顺序执行,注册在 server 上的先执行,注册在具体路由上的后执行。

每个中间件内部通过调用 next() 决定是否继续往下传递,不调用即在此处终止(例如认证失败直接返回 401)。

2.2 三种内置中间件

LoggingMiddleware:把请求/响应按 curl -v 风格打印到指定 Stream;本项目 setOutput(Serial),默认未挂载(见 6.1)。

CorsMiddleware:处理 OPTIONS 预检,并给带 Origin 的响应追加 CORS 头;本项目 Origin 为 http://192.168.4.1,方法为 POST,GET,OPTIONS,DELETE,允许头 X-Custom-Header,Max-Age 600,不携带凭据。

AuthenticationMiddleware:支持 Basic / Digest 两种认证方式;本项目用户名 admin、密码 admin、Realm My Super App、认证方式 DIGEST_AUTH。

2.3 CORS 头说明

中间件会在响应里追加:Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers、Access-Control-Allow-Credentials、Access-Control-Max-Age。

其中 Origin 只回显配置里允许的地址,不是 *;Allow-Credentials=false 表示浏览器请求不带 Cookie/Authorization;Max-Age=600 让浏览器缓存预检结果 10 分钟,减少 OPTIONS 请求次数。

2.4 Digest 认证要点

Digest 不在链路上传明文密码,而是服务端下发 nonce,客户端用”用户名 + realm + 密码 + nonce + uri”做 MD5 摘要后回传 response,服务端按同样算法校验。

所以第一次请求一定返回 401 Unauthorized 并带 WWW-Authenticate: Digest realm=..., nonce=..., opaque=...,浏览器收到后弹登录框,curl 需要加 --digest 才会自动完成第二步。

三、实现思路

整体分四层,职责单一、互相解耦:

WiFi SoftAP(ESP32_Demo,192.168.4.1)
   │ HTTP
服务层    WebServer + Middlewares:CORS / Digest Auth / Logging(可选)
   │
数据层    count 计数 + serialLog 文本缓存(上限 6000 字符,先进先出)
   │
展示层    web_page.h(HTML/CSS/JS):每秒 fetch /serial,iOS 风格卡片滚动显示

关键设计取向:

非阻塞计时:用 millis() 差值判断是否满 1 秒,不用 delay(1000),保证 HTTP 请求随时能被响应。

串口与网页同源:每行文本先拼成同一个 String,再分别写串口和写缓存,保证两边内容完全一致,不存在”串口有、网页没有”的差异。

前后端分离到文件:网页代码单独放在 web_page.h,.ino 只保留设备逻辑与路由,改样式不用碰设备代码。

缓存有上限:serialLog 超过 6000 字符就从头丢弃旧内容,长时间运行也不会把 RAM 吃满。

时间戳可校准:AP 模式没有外网,不做 NTP,改由网页把浏览器的系统时间同步给设备。

四、软件代码实现流程

4.1 文件结构

工程由三个文件组成:

09Middleware.ino:设备端逻辑,包括热点、中间件配置、五条路由、串口计时输出与缓存维护。

web_page.h:网页端代码,HTML + CSS + JavaScript,以 PROGMEM 常量 INDEX_HTML 保存,通过 #include "web_page.h" 引入。

ci.yml:编译约束声明 requires: CONFIG_SOC_WIFI_SUPPORTED=y,保证只在带 WiFi 的芯片上编译。

INDEX_HTML 放在 Flash 里不占 RAM,路由中用 server.send(200, "text/html; charset=utf-8", INDEX_HTML) 返回。

4.2 启动流程(setup)

Serial.begin(115200),初始化调试串口。

setenv("TZ", "CST-8", 1) + tzset(),设定北京时间时区,供时间戳格式化使用。

WiFi.softAP("ESP32_Demo", "") 开热点,串口打印 IP address: 192.168.4.1。

配置三个中间件对象:日志中间件输出到 Serial;CORS 参数如 2.2;认证设置为 Digest、admin/admin。

server.addMiddleware(&cors) 挂全局 CORS;日志中间件默认注释,需要排查请求时再打开。

注册路由(见 4.3)。

collectAllHeaders() + server.begin(),串口打印 HTTP server started。

4.3 路由一览

/(GET):串口监视页面,返回 INDEX_HTML,类型 text/html、编码 UTF-8。

/serial(GET):网页轮询接口,返回当前 serialLog 全量文本。

/clear(GET):清空网页端显示,把 serialLog 置空并返回 cleared。

/time?ts=(GET):浏览器把系统时间同步给设备,ts 合法返回 ok,否则返回 400。

/protected(GET):演示 Digest 认证(挂 auth 中间件),认证通过返回 Protected,否则 401。

其他路径:由 onNotFound 处理,返回 404 Page not found。

测试命令:

curl -v http://192.168.4.1/serial

curl -v -X OPTIONS -H "origin: http://192.168.4.1" http://192.168.4.1/

curl -v --digest -u admin:admin http://192.168.4.1/protected

curl -v "http://192.168.4.1/time?ts=1763391600"

4.4 运行流程(loop)

server.handleClient() 处理 HTTP 请求。

每满 1000 ms:count++ → 拼出一行 timeStamp() + " ESP32 WiFi test !! count " + count → Serial.println() → appendToWebLog() 写入缓存。

delay(2) 让出 CPU,避免 WiFi 任务与看门狗饥饿。

输出示例(串口与网页完全一致):

[21:30:05] ESP32 WiFi test !! count 12

[21:30:06] ESP32 WiFi test !! count 13

4.5 核心代码逻辑

时间戳生成:以 time() 取当前系统时间,用 localtime_r 按 CST-8 时区格式化;未同步过时间时输出占位符,避免出现 1970 年的假时间。

// 生成 [时:分:秒] 时间戳(ESP32 处于 AP 模式无法联网对时,由网页端把系统时间同步过来)
bool timeSynced = false;

String timeStamp() {
  if (!timeSynced) return String("[--:--:--]");
  char buf[16];
  time_t nowSec = time(nullptr);
  struct tm tmv;
  localtime_r(&nowSec, &tmv);
  strftime(buf, sizeof(buf), "[%H:%M:%S]", &tmv);
  return String(buf);
}

时间同步接口:网页把 Date.now()/1000 作为 ts 传上来,设备校验合理范围后直接改写系统时间。

long long ts = atoll(server.arg("ts").c_str());if (ts > 1000000000LL) {
  struct timeval tv = { (time_t)ts, 0 };
  settimeofday(&tv, nullptr);
  timeSynced = true;}

缓存维护:追加新行,超出上限则截掉最旧的一段,保证内容始终是”最近的 N 行”。

void appendToWebLog(const String &line) {
  serialLog += line;
  serialLog += "\n";
  if (serialLog.length() > SERIAL_LOG_MAX) {
    serialLog.remove(0, serialLog.length() - SERIAL_LOG_MAX);
  }}

4.6 网页端流程

页面加载即 poll(),其后 setInterval(poll, 1000) 每秒执行;同时 syncTime() 对时,之后每 60 秒再对一次,抵消晶振漂移。

fetch('/serial', {cache:'no-store'}) 取纯文本;内容与上次不同才写入 DOM,避免无意义重排。

滚动策略:默认跟随最新一行自动滚到底;用户上滑查看历史时(距底部超过 24 px)暂停跟随,滑回底部附近自动恢复。

“清除显示”按钮先清空本地文本,再请求 /clear 清空设备端缓存,防止下一次轮询把旧内容刷回来。

顶部显示标题、作者与”更新于 HH:MM:SS”状态;请求失败时改为”连接断开,重试中…“,用于区分网络故障与页面故障。

布局为整屏 flex:标题栏 + 白色圆角卡片 + 底部按钮,卡片内 overflow-y: auto + -webkit-overflow-scrolling: touch 实现移动端惯性滑动,配色与控件遵循 iOS 风格(#f2f2f7 背景、16 px 圆角、系统蓝 #007aff、按下缩放反馈)。

五、项目功能

AP 热点:ESP32_Demo 无密码,默认 192.168.4.1,无需路由器即可访问。

中间件演示:全局 CORS 响应头、OPTIONS 预检、/protected 的 Digest 认证、可选的请求日志。

串口输出:115200 波特率,每秒一行,count 自增,带 [时:分:秒] 时间戳。

网页同步:iOS 风格卡片实时显示串口内容,与串口逐行一致。

滑动查看:内容超出卡片高度后可滚动,支持跟随最新/暂停跟随。

清除显示:一键清空页面与设备端缓存。

时间校准:浏览器把系统时间同步给设备,页面每 60 秒自动校时。

状态提示:连接正常显示更新时间,断开显示重试提示。

分层解耦:网页代码与设备代码分文件维护。

资源占用(当前版本):Flash 约 74%,RAM 约 14%,页面 HTML 约 4 KB。

六、出现问题及解决办法

6.1 网页轮询把串口刷满日志

现象:页面每秒请求 /serial,LoggingMiddleware 会把每个请求按 curl 风格打印十几行,串口里几乎看不到计数字符串。

原因:日志中间件挂在全局,轮询频率高时日志量远超业务输出。

解决:把 server.addMiddleware(&logger) 注释保留,需要排查请求时再取消注释;这样默认状态下串口只有每秒一行的业务输出。

6.2 AP 模式下时间显示为 1970 年

现象:直接调用 time() 得到的始终是 1970 年附近的时间,时间戳没有意义。

原因:ESP32_Demo 是设备自己开的热点,没有外网出口,configTime() 的 NTP 请求发不出去。

解决:由网页端把浏览器系统时间传上来(/time?ts=Unix秒),设备 settimeofday() 写入系统时间;未同步前输出 [--:--:--],避免显示错误时间。页面每 60 秒再对一次,抵消晶振漂移。

6.3 输出字符串中的全角逗号丢失

现象:源码里本来写着 !!,count,编译出来的固件里逗号不见了,串口打印成 !!count。

原因:全角标点(U+FF0C)在部分编辑/复制环节被吞掉,肉眼在等宽字体下不易察觉。

解决:改用 C++ 转义 "\uFF0C" 明确表达全角逗号;若版本迭代中不需要该符号,则直接删除并确认源码字符码位(可用脚本打印 Substring 的每个字符 U+ 码位核对)。

6.4 编译报 build.options.json: Access is denied

原因:Arduino IDE 与 arduino-cli 共用同一个构建目录,IDE 正持有文件锁。

解决:命令行编译时指定独立构建目录:

arduino-cli compile --fqbn esp32:esp32:m5stack_atoms3 --build-path "%TEMP%\mw_build" .

6.5 页面一直显示旧内容

原因:浏览器缓存了旧版页面或旧 fetch 结果,尤其固件更新后更容易出现。

解决:请求侧统一加 cache: 'no-store',服务端返回 charset=utf-8;必要时 Ctrl+F5 强刷或关闭旧标签重新打开。

6.6 串口中文乱码

现象:打印中文或全角符号时监视器出现 ????。

原因:终端按 GBK 解码,而设备输出 UTF-8。

解决:把串口监视器编码设为 UTF-8;数值与英文部分不受影响。

6.7 /protected 用浏览器访问被拒

现象:浏览器弹登录框,输入 admin/admin 也一直 401。

原因:中途取消或输错一次后,浏览器会缓存旧 nonce,而 Digest 的 nonce 是一次性/有时效的。

解决:关掉标签重开,或换无痕窗口;命令行用 curl --digest -u admin:admin 验证,排除浏览器因素。

6.8 页面滚动不跟手 / 一直跳到底部

原因:轮询每次重写 textContent 后无条件滚到底,用户想往回翻就被拽回。

解决:加”是否在底部附近(<24 px)“的判定变量 stick,只在跟随状态下自动滚到底;用户上滑即暂停跟随。

七、调试感想

中间件的价值在”一次写、处处生效”。 CORS 头如果写在每个 handler 里,新增路由时极容易漏;抽成中间件后,路由只管业务,公共协议细节收敛到一处。

串口是这套链路的地基。 网页有问题时,先看串口在不在正常输出:串口有、网页没有,问题在 HTTP/前端;串口都没有,问题在计时或主循环。

AP 模式天然隔离外网。 一开始想用 NTP 对时,后来意识到热点没有出口,改由浏览器传时间,反而更准(用的是手机/电脑的系统时间)。

全角标点是隐形坑。 显示上看不出差别,编译也不报错,只能靠核对码位或打印字节确认,涉及中文标点的字符串最好用转义或固定模板。

轮询频率要和日志策略匹配。 1 秒轮询配全量日志中间件,串口一定被刷屏;调试期打开、交付时关闭,比无脑常开更实用。

节流与增量更新能省很多事。 前端只在内容变化时写 DOM,设备端缓存超出上限才裁掉旧行,CPU 与 RAM 都更可控。

八、后续可扩展方向

用 Server-Sent Events 或 WebSocket 替代轮询,做到真正推送、零延迟。

串口内容持久化到 LittleFS,断电后仍能回看历史日志。

页面增加”暂停/继续”与”导出日志”按钮,便于现场取证。

增加 STA + AP 双模:连上路由器后启用 NTP 自动对时,AP 模式作为兜底。

把计数扩展到真实传感器数据,形成”设备采集 → 串口 → 网页”的通用模板。

为 /serial、/clear 增加 Digest 认证或令牌校验,避免同一热点下的其他设备随意清空数据。




关键词: ESP32     AP    

共1条 1/1 1 跳转至页

回复

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