音视频音频处理嵌入式物联网语音【免费下载链接】esp-adfEspressif Advanced Development Framework for Multimedia Applications项目地址https://gitcode.com/gh_mirrors/es/esp-adf点击查看免费下载本文以esp_ota_service组件的 CHANGELOG.md 为核心脉络完整梳理其从 v0.5.0 初始版本到 v0.5.2~1 的演进路径并逐层拆解组件引以为核心的数据源source— 写入目标target— 版本检查器checker— 完整性校验器verifier四层 OTA 流水线架构。读者将掌握该组件提供的全部内置抽象实现、Kconfig 配置项、事件总线协议、断点续传与回滚机制以及如何在 ESP-ADF 工程中像ota_http示例那样快速组装一条可运行的 OTA 升级链路。一、版本演进总览从 v0.5.0 到 v0.5.2~1esp_ota_service是 Espressif 高级多媒体开发框架ESP-ADF中的esp_service_t子类负责实现完整的空中固件升级OTA流水线。组件的演进记录集中保存在 CHANGELOG.md 中自上而下覆盖了从初始版本到当前版本的全部变更可按时间线归纳如下版本类型核心变更v0.5.0Features组件初始版本引入四层 OTA 流水线、全部内置 source/target/checker/verifier、NVS 断点续传、回滚、暂停/恢复、事件总线与 MCP 集成v0.1.0~1Changes将 Kconfig 菜单统一重命名为ESP-Service: OTA Service与esp_service系列组件在 menuconfig 中的分组保持一致README 增加 Component Registry 徽章v0.5.1Changes新增对 ESP-IDF v6.0 及更高版本的支持v0.5.2Changes将gmf_io依赖版本升级到 v1.0v0.5.2~1Bug Fixes更新测试应用的esp-board-manager依赖版本其中 v0.5.0 是信息密度最高的一个版本也是本文展开的主干——它一次性交付了组件的全部核心能力。v0.1.0~1 的 Kconfig 菜单改名与 v0.5.1 起的 ESP-IDF v6.0 支持则分别体现了组件在用户配置体验与工具链兼容性两个维度上的持续打磨。二、四层 OTA 流水线架构source / target / checker / verifierv0.5.0 最核心的设计是可组合的四层 OTA 流水线。升级过程被拆分为四个彼此独立的抽象层任意组合传输方式HTTP/HTTPS、文件系统、BLE与写入目标应用分区、数据分区、Bootloader都无需修改核心服务代码数据源esp_ota_service_source_t提供要写入分区的字节流写入目标esp_ota_service_target_t接收字节流并写入 flash 分区版本检查器esp_ota_service_checker_t下载前回答是否需要升级完整性校验器esp_ota_service_verifier_t下载过程中流式验证镜像完整性。每个抽象层本质上都是函数指针结构体vtable。以 esp_ota_service_source_t 为例接口包含open(uri)、read(buf, len)、get_size()、seek(offset)、close()、destroy()六个钩子esp_ota_service_target_t 则包含open(partition_label)、write()、commit()、abort()、get_write_offset()、set_write_offset()、destroy()。v0.5.0 交付的内置实现如下表层内置实现创建函数说明sourceesp_ota_service_source_http_create()HTTP/HTTPS 下载见 esp_ota_service_source_http.hsourceesp_ota_service_source_fs_create()本地文件系统file://sdcard/firmware.bin见 esp_ota_service_source_fs.hsourceesp_ota_service_source_ble_create()可选BLE GATT 外设遵循官方 ESP BLE OTA APP 协议Kconfig 门控targetesp_ota_service_target_app_create()应用分区esp_ota_*API自动选择下一个 OTA 槽位targetesp_ota_service_target_data_create()原始数据分区targetesp_ota_service_target_bootloader_create()可选Bootloader 升级Kconfig 门控checkeresp_ota_service_checker_app_create()读取远端镜像头esp_app_desc_t比较版本checkeresp_ota_service_checker_data_version_create()读取数据镜像前 4 字节 packed semver 比较checkeresp_ota_service_checker_manifest_create()拉取 JSON 清单version sha256 sizecheckeresp_ota_service_checker_tone_desc_create()音调/提示音描述检查verifieresp_ota_service_verifier_sha256_create()流式 SHA-256 校验基于 mbedtlsverifieresp_ota_service_verifier_md5_create()流式 MD5 校验2.1 升级条目与流水线执行顺序一次升级会话由一组esp_ota_upgrade_item_t描述见 esp_ota_service.h 中定义每个条目代表一个分区的一次升级typedef struct esp_ota_upgrade_item { const char *uri; /* 传给 source-open() 的 URI必填服务会深拷贝 */ const char *partition_label; /* 传给 target-open() 的分区标签NULL 表示自动选择下一个 OTA 应用槽位 */ esp_ota_service_source_t *source; /* 数据流来源必填 */ esp_ota_service_target_t *target; /* 写入目标必填 */ esp_ota_service_verifier_t *verifier; /* 可选的流式完整性校验器NULL 不校验 */ esp_ota_service_checker_t *checker; /* 可选的下载前版本检查器NULL 跳过版本检查 */ bool skip_on_fail; /* true 时失败继续下一个条目false默认中止整个会话 */ bool resumable; /* 是否启用 NVS 断点续传 */ } esp_ota_upgrade_item_t;在 esp_ota_service.c 的esp_ota_service_worker_task()与process_item()中可以清晰看到每个条目的标准执行顺序版本检查若checker非空先调用checker-check()发出ESP_OTA_SERVICE_EVT_ITEM_VER_CHECK事件若判定无需升级则静默跳过不触发ITEM_BEGIN/ITEM_END打开数据源source-open(uri)并读取get_size()作为总字节数开启校验器verifier-verify_begin()若拒绝镜像则条目以 SKIPPED 收尾打开目标target-open(partition_label)读-校验-写循环source-read()→verifier-verify_update()→target-write()直到 EOF每次读取后按节流周期约 1 秒发布ITEM_PROGRESS结束校验verifier-verify_finish()不通过则中止该条目提交target-commit()成功后清除断点续传记录失败路径调用target-abort()。2.2 暂停与恢复v0.5.0 还内置了下载过程中的暂停/恢复能力对运行中的会话调用esp_service_pause()/esp_service_resume()。从源码看esp_ota_service_on_pause()与esp_ota_service_on_resume()实际是通过设置/清除结构体内的atomic_bool paused标志实现的worker 读取循环每 50 ms 轮询一次该标志以响应暂停见 esp_ota_service.c。三、事件总线6 种事件覆盖整个会话生命周期esp_ota_service通过 ADF Event Hub 向应用上报进度。订阅方式为esp_service_event_subscribe((esp_service_t *)svc, sub)每次回调收到的adf_event_t::payload是指向esp_ota_service_event_t *的堆内存含item_label深拷贝由事件中心在释放回调时回收。协议要求先读取evt-id再访问对应的联合体分支。6 种事件及其关键字段如下事件含义关键字段ESP_OTA_SERVICE_EVT_SESSION_BEGINWorker 任务已启动—ESP_OTA_SERVICE_EVT_ITEM_VER_CHECK版本检查完成ver_check.upgrade_available、errorESP_OTA_SERVICE_EVT_ITEM_BEGIN下载写入循环即将开始item_index、item_labelESP_OTA_SERVICE_EVT_ITEM_PROGRESS约每秒一次进度更新progress.bytes_written、progress.total_bytesESP_OTA_SERVICE_EVT_ITEM_END单个分区升级结束item_end.status、item_end.reason、errorESP_OTA_SERVICE_EVT_SESSION_END全部条目完成或中止session_end.{success,failed,skipped}_count、abortedESP_OTA_SERVICE_EVT_ITEM_VER_CHECK的语义需要特别注意源码注释与实现一致error ! ESP_OK表示检查器报错随后会触发ITEM_END(FAILED)error ESP_OK且!upgrade_available时条目静默跳过不触发ITEM_BEGIN/ITEM_ENDerror ESP_OK且upgrade_available时继续下载。ITEM_END的reason字段进一步细分了失败/跳过原因VERIFIER_REJECTED校验器拒绝计为 SKIPPED、CHECK_FAILED、ABORTED、PIPELINE下载/写入/提交路径出错。事件 ID 从 2 开始0 为非法1 保留给ESP_SERVICE_EVENT_STATE_CHANGEDESP_OTA_SERVICE_EVT_MAX为哨兵值、永不被发布。ota_http示例的事件处理器esp_ota_service_http_example.c演示了标准用法在SESSION_END中检查aborted/failed_count判定整场升级成败并通过 Event Group 向主任务通知DONE/FAIL/SKIP三种结果。四、断点续传、回滚与镜像确认4.1 基于 NVS 的断点续传CONFIG_OTA_ENABLE_RESUME默认开启v0.5.0 引入的断点续传机制把下载偏移每 N KB 保存到 NVS命名空间ota_resume键格式u{idx}/w{idx}/i{idx}见 esp_ota_service_resume.c。失败或重启后下一次升级会从最后保存的偏移继续数据源通过seek()跳到断点目标通过set_write_offset()跳过已写入区域成功完成后清除对应记录。关键约束源码在esp_ota_service_set_upgrade_list()中做了严格校验违反即返回ESP_ERR_NOT_SUPPORTED启用resumable true要求数据源实现了seek()且目标实现了set_write_offset()数据分区与 Bootloader 目标在open()时会整分区擦除无法断点续传因此必须设resumable falseBLE 数据源未实现seek()同样必须设resumable false每次调用esp_ota_service_set_upgrade_list()都会清空全部历史续传记录因为新列表可能与旧布局不匹配并且 URI 长度上限为 255 字符续传存储的容量限制。此外从process_item()的实现可以看到一个健壮性细节即使 NVS 中存有断点若目标get_write_offset()返回 0说明目标侧没有残留数据服务会判定续传记录过期自动从零开始重新下载并清除该记录。4.2 双镜像回滚CONFIG_OTA_ENABLE_ROLLBACK配合 ESP-IDF 的 A/B 双镜像机制组件提供了完整的回滚闭环见 esp_ota_service.h 中的三个 APIesp_ota_service_is_pending_verify()查询当前运行镜像是否处于ESP_OTA_IMG_PENDING_VERIFY待验证状态。该函数不依赖服务句柄、不分配内存官方建议在app_main()早期调用以便在后续任何复位触发 bootloader 自动回滚之前完成自检与裁决esp_ota_service_confirm_update()新固件验证通过后如 WiFi 已成功连接调用取消下次重启时的自动回滚。仅在CONFIG_OTA_ENABLE_ROLLBACK开启且当前镜像处于 PENDING_VERIFY 时生效esp_ota_service_rollback()标记当前镜像无效并重启回到旧固件成功时不返回。ota_http示例app_main.c展示了完整模式OTA 重启后检查镜像状态先尝试连接 WiFi——连接失败且镜像处于 PENDING_VERIFY 时调用rollback()连接成功则调用confirm_update()取消回滚。注意若未调用confirm_update()每次重启都会触发回滚这是双镜像机制的安全默认行为。五、Kconfig 配置项详解组件在 Kconfig 中按Verification and rollback / Download sources / Resume / Advanced targets四组组织配置项v0.1.0~1 起统一挂载在ESP-Service: OTA Service菜单下配置项默认值范围说明OTA_FORCE_VERSION_CHECKn—开启后esp_ota_service_checker_app_create(NULL)默认拒绝版本相同或更旧的固件也可在运行时通过esp_ota_service_checker_app_cfg_t::version_policy按 checker 覆盖OTA_ENABLE_ROLLBACKn—开启 OTA 回滚支持新镜像以 PENDING_VERIFY 启动需调用esp_ota_service_confirm_update()确认OTA_HTTP_TIMEOUT_MS100001000–60000HTTP/HTTPS 数据源默认读超时可在esp_ota_service_source_http_cfg_t中按 source 覆盖OTA_ENABLE_BLE_SOURCEn—编译 BLE 数据源官方 ESP BLE OTA APP 协议svc 0x8018、RECV_FW 0x8020、COMMAND 0x8022分扇区带 ACKGATT 服务基于 NimBLE 原生实现无需托管组件OTA_BLE_RING_BUF_SIZE81922048–32768BLE 数据源环形缓冲区大小字节越大越能吸收 APP 快速下发扇区时的突发数据OTA_BLE_WAIT_START_MS300005000–120000open()等待 APP 发送携带固件长度的 Start OTA 命令的超时时间OTA_ENABLE_RESUMEy—启用 NVS 断点续传默认开启OTA_RESUME_SAVE_INTERVAL_KB6416–256每写入多少 KB 保存一次续传进度越小粒度越细但 NVS 磨损越大OTA_ENABLE_BOOTLOADER_OTAn—编译 Bootloader 升级目标先写入暂存分区校验后拷贝到 Bootloader 区域偏移 0x0风险提示Bootloader OTACONFIG_OTA_ENABLE_BOOTLOADER_OTA无原子性保证最终拷贝途中断电可能让设备变砖建议仅配合可恢复 Bootloader 或受控工厂环境使用组件自身的test_apps当前也暂未覆盖该路径CHANGELOG/README 中标注为 TODO。除上述 Kconfig 项外其余调节参数worker 任务栈、读写块大小、停止超时都是 esp_ota_service_cfg_t 的运行时字段用ESP_OTA_SERVICE_CFG_DEFAULT()初始化后按需覆盖worker_task.stack_size默认 6144 字节ESP_OTA_SERVICE_DEFAULT_WORKER_STACK_SIZEpriority 默认 5core_id -1表示任意核write_chunk_size默认 4096 字节非零时合法范围 512–65536源码在esp_ota_service_create()中校验越界返回ESP_ERR_INVALID_ARGstop_timeout_msesp_service_stop()等待 worker 退出的最大时间默认 10000 ms非零时最小 1000 ms。六、快速上手一条完整的 HTTP OTA 链路6.1 固定的四步模式官方推荐的流程详见 ota_http 示例永远是创建流水线组件 → 订阅事件 →esp_ota_service_set_upgrade_list()→esp_service_start()。esp_ota_service_cfg_t svc_cfg ESP_OTA_SERVICE_CFG_DEFAULT(); esp_ota_service_t *svc NULL; esp_ota_service_create(svc_cfg, svc); /* 1. 创建服务 */ adf_event_subscribe_info_t sub ADF_EVENT_SUBSCRIBE_INFO_DEFAULT(); sub.handler on_ota_adf_event; esp_service_event_subscribe((esp_service_t *)svc, sub); /* 2. 订阅事件 */ /* 3. 组装条目HTTP 数据源 应用分区目标 SHA-256 校验器 */ esp_ota_upgrade_item_t items[] {{ .uri http://10.18.20.234:18070/firmware.bin, .partition_label NULL, .source src, /* esp_ota_service_source_http_create() */ .target tgt, /* esp_ota_service_target_app_create() */ .verifier ver, /* esp_ota_service_verifier_sha256_create() */ .checker NULL, .skip_on_fail false, .resumable true, }}; esp_ota_service_set_upgrade_list(svc, items, 1); /* 4. 设置升级列表 */ esp_service_start((esp_service_t *)svc); /* 5. 启动立即返回worker 后台执行 */所有权规则重要从esp_ota_service_set_upgrade_list()被调用的那一刻起服务就接管列表中每个source、target、checker、verifier的所有权。绝不要直接调用它们的destroy()——包括该调用失败的错误路径服务也会代为释放最终统一由esp_ota_service_destroy()清理。这是 v0.5.0 明确设计的资源模型示例代码中特意用注释标注了这一点。6.2 不同场景的组件选型README 给出了一张实用的选型表覆盖最常见的升级场景场景sourcecheckerverifiertargetHTTP OTA版本 SHA-256 校验source_http_create()checker_manifest_create()verifier_sha256_create()target_app_create()HTTP OTA仅版本检查source_http_create()checker_app_create()—target_app_create()SD 卡 / U 盘source_fs_create()checker_app_create()—target_app_create()BLE无 WiFisource_ble_create()——target_app_create()多分区批量升级每个分区一个 source每个分区一个 checker可选target_app_create()/target_data_create()数据分区升级source_http_create()/source_fs_create()checker_data_version_create()—target_data_create()其中esp_ota_service_checker_manifest_create()拉取 JSON 清单{version:1.2.3,project_name:my_app,size:1048576,sha256:a1b2c3...,md5:d41d8c...}清单含 SHA-256 摘要时会把esp_ota_service_check_result_t::has_hash true/hash[32]置位——调用方可以据此在启动会话前配置esp_ota_service_verifier_sha256_create()的期望摘要实现先比对版本、再流式校验哈希的完整链路完整模式见 ota_http 示例 的 Step 1–Step 3。6.3 从 manifest 到 SHA-256 校验的完整模式ota_http示例展示了推荐的进阶用法先手动调用manifest_chk-check()预取清单判断版本、拿到哈希据此装配 SHA-256 校验器再把checker NULL交给流水线——因为版本已在会话外确认过而哈希由 verifier 在下载过程中流式验证。esp_ota_service_checker_manifest_parse_json()是同一解析逻辑的纯函数版本可供单元测试与宿主机工具直接复用见 esp_ota_service_checker_manifest.h。七、自定义 source / target / checker / verifier每种抽象都是函数指针结构体实现接口后交给esp_ota_service_set_upgrade_list()即可服务接管所有权并在生命周期结束时调用destroy()。以自定义数据源为例模式完全适用于另外三层static esp_err_t my_open(esp_ota_service_source_t *self, const char *uri) { ... } static int my_read(esp_ota_service_source_t *self, uint8_t *buf, int len) { ... } static int64_t my_get_size(esp_ota_service_source_t *self) { return -1; } static esp_err_t my_close(esp_ota_service_source_t *self) { ... } static void my_destroy(esp_ota_service_source_t *self) { free(self); } esp_err_t my_source_create(esp_ota_service_source_t **out_src) { esp_ota_service_source_t *src calloc(1, sizeof(esp_ota_service_source_t)); if (!src) { return ESP_ERR_NO_MEM; } src-open my_open; src-read my_read; src-get_size my_get_size; src-seek NULL; /* 无 seek —— resumable 必须为 false */ src-close my_close; src-destroy my_destroy; *out_src src; return ESP_OK; }注意接口语义约定read返回0表示实际读取字节数、0表示流结束、0表示读取错误get_size返回-1表示总大小未知如 HTTP chunked 编码。各 vtable 定义分别见 source、target、checker、verifier 四个头文件verifier 的钩子按verify_begin → verify_update×N → verify_finish顺序被调用任一钩子返回非ESP_OK即中止该条目。八、工程化辅助测试与 MCP 远程调用测试覆盖组件在test_apps/下提供自动化测试含 pytest 用例v0.5.2~1 与 v0.5.2 两次依赖升级esp-board-manager、gmf_iov1.0正是围绕测试应用与构建链路所做的维护示例工程ota_http、ota_fs、ota_ble各自配套 pytest 与工具脚本见 tools/可完成版本化固件构建、SD 卡写入、HTTP 服务起停与 BLE 推送。MCP 集成CONFIG_ESP_MCP_ENABLEv0.5.0 起支持通过 MCP 工具远程触发 OTA。esp_ota_service_mcp_schema_get()返回工具描述 JSONesp_ota_service_tool_invoke()分发esp_ota_service_get_version、esp_ota_service_get_progress、esp_ota_service_check_update等操作esp_ota_service_mcp_cache_update_info()可将应用侧的check_update结果缓存供 MCP 工具查询见 esp_ota_service_mcp.h。这为由 LLM/Agent 通过 MCP 协议远程查询固件状态并触发升级的运维场景提供了现成接口。九、总结回顾 CHANGELOG.md 的演进轨迹v0.5.0 一次交付了四层可组合流水线、三路数据源、三类目标、四类检查器、两种校验器以及断点续传/回滚/暂停恢复/事件总线/MCP 集成等完整能力随后的版本在 Kconfig 菜单组织v0.1.0~1、ESP-IDF v6.0 工具链支持v0.5.1与构建依赖维护v0.5.2、v0.5.2~1上持续打磨。对开发者而言使用该组件的收益在于任意传输方式与任意写入目标的组合无需改动核心代码一条升级会话可批量覆盖应用分区、数据分区与音调分区并通过统一事件流掌握全过程的版本判定、下载进度与成败统计。深入阅读 README_CN.md、主头文件 与 ota_http 示例即可从示例工程出发快速落地生产级 OTA 方案。赞分享音视频音频处理嵌入式物联网语音【免费下载链接】esp-adfEspressif Advanced Development Framework for Multimedia Applications项目地址https://gitcode.com/gh_mirrors/es/esp-adf点击查看免费下载相关推荐ESP-ADF OTA 服务esp_ota_serviceAPI 参考模块化四阶段升级流水线与实战配置ESP ADF OTA 服务esp_ota_serviceAPI 参考模块化四阶段升级流水线与实战配置 ESP ADF 的 OTA 服务OTA serv音视频音频处理嵌入式物联网语音ESP-ADF OTA Service 空中升级服务完全指南四层流水线架构、配置详解与 HTTP/SD/BLE 三种实战ESP ADF OTA Service 空中升级服务完全指南四层流水线架构、配置详解与 HTTP/SD/BLE 三种实战 ESP ADFEspressif音视频音频处理嵌入式物联网语音esp-adf esp_button_service 组件深度解析将 esp_board_manager 按键设备零配置接入 ADF 事件总线esp adf esp_button_service 组件深度解析将 esp_board_manager 按键设备零配置接入 ADF 事件总线 本文以 esp音视频音频处理嵌入式物联网语音上一篇解锁智能解析新体验百度网盘资源获取秒级解决方案下一篇iOS微信抢红包插件2025升级版零门槛自动抢红包全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/14 6:33:45 · 阅读 1.2k esp_ota_service 演进史与技术拆解：ESP-ADF 四层 OTA 流水线组件深度指南
音视频音频处理嵌入式物联网语音【免费下载链接】esp-adfEspressif Advanced Development Framework for Multimedia Applications项目地址https://gitcode.com/gh_mirrors/es/esp-adf点击查看免费下载本文以esp_ota_service组件的 CHANGELOG.md 为核心脉络完整梳理其从 v0.5.0 初始版本到 v0.5.2~1 的演进路径并逐层拆解组件引以为核心的数据源source— 写入目标target— 版本检查器checker— 完整性校验器verifier四层 OTA 流水线架构。读者将掌握该组件提供的全部内置抽象实现、Kconfig 配置项、事件总线协议、断点续传与回滚机制以及如何在 ESP-ADF 工程中像ota_http示例那样快速组装一条可运行的 OTA 升级链路。一、版本演进总览从 v0.5.0 到 v0.5.2~1esp_ota_service是 Espressif 高级多媒体开发框架ESP-ADF中的esp_service_t子类负责实现完整的空中固件升级OTA流水线。组件的演进记录集中保存在 CHANGELOG.md 中自上而下覆盖了从初始版本到当前版本的全部变更可按时间线归纳如下版本类型核心变更v0.5.0Features组件初始版本引入四层 OTA 流水线、全部内置 source/target/checker/verifier、NVS 断点续传、回滚、暂停/恢复、事件总线与 MCP 集成v0.1.0~1Changes将 Kconfig 菜单统一重命名为ESP-Service: OTA Service与esp_service系列组件在 menuconfig 中的分组保持一致README 增加 Component Registry 徽章v0.5.1Changes新增对 ESP-IDF v6.0 及更高版本的支持v0.5.2Changes将gmf_io依赖版本升级到 v1.0v0.5.2~1Bug Fixes更新测试应用的esp-board-manager依赖版本其中 v0.5.0 是信息密度最高的一个版本也是本文展开的主干——它一次性交付了组件的全部核心能力。v0.1.0~1 的 Kconfig 菜单改名与 v0.5.1 起的 ESP-IDF v6.0 支持则分别体现了组件在用户配置体验与工具链兼容性两个维度上的持续打磨。二、四层 OTA 流水线架构source / target / checker / verifierv0.5.0 最核心的设计是可组合的四层 OTA 流水线。升级过程被拆分为四个彼此独立的抽象层任意组合传输方式HTTP/HTTPS、文件系统、BLE与写入目标应用分区、数据分区、Bootloader都无需修改核心服务代码数据源esp_ota_service_source_t提供要写入分区的字节流写入目标esp_ota_service_target_t接收字节流并写入 flash 分区版本检查器esp_ota_service_checker_t下载前回答是否需要升级完整性校验器esp_ota_service_verifier_t下载过程中流式验证镜像完整性。每个抽象层本质上都是函数指针结构体vtable。以 esp_ota_service_source_t 为例接口包含open(uri)、read(buf, len)、get_size()、seek(offset)、close()、destroy()六个钩子esp_ota_service_target_t 则包含open(partition_label)、write()、commit()、abort()、get_write_offset()、set_write_offset()、destroy()。v0.5.0 交付的内置实现如下表层内置实现创建函数说明sourceesp_ota_service_source_http_create()HTTP/HTTPS 下载见 esp_ota_service_source_http.hsourceesp_ota_service_source_fs_create()本地文件系统file://sdcard/firmware.bin见 esp_ota_service_source_fs.hsourceesp_ota_service_source_ble_create()可选BLE GATT 外设遵循官方 ESP BLE OTA APP 协议Kconfig 门控targetesp_ota_service_target_app_create()应用分区esp_ota_*API自动选择下一个 OTA 槽位targetesp_ota_service_target_data_create()原始数据分区targetesp_ota_service_target_bootloader_create()可选Bootloader 升级Kconfig 门控checkeresp_ota_service_checker_app_create()读取远端镜像头esp_app_desc_t比较版本checkeresp_ota_service_checker_data_version_create()读取数据镜像前 4 字节 packed semver 比较checkeresp_ota_service_checker_manifest_create()拉取 JSON 清单version sha256 sizecheckeresp_ota_service_checker_tone_desc_create()音调/提示音描述检查verifieresp_ota_service_verifier_sha256_create()流式 SHA-256 校验基于 mbedtlsverifieresp_ota_service_verifier_md5_create()流式 MD5 校验2.1 升级条目与流水线执行顺序一次升级会话由一组esp_ota_upgrade_item_t描述见 esp_ota_service.h 中定义每个条目代表一个分区的一次升级typedef struct esp_ota_upgrade_item { const char *uri; /* 传给 source-open() 的 URI必填服务会深拷贝 */ const char *partition_label; /* 传给 target-open() 的分区标签NULL 表示自动选择下一个 OTA 应用槽位 */ esp_ota_service_source_t *source; /* 数据流来源必填 */ esp_ota_service_target_t *target; /* 写入目标必填 */ esp_ota_service_verifier_t *verifier; /* 可选的流式完整性校验器NULL 不校验 */ esp_ota_service_checker_t *checker; /* 可选的下载前版本检查器NULL 跳过版本检查 */ bool skip_on_fail; /* true 时失败继续下一个条目false默认中止整个会话 */ bool resumable; /* 是否启用 NVS 断点续传 */ } esp_ota_upgrade_item_t;在 esp_ota_service.c 的esp_ota_service_worker_task()与process_item()中可以清晰看到每个条目的标准执行顺序版本检查若checker非空先调用checker-check()发出ESP_OTA_SERVICE_EVT_ITEM_VER_CHECK事件若判定无需升级则静默跳过不触发ITEM_BEGIN/ITEM_END打开数据源source-open(uri)并读取get_size()作为总字节数开启校验器verifier-verify_begin()若拒绝镜像则条目以 SKIPPED 收尾打开目标target-open(partition_label)读-校验-写循环source-read()→verifier-verify_update()→target-write()直到 EOF每次读取后按节流周期约 1 秒发布ITEM_PROGRESS结束校验verifier-verify_finish()不通过则中止该条目提交target-commit()成功后清除断点续传记录失败路径调用target-abort()。2.2 暂停与恢复v0.5.0 还内置了下载过程中的暂停/恢复能力对运行中的会话调用esp_service_pause()/esp_service_resume()。从源码看esp_ota_service_on_pause()与esp_ota_service_on_resume()实际是通过设置/清除结构体内的atomic_bool paused标志实现的worker 读取循环每 50 ms 轮询一次该标志以响应暂停见 esp_ota_service.c。三、事件总线6 种事件覆盖整个会话生命周期esp_ota_service通过 ADF Event Hub 向应用上报进度。订阅方式为esp_service_event_subscribe((esp_service_t *)svc, sub)每次回调收到的adf_event_t::payload是指向esp_ota_service_event_t *的堆内存含item_label深拷贝由事件中心在释放回调时回收。协议要求先读取evt-id再访问对应的联合体分支。6 种事件及其关键字段如下事件含义关键字段ESP_OTA_SERVICE_EVT_SESSION_BEGINWorker 任务已启动—ESP_OTA_SERVICE_EVT_ITEM_VER_CHECK版本检查完成ver_check.upgrade_available、errorESP_OTA_SERVICE_EVT_ITEM_BEGIN下载写入循环即将开始item_index、item_labelESP_OTA_SERVICE_EVT_ITEM_PROGRESS约每秒一次进度更新progress.bytes_written、progress.total_bytesESP_OTA_SERVICE_EVT_ITEM_END单个分区升级结束item_end.status、item_end.reason、errorESP_OTA_SERVICE_EVT_SESSION_END全部条目完成或中止session_end.{success,failed,skipped}_count、abortedESP_OTA_SERVICE_EVT_ITEM_VER_CHECK的语义需要特别注意源码注释与实现一致error ! ESP_OK表示检查器报错随后会触发ITEM_END(FAILED)error ESP_OK且!upgrade_available时条目静默跳过不触发ITEM_BEGIN/ITEM_ENDerror ESP_OK且upgrade_available时继续下载。ITEM_END的reason字段进一步细分了失败/跳过原因VERIFIER_REJECTED校验器拒绝计为 SKIPPED、CHECK_FAILED、ABORTED、PIPELINE下载/写入/提交路径出错。事件 ID 从 2 开始0 为非法1 保留给ESP_SERVICE_EVENT_STATE_CHANGEDESP_OTA_SERVICE_EVT_MAX为哨兵值、永不被发布。ota_http示例的事件处理器esp_ota_service_http_example.c演示了标准用法在SESSION_END中检查aborted/failed_count判定整场升级成败并通过 Event Group 向主任务通知DONE/FAIL/SKIP三种结果。四、断点续传、回滚与镜像确认4.1 基于 NVS 的断点续传CONFIG_OTA_ENABLE_RESUME默认开启v0.5.0 引入的断点续传机制把下载偏移每 N KB 保存到 NVS命名空间ota_resume键格式u{idx}/w{idx}/i{idx}见 esp_ota_service_resume.c。失败或重启后下一次升级会从最后保存的偏移继续数据源通过seek()跳到断点目标通过set_write_offset()跳过已写入区域成功完成后清除对应记录。关键约束源码在esp_ota_service_set_upgrade_list()中做了严格校验违反即返回ESP_ERR_NOT_SUPPORTED启用resumable true要求数据源实现了seek()且目标实现了set_write_offset()数据分区与 Bootloader 目标在open()时会整分区擦除无法断点续传因此必须设resumable falseBLE 数据源未实现seek()同样必须设resumable false每次调用esp_ota_service_set_upgrade_list()都会清空全部历史续传记录因为新列表可能与旧布局不匹配并且 URI 长度上限为 255 字符续传存储的容量限制。此外从process_item()的实现可以看到一个健壮性细节即使 NVS 中存有断点若目标get_write_offset()返回 0说明目标侧没有残留数据服务会判定续传记录过期自动从零开始重新下载并清除该记录。4.2 双镜像回滚CONFIG_OTA_ENABLE_ROLLBACK配合 ESP-IDF 的 A/B 双镜像机制组件提供了完整的回滚闭环见 esp_ota_service.h 中的三个 APIesp_ota_service_is_pending_verify()查询当前运行镜像是否处于ESP_OTA_IMG_PENDING_VERIFY待验证状态。该函数不依赖服务句柄、不分配内存官方建议在app_main()早期调用以便在后续任何复位触发 bootloader 自动回滚之前完成自检与裁决esp_ota_service_confirm_update()新固件验证通过后如 WiFi 已成功连接调用取消下次重启时的自动回滚。仅在CONFIG_OTA_ENABLE_ROLLBACK开启且当前镜像处于 PENDING_VERIFY 时生效esp_ota_service_rollback()标记当前镜像无效并重启回到旧固件成功时不返回。ota_http示例app_main.c展示了完整模式OTA 重启后检查镜像状态先尝试连接 WiFi——连接失败且镜像处于 PENDING_VERIFY 时调用rollback()连接成功则调用confirm_update()取消回滚。注意若未调用confirm_update()每次重启都会触发回滚这是双镜像机制的安全默认行为。五、Kconfig 配置项详解组件在 Kconfig 中按Verification and rollback / Download sources / Resume / Advanced targets四组组织配置项v0.1.0~1 起统一挂载在ESP-Service: OTA Service菜单下配置项默认值范围说明OTA_FORCE_VERSION_CHECKn—开启后esp_ota_service_checker_app_create(NULL)默认拒绝版本相同或更旧的固件也可在运行时通过esp_ota_service_checker_app_cfg_t::version_policy按 checker 覆盖OTA_ENABLE_ROLLBACKn—开启 OTA 回滚支持新镜像以 PENDING_VERIFY 启动需调用esp_ota_service_confirm_update()确认OTA_HTTP_TIMEOUT_MS100001000–60000HTTP/HTTPS 数据源默认读超时可在esp_ota_service_source_http_cfg_t中按 source 覆盖OTA_ENABLE_BLE_SOURCEn—编译 BLE 数据源官方 ESP BLE OTA APP 协议svc 0x8018、RECV_FW 0x8020、COMMAND 0x8022分扇区带 ACKGATT 服务基于 NimBLE 原生实现无需托管组件OTA_BLE_RING_BUF_SIZE81922048–32768BLE 数据源环形缓冲区大小字节越大越能吸收 APP 快速下发扇区时的突发数据OTA_BLE_WAIT_START_MS300005000–120000open()等待 APP 发送携带固件长度的 Start OTA 命令的超时时间OTA_ENABLE_RESUMEy—启用 NVS 断点续传默认开启OTA_RESUME_SAVE_INTERVAL_KB6416–256每写入多少 KB 保存一次续传进度越小粒度越细但 NVS 磨损越大OTA_ENABLE_BOOTLOADER_OTAn—编译 Bootloader 升级目标先写入暂存分区校验后拷贝到 Bootloader 区域偏移 0x0风险提示Bootloader OTACONFIG_OTA_ENABLE_BOOTLOADER_OTA无原子性保证最终拷贝途中断电可能让设备变砖建议仅配合可恢复 Bootloader 或受控工厂环境使用组件自身的test_apps当前也暂未覆盖该路径CHANGELOG/README 中标注为 TODO。除上述 Kconfig 项外其余调节参数worker 任务栈、读写块大小、停止超时都是 esp_ota_service_cfg_t 的运行时字段用ESP_OTA_SERVICE_CFG_DEFAULT()初始化后按需覆盖worker_task.stack_size默认 6144 字节ESP_OTA_SERVICE_DEFAULT_WORKER_STACK_SIZEpriority 默认 5core_id -1表示任意核write_chunk_size默认 4096 字节非零时合法范围 512–65536源码在esp_ota_service_create()中校验越界返回ESP_ERR_INVALID_ARGstop_timeout_msesp_service_stop()等待 worker 退出的最大时间默认 10000 ms非零时最小 1000 ms。六、快速上手一条完整的 HTTP OTA 链路6.1 固定的四步模式官方推荐的流程详见 ota_http 示例永远是创建流水线组件 → 订阅事件 →esp_ota_service_set_upgrade_list()→esp_service_start()。esp_ota_service_cfg_t svc_cfg ESP_OTA_SERVICE_CFG_DEFAULT(); esp_ota_service_t *svc NULL; esp_ota_service_create(svc_cfg, svc); /* 1. 创建服务 */ adf_event_subscribe_info_t sub ADF_EVENT_SUBSCRIBE_INFO_DEFAULT(); sub.handler on_ota_adf_event; esp_service_event_subscribe((esp_service_t *)svc, sub); /* 2. 订阅事件 */ /* 3. 组装条目HTTP 数据源 应用分区目标 SHA-256 校验器 */ esp_ota_upgrade_item_t items[] {{ .uri http://10.18.20.234:18070/firmware.bin, .partition_label NULL, .source src, /* esp_ota_service_source_http_create() */ .target tgt, /* esp_ota_service_target_app_create() */ .verifier ver, /* esp_ota_service_verifier_sha256_create() */ .checker NULL, .skip_on_fail false, .resumable true, }}; esp_ota_service_set_upgrade_list(svc, items, 1); /* 4. 设置升级列表 */ esp_service_start((esp_service_t *)svc); /* 5. 启动立即返回worker 后台执行 */所有权规则重要从esp_ota_service_set_upgrade_list()被调用的那一刻起服务就接管列表中每个source、target、checker、verifier的所有权。绝不要直接调用它们的destroy()——包括该调用失败的错误路径服务也会代为释放最终统一由esp_ota_service_destroy()清理。这是 v0.5.0 明确设计的资源模型示例代码中特意用注释标注了这一点。6.2 不同场景的组件选型README 给出了一张实用的选型表覆盖最常见的升级场景场景sourcecheckerverifiertargetHTTP OTA版本 SHA-256 校验source_http_create()checker_manifest_create()verifier_sha256_create()target_app_create()HTTP OTA仅版本检查source_http_create()checker_app_create()—target_app_create()SD 卡 / U 盘source_fs_create()checker_app_create()—target_app_create()BLE无 WiFisource_ble_create()——target_app_create()多分区批量升级每个分区一个 source每个分区一个 checker可选target_app_create()/target_data_create()数据分区升级source_http_create()/source_fs_create()checker_data_version_create()—target_data_create()其中esp_ota_service_checker_manifest_create()拉取 JSON 清单{version:1.2.3,project_name:my_app,size:1048576,sha256:a1b2c3...,md5:d41d8c...}清单含 SHA-256 摘要时会把esp_ota_service_check_result_t::has_hash true/hash[32]置位——调用方可以据此在启动会话前配置esp_ota_service_verifier_sha256_create()的期望摘要实现先比对版本、再流式校验哈希的完整链路完整模式见 ota_http 示例 的 Step 1–Step 3。6.3 从 manifest 到 SHA-256 校验的完整模式ota_http示例展示了推荐的进阶用法先手动调用manifest_chk-check()预取清单判断版本、拿到哈希据此装配 SHA-256 校验器再把checker NULL交给流水线——因为版本已在会话外确认过而哈希由 verifier 在下载过程中流式验证。esp_ota_service_checker_manifest_parse_json()是同一解析逻辑的纯函数版本可供单元测试与宿主机工具直接复用见 esp_ota_service_checker_manifest.h。七、自定义 source / target / checker / verifier每种抽象都是函数指针结构体实现接口后交给esp_ota_service_set_upgrade_list()即可服务接管所有权并在生命周期结束时调用destroy()。以自定义数据源为例模式完全适用于另外三层static esp_err_t my_open(esp_ota_service_source_t *self, const char *uri) { ... } static int my_read(esp_ota_service_source_t *self, uint8_t *buf, int len) { ... } static int64_t my_get_size(esp_ota_service_source_t *self) { return -1; } static esp_err_t my_close(esp_ota_service_source_t *self) { ... } static void my_destroy(esp_ota_service_source_t *self) { free(self); } esp_err_t my_source_create(esp_ota_service_source_t **out_src) { esp_ota_service_source_t *src calloc(1, sizeof(esp_ota_service_source_t)); if (!src) { return ESP_ERR_NO_MEM; } src-open my_open; src-read my_read; src-get_size my_get_size; src-seek NULL; /* 无 seek —— resumable 必须为 false */ src-close my_close; src-destroy my_destroy; *out_src src; return ESP_OK; }注意接口语义约定read返回0表示实际读取字节数、0表示流结束、0表示读取错误get_size返回-1表示总大小未知如 HTTP chunked 编码。各 vtable 定义分别见 source、target、checker、verifier 四个头文件verifier 的钩子按verify_begin → verify_update×N → verify_finish顺序被调用任一钩子返回非ESP_OK即中止该条目。八、工程化辅助测试与 MCP 远程调用测试覆盖组件在test_apps/下提供自动化测试含 pytest 用例v0.5.2~1 与 v0.5.2 两次依赖升级esp-board-manager、gmf_iov1.0正是围绕测试应用与构建链路所做的维护示例工程ota_http、ota_fs、ota_ble各自配套 pytest 与工具脚本见 tools/可完成版本化固件构建、SD 卡写入、HTTP 服务起停与 BLE 推送。MCP 集成CONFIG_ESP_MCP_ENABLEv0.5.0 起支持通过 MCP 工具远程触发 OTA。esp_ota_service_mcp_schema_get()返回工具描述 JSONesp_ota_service_tool_invoke()分发esp_ota_service_get_version、esp_ota_service_get_progress、esp_ota_service_check_update等操作esp_ota_service_mcp_cache_update_info()可将应用侧的check_update结果缓存供 MCP 工具查询见 esp_ota_service_mcp.h。这为由 LLM/Agent 通过 MCP 协议远程查询固件状态并触发升级的运维场景提供了现成接口。九、总结回顾 CHANGELOG.md 的演进轨迹v0.5.0 一次交付了四层可组合流水线、三路数据源、三类目标、四类检查器、两种校验器以及断点续传/回滚/暂停恢复/事件总线/MCP 集成等完整能力随后的版本在 Kconfig 菜单组织v0.1.0~1、ESP-IDF v6.0 工具链支持v0.5.1与构建依赖维护v0.5.2、v0.5.2~1上持续打磨。对开发者而言使用该组件的收益在于任意传输方式与任意写入目标的组合无需改动核心代码一条升级会话可批量覆盖应用分区、数据分区与音调分区并通过统一事件流掌握全过程的版本判定、下载进度与成败统计。深入阅读 README_CN.md、主头文件 与 ota_http 示例即可从示例工程出发快速落地生产级 OTA 方案。赞分享音视频音频处理嵌入式物联网语音【免费下载链接】esp-adfEspressif Advanced Development Framework for Multimedia Applications项目地址https://gitcode.com/gh_mirrors/es/esp-adf点击查看免费下载相关推荐ESP-ADF OTA 服务esp_ota_serviceAPI 参考模块化四阶段升级流水线与实战配置ESP ADF OTA 服务esp_ota_serviceAPI 参考模块化四阶段升级流水线与实战配置 ESP ADF 的 OTA 服务OTA serv音视频音频处理嵌入式物联网语音ESP-ADF OTA Service 空中升级服务完全指南四层流水线架构、配置详解与 HTTP/SD/BLE 三种实战ESP ADF OTA Service 空中升级服务完全指南四层流水线架构、配置详解与 HTTP/SD/BLE 三种实战 ESP ADFEspressif音视频音频处理嵌入式物联网语音esp-adf esp_button_service 组件深度解析将 esp_board_manager 按键设备零配置接入 ADF 事件总线esp adf esp_button_service 组件深度解析将 esp_board_manager 按键设备零配置接入 ADF 事件总线 本文以 esp音视频音频处理嵌入式物联网语音上一篇解锁智能解析新体验百度网盘资源获取秒级解决方案下一篇iOS微信抢红包插件2025升级版零门槛自动抢红包全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考