cbb
31b90f68b3
根目录原本平铺 7 个 HTML, 而 js/ 已按功能域分子目录, 两级结构不对称; 且自包含实验页与主功能页平级摆放, 看不出可随时删除。现按角色分三层: tabs.html 标签外壳留在根 = 工具入口 pages/ index / can / can_monitor / motor 主功能页 lab/ continuity_test / spi_test 自包含实验页(零外部依赖) scripts/ build_mem.bat 随迁修正(全部实跑验证): - pages/ 下 4 页共 22 处 css/js 引用加 ../ 前缀; 页面互链同目录无需改 - js/motor/main.js 的 Worker URL 改用 import.meta.url 解析: 原文档相对 路径 "js/motor/tick.worker.js" 在 pages/ 下会解析成 /pages/js/... 而 404, 静默退化到 setTimeout 兜底、丢失后台不节流能力(已验证旧写法 404) - tabs.html 的 TABS 登记新路径; pageToTab 改按文件名匹配, 旧版 localStorage 存的裸文件名(can.html)自动迁移到 pages/can.html - esp32_server.py: GET / 与 /index.html 302 到 /tabs.html(根下已无 index.html); 注入脚本的 ⌂ 主页判定基准由 index.html 改为 tabs.html - serve.bat 打印外壳与 OTA 页新地址; README 补目录结构与路径约定 验证: 39/39 静态资源 200, 7 页 200 且注入生效, 逐页解析引用 0 坏链, 路由 / 与 /index.html 302、未知页 404, node --check 与 py_compile 通过。
81 lines
4.8 KiB
Markdown
81 lines
4.8 KiB
Markdown
# DCU ESP32 调试控制台（Web 前端 + 本地页面服务）
|
||
|
||
`G:\Robot_v2\DCU\tools\ESP32` —— ESP32-C3（`DCU/ESP32_COMM` 固件）的上位机调试界面。
|
||
|
||
本目录**不含固件代码，也不直接访问硬件**：HTML/CSS/JS 是纯前端，页面本体由
|
||
`esp32_server.py` 以静态文件方式提供（同源相对路径），而所有业务 API 由 ESP32
|
||
固件的 80 端口跨域提供。设备 IP 存在浏览器 `localStorage` 的 `dcu_esp_ip`
|
||
（默认 `192.168.31.127`，见 `js/common/base-url.js`）。
|
||
|
||
## 启动方式
|
||
|
||
| 入口 | 形态 | 说明 |
|
||
|------|------|------|
|
||
| `esp32_app.vbs` | 桌面窗口 | pywebview + WebView2，无控制台窗口；服务跑在独立子进程 |
|
||
| `esp32_web.vbs` | 默认浏览器标签页 | 无控制台窗口 |
|
||
| `serve.bat` | 控制台模式 | 端口 8080，窗口内可见服务器日志，用于调试 |
|
||
|
||
窗口模式为何拆两个进程：`pythonw` + `pythonnet`（pywebview 依赖）环境下 Python
|
||
后台线程会被静默杀死，把 HTTP 服务放进独立子进程可规避，与 `tools/ecat/ecat_server.py`
|
||
同款结构。pywebview 窗口没有地址栏与刷新按钮，因此服务器会向 HTML 响应注入
|
||
`_reload.html`（右下角 ⟳ 悬浮按钮 + F5/Ctrl+R 拦截）。
|
||
|
||
`build_mem.bat`（在 `scripts/`）是从 Git Bash 调用 ESP-IDF 构建 `DCU/ESP32_COMM` 的辅助脚本
|
||
（会先清掉 MSYS 环境变量绕过 IDF 的 MSys 检测）。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
tabs.html 标签外壳 = 工具入口（GET / 会 302 到这里）
|
||
pages/ 主功能页，各自引用 ../css 与 ../js
|
||
lab/ 自包含实验页，零外部依赖，删文件即可移除
|
||
css/ js/ 共享样式与 ES module
|
||
scripts/ 构建辅助脚本
|
||
esp32_server.py 本地页面服务 + 桌面窗口外壳
|
||
esp32_app.vbs esp32_web.vbs serve.bat 三个启动入口
|
||
```
|
||
|
||
## 页面
|
||
|
||
`tabs.html` 是单窗口多标签外壳，用 iframe 承载下列功能页，激活标签记忆在
|
||
`localStorage` 的 `dcu_tab`（按文件名匹配，与目录层级无关）：
|
||
|
||
| 页面 | 用途 | 主要脚本 |
|
||
|------|------|----------|
|
||
| `pages/index.html` | OTA 中继控制台（ESP32 WiFi OTA / GD32 relay / BLE OTA） | `js/app.js`、`js/ota/*`、`js/ble_ota.js`、`js/ble/*` |
|
||
| `pages/can.html` | CAN 通信（DBC 解析、消息编辑与批量发送） | `js/can.js`、`js/can/*` |
|
||
| `pages/can_monitor.html` | CAN 接收监控（独立页；也被 `can.html` 内嵌复用） | `js/can_monitor.js` |
|
||
| `pages/motor.html` | 电机控制台（CAN FD） | `js/motor/main.js`、`js/motor/tick.worker.js` |
|
||
| `lab/continuity_test.html` | LAN9252 通断测试（自包含，含 WebGL 液态玻璃效果） | 内联 |
|
||
| `lab/spi_test.html` | 【临时功能 SPI-SPEEDTEST】SPI 链路测速，完全自包含，删文件即可移除 | 内联 |
|
||
|
||
## 目录约定
|
||
|
||
- `css/` —— `base`（变量/基础）、`layout`、`components`、`can`、`motor`、`responsive`。
|
||
- `js/common/` —— 跨页公用：`base-url`（设备 IP）、`connection`、`polling`、`log`、`toast`、`utils`、`heap-low-history`。
|
||
- `js/ota/`、`js/ble/`、`js/can/`、`js/motor/` —— 按功能域拆分的 ES module，跨域引用只走 `js/common/`。
|
||
- 子系统配色：ESP32 = 青绿 · GD32 = 琥珀 · BLE = 蓝 · CAN = 绿 · 内存/调试 = 紫。
|
||
|
||
## 改动须知
|
||
|
||
- **改 CSS/JS 后必须 bump 引用处的 `?v=` 缓存版本**，否则浏览器会加载旧代码。
|
||
- `pages/` 与 `lab/` 下的页面引用共享资源要用 `../css/`、`../js/` 前缀；
|
||
**JS 模块内部引用其他资源（如 Worker）须用 `import.meta.url` 解析**，
|
||
不能写文档相对路径，否则页面换层级就会 404（见 `js/motor/main.js` 的 `TICK_WORKER_URL`）。
|
||
- 新增功能页放 `pages/`，并在 `tabs.html` 的 `TABS` 数组登记；
|
||
一次性/实验页放 `lab/` 并保持自包含。
|
||
- OTA 流程以设备端为真相来源：WiFi OTA 由设备回读分区算 SHA-256 后自动重启；
|
||
BLE OTA 由前端发 `0xF8 + 32B SHA-256`、设备端比较并通过 FINISH 事件报结果
|
||
（前端不做 SHA 预比较）；GD32 relay 状态以 `/system/status` 为准。
|
||
- 监控 UI 需区分 `valid`（通信是否成功）与 `count > 0`（是否有数据），
|
||
以便分辨「正常空闲」和「真实通信错误」。
|
||
- 响应式 grid 表隐藏列用 `0fr` 宽度实现，不要改变 grid track 数量。
|
||
- 新增 CAN 工作模式时，需在页面上显式补按钮与说明文字。
|
||
- DBC 文件常为 GBK/GB2312：先按 UTF-8（`{fatal: true}`）尝试，失败回退 GB18030，并去 BOM。
|
||
|
||
## 相关仓库
|
||
|
||
- `DCU/ESP32_COMM` —— ESP32-C3 固件（OTA、SPI Link v2、CAN FD bridge）。
|
||
- `DCU/DCU_APP`、`DCU/GD32E50X_BOOT` —— GD32 侧应用与 bootloader。
|
||
- `DCU/tools/ecat` —— LAN9252 EtherCAT 主站工具集（同类结构的姊妹工具）。
|