Mr-PauI/ESP32-BinForge

**ESP32-BinForge** 是一款用于处理 ESP32 固件 `.bin` 文件的精简工具。它提供对固件镜像的结构化分析，支持就地数据注入，并重新生成 CRC，以确保二进制文件在修改后仍可烧录——从而使构建后定制变得安全且简单。 该工具专为无需重新编译固件即可进行构建后定制的工作流而设计，例如嵌入资源、配置 blob 或替换占位符数据。BinForge 包含一对跨平台 CLI 工具、一个 Windows GUI 实现以及一个（仍处于 alpha 阶段的）[浏览器/WASM 版本](https://mr-paui.github.io/ESP32-BinForge/)。 该工具提供了一个保留的嵌入区域。该区域的解释和使用完全由用户自定义。 数据区域由随机生成的 [magic byte](https://github.com/Mr-PauI/ESP32-BinForge/blob/main/blobs/blob_32b.h) 序列定义。该序列被特意设计为不可压缩的，以防止工具链或链接器在编译期间折叠或去重该区域。最小尺寸为 32 字节，但提供了许多标准尺寸的头部，并且包含的 [blobgen](https://github.com/Mr-PauI/ESP32-BinForge/blob/main/bin/windows-x86_x64/blobgen.exe) 工具可以生成特定大小的 blob。 在注入用户数据之前，应将此二进制 blob 区域的内容视为未定义。 下面是同一个固件在 3 个并发终端会话中的屏幕截图。最左边的图像代表包含的演示固件 在未经修改的情况下编译和烧录。接下来的两个终端窗口显示了编译后的 .bin 文件经过 BinForge 处理后的结果 BinForge 提供了两个 CLI 工具，用于处理固件 blob 和管理 .bin 文件：`blobgen` 和 `ESP32-BinForge-CLI`。 ## ESP32-BinForge-CLI 该工具根据传递的参数提供多种功能。 用法： ``` ESP32-BinForge-CLI # Analyze .bin file ESP32-BinForge-CLI # regenerate CRC only ESP32-BinForge-CLI # merge data and regenerate CRC ``` ## blobgen 此工具用于创建特定大小的保留二进制 blob。 用法： ``` blobgen ``` 有关 BinForge GUI 的使用信息，请参阅 [Wiki](https://github.com/Mr-PauI/ESP32-BinForge/wiki/GUI-Usage)。 ## 当前功能 - **数据注入** - 将用户提供的数据注入到固件镜像的预定义区域 - 注入后自动重新生成 CRC - 包含 [PlatformIO](https://github.com/Mr-PauI/ESP32-BinForge/tree/main/examples/PlatformIO) 和 [Arduino](https://github.com/Mr-PauI/ESP32-BinForge/tree/main/examples/Arduino) 示例 - **仅 CRC 模式** - 为由外部工具修改的二进制文件重新生成 CRC - **SHA-256 处理** - 目前禁用 SHA-256 检查（对于修改后的镜像，这是必需的） - SHA-256 重新生成计划在未来的版本中实现 - **检查 .bin 文件内容** – 分析 ESP32 固件镜像并显示详细的段信息，包括 flash 模式、芯片类型、入口地址、段加载地址、文件偏移量、大小、CRC 检查以及 SHA-256 的存在情况，提供对二进制内容的清晰视图。报告基本的结构错误以及任何 CRC 不匹配的情况。 ## 它*不*做什么 - **不**重新生成 SHA-256 哈希（目前） - 除了更新校验和外，**不**验证注入数据的正确性 - **不**剥离 SHA-256 哈希，这意味着目前应避免重新处理已合并或已验证的二进制文件，因为 SHA-256 可能会被误解为镜像头部。 ## 使用场景 - **编译后固件定制** 在构建后修改固件镜像，无需重新编译或重新链接。 - **将资源或数据 blob 注入 ESP32 二进制文件** 嵌入 ROM 常驻资源，如 logo、表格、查找数据或游戏图像。 - **在手动或自动二进制编辑后修复 CRC** 重新验证修改后的固件镜像，使其保持可烧录状态。 - **闭源或受限源码固件工作流** 在源代码不可用或重新构建不切实际时，自定义或参数化固件镜像。 - **制造和部署变体** 从单个基础镜像生成多个固件变体（品牌、配置、区域数据）。 - **后期阶段的固件更改** 在代码冻结、认证或构建系统锁定后应用更改。 - **资源受限系统的 ROM 支持数据** 将大型静态数据存储在 flash/ROM 中，而不是消耗 RAM。 - **固件实验和逆向工程工作流** 安全地修改二进制文件，以用于测试、研究或探索性开发。 - **模拟器和复古固件用例** 将 ROM 镜像或游戏数据直接嵌入固件，用于独立的模拟目标。 - **许可、配置和设备个性化** 注入每台设备的密钥、许可证号、API token 或其他元数据，而无需重新构建固件。CRC 检查允许固件检测注入的数据是否仍处于默认状态。 - **工具和自动化流水线** 集成到脚本或 CI 系统中，以实现可重复的构建后固件修改。 ## 范围和兼容性 - 基于 ESP32 固件镜像规范 - 适用于 ESP32、ESP32-S2、ESP32-S3、ESP32-C2、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-C61、ESP32-H2、ESP32-H21、ESP32-H4、ESP32-P4 和 ESP32-S31 （与早期 Espressif MCU 的兼容性尚未验证） ## 设计约束 - BinForge 对每个固件镜像仅操作单个保留数据 blob。 - blob 由固定的 32 字节 [magic pattern](https://github.com/Mr-PauI/ESP32-BinForge/blob/main/blobs/blob_32b.h) 标识。由于此原因，blob 的最小尺寸为 32 字节。 - 注入是就地执行的；固件布局和段大小不会被修改。 - 该工具不解释 blob 内容——所有语义均由用户代码定义。 - blob 的完整性使用在 blob 创建时生成的 CRC32 进行验证。 - 用户有责任确保注入的数据适合保留区域。 - BinForge 对未加密的 ESP32 固件镜像进行操作。 - 它不是 DRM 或安全许可解决方案。 - 它不对加密固件进行操作。任何固件加密必须在 BinForge 的修改完成*之后*应用。 ## 许可证 MIT 许可证 — 详情请参阅 [`LICENSE`](https://github.com/Mr-PauI/ESP32-BinForge/blob/main/LICENSE)。 本项目包含来自 Espressif Systems 的 esp_app_format.h，该文件基于 Apache 2.0 许可证授权。

标签：ESP32, SOC Prime, UML, 二进制处理, 固件工具, 开发工具, 文档结构分析, 物联网