# OTATools **Repository Path**: NetADs/otatools ## Basic Information - **Project Name**: OTATools - **Description**: 通用OTA更新工具组件 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-29 - **Last Updated**: 2026-08-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OTATools 通用 ESP32S3 OTA 更新工具组件 ## 项目简介 本项目是一个基于 ESP-IDF v5.5.3 的 OTA（Over-The-Air）更新组件，为 ESP32 系列芯片提供高兼容性、易集成的无线固件更新能力。 ## 核心特性 - ✅ 符合 ESP-IDF v5.5.3 标准组件结构 - ✅ 支持 HTTPS 安全下载 - ✅ 支持 Secure Boot 验证 - ✅ 自动失败回滚机制 - ✅ 断点续传支持 - ✅ 实时进度回调 - ✅ 详细日志输出 - ✅ 兼容 ESP32/ESP32S3/ESP32C3 ## 目录结构 本项目本身就是一个 ESP-IDF 组件库。 ``` . ├── include/ # 公共头文件 │ └── ota_tool.h # OTA API 接口 ├── src/ # 源代码 │ ├── ota_tool_main.c # 主逻辑和状态机 │ ├── ota_tool_https.c # HTTPS 下载处理 │ ├── ota_tool_verify.c # 固件验证 │ └── ota_tool_internal.h # 内部数据结构 ├── examples/ # 示例项目 │ └── simple_ota/ # 简单 OTA 示例 ├── CMakeLists.txt # 组件构建配置 ├── Kconfig # menuconfig 配置 ├── idf_component.yml # 组件描述文件 ├── README.md # 使用文档 ├── CHANGELOG.md # 更新日志 └── .gitignore # Git 忽略配置 ``` ## 快速开始 ### 作为 Git 组件库使用 此项目是一个独立的 ESP-IDF 组件库，可以通过以下方式集成到你的项目中： #### 方式一：通过 Gitee Git URL（推荐） 在你的ESP-IDF项目的根目录下，编辑 `idf_component.yml` 文件添加： ```yaml dependencies: ota_tool: git: https://gitee.com/NetADs/otatools.git version: ">=1.0.0" ``` ESP-IDF 的组件管理器会自动从 Gitee 下载并管理此组件。 #### 方式二：本地开发测试 开发阶段可以在项目的 `idf_component.yml` 中使用本地路径： ```yaml dependencies: ota_tool: path: /absolute/path/to/ota_tool ``` 或者使用相对于项目目录的路径： ```yaml dependencies: ota_tool: path: ../ota_tool ``` #### 方式三：发布到 ESP Component Registry（未来） 可以将组件发布到 [ESP Component Registry](https://components.espressif.com/)，然后用户可以直接使用： ```yaml dependencies: ota_tool: "^1.0.0" ``` ### 配置项目 #### 1. 使用默认配置 项目已提供标准配置文件： - `sdkconfig.defaults` - ESP-IDF 配置默认值 - `partitions.csv` - OTA 分区表 运行以下命令应用配置： ```bash idf.py reconfigure ``` #### 2. 自定义配置 如需修改配置： ```bash idf.py menuconfig ``` 进入 `Partition Table` → 选择 `Two OTA apps` 标准分区表配置（`partitions.csv`）： ```csv # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, , 0x6000, phy_init, data, phy, , 0x6000, factory, app, factory, , 0x200000, ota_0, app, ota_0, , 0x200000, ota_1, app, ota_1, , 0x200000, ``` ### 在代码中使用 ```c #include "ota_tool.h" // 定义回调函数 void on_start(void) { printf("OTA update started\n"); } void on_progress(size_t downloaded, size_t total) { printf("Progress: %zu%%\n", (downloaded * 100) / total); } void on_complete(esp_err_t result) { if (result == ESP_OK) { printf("OTA update successful! Rebooting...\n"); } else { printf("OTA update failed: %s\n", esp_err_to_name(result)); } } // 在应用中启动 OTA void trigger_ota_update(void) { ota_tool_config_t config = { .firmware_url = "https://example.com/firmware.bin", .buffer_size = 4096, .retry_count = 3, .skip_cert_verification = false, // 生产环境必须为 false .on_start = on_start, .on_progress = on_progress, .on_complete = on_complete, }; esp_err_t ret = ota_tool_start(&config); if (ret != ESP_OK) { ESP_LOGE("APP", "Failed to start OTA: %s", esp_err_to_name(ret)); } } ``` ### 配置 menuconfig ```bash idf.py menuconfig ``` 进入 `Component config` → `OTA Tool Configuration`： - **Enable OTA debug log**: 启用调试日志（默认禁用，生产环境建议禁用） **注意**: Kconfig 只保留调试开关配置，其他参数（如缓冲区大小、重试次数等）已在代码中设置合理默认值，可通过 API 参数覆盖。 ## 编译和测试 ### 编译示例项目 ```bash cd examples/simple_ota idf.py build ``` ### 烧录到设备 ```bash idf.py -p PORT flash monitor ``` 将 `PORT` 替换为你的串口设备： - Windows: `COM3`, `COM4`, ... - Linux: `/dev/ttyUSB0` - macOS: `/dev/tty.usbserial-xxxx` ## 文档 - [API 参考文档](README.md#api-概述) - [示例项目说明](examples/simple_ota/README.md) - [集成指南](docs/INTEGRATION_GUIDE.md) - 重要：如何集成到你的项目 - [系统架构](docs/ARCHITECTURE.md) - [接口文档](docs/INTERFACES.md) - [开发者指南](docs/DEVELOPER_GUIDE.md) ## API 概述 ### 核心函数 - `ota_tool_start()` - 启动 OTA 更新 - `ota_tool_cancel()` - 取消 OTA 操作 - `ota_tool_get_state()` - 获取当前状态 - `ota_tool_get_progress_percent()` - 获取下载进度 - `ota_tool_is_rollback_boot()` - 检测是否回滚启动 ### 配置结构 ```c typedef struct { const char *firmware_url; // 下载地址（必需） const char *cert_pem; // 服务器证书（可选） size_t buffer_size; // 缓冲区大小（默认：4096） uint8_t retry_count; // 重试次数（默认：3） bool skip_cert_verification; // 跳过证书验证（默认：false） bool enable_http; // 启用 HTTP（默认：false） // 回调函数 void (*on_start)(void); void (*on_progress)(size_t downloaded, size_t total); void (*on_complete)(esp_err_t result); } ota_tool_config_t; ``` ### 状态枚举 ```c typedef enum { OTA_TOOL_STATE_IDLE = 0, OTA_TOOL_STATE_DOWNLOADING, OTA_TOOL_STATE_VERIFYING, OTA_TOOL_STATE_ACTIVATING, OTA_TOOL_STATE_REBOOTING, OTA_TOOL_STATE_ROLLBACK, OTA_TOOL_STATE_ABORTED, OTA_TOOL_STATE_FAILED } ota_tool_state_t; ``` 详细 API 文档请查看 [README.md](README.md) 和 [docs/INTERFACES.md](docs/INTERFACES.md) ## 系统要求 - **ESP-IDF**: v5.5.3 或更高版本 - **支持芯片**: ESP32, ESP32S3, ESP32C3 - **分区要求**: 至少 2 个 OTA 分区 ## 安全建议 ### 生产环境部署 ⚠️ 1. **必须使用 HTTPS** - 绝对禁止使用 HTTP 2. **启用证书验证** - `skip_cert_verification = false` 3. **启用 Secure Boot** - 在 menuconfig 中启用安全启动 4. **使用固件签名** - 对固件镜像进行数字签名 5. **提供服务器证书** - 在 `cert_pem` 中配置服务器证书 ### 开发测试 🔧 - 可使用自签名证书 + `skip_cert_verification = true` - 可使用 HTTP（仅限内网测试） - 可禁用 Secure Boot ## 故障排查 ### 常见问题 **Q: OTA 失败，错误 `ESP_ERR_OTA_VALIDATE_FAILED`** A: 固件镜像损坏或分区表配置错误。检查固件完整性和分区表配置。 **Q: HTTPS 连接失败，错误 `ESP_ERR_TLS_HANDSHAKE`** A: 证书验证失败。检查系统时间是否同步、证书是否有效。 **Q: 下载进度一直卡在 0%** A: 网络连接问题。检查 WiFi 连接、固件 URL 是否可访问。 **Q: 设备重启后仍运行旧固件** A: 启动分区未正确设置。检查 `esp_ota_set_boot_partition()` 返回值。 **Q: 内存不足错误 `ESP_ERR_NO_MEM`** A: 减小缓冲区大小或检查内存泄漏。 ### 获取调试信息 启用详细日志： ```bash idf.py menuconfig # Component config -> Log output -> Default log verbosity -> DEBUG ``` 查看日志输出： ```bash idf.py monitor ``` ## 参与贡献 1. Fork 本仓库 2. 创建 `feature/xxx` 分支 3. 提交代码 4. 创建 Pull Request 我们欢迎以下贡献： - Bug 修复 - 功能增强 - 文档改进 - 测试用例 ## 许可证 Apache License 2.0 ## 相关链接 - [ESP-IDF OTA 官方文档](https://docs.espressif.com/projects/esp-idf/en/v5.5.3/esp32s3/api-guides/ota.html) - [ESP Component Registry](https://components.espressif.com/) - [Gitee 仓库](https://gitee.com/NetADs/otatools)