5.0 KiB
5.0 KiB
1. 采用的系统/方法
仓库是一个混合工程：Web 前端（HTML/CSS/JS）+ Python3 本地调试服务器，以及通过外部脚本触发的 ESP-IDF 固件构建。没有 Makefile、Dockerfile、CI 流水线或统一的包管理器；构建由多个独立的 Windows 批处理脚本和 Python 启动器拼凑而成，分别承担不同的构建目标。
1.1 前端静态服务与桌面窗口
- 核心运行体
esp32_server.py用 stdlibhttp.server.ThreadingHTTPServer在本地提供静态页面，并实现/ecat/api/*反向代理到tools/ecat/build_native/ecat_native.exe（端口 8090–8095 自动探测）。 - 三种启动入口：
serve.bat：控制台模式，默认端口 2625，输出日志方便调试。esp32_app.vbs：pythonw.exe启动 pywebview 桌面窗口（无控制台），子进程承载 HTTP 服务，避免 pythonw 后台线程被杀。esp32_web.vbs：pythonw.exe启动后默认打开浏览器标签页。
- 窗口模式下服务端向 HTML 响应注入
_reload.html，为 WebView2 补充 F5 / Ctrl+R 刷新能力。
1.2 ESP-IDF 固件构建
scripts/build_mem.bat通过 Git Bash 调用idf.py build构建G:\Robot_v2\DCU\ESP32_COMM下的 DCU/ESP32 固件。- 预先
unset MSYSTEM*/MINGW_*环境变量绕过 ESP-IDF 的 MSys 检测，并将工具链路径固定到C:\Espressif与F:\software\.espressif\v6.0\esp-idf\export.bat——路径硬编码于脚本中。
1.3 GD32 OTA / 刷写
scripts/flash_gd32.py：经本服务的 Web API 把 GD32 固件中继下载到设备侧 Flash。- EtherCAT 链路依赖
tools/ecat/build_native/ecat_native.exe（由build_native.bat编译，需 VS2022 + Npcap），首次请求时由esp32_server.py的_ecat_autostart自动拉起（带--parent-pid防止清场已有实例），未找到时用端口扫描复用已运行的进程。
2. 关键文件
| 文件 | 角色 |
|---|---|
esp32_server.py |
静态文件服务、EtherCAT 反向代理、app 窗口租约、ECAT 守护进程管理 |
serve.bat |
控制台模式启动器（Python 标准输出可见） |
esp32_app.vbs |
pywebview 桌面窗口启动器（隐藏控制台） |
esp32_web.vbs |
默认浏览器 tab 启动器（隐藏控制台） |
scripts/build_mem.bat |
通过 ESP-IDF 构建 ESP32 端固件 |
scripts/flash_gd32.py |
通过本服务中继刷写 GD32 固件 |
README.md |
记录目录约定、双链路架构与三处构建依赖 |
3. 架构与约定
- 分层清晰：前端是纯静态资源，不碰硬件；业务 API 跨域访问 ESP32 固件的 80 端口；只有 EtherCAT 后端需要本机 C/SOEM 守护进程。
- 同源代理解 CORS：ECAT 后端绑 127.0.0.1 且禁止预检，所有 POST JSON 请求统一走
/ecat/api/*同源转发，页面与两个仓库（前端 + ecat）互不耦合。 - 自动生命周期管理：ECAT 守护进程首次代理时才拉起，
--parent-pid保证父退出后自杀；已存在进程直接复用（端口 8090–8095 轮询探测），避免重复拉起触发对从站的 INIT 清理。 - 单实例锁：多双击
esp32_app.vbs时通过/api/focus聚焦已有实例而非创建新窗口。 - 版本化缓存：README 明确“改 CSS/JS 后必须 bump 引用处的
?v=缓存版本”，否则浏览器加载旧代码。 - 模块组织：新增功能页放
pages/并在tabs.html的 TABS 数组登记；一次性实验页放lab/保持自包含。
4. 约束与规则
- ESP32 固件构建依赖外仓路径：
scripts/build_mem.bat将ESP_IDF_EXPORT指向F:\software\.espressif\v6.0\esp-idf\export.bat，并 cd 到G:\Robot_v2\DCU\ESP32_COMM再idf.py build——这要求开发者拥有与仓库一致的磁盘布局，不是可移植构建。 - ECAT 后端必须先存在或可由本服务拉起：若未找到
tools/ecat/build_native/ecat_native.exe，电机链路会报错提示“请先运行 tools\ecat\build_native.bat”；前端js/motor/main.js对错误消息中包含build_native/Npcap 的情况做归类。 - WebSocket 租约决定循环启停：
ws/app-lease上所有 app 窗口断开则自动停止 EtherCAT PDO 循环并把从站退回 INIT。 - 刷新率上限与链路绑定：WiFi 链路默认 250ms、最低 50ms；ECAT 链路默认 50ms、最低 1ms（受限于 Python Event.wait 与 GIL）。切链路时各记一份
state.refreshByTp并立即重排节拍。 - 1ms ECAT 档位 ≠ 1000Hz：底层以 UNTHROTTLED_MAX_MS=20 作为“不限速”阈值，1ms 档实际约 125 Hz；低于 20ms 要同时关掉理论值与 tickStuck 统计，否则界面会撒谎。
5. 不存在的内容
- 没有 Makefile / Gradle / npm scripts / Dockerfile / CI YAML — 该项目在 Windows 环境内用批处理与 VBScript 手工组装构建/发布流程。
- 无统一的版本号定义文件（版本号来源于 Git tag / changelog 和设备端 SHA-256）。
- 无交叉编译配置：ESP-IDF 构建路径硬编码，ECAT native 产物预期在 Windows 上由 VS2022 构建。