基于公开 ESP-IDF v6.1 维护 fork 的设备业务基座。当前具备持久 UUID、硬件事实、心跳、分区、配置事务、Wi-Fi station、本次启动 SNTP 时间同步门、USB status/restart/config.set 协议、配置后启动的严格 TLS MQTT 命令通道，以及 OTA pending 新槽本地确认。受控签名构建还具备 ota.start 下载和按 operation ID 查询 ota.result 持久收据的软件链，并提供只读、失败保守拒绝的双应用槽固件身份观察接口，供未来 Container 绑定。FRP 已接入公开组件和单 owner；受控 loopback 管理端点已有只读 status 软件候选，能在绑定成功后开放 FRP 启动门，但尚无同板资源及真实 FRPS 闭环；当前实板仍是未签名旧基座，五能力完整验收尚未完成。
flowchart LR
sdk_lock["sdk-lock.json：IDF / lwIP 精确提交"] --> sdk["公开 ESP-IDF v6.1 fork"]
sdk --> firmware["firmware：C3 现行应用 / ESP32 UART 前置"]
identity["device_identity：NVS UUID"] --> firmware
state["device_protocol / remote_config / wifi_runtime / safety_runtime"] --> firmware
state -->|"v3 凭据 / 控制任务"| mqtt_owner["mqtt_owner：TLS / SUBACK / HMAC / 结果"]
mqtt_owner --> mqtt
state -->|"v3 FRP 配置 / 端点门"| frp_owner["frp_owner：单实例 / 状态 / 停止收敛"]
state -->|"FRP 独立 HMAC / boot 期限"| frp_status["frp_status_listener：loopback 只读 status"]
frp_status -->|"绑定成功"| frp_owner
frp_owner -->|"端点就绪后才允许 start"| frp["公开 esp-frp：严格 TLS / Yamux / Token"]
time["time_runtime：SNTP 同步证明"] --> firmware
state -->|"控制任务轮询"| time
time --> idf_time["ESP-IDF esp_netif_sntp"]
ota["esp-ota：HTTPS / 镜像验签 / 槽机制"] --> firmware
receipt["ota_operation：产品约束 / operation 收据"] --> firmware
receipt -->|"只读有效槽 / 完整签名镜像身份"| image_set["可启动固件集合：未来 Container 绑定输入"]
firmware -->|"控制任务进展 + 30 秒本地窗口"| ota
state -->|"受控签名构建的 ota.start"| receipt
receipt -->|"预检 / 准备 / 选槽"| ota
ota -->|"TLS / 有界重试"| https["ESP-IDF esp_http_client：HTTPS"]
ota -->|"固定槽写入 / 签名 / 选槽 / 回滚"| slot["ESP-IDF app_update：A/B 回滚状态"]
receipt <-->|"operation ID / 摘要与槽事实"| nvs["base_store NVS：base_ota/operation"]
owner["ota_operation：启动 / OTA 共用串行 owner"] --> receipt
owner --> slot
binding["可选 container_binding：固件集合适配"] -->|"仅显式探针，未装配产品"| container["公开 esp-container：绑定对账 API"]
owner --> binding
image_set --> binding
layout["partitions：4 MiB 与双应用槽"] --> firmware
host["tools/device-control.py：公开串口示例"] <-->|"JSON 命令与设备结果"| state
firmware --> image["build/esp_base.bin"]
lab["apps/mqtt_integration：隔离测试应用"] --> mqtt["公开 esp-mqtt：官方核心 + emqtt_ 运行接口"]
mqtt <-->|"MQTT / 严格 TLS"| broker["Broker：实验已验收 / 设备级待联调"]
image --> board["经恢复基线核对的真实 ESP"]
source "$IDF_PATH/export.sh"
idf.py -C firmware build2026-09-26 固定 SDK 对当前工作树的普通 C3 构建通过，最新镜像 957712 字节、SHA-256 42f3c7a3f28f9a28874505f6148c472c9765926f4618e9498630454a8c3ac485，生成配置和分区仍为原 C3 基线；Base host ASan/UBSan 全套、离线预检假件 12/12、串口伪终端 5/5 通过。P1-04 C3 私有双份 Flash 的真实只读预检因 base_store 后 31 页不是有效 NVS 页而阻断，没有生成 v3 候选。ESP32 仓外副本以临时 ECDSA P-256 测试键构建的签名 Base 为 0xffff4 字节，离线验签有效；其探针三包槽各仅 0x60000，小于现有 532480 字节签名包，不能作为目标布局。产品仓 esp32 构建仍在布局/OTA/签名链守卫处退出，没有可刷写的 ESP32 Base 制品。详细输入与范围见开发检查点；P2-08/P6-03 仍在进行中。
IDF_PATH 指向 sdk-lock.json 固定的公开 ESP-IDF v6.1 fork 578cf89c343e388db43ba1f4ddcd602fedcb763c，其 lwIP 子模块固定为公开 esp-lwip@2758df4cd3666b3b2a5b53830148379326425c0d；准备及检查见宿主工具。构建会核对这两个提交、SDK 工作树、其他子模块及实际 lwIP 组件路径。其余依赖来自本仓、官方 cJSON 和 Component Manager 锁定的公开 esp-mqtt@5bff093646d8db810d64c50c39edc004e78bf40c、esp-ota@3c3f72b823ce856b02f838fef17db1368e6d5448、esp-frp@3a40a2c06580232bbe23cb981eeb21c4d14d33c1，不读取工作区相邻仓库。普通基座的软件候选使用 v3 配置；MQTT 的 HMAC、Topic 和 ClientID 合同未变，无凭据时不创建客户端。FRP 有独立 Token、CA、代理名和管理 key，loopback status listener 未绑定时不创建连接；完整请求合同见设备协议。隔离测试应用直接调用 emqtt_ 接口。构建制品和实板结论以开发检查点为准；编译不写设备。
NVS 初始化失败时保留原分区并停止初始化，不自动擦除。身份沿用 nvs/base_identity/device_uuid；分区地址和大小保持迁移基线。配置 base_store/base_config/committed 只接受 v3，旧 v1/v2 记录会使启动停止且不写入；现有实板必须在完整 Flash 备份、两槽与同一 NVS key 离线迁移验证后才可首次启动该镜像。只读预检和候选见离线迁移。当前可构建镜像只对应 ESP32-C3、4 MiB，无 GPIO 动作。ESP32-D0WD-V3 已有 UART0 控制入口与芯片事实适配前置，但自己的新分区布局、OTA 产品约束和签名启动链尚未冻结；esp32 构建会明确失败，不能把旧 ESP-AT 或 C3 分区刷到这块板。
pending OTA 槽只在身份、配置、USB 控制任务初始化成功，控制循环实际开始、在本地 30 秒窗口内持续报告进展，且跨过窗口终点再完成一轮后确认。Wi-Fi 初始化失败时状态为 failed，USB 控制仍启动，不因此回滚；窗口内 config.set 返回 ota_verification_pending，确认成功后恢复；不等待 Wi-Fi、Broker 或 FRPS 在线。确认 SDK 报错但 otadata 已为 VALID 时按持久状态清门。启动或活性检查失败时由 IDF 尝试回滚；无可回退镜像时当前执行暂留，但下次复位不保证可启动，需人工恢复。
普通应用使用编译期 CONFIG_ESP_BASE_TIME_SERVER（默认 pool.ntp.org）启动官方 SNTP。本次启动收到同步事件且时间合理后才报告 time_ready=true；初始化或同步失败时保持 false，USB 与 pending OTA 本地确认继续运行。签名构建的 HTTPS OTA 必须先有 Wi-Fi IP 和 time_ready。普通未签名构建拒绝 OTA；签名镜像的首次迁移、真实 TLS/回滚和 SNTP 网络行为仍待实板验收。
签名构建的 ota.start 在下载前将最近一次 operation ID、设备 ID、完整镜像摘要/长度和双槽写入 base_store/base_ota/operation 并读回。只读 ota.result 可在新 boot 按原 operation ID 查询：worker 活跃和新槽 pending 为 running，新槽 VALID 且镜像摘要相同才 succeeded，有可核对失败证据才 failed，其余为 unknown。旧回滚镜像若不含此查询代码，工具仍须报告 unknown；本轮没有升级实板上的旧镜像。
签名构建的 esp_base_ota_observe_firmware_set 在调用方串行化所有 app/otadata 写入时读取运行、下次启动及另一槽状态，再调用锁定 esp-ota 验签并计算完整 signed bin 摘要。只有当前槽为 VALID 且下次启动槽与之相同，另一槽为 VALID 并由 IDF 判定可回滚，或另一槽镜像确实无效时才返回确定集合；pending、状态变化及仍可能被 bootloader 回退扫描加载的歧义镜像全部拒绝。当前没有独立包分区或 Container 运行接线，接口的 host 假件与 C3 编译不证明实板启动/回滚。
启动与 ota.start 现使用同一本次 boot 的串行 owner；可选 Container 固件集合适配在 claim 内将只读签名集合逐字段送入 Container，并在操作后复读。当前主应用没有包分区或 Container 产品调用方，这只提供可独立验证的接线，不能算三包槽、联合 OTA 或实板验收。
- 固件入口
- 设备协议
- 公开串口主机示例
- 配置候选断电验收
- 官方 MQTT 集成测试应用
- MQTT 实板验收记录
- MQTT 公开组件硬切软件候选
- FRP 平台接线软件候选
- 乐鑫官方仓库全景与 ESP Base 选型
- 乐鑫 342 个公开仓库逐项清单
- 来源记录
- 嵌入式工程标准
新代码及维护者拥有的选定迁移代码使用 Apache-2.0。未导入 GPL FRP POC、私有历史、设备恢复字节或生产配置。