AlexMelanFromRingo/chipforge

# chipforge 一款专为 ESP 微控制器板设计的模块化、透明且安全至上的烧录/转储工具。 chipforge 的构建围绕三个核心原则：**先读后写**、**宁可大声报错也不静默失败**，以及**拒绝黑盒魔法**。每一个协议字节都有文档记录，每一个决策都可追溯。写入和擦除操作仅在 `--stub` 构建中可用，且始终强制要求备份，并在写入后进行 MD5 验证。 ## 为什么原生优先？ `espflash`（esp-rs Rust 生态系统工具）针对 ESP32 系列设计，且从未支持过 ESP8266 —— 在该生态中，ESP8266 并不是受支持的 Rust 片上目标。任何想要通过 Rust 服务 NodeMCU V3 (ESP8266) 的工具都必须自行实现 ROM 串口协议。chipforge 正是这么做的。完整的现有技术调查请参阅 [docs/research/03-tooling-prior-art.md](docs/research/03-tooling-prior-art.md)。 ## 状态 — 1.5（已完成） | 功能 | 状态 | 备注 | |---|:---:|---| | 列出串口 + 检测转换器 | 是 | `chipforge ports` | | 芯片识别（类型，MAC） | 是 | `chipforge -p info` | | Flash JEDEC ID 及容量 | 是（需 `--stub`） | `chipforge -p --stub info` | | 固件镜像头解析（离线） | 是 | `chipforge image-info ` | | 比较两份二进制转储（离线） | 是 | `chipforge diff ` | | 读取 / 转储 flash | **是（需 `--stub`）** | 自有 MIT stub **或** 可选 GPL stub — 见下文 | | 完整验证的备份 | **是（需 `--stub`）** | 双重 MD5 验证；附带 `.json` sidecar — 见下文 | | 自有 MIT ESP8266 stub | **是**（`--features stub-own`） | 从零编写，无 GPL；硬件验证字节匹配 — 见下文 | | 写入 flash | **是（需 `--stub`，强制备份）** | 默认使用 Deflate 压缩；写入后 MD5 验证 — 见下文 | | 擦除（整片/区域） | **是（需 `--stub`，强制备份）** | 支持整片或 4 KB 对齐区域 — 见下文 | | 验证 | **是（需 `--stub`）** | 通过 MD5 比较 flash 区域与文件 | | 交互式 TUI | 是 | `chipforge tui` | | ESP32 系列（可选后端） | 是（`--features backend-espflash`） | 通过 espflash 实现 — 见下文 | 分阶段交付于 1.0 → 1.5（标签 `v0.1.0`–`v0.1.5`），每个阶段均可独立发布。 **为什么写入/擦除受备份限制？** 在进行任何 flash 或擦除操作之前，chipforge 会自动读取当前 flash 的 MD5，并重用 `~/.chipforge/backups/` 中匹配的备份，或者创建一个经过全新验证的备份。传入 `--i-have-backup` 可跳过此限制（您将收到警告）。这是一项强制策略，而非软警告。 ### Stub 选项（读取 ESP8266 flash） 读取 ESP8266 flash 需要先将一个小型 stub loader 上传到 RAM —— ROM bootloader 没有读取 flash 的命令。chipforge 提供了**两**种 stub；它们都完全在 RAM 中运行并使用相同的主机协议，因此用法完全一致。 | Stub | 功能标志 | 该构建的许可证 | 来源 | |---|---|---|---| | **自有 MIT stub**（推荐） | `--features stub-own` | MIT OR Apache-2.0 | `chipforge-esp-stub` — 本仓库内从零编写的 C (Xtensa LX106) 代码 | | 遗留 GPL stub | `--features stub-gpl` | GPL-2.0-or-later | `chipforge-esp-stub-gpl` — 衍生自 Espressif 的 stub | **自有 MIT stub** 从零开始编写并经过了**硬件验证**：在真正的 NodeMCU V3 上，其完整的 4 MB 备份与 GPL/Espressif stub 的备份**字节完全一致**（MD5 相同）。使用它可以让您的整个构建保持宽松许可： ``` cargo build -p chipforge-cli --release --features stub-own ``` **遗留 GPL stub** 位于**独立的** crate `chipforge-esp-stub-gpl` (GPL-2.0-or-later) 中，它**不是**默认的工作区成员。启用 `--features stub-gpl` 会使**该构建**变为 GPL-2.0-or-later： ``` cargo build -p chipforge-cli --release --features stub-gpl ``` 默认构建（无 stub 功能）保持为 MIT OR Apache-2.0，可以识别芯片并离线检查/比对镜像，但无法读取 flash。从源码构建 stub blob 需要 `xtensa-lx106` 工具链；预构建的 blob 已签入仓库，因此构建 chipforge 本身**不**需要该工具链。有关 stub 的设计以及在其开发过程中发现的四个 ESP8266 ROM loader 坑，请参阅 [docs/superpowers/specs/2026-06-26-chipforge-1.3-own-stub-design.md](docs/superpowers/specs/2026-06-26-chipforge-1.3-own-stub-design.md)。 **使用 stub 构建后的用法**（`stub-own` 和 `stub-gpl` 一致）： ``` # 显示 flash 大小和 JEDEC id（需要 stub） chipforge -p --stub info # 完整 flash 备份 — 双重 MD5 校验（设备 MD5 + 本地 MD5），写入 .json sidecar chipforge -p --stub backup chipforge -p --stub backup -o my-backup.bin # 转储特定 flash 区域 chipforge -p --stub dump --addr 0x0 --size 0x10000 -o region.bin ``` ### 写入与备份限制 `flash` 和 `erase` 需要 `--stub`（使用 `--features stub-own` 或 `--features stub-gpl` 构建）。在进行任何写入或擦除之前，chipforge 会运行**自动备份限制机制**：它读取当前 flash 的 MD5，然后重用 `~/.chipforge/backups/` 中已有的匹配备份，或者创建一个全新的验证备份。只有通过了这一关，写入或擦除操作才会继续。传入 `--i-have-backup` 可跳过此限制 —— 您将收到明显的警告。 ``` # 写入固件（默认 deflate 压缩，写入后 MD5 校验，受备份保护） chipforge -p --stub flash --addr 0x0 firmware.bin # 不压缩写入，然后重启 chipforge -p --stub flash --addr 0x0 fw.bin --no-compress --reboot # 擦除整个芯片（受备份保护） chipforge -p --stub erase # 擦除 4 KB 对齐区域（受备份保护） chipforge -p --stub erase --region 0x3fc000:0x4000 # 使用文件验证 flash 区域（无限制 — 只读） chipforge -p --stub verify --addr 0x0 firmware.bin ``` ## ESP32 系列（espflash 后端） chipforge 1.4 通过 [espflash](https://github.com/esp-rs/espflash) 库 (MIT OR Apache-2.0) 为 ESP32 系列添加了可选的第二个后端。它**默认关闭** —— 默认构建保持不变，依然是 MIT OR Apache-2.0，且没有额外的依赖。 **支持的芯片：** ESP32、ESP32-S2、ESP32-S3、ESP32-C2、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-C61、ESP32-H2、ESP32-P4。 **使用 espflash 后端构建：** ``` cargo build -p chipforge-cli --release --features backend-espflash ``` **在运行时选择后端：** ``` chipforge --backend espflash -p info chipforge --backend espflash -p backup chipforge --backend espflash -p dump --addr 0x0 --size 0x10000 -o region.bin chipforge --backend espflash -p flash --addr 0x0 firmware.bin chipforge --backend espflash -p erase chipforge --backend espflash -p verify --addr 0x0 firmware.bin ``` **关键注意事项：** - ESP8266 **不**受 espflash 支持，将继续使用默认的 `--backend native` 路径。 - `--backend espflash` **与 `--sim` 不兼容**（模拟器仅针对 ESP8266 原生协议）。 - espflash 库采用 MIT OR Apache-2.0 许可；启用 `--features backend-espflash` **不会**改变 chipforge 自身的许可证。 - **该后端上的标志行为：** espflash 后端**不支持** `flash --no-compress` 和 `flash --reboot` 标志 —— espflash 内部自行管理压缩，并在操作完成后执行硬重置。这些标志仅适用于原生后端。 - **验证说明：** espflash 后端仅针对真实的 ESP32 硬件进行了验证。chipforge 的内置模拟器运行的是 ESP8266 原生协议，并没有测试 espflash 代码路径。如果您没有 ESP32 设备，请使用 `--backend native` (ESP8266)，或者将 espflash 后端视为在您的环境中未经测试。 ## 安装 / 构建 前置条件：Rust 工具链（稳定版，1.88+ — edition 2024 + let-chains）。 ``` cargo build --release ``` 二进制文件位于 `target/release/chipforge`。在 Linux 或 Windows 上不需要额外的依赖；serialport crate 已经打包了所需的一切。 ### 关于 Stub 支持的许可说明 chipforge **自有**的 stub crate `chipforge-esp-stub` 采用 MIT OR Apache-2.0 许可，因此使用 `--features stub-own` 构建的版本 —— 包括完整的 flash 读取/备份/转储 —— 完全是宽松许可的。采用 GPL 许可的 Espressif stub 被隔离在独立、可选、默认关闭的 crate `chipforge-esp-stub-gpl` 中；只有在您选择启用 `--features stub-gpl` 时它才会被链接，这会使该构建变为 GPL。所有其他工作区 crate（`chipforge-core`、`chipforge-esp`、`chipforge-cli`、`chipforge-esp-stub`、`chipforge-espflash`）均为 MIT OR Apache-2.0。详情请参阅上面的“Stub 选项”小节。 ## 快速入门 **列出端口并检测转换器：** ``` chipforge ports chipforge ports --json ``` **识别连接的芯片**（先将开发板置于下载模式 —— 见下文）： ``` chipforge -p /dev/ttyUSB0 info # Linux chipforge -p COM6 info # Windows chipforge -p /dev/ttyUSB0 info --json ``` **解析固件镜像头（无需开发板）：** ``` chipforge image-info firmware.bin ``` **对比两份二进制转储（无需开发板）：** ``` chipforge diff before.bin after.bin ``` ### 平台注意事项 - **Windows：** 端口显示为 `COMx`（例如 `COM6`）。如果 Windows 无法识别开发板，请从 WCH 安装 CH340 驱动程序。 - **Linux：** 端口通常为 `/dev/ttyUSB0`。将您的用户添加到 `dialout` 组（`sudo usermod -aG dialout $USER`）并重新登录。 - **WSL2：** WSL2 无法直接看到 USB 串口设备。请使用 `usbipd-win` 将 COM 端口转发到 WSL2，或者在 Windows 上原生构建并运行二进制文件来连接 COM 端口 —— 无需 usbipd。 ### 环境变量 | 变量 | 等效标志 | 示例 | |---|---|---| | `CHIPFORGE_PORT` | `-p / --port` | `/dev/ttyUSB0` 或 `COM6` | | `CHIPFORGE_BAUD` | `-b / --baud` | `115200` | | `CHIPFORGE_BACKEND` | `--backend` | `native` 或 `espflash`（通过 `--features backend-espflash` 选配启用） | ### 全局标志概览 | 标志 | 默认值 | 描述 | |---|---|---| | `-p / --port` | 自动检测 | 串口 | | `-b / --baud` | `115200` | 初始波特率 | | `--backend native\|espflash` | `native` | 协议后端；`native` 始终可用，`espflash` 通过 `--features backend-espflash` 选配启用 | | `--json` | 关闭 | 输出机器可读的 JSON | | `-v / --verbose` | 关闭 | 提高日志详细程度（重复使用以获取更多） | ## NodeMCU V3 下载模式 NodeMCU V3 (LoLin) 采用 **CH340G** USB-UART 转换器，其 DTR 和 RTS 分别连接到 GPIO0 和 EN。chipforge 通过“经典重置”时序自动触发下载模式：RTS 将 EN 拉低，同时 DTR 保持 GPIO0 为低电平，随后两者释放。 **手动后备方案**（如果自动重置无效）： 1. 按住 **FLASH** 按钮（将 GPIO0 拉低）。 2. 短按 **RST** 按钮（向 EN 发送脉冲）。 3. 释放 **FLASH**。 现在开发板已进入 ROM 下载模式。请在几秒钟内运行您的 `chipforge` 命令。 完整的硬件参考，包括启动引脚、CH340G 接线及 flash 芯片详情，请参阅 [docs/research/04-nodemcu-v3-hardware.md](docs/research/04-nodemcu-v3-hardware.md)。 ## 安全性 - **写入操作仅限 stub、写入后 MD5 验证且强制备份。** Flash 写入和擦除需要 `--stub`（选配启用的 GPL 构建）。在进行任何写入或擦除之前，chipforge 会运行自动备份限制机制。每次写入后，写入的区域都会被回读并与源文件进行 MD5 验证。 - **写入前强制备份机制：** chipforge 会自动读取当前 flash 的 MD5，并在进行任何写入或擦除之前，重用 `~/.chipforge/backups/` 中的匹配备份或创建一个全新的验证备份。传入 `--i-have-backup` 可跳过此步骤并警告。 - **Flash 容量保护：** 写入操作（1.2+ 版本）将拒绝写入超出检测到的 flash 容量的数据。 - **杜绝静默失败：** 每个协议错误都会作为特定的 `Error` 变体抛出。chipforge 绝不容忍 CRC 校验不匹配或意外响应。 ## 交互式 TUI `chipforge tui` 打开一个全屏终端 UI（使用 [ratatui](https://github.com/ratatui-org/ratatui) 构建），让您无需输入单独的命令即可探索端口、连接到芯片并执行读取/备份/转储操作。它可以在 Windows 控制台以及 Linux 和 macOS 终端上运行。 ### 运行 TUI ``` # 使用自动检测的端口启动 chipforge tui # 显式指定端口 chipforge tui -p # 无硬件探索 — 运行内置 ESP8266 模拟器 chipforge tui --sim # 在真实的 ESP8266 上使用 stub 以获得完整的 flash 读取支持 chipforge tui -p --stub ``` 在真正的 ESP8266 上，备份和转储必须使用 `--stub`（ROM 没有读取 flash 的命令）。首先使用 `--features stub-own` (MIT) 或 `--features stub-gpl` 进行构建 —— 请参阅上面的“Stub 选项”部分。`--sim` 意味着使用 ESP8266 原生路径，且与 `--backend espflash` 不兼容。 ### 快捷键 | 按键 | 操作 | |---|---| | ↑ / ↓ | 向上 / 向下移动选择 | | Tab | 在端口列表和操作菜单之间切换焦点 | | Enter | 执行所选操作 | | q 或 Esc | 退出 | ### 操作 | 操作 | 描述 | |---|---| | 连接 / 信息 | 在下载模式下打开所选端口并显示芯片信息（类型，MAC，带 `--stub` 时显示 flash JEDEC ID 及容量） | | 备份 | 运行经过完整验证的备份（强制备份 —— 自动 MD5 检查会重用匹配的备份或创建新备份；在真正的 ESP8266 上需要 `--stub`） | | 转储 64 KB @ 0x0 | 将 flash 的前 64 KB 转储到文件中（在真正的 ESP8266 上需要 `--stub`） | ### 注意事项 - **长时间操作期间忙碌：** 当备份或转储正在运行时，UI 不接受输入。面板中会显示实时进度条和滚动日志，直到操作完成。 - **仅限读取/备份/转储：** 1.5 版本的 TUI 不公开擦除或写入 flash 的操作。首个交互界面被刻意设计得非常安全 —— 破坏性操作目前仍仅限于命令行。 - **串口监视器：** 延期至未来的更新。 - **Windows 控制台：** 借助 crossterm 的 Windows 控制台后端，TUI 可以在 Windows 终端、cmd.exe 和 PowerShell 中正确渲染。 ## 对比 | 功能 | esptool.py | espflash | chipforge 1.5 | |---|:---:|:---:|:---:| | 支持 ESP8266 | 是 | **否** | 是 | | 支持 ESP32 系列 | 是 | 是 | 是（需 `--backend espflash`） | | Flash 转储 / 备份 | 是 | 是 | 是（需 `--stub`） | | Flash 写入 / 擦除 | 是 | 是 | 是（需 `--stub`，强制备份） | | 芯片识别（离线安全读取） | 是 | 是 | 是 | | 列出端口 + 转换器检测 | 是 | 是 | 是 | | 离线镜像信息检查 | 是 | 部分 | 是 | | 比较两份转储 | 否 | 否 | 是 | | 纯 Rust，无 Python runtime | 否 | 是 | 是 | | MIT / Apache-2.0 许可证 | 否 (GPL-2) | Apache-2.0 | 是 | | 在无 GPL 构建中读取 ESP8266 flash | 否 | 不适用 | **是**（自有 MIT stub） | | 安全至上的备份机制 | 否 | 否 | 是（1.2+ 版本） | espflash 的 `board-info` / `list-ports` 需要 ESP32 系列 —— 它根本无法与 ESP8266 通信。请参阅 [docs/research/03-tooling-prior-art.md](docs/research/03-tooling-prior-art.md)。 ## 许可证 您可以选择以下任一许可证： - MIT 许可证 ([LICENSE-MIT](LICENSE-MIT) 或 https://opensource.org/licenses/MIT) - Apache 许可证，版本 2.0 ([LICENSE-APACHE](LICENSE-APACHE) 或 https://www.apache.org/licenses/LICENSE-2.0) 任选其一。 chipforge 自有的 ESP8266 stub (`chipforge-esp-stub`) 与项目的其他部分一样采用 MIT OR Apache-2.0 许可，因此 flash 读取/备份/转储功能可以在完全宽松许可的 `--features stub-own` 构建中使用。 可选的**替代** stub loader crate `chipforge-esp-stub-gpl` 包含了基于 GPL 许可的 Espressif stub 代码，它是一个独立的 crate，**不是**默认工作区的成员，除非您选择启用 `--features stub-gpl`，否则**不会**被链接。启用该功能会使该构建变为 GPL-2.0-or-later；默认构建和 `stub-own` 构建仍保持为 MIT OR Apache-2.0。 ## 延伸阅读 - [docs/research/01-esp-rom-protocol.md](docs/research/01-esp-rom-protocol.md) — SLIP 帧封装与 ROM bootloader 协议 - [docs/research/02-usb-uart-converters.md](docs/research/02-usb-uart-converters.md) — CH340、CP210x、FT232R 及自动重置接线 - [docs/research/03-tooling-prior-art.md](docs/research/03-tooling-prior-art.md) — esptool.py、espflash 与现有技术的烧录工具 - [docs/research/04-nodemcu-v3-hardware.md](docs/research/04-nodemcu-v3-hardware.md) — NodeMCU V3 硬件参考 - [docs/design/architecture.md](docs/design/architecture.md) — crate 依赖图与 trait 边界 - [docs/superpowers/specs/2026-06-26-chipforge-1.3-own-stub-design.md](docs/superpowers/specs/2026-06-26-chipforge-1.3-own-stub-design.md) — 自有 MIT ESP8266 stub：设计、ROM 调试与四个根本原因踩坑记录 - [docs/design/adding-a-chip.md](docs/design/adding-a-chip.md) — 如何添加新的芯片系列 - [docs/design/adding-a-converter.md](docs/design/adding-a-converter.md) — 如何添加 USB-UART 转换器

标签：ESP32, ESP8266, Rust, 可视化界面, 嵌入式开发, 烧录工具, 硬件接口, 网络流量审计, 通知系统