固件构建、交付与烧录

平台版本锁定一组组件源码，固件版本写在应用描述中，两者独立。二进制只放本机忽略目录、私有OSS或硬件Release附件，不放Git历史；不能把包含逐板凭据的私密构建作为通用包。

产品与工程

产品	工程（相对总仓库）	芯片/容量	OTA槽/合并工厂地址
p_relay_4ch，硬件2.1.0	hardware/ESP32_4_RelayModule/software/esp32_3.0.0	ESP32-C3 / 4MB	ota_0=0x20000，ota_1=0x200000，各0x1e0000；工厂0x0
p_env_sensor，硬件esp32-16mb-v1	hardware/EnvSense-Box/software/esp32/env_sense_box_v1.1	ESP32 / 实测16MB	ota_0=0x20000，ota_1=0x400000，各0x3e0000；工厂0x0，内部bootloader在0x1000

目录名保留历史，不代表IDF3或固件1.1。两工程使用ESP-IDF6.1。NVS为0x9000/24KiB，不能从参考原理图的N8标注推断测试板Flash容量；先读实际硬件。

构建通用交付包

执行位置总仓库根目录。先安装IDF6.1及对应Python环境、编译工具链，激活环境；macOS本机激活脚本只是安装位置示例，其他机器使用自身IDF导出脚本。BASE_CONFIG是本地受保护sdkconfig，输出必须全新目录且在Git外/忽略local-tools。

source "$IDF_EXPORT_SCRIPT"
python tools/firmware_bundle.py --base-config "$BASE_CONFIG"   --version 3.2.0-dev.11 --output "$BUNDLE_DIR"
# 传感器改用其BASE_CONFIG、独立输出目录、独立固件版本
python tools/firmware_bundle.py --product p_env_sensor --base-config "$SENSOR_BASE_CONFIG"   --version 1.4.0-dev.7 --output "$SENSOR_BUNDLE_DIR"

版本仅举例；当前正式配套为继电器3.2.0、EnvSense1.4.0，各自硬件Release提供附件。开发候选和正式版本的实物范围以事实基线为准。若已运行各硬件tools/build-ota.py --base-config ... --output ... --version ... --generic，可用--build-output <该目录>打包，避免重复编译。构建工具去掉逐板材料并验证MQTT TLS、芯片、容量、版本及空NVS。构建失败看私有build.log，别把完整配置贴到公开日志。

输出OTA应用、单地址工厂镜像、manifest、SHA256SUMS和烧录说明。正式硬件Release还需从同一sourceCommit生成源码ZIP（git archive固定提交），记录源码与二进制关系。打包本身不发布、不烧录、不创建数据库任务。

三种写入区别

操作	适用情况	数据影响
普通OTA应用	已具备兼容双分区/身份的设备	写备用槽，保留NVS/WiFi；失败可回旧槽
USB只更新应用	同协议开发联调，已核对分区和当前启动槽	只写选定应用槽，保留身份/WiFi；不是备用槽OTA事务
工厂合并镜像0x0	空板或接受破坏性重建	覆盖整片Flash和NVS/OTA状态，清WiFi与本地身份，首次生成新身份

工厂重刷先在平台解绑，随后全片烧录、正常BLE配网认领；不删除云端历史。不能用工厂镜像完成无损OTA，也不能把单应用文件写0x0。

USB与网页烧录

关闭串口监视器、确认端口与MAC、使用IDF环境的esptool。以下只读识别；读取分区与OTA选择后才能决定应用槽：

python -m esptool --port "$PORT" chip-id
python -m esptool --port "$PORT" flash-id

同协议当前ota_0应用示例（只有实测启动槽确认为ota_0且芯片/容量匹配才使用）：

python -m esptool --chip esp32c3 --port "$PORT" --baud 115200   write-flash 0x20000 "$RELAY_OTA_BIN"

空板继电器工厂包用esp32c3；传感器用esp32及其16MB镜像：

python -m esptool --chip esp32c3 --port "$PORT" --baud 115200   write-flash 0x0 "$RELAY_FACTORY_BIN"

写入后必须出现Hash verified，再核对启动版本、联网与实际功能，不能只看上传进度。开发板无需复杂Flash备份，仍须避免误写另一块板。

Web工具箱→ESP32烧录使用桌面Chrome/Edge、HTTPS和Web Serial；登录选择对应产品最新版稳定工厂包，确认清除配置后烧录。下载直接到私有OSS并校验原字节哈希。开发候选没有登记为稳定包时，不会出现在“最新版”，不能用网页旧稳定包验证新修复。

升级失败

连接失败查USB数据线、驱动、串口占用；噪声/写入不稳定先降115200。OTA下载失败查证书/签名/内存，应用启动回滚查启动校验日志。旧无双分区固件须先USB初始化；任何跨协议降级都先核对NVS格式，不能假设旧版可读新身份。