一、需求边界#

工程位于完整杰理 SDK 的玩具应用目录中，OTA只在玩具层实现。设计时固定了以下边界：

• 不修改 PAIPOP_JIELI_SDK；
• 不修改杰理公共升级模块源码；
• 玩具 Makefile 只链接现有的 apps/common/update/net_update.c；
• 不增加新的玩具状态机状态；
• 不改变原有按键、配网、对话和提示音逻辑；
• 第一版只升级应用固件，不实现 Resource OTA；
• 不实现断点续传和用户取消；
• 每次开机只检查一轮更新，并进行有限重试；
• 单备份设备不能通过 OTA 迁移到双备份，必须先完整 USB 烧录。

这样做的核心目的是把云端协议和玩具业务隔离开：OTA服务可以等待空闲、下载和切换固件，但不能把原有交互状态机改造成“OTA专用状态机”。

二、先理解双备份#

单备份设备只有一个正在运行的应用区。如果直接擦除并覆盖这个区域，中途断电就可能留下不完整固件，设备无法继续启动。

双备份可以抽象为两个应用槽位：

1
Flash
2
├── Bootloader与启动信息
3
├── 应用区A：当前固件
4
├── 应用区B：备用/目标固件
5
├── VM配置区
6
└── 音频等预留资源区

当设备从A区运行时，新固件写入B区：

1
运行A区
2
  → 擦除并写入B区
3
  → 校验B区
4
  → 修改下一次启动信息
5
  → 重启进入B区

下一次升级时，A、B角色互换。

下载阶段如果在10%、50%或99%断电，当前活动区并没有被覆盖，Bootloader仍可从旧固件启动。只有新固件完整写入并通过校验，启动信息才会切换。

本工程启用：

1
#define CONFIG_DOUBLE_BANK_ENABLE 1

打包配置使用8 MB Flash，并保留VM和音频资源区域。双备份基线必须先通过完整烧录文件建立；不能让一台仍使用单备份布局的设备直接接收双备份OTA包。

三、构建系统会产生哪些文件#

这个工程的默认 make 并不只是编译，它还会执行后处理脚本和USB下载：

1
源码
2
  → .o/.d
3
  → LTO链接
4
  → sdk.elf
5
  → download.bat提取可烧录段
6
  → app.bin
7
  → 杰理打包工具
8
  ├── jl_isd.fw
9
  ├── jl_isd.ufw
10
  ├── db_update_data.bin
11
  ├── db_update_files_data.bin
12
  └── jl_isd_extend.bin

1
.text
2
.data
3
.ram0_data
4
.cache_ram_data

1
-update_files normal

1
db_update_files_data.bin

1
artifacts/
2
├── v1.1.1_usb_baseline/
3
│   └── jl_isd.fw
4
└── v1.2.1/
5
    └── db_update_files_data.bin

四、OTA模块如何接入玩具启动流程#

应用启动时调用：

1
paipop_ota_init();

它只初始化OTA控制结构并打印适配版本，不会立刻访问后台。

Wi-Fi取得DHCP地址后，配网服务调用：

1
paipop_ota_network_ready();

OTA服务通过 check_started 保证本次开机只创建一个检查线程。Wi-Fi断开或模块停止时调用：

1
paipop_ota_network_down();

若此时正在下载，活动HTTP操作会被终止。

五、为什么开机后延迟30秒#

OTA线程先等待网络有效，再延迟30秒。这样可以让以下流程先完成：

• DHCP和NTP校时；
• Paipop后台配置获取；
• 语音引擎初始化；
• 开机或联网提示音播放；
• 玩具状态机进入等待触发状态。

OTA只在以下状态继续：

1
ENGINE_EXIT
2
或 ENGINE_INIT_FAILED
3
并且当前没有提示音正在播放

这里 ENGINE_INIT -> ENGINE_EXIT 表示语音引擎初始化完成后进入等待触发状态，不是初始化失败。

如果设备正在对话或播放语音，OTA继续等待，不会强制打断。force_update 第一版也只记录，不会改变这一规则。

六、OTA凭据与首次领取#

tenBackend OTA使用一套独立凭据：

• Base URL；
• App ID；
• App Key；
• Key Version；
• 设备身份。

它们不能复用 PaipopKey、license 或 ai_app_code。

当前代码支持三级来源：

1
源码中配置的App Key
2
  ↓ 不存在
3
VM中保存的凭据
4
  ↓ 不存在
5
一次性provision_token领取

如果启用首次领取，设备调用：

1
POST /api/device/ws-auth/provision

后台返回App Key和Key Version后，设备将凭据写入专用VM记录。记录中包含magic、schema、长度、CRC32和设备身份摘要，写入后立即读回校验。

需要注意：VM只是Flash存储区，不是硬件安全区。CRC32只能发现记录损坏，不能加密App Key，也不能抵抗物理读出。当前把App Key放在源码中同样只是联调方案。

七、HMAC认证是如何工作的#

设备访问更新检查和状态接口时使用HMAC-SHA256。每次POST都会重新生成13位UTC毫秒时间戳，并组织：

1
App ID
2
设备身份
3
时间戳

字段按协议排序并进行RFC3986编码，然后计算：

1
digest = HMAC-SHA256(App Key, canonical_string)
2
signature = Base64(digest)

请求头携带App ID、设备身份、时间戳、Signature和Key Version。App Key本身不会通过网络发送。

服务器根据设备身份和Key Version找到同一份App Key，重新计算HMAC并比较。匹配说明请求方掌握合法密钥，且参与签名的字段没有被修改。

时间戳用于限制重放。如果设备时间无效，会先进行一次有限超时的NTP校时；校时失败则本次OTA按认证/网络条件不满足处理。

1
HMAC：你是谁，请求有没有被伪造？
2
SHA-256：下载到的文件有没有变化？

八、检查更新接口#

设备调用：

1
POST /api/device/ota/check

请求中包含：

• 当前版本和 version_code；
• 硬件型号；
• 板型；
• 分区布局；
• 电量；
• Wi-Fi RSSI；
• 是否连接外部电源。

Type-C USB供电、USB从机模式或充电状态都会按外部电源处理，并向后台提供有效电量100%，避免后台把USB测试机误判为低电量。

本地升级门槛为：

1
电量不低于30%
2
Wi-Fi RSSI不低于-75 dBm

后台命中更新后返回：

• Task ID；
• Firmware ID；
• 目标版本；
• 目标 version_code；
• 完整下载URL；
• URL过期时间；
• 文件大小；
• SHA-256；
• force_update。

设备还会本地检查：

1
目标version_code > 当前version_code
2
URL协议有效
3
URL不会在30秒内过期
4
size有效
5
SHA-256格式有效
6
电量和RSSI满足门槛
7
玩具处于空闲状态

若后台明确返回无更新，本次开机不再检查。普通网络错误最多检查三次，延迟分别为：

1
0秒、60秒、300秒

九、Task ID、Firmware ID与Key Version#

这三个字段常被混淆：

1
Firmware ID：标识固件文件
2
Task ID：标识一次发布活动
3
Key Version：标识设备当前使用哪一版HMAC密钥

同一个Firmware ID可以用于单设备allowlist、5%灰度和全量发布，每次使用不同Task ID。设备后续上报的下载进度和升级结果都通过Task ID关联到这次发布。

Key Version属于设备认证系统，不属于固件发布表单，因此管理台上传固件时不需要填写。设备会在HMAC请求头中自动携带它。

十、流式下载与写入非活动区#

下载开始后设置：

1
ota.busy = 1;

玩具层此时阻止新的触摸对话和摇晃打断。检查更新和等待空闲期间不设置busy，因此不影响原有交互。

下载缓冲区只有4 KB：

1
#define PAIPOP_OTA_DOWNLOAD_BUF_SIZE (4 * 1024)

数据链路是：

1
HTTP响应
2
  → 4 KB RAM缓冲区
3
  → SHA-256累计计算
4
  → net_fwrite()
5
  → 杰理net_update模块
6
  → 非活动应用区

设备不需要在RAM中保存完整的1 MB固件。

升级写入口是：

1
net_fopen(CONFIG_UPGRADE_OTA_FILE_NAME, "w");

这里的文件名是升级模块提供的虚拟入口，不代表设备存在Windows式目录。net_fwrite() 会把数据交给杰理双备份写入任务。

玩具Makefile链接现有的 apps/common/update/net_update.c，并在应用任务表中注册 update 和 dw_update。如果缺少这些任务，底层写入会失败并提示找不到升级任务。

十一、下载过程的检查#

下载开始时先验证：

1
HTTP状态码 == 200
2
Content-Length == 后台size

每读取一块数据，同时进行：

1
mbedtls_sha256_update(...);
2
net_fwrite(...);

设备每跨过约10%上报一次 downloading 状态。

下载结束后必须同时满足：

1
实际接收字节数 == 后台size
2
本地SHA-256 == 后台SHA-256
3
每次Flash写入长度 == 输入长度

失败时调用：

1
net_fclose(fd, 1);

表示中止升级，不切换启动区。

完整下载最多尝试两次，第一次失败后等待约2秒。若URL即将过期，或者下载服务器返回401/403，设备最多重新调用一次 /api/device/ota/check 获取新URL。

十二、状态上报#

状态接口为：

1
POST /api/device/ota/status

正常状态链是：

1
detected
2
→ confirmed
3
→ downloading 0%
4
→ downloading 10% ... 100%
5
→ downloaded
6
→ 重启
7
→ success

下载、长度、哈希、Flash写入和启动切换失败时上报 failed，并使用稳定错误字符串，例如：

1
firmware_download_failed
2
firmware_size_mismatch
3
firmware_sha256_mismatch
4
ota_write_failed
5
ota_set_boot_failed
6
download_url_expired

进度上报失败不阻塞安全下载，防止固件正确下载却因为一次遥测失败而被强制中断。

十三、保存待确认记录并切换启动区#

长度和SHA-256都正确后，设备先在另一个VM项中保存待确认记录，包括：

• magic和schema；
• 校验值；
• Task ID；
• 目标版本；
• 目标 version_code；
• 总字节数；
• 当前升级阶段。

只有记录保存成功，才继续上报 downloaded 并调用：

1
net_fclose(update_fd, 0);

参数0表示正常结束。杰理公共升级模块完成固件结构校验、写入启动信息并安排软重启。玩具层不额外调用 system_reset()，避免在底层启动信息尚未写完时强制复位。

成功路径会看到类似：

1
image verified, reboot scheduled

随后播放短促的OTA提示音，由升级模块自动重启。

十四、新固件如何确认升级结果#

新固件启动、联网并进入空闲后，OTA服务读取待确认记录：

1
记录中的目标version_code
2
        对比
3
当前固件编译进去的version_code

相同则上报：

1
success

仍然运行旧版本则上报：

1
failed / boot_not_target

只有后台明确返回 accepted=true，设备才清除待确认记录。若上报时断网，记录继续保留，下次联网再次上报。

当前玩具层无法从公共升级模块明确证明“发生了Bootloader回滚”，因此不会仅凭版本不匹配就上报 rollback。

十五、实际测试的判断方法#

一次完整OTA至少应观察到：

1
旧固件启动：current=10101
2
OTA检查命中：target=10201
3
下载进度：10% ... 100%
4
长度和SHA-256通过
5
image verified, reboot scheduled
6
系统软重启
7
新固件启动：current=10201
8
联网后上报success

如果重启日志已经显示目标版本，说明双备份切换成功。由于OTA线程在DHCP后还会等待约30秒，只有几秒钟的重启日志通常看不到最终 success，建议至少记录启动后40秒。

常见问题可以按下面顺序排查：

十六、为什么当前OTA不会覆盖音频资源#

当前OTA包大小接近应用代码大小，不包含完整音频预留区。OTA只改写应用槽位，不主动擦除：

• AUPACKRES音频资源；
• Wi-Fi VM配置；
• OTA凭据VM；
• 其他保留区。

如果修改了 audlogo 中的MP3，需要重新USB完整烧录，或者后续单独设计Resource OTA。

十七、当前方案与量产方案的差距#

这套实现已经具备功能闭环：

1
认证检查
2
灰度命中
3
流式下载
4
长度与SHA-256校验
5
双备份写入
6
失败保留旧固件
7
重启确认
8
状态上报

但它仍是联调和样机级实现，正式量产至少还应补齐：

1
发布系统使用私钥签名固件摘要
2
设备使用内置公钥验证签名

十八、总结#

这次实现最重要的不是“把一个 .bin 下载下来”，而是打通了完整生命周期：

1
发布身份
2
→ 设备认证
3
→ 策略命中
4
→ 安全下载
5
→ 非活动区写入
6
→ 内容校验
7
→ 原子切换
8
→ 重启确认
9
→ 云端闭环

其中几组概念必须分清：

1
jl_isd.fw：USB完整烧录基线
2
db_update_files_data.bin：后台OTA包
3

4
HMAC-SHA256：设备请求认证
5
SHA-256：固件内容完整性
6
数字签名：证明固件由官方签发
7

8
Firmware ID：一个固件文件
9
Task ID：一次发布任务
10
Key Version：一版设备认证密钥

双备份解决的是“升级中断后还能启动”，HMAC解决的是“谁在请求后台”，SHA-256解决的是“文件有没有变化”。只有再配合HTTPS、固件数字签名、安全启动和明确回滚，才是一套更接近成熟量产设备的OTA安全体系。