# OTA 功能与多媒体稳定性修复说明

## 1. 文档目的

本文整理以下两个提交的背景、问题原因、解决方式、关键代码、验证成果和后续影响：

```text
0cfb102 fix(multimodal): harden playback and client lifecycle handling
5a18036 feat(ota): add authenticated firmware update workflow
```

两个提交需要分开理解：

- 多媒体稳定性修复处理的是原本就存在的通用并发和时序问题。即使不增加 OTA，也可能在网络重连、快速打断对话或音频初始化较慢时出现。
- OTA 提交实现了完整的固件检查、鉴权、下载、校验、切换和重启流程，同时增加了 OTA 与语音网络任务之间的资源协调。
- OTA 改变了设备启动顺序，并增加了一次 HTTPS 请求，因此提高了原有多媒体问题的触发概率，但不是这些问题的唯一根因。

## 2. 总体结论

本次修改解决了以下核心问题：

1. “服务器连接成功”提示音播放失败后不再被永久跳过。
2. WebSocket、多媒体会话和音频任务的启动、停止不再并发交叉执行。
3. 上一轮对话遗留的音频包和播放事件不会再错误影响下一轮对话。
4. 设备启动后可自动检查固件版本，正常周期为每 6 小时一次。
5. OTA 上报使用具有 `ota:report` 权限的设备 JWT；遇到 `401/403` 时刷新 JWT 并重试一次。
6. 可选支持 HMAC 内部签名，但默认不启用，不影响当前只使用设备 JWT 的服务端。
7. 固件下载后会校验 HTTPS 状态、文件大小、SHA-256 和 ESP-IDF 镜像格式，全部通过后才切换启动分区。
8. OTA 请求会暂时释放语音相关网络和内存资源，结束后恢复本地唤醒与 WebSocket。

---

## 3. 多媒体稳定性修复

### 3.1 “服务器连接成功”提示音不播放

#### 问题原因

原逻辑在收到 WebSocket 连接成功事件时，先把提示音状态设置成“已经播放”，然后立即调用音频播放接口：

```c
if (!s_server_success_prompt_played) {
    s_server_success_prompt_played = true;
    should_play_prompt = true;
}

if (should_play_prompt) {
    (void)domain_runtime_behavior_play_prompt_file(
            "/littlefs/audio_prompts/server_connect_success.opus");
}
```

这段逻辑有两个问题：

1. WebSocket 的“已连接”只代表网络连接完成，不代表音频播放链路已经准备好。
2. 播放接口的返回值被忽略。即使播放失败，状态也已经变成“播放过”，之后不会再尝试。

因此，只要连接成功时音频通道正在初始化、停止、切换或者被其他播放占用，就可能出现提示音完全不播放。没有 OTA 时也可能发生；OTA 增加启动阶段的 HTTPS 和语音服务恢复流程后，更容易撞上这个时间窗口。

#### 解决方式

连接成功事件现在只负责登记“待播放”，真正的播放由多媒体监控任务在以下条件满足后执行：

- WebSocket 仍然处于连接状态；
- 当前没有正在进行的云端交互任务；
- 当前没有另一线程正在播放该提示音；
- 已达到下一次允许重试的时间。

关键代码如下：

```c
#define CONTROL_PLANE_SERVER_SUCCESS_PROMPT_RETRY_MS 1000U
#define CONTROL_PLANE_SERVER_SUCCESS_PROMPT_MAX_ATTEMPTS 3U

static void control_plane_schedule_server_success_prompt(void)
{
    uint32_t now_ms = (uint32_t)(xTaskGetTickCount() * portTICK_PERIOD_MS);

    portENTER_CRITICAL(&s_multimodal_runtime_lock);
    if (!s_server_success_prompt_played &&
        s_server_success_prompt_attempts <
                CONTROL_PLANE_SERVER_SUCCESS_PROMPT_MAX_ATTEMPTS) {
        s_server_success_prompt_pending = true;
        s_server_success_prompt_next_attempt_ms = now_ms;
    }
    portEXIT_CRITICAL(&s_multimodal_runtime_lock);
}
```

播放结束后才根据真实返回值更新状态：

```c
esp_err_t err = domain_runtime_behavior_play_prompt_file(
        CONTROL_PLANE_SERVER_SUCCESS_PROMPT_FILE);

portENTER_CRITICAL(&s_multimodal_runtime_lock);
s_server_success_prompt_in_progress = false;

if (err == ESP_OK) {
    s_server_success_prompt_played = true;
    s_server_success_prompt_pending = false;
} else if (s_server_success_prompt_attempts >=
                   CONTROL_PLANE_SERVER_SUCCESS_PROMPT_MAX_ATTEMPTS) {
    s_server_success_prompt_pending = false;
} else {
    s_server_success_prompt_next_attempt_ms =
            now_ms + CONTROL_PLANE_SERVER_SUCCESS_PROMPT_RETRY_MS;
}
portEXIT_CRITICAL(&s_multimodal_runtime_lock);
```

现在只有播放接口返回 `ESP_OK` 时，提示音才会被标记为播放成功。失败时最多重试 3 次，每次间隔 1 秒。

### 3.2 多媒体启动和停止相互冲突

#### 问题原因

设备中有多个任务可能操作多媒体客户端：

- Wi-Fi 状态机在网络恢复后启动 WebSocket；
- 网络断开或空闲超时时停止 WebSocket；
- OTA 检查前释放语音网络资源；
- OTA 检查后恢复 WebSocket 和本地唤醒；
- 下行音频断流保护可能触发恢复流程。

原来的 `starting`、`stopping` 标志只能描述状态，不能保证完整的启动过程和停止过程互斥。可能出现任务 A 正在释放传输和音频资源，任务 B 已经开始重新注册回调或建立连接的情况。

#### 解决方式

在客户端层和会话层分别增加生命周期互斥锁，并设置 30 秒的有限等待时间：

```c
#define CONTROL_PLANE_CLIENT_LIFECYCLE_WAIT_MS 30000U

static bool lock_client_lifecycle(void)
{
    TickType_t timeout_ticks =
            pdMS_TO_TICKS(CONTROL_PLANE_CLIENT_LIFECYCLE_WAIT_MS);

    if (xSemaphoreTake(s_client_lifecycle_mutex, timeout_ticks) != pdTRUE) {
        ESP_LOGW(TAG, "Timeout acquiring multimodal client lifecycle lock");
        return false;
    }
    return true;
}
```

启动和停止都必须先拿到同一把锁：

```c
esp_err_t control_plane_start_multimodal_client(void)
{
    if (!lock_client_lifecycle()) {
        return ESP_ERR_TIMEOUT;
    }

    esp_err_t err = control_plane_start_multimodal_client_locked();
    unlock_client_lifecycle();
    return err;
}

esp_err_t control_plane_stop_multimodal_client(void)
{
    if (!lock_client_lifecycle()) {
        return ESP_ERR_TIMEOUT;
    }

    stop_watchdog_task();
    esp_err_t err = control_plane_multimodal_stop();
    unlock_client_lifecycle();
    return err;
}
```

这样可以保证一个完整的停止流程结束后，另一个任务才能启动新的会话。停止接口也从无返回值改为返回 `esp_err_t`，调用方可以知道停机是否真正完成。

### 3.3 上一轮音频事件污染下一轮对话

#### 问题原因

音频数据、解码任务和播放完成回调运行在不同任务中。当用户快速打断上一轮回复并立即开始下一轮时，可能出现以下顺序：

```text
第 1 轮开始播放
用户打断第 1 轮
第 2 轮开始播放
第 1 轮的“播放结束”事件晚到
第 2 轮被错误地标记为结束
```

旧实现只有“当前是否播放中”的布尔状态，不能判断某个音频包或事件属于哪一轮回复。

#### 解决方式

每次开始下行回复时生成一个递增的 `playback_generation`，可以把它理解为“播放批次号”：

```c
static uint32_t advance_downstream_playback_generation_locked(void)
{
    s_audio.downstream_playback_generation++;
    if (s_audio.downstream_playback_generation == 0U) {
        s_audio.downstream_playback_generation = 1U;
    }

    s_audio.downstream_decoder_reset_pending = true;
    return s_audio.downstream_playback_generation;
}
```

开始新回复时把本轮批次号返回给会话层：

```c
esp_err_t multimodal_audio_begin_downstream_response(
        uint32_t *out_playback_generation)
{
    portENTER_CRITICAL(&s_audio_runtime_lock);
    uint32_t playback_generation =
            advance_downstream_playback_generation_locked();
    s_audio.downstream_response_active = true;
    portEXIT_CRITICAL(&s_audio_runtime_lock);

    *out_playback_generation = playback_generation;
    return ESP_OK;
}
```

每个音频包在解码前检查批次号：

```c
snapshot_downstream_playback_state(
        &playback_generation,
        &decoder_reset_pending);

if (playback_generation != expected_generation) {
    return ESP_ERR_INVALID_STATE;
}
```

播放事件到达控制层时再次检查：

```c
generation_matches = s_current_playback_generation != 0U &&
                     s_current_playback_generation ==
                             event->playback_generation;

if (!generation_matches) {
    ESP_LOGD(TAG,
             "Ignore stale or local playback event type=%d generation=%u",
             (int)event->type,
             (unsigned)event->playback_generation);
    return;
}
```

因此，旧回复的音频包、停止事件、完成事件或断流事件即使晚到，也只能影响旧批次，不能结束当前新回复。

### 3.4 启动失败后的残留回调

#### 问题原因

多媒体客户端启动包含注册回调、启动监控任务、初始化音频、获取鉴权和建立传输等多个步骤。如果中途失败，已经注册的回调可能继续指向一次未完成的会话。

#### 解决方式

启动失败时停止监控任务并注销已经注册的回调：

```c
esp_err_t err = control_plane_multimodal_start();
if (err != ESP_OK) {
    stop_watchdog_task();
    (void)control_plane_multimodal_register_downstream_audio_callback(
            NULL,
            NULL);
    (void)control_plane_multimodal_register_event_callback(NULL, NULL);
    return err;
}
```

会话层在状态锁失败时也会停止已启动的传输、注销音频回调，并停止本地响应事件工作任务，避免“启动一半”的资源留到下一次重试。

### 3.5 多媒体修复成果

设备实测日志确认：

- WebSocket 成功连接；
- “服务器连接成功”提示音在第 1 次尝试即播放成功；
- 多轮唤醒、ASR、TTS 下发、音频播放和状态上报均正常；
- 快速开始下一轮对话时，没有观察到旧事件错误结束新回复；
- 没有出现栈溢出、断言、崩溃或重启。

日志中仍出现两次短暂下行音频断流，约为 410 ms 和 230 ms，但播放器分别在约 290 ms 和 110 ms 后自动恢复，没有丢失整段回复。这属于网络数据到达不均匀，现有缓冲和恢复机制已经正确处理。

### 3.6 多媒体修复的后续影响

正面影响：

- Wi-Fi 重连、OTA、空闲断开和异常恢复时的启停行为更稳定；
- 快速打断和连续对话的状态隔离更可靠；
- 播放失败和停机超时有明确日志，不再静默失败。

需要注意：

- 生命周期锁的最长等待时间为 30 秒。如果底层网络或音频停止异常，调用方会收到 `ESP_ERR_TIMEOUT`，而不是无限等待。
- 提示音最多重试 3 次。如果连续 3 次都失败，本轮启动中不会无限重试，以免持续占用音频通道。
- 播放事件结构新增了 `playback_generation`。以后新增任何播放回调或本地音频来源时，都应明确它属于哪一个播放批次。

---

## 4. OTA 功能实现

### 4.1 OTA 完整流程

设备端流程如下：

```text
设备启动
  -> 确认当前待验证固件
  -> 等待 Wi-Fi
  -> 暂停本地唤醒和 WebSocket
  -> 检查内部内存和 DMA 连续内存
  -> 获取具有 ota:report 权限的新 JWT
  -> POST 上报设备 ID、序列号和当前版本
  -> HTTP 204：没有更新，恢复语音服务，6 小时后再检查
  -> HTTP 200：解析新固件信息
       -> 强制更新：等待当前对话结束后开始下载
       -> 非强制且已确认：等待当前对话结束后开始下载
       -> 非强制且未确认：恢复语音服务，6 小时后再次查询
  -> GET 下载固件
  -> 校验大小、SHA-256 和 ESP-IDF 镜像格式
  -> 设置新启动分区
  -> 重启
  -> 新固件启动成功后确认镜像，取消回滚
```

OTA 采用三层职责划分：

- 控制层：决定何时检查、何时暂停和恢复语音、是否允许更新、失败后多久重试。
- 领域层：构造上报 JSON、添加 JWT/HMAC 请求头、解析服务端响应、转换 SHA-256。
- 平台层：执行 HTTPS GET、写入 OTA 分区、计算摘要、验证镜像并切换启动分区。

### 4.2 固件版本存储

仓库根目录的 `version.txt` 当前内容为：

```text
1.0.0
```

构建时 ESP-IDF 会将版本写入应用描述信息。设备运行时通过应用描述读取版本，而不是从普通配置文件或 NVS 中读取：

```c
const esp_app_desc_t *app_desc = esp_app_get_description();
strlcpy(out, app_desc->version, out_len);
```

因此，发布新固件前必须更新 `version.txt`，否则服务端会一直看到旧版本号。

### 4.3 OTA 检查时机

默认配置如下：

```c
CONFIG_TQ_OTA_ENABLE=y
CONFIG_TQ_OTA_POLL_INTERVAL_MS=21600000
CONFIG_TQ_OTA_CONFIRMATION_POLL_MS=21600000
CONFIG_TQ_OTA_HTTP_TIMEOUT_MS=15000
CONFIG_TQ_OTA_INSTALL_TIMEOUT_MS=600000
CONFIG_TQ_OTA_TASK_STACK_BYTES=16384
CONFIG_TQ_OTA_MIN_FREE_INTERNAL_BYTES=32768
CONFIG_TQ_OTA_MIN_LARGEST_DMA_BYTES=4096
```

含义为：

- 启动联网后立即执行首次检查；
- 没有更新时，每 6 小时检查一次；
- 有非强制更新但小程序尚未确认时，每 6 小时重新查询；
- 版本上报请求最多等待 15 秒；
- 固件下载和安装总时限为 10 分钟；
- OTA 独立任务栈为 16 KB；
- HTTPS 开始前至少保留 32 KB 内部内存和 4 KB 最大 DMA 连续块。

### 4.4 设备与服务端的数据交换

#### 4.4.1 请求体

设备向版本上报接口发送 HTTP POST，请求体如下：

```json
{
  "deviceId": "设备唯一 ID",
  "version": "1.0.0",
  "serialNumber": "设备序列号"
}
```

其中：

- `deviceId` 用于确认是哪台设备；
- `version` 是当前正在运行的固件版本；
- `serialNumber` 可选，用于服务端进一步关联设备。

构造请求体的代码如下：

```c
bool ok = cJSON_AddStringToObject(
        root,
        "deviceId",
        request->device_id) != NULL &&
          cJSON_AddStringToObject(
        root,
        "version",
        request->current_version) != NULL;

if (ok && request->serial_number != NULL &&
    request->serial_number[0] != '\0') {
    ok = cJSON_AddStringToObject(
            root,
            "serialNumber",
            request->serial_number) != NULL;
}
```

#### 4.4.2 JWT 和 scope

请求始终携带设备 JWT：

```http
Authorization: Bearer <device-jwt>
```

设备在 OTA 上报前要求 JWT 至少具有 `ota:report` 权限：

```c
control_plane_device_auth_result_t auth_result =
        control_plane_multimodal_device_auth_ensure(
                CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_REPORT,
                force_jwt_refresh);
```

`scope` 可以理解为 JWT 中的“允许操作清单”。当前设备认识以下四类权限：

```c
#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_VOICE_SESSION (1u << 0)
#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_REPORT    (1u << 1)
#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_READ      (1u << 2)
#define CONTROL_PLANE_DEVICE_AUTH_SCOPE_OTA_CONFIRM   (1u << 3)
```

它们分别表示：

- `voice:session`：允许建立语音会话；
- `ota:report`：允许上报当前固件版本；
- `ota:read`：允许读取 OTA 固件资源；
- `ota:confirm`：允许确认升级。

日志中的 `scope=0x0000000f` 表示低 4 位全部为 1，即上述四种权限全部具备。OTA 版本上报实际只强制要求 `ota:report`。

首次启动检查会强制刷新 JWT，避免缓存 JWT 因签发时间、过期时间或权限集合不满足而被服务端拒绝：

```c
for (int attempt = 0; attempt < 2; ++attempt) {
    bool force_jwt_refresh = force_initial_jwt_refresh || attempt > 0;

    err = control_plane_ota_prepare_report(
            &ctx->request,
            ctx->device_id,
            sizeof(ctx->device_id),
            ctx->serial_number,
            sizeof(ctx->serial_number),
            ctx->version,
            sizeof(ctx->version),
            ctx->jwt,
            sizeof(ctx->jwt),
            force_jwt_refresh);

    err = domain_runtime_ota_report(&ctx->request, response);

    bool unauthorized = err == ESP_OK &&
            (response->http_status == 401 ||
             response->http_status == 403);
    if (!unauthorized) {
        break;
    }

    control_plane_multimodal_device_auth_invalidate(
            response->http_status);
}
```

如果服务端仍返回 `401/403`，设备会让当前 JWT 失效、重新获取，并且只重试一次，避免错误配置造成无限鉴权请求。

#### 4.4.3 可选 HMAC

HMAC 不是 JWT，也不是固件 SHA-256 校验。

- JWT 证明“这台设备是谁，以及它有哪些权限”。
- HMAC 证明“请求内容由持有共享密钥的一方生成，并且内容没有被修改”。
- 固件 SHA-256 证明“下载到的固件文件与服务端声明的文件完全一致”。

默认配置中 HMAC 密钥为空，因此当前请求只发送 JWT：

```c
CONFIG_TQ_OTA_INTERNAL_AUTH_SECRET=""
```

只有部署环境明确要求内部签名，并配置非空共享密钥时，设备才增加下面三个请求头：

```http
X-Internal-Timestamp: <Unix 时间戳>
X-Internal-Nonce: <随机数>
X-Internal-Signature: <HMAC-SHA256 后的 Base64>
```

签名原文由请求方法、路径、查询参数、请求体摘要、时间戳和随机数组成：

```c
snprintf(signature_payload,
         (size_t)payload_len + 1U,
         "POST\n%s\n%s\n%s\n%s\n%s",
         path,
         query,
         body_hash,
         timestamp,
         nonce);

mbedtls_md_hmac(md_info,
                (const uint8_t *)secret,
                strlen(secret),
                (const uint8_t *)signature_payload,
                (size_t)payload_len,
                digest);
```

HMAC 使用时间戳防止旧请求被长期重放，使用随机数防止同一秒内的重复请求被重放。因此启用 HMAC 时必须先保证设备时间已经同步。当前代码会拒绝早于合理时间范围的时间戳：

```c
time_t now = time(NULL);
if ((int64_t)now < 1700000000LL) {
    return ESP_ERR_INVALID_STATE;
}
```

当前服务端如果没有要求内部 HMAC，必须保持密钥为空，不应自行填写一个与服务端不一致的值。

#### 4.4.4 服务端响应

没有更新时，服务端返回：

```http
HTTP/1.1 204 No Content
```

设备收到 204 后恢复语音服务，并在 6 小时后再次检查。

有更新时，服务端返回 HTTP 200，数据结构类似：

```json
{
  "code": 200,
  "data": {
    "notUptodate": 1,
    "version": "1.0.1",
    "url": "https://example.com/firmware.bin",
    "sha256": "64 位十六进制 SHA-256",
    "sizeBytes": 2140400,
    "force": 0,
    "update": 1
  }
}
```

字段含义：

- `notUptodate=1`：当前固件不是最新版本；
- `version`：目标固件版本；
- `url`：固件 HTTPS 下载地址；
- `sha256`：固件文件的 SHA-256；
- `sizeBytes`：固件精确字节数；
- `force=1`：强制更新，不等待小程序确认；
- `update=1`：非强制更新已经由小程序或服务端确认，可以开始更新。

设备严格检查字段类型、长度和数值：

```c
if (err != ESP_OK ||
    !cJSON_IsNumber(size_bytes) ||
    size_bytes->valuedouble <= 0 ||
    size_bytes->valuedouble > (double)UINT32_MAX ||
    strlen(firmware->sha256) != 64U) {
    return ESP_ERR_INVALID_RESPONSE;
}

firmware->forced =
        cJSON_IsNumber(forced) && forced->valueint == 1;
firmware->confirmed =
        cJSON_IsNumber(confirmed) && confirmed->valueint == 1;
```

### 4.5 OTA 与语音任务的资源协调

#### 问题原因

ESP32-S3 的内部 RAM 和 DMA 连续内存有限。WebSocket、TLS、音频录制、Opus 解码和本地唤醒同时运行时，再启动 OTA HTTPS 可能造成：

- TLS 建连内存不足；
- 最大连续 DMA 块不足；
- WebSocket 和 OTA 同时竞争网络资源；
- OTA 完成后语音任务没有恢复；
- 多媒体停止未完成，OTA 已经开始申请大块内存。

#### 解决方式

OTA 在每次 HTTPS 操作前申请一个“语音资源窗口”：

```c
s_ota_voice_services_reserved = true;

esp_err_t wake_stop_err = control_plane_local_wake_stop(1000);
if (wake_stop_err != ESP_OK) {
    return wake_stop_err;
}

esp_err_t stop_err = control_plane_stop_multimodal_client();
if (stop_err != ESP_OK) {
    return stop_err;
}
```

语音服务完全停止后检查内存：

```c
domain_ota_memory_headroom_t headroom = {0};
esp_err_t err = domain_runtime_ota_get_memory_headroom(&headroom);

if (headroom.free_internal <
            CONFIG_TQ_OTA_MIN_FREE_INTERNAL_BYTES ||
    headroom.largest_dma <
            CONFIG_TQ_OTA_MIN_LARGEST_DMA_BYTES) {
    return ESP_ERR_NO_MEM;
}
```

OTA 检查结束后释放窗口，并根据之前的状态恢复服务：

```c
control_plane_ota_set_voice_services_reserved(false);

if (window->restore_local_wake &&
    control_plane_voice_turn_is_idle() &&
    control_plane_ota_start_default_local_wake()) {
    ESP_LOGI(TAG,
             "Local wake restore requested after OTA HTTPS window");
}

if (window->restore_multimodal ||
    !control_plane_voice_turn_is_idle()) {
    (void)control_plane_schedule_websocket_wait_task();
}
```

后续周期检查不会强行打断正在进行的对话。如果当前语音交互未结束，OTA 会进入等待资源状态，等设备空闲后再检查或升级。

### 4.6 固件下载与完整性校验

下载只接受 HTTPS 地址：

```c
if (url == NULL ||
    strncmp(url, "https://", 8) != 0 ||
    expected_sha256 == NULL ||
    expected_size == 0U ||
    timeout_ms <= 0) {
    return ESP_ERR_INVALID_ARG;
}
```

设备先选择当前未运行的 OTA 分区，并确认固件能放入该分区：

```c
const esp_partition_t *partition =
        esp_ota_get_next_update_partition(NULL);

if (partition == NULL || expected_size > partition->size) {
    return ESP_ERR_INVALID_SIZE;
}
```

服务器必须返回 HTTP 200。如果存在 `Content-Length`，必须和 `sizeBytes` 完全一致：

```c
int status_code = esp_http_client_get_status_code(client);
if (status_code != 200) {
    return ESP_ERR_INVALID_RESPONSE;
}

if (content_length >= 0 &&
    (uint64_t)content_length != expected_size) {
    return ESP_ERR_INVALID_SIZE;
}
```

设备边下载、边计算 SHA-256、边写入未运行分区，不需要把完整固件放进内存：

```c
while (received < expected_size) {
    int read_len = esp_http_client_read(
            client,
            (char *)buffer,
            read_capacity);

    mbedtls_sha256_update(
            &sha_ctx,
            buffer,
            (size_t)read_len);

    err = esp_ota_write(
            ota_handle,
            buffer,
            (size_t)read_len);

    received += (uint64_t)read_len;
}
```

下载结束后比较摘要，再由 ESP-IDF 验证镜像格式：

```c
if (memcmp(actual_sha256,
           expected_sha256,
           sizeof(actual_sha256)) != 0) {
    return ESP_ERR_INVALID_CRC;
}

err = esp_ota_end(ota_handle);
if (err != ESP_OK) {
    return err;
}

err = esp_ota_set_boot_partition(partition);
```

任何失败都会调用 `esp_ota_abort()`，当前正在运行的分区保持不变，不会启动一个只下载了一半或校验失败的镜像。

### 4.7 回滚保护

OTA 配置启用了 ESP-IDF 应用回滚功能。新镜像第一次启动时处于待验证状态，运行时启动 OTA 服务会确认当前镜像：

```c
esp_ota_img_states_t state = ESP_OTA_IMG_UNDEFINED;
esp_err_t err = esp_ota_get_state_partition(running, &state);

if (err == ESP_ERR_NOT_FOUND ||
    state != ESP_OTA_IMG_PENDING_VERIFY) {
    return ESP_OK;
}

return esp_ota_mark_app_valid_cancel_rollback();
```

如果新固件无法正常启动并完成确认，ESP-IDF 可以回滚到上一份可用固件。

### 4.8 OTA 实现成果

在最终设备日志中已经确认：

```text
Device JWT ready (exp=1786692109 scope=0x0000000f kv=1)
OTA version report response: http=204
OTA task stack phase=version_report headroom=8072B configured=16384B
OTA HTTPS window released: restore_multimodal=1 restore_local_wake=1
Local wake restore requested after OTA HTTPS window
OTA version report complete: running firmware is current (http=204)
WebSocket connected
Server success prompt played on attempt 1
```

这组结果证明：

- 启动检查前成功生成了新 JWT；
- JWT 权限覆盖 OTA 上报要求；
- 服务端返回 204，表示当前没有新版本；
- 没有再次出现 401 或 403；
- 16 KB OTA 栈在版本上报阶段仍剩余约 8072 B；
- OTA HTTPS 结束后，本地唤醒和 WebSocket 均成功恢复；
- 服务器连接成功提示音正常播放；
- 后续多轮对话和下发音频正常。

ESP-IDF 5.5.4 完整编译通过。生成的应用固件大小约为 `0x20a8f0` 字节，最小应用分区仍有 `0x175710` 字节，即约 42% 空间可用。

### 4.9 OTA 的后续影响和注意事项

#### 启动时间

设备联网后的首次 OTA 检查会先于语音服务执行，因此 WebSocket 和本地唤醒会比以前晚几秒启动。这是有意的资源保护策略，不是故障。版本接口超时上限为 15 秒；失败后会释放 OTA 窗口并恢复语音。

#### 网络流量

正常情况下每 6 小时增加一次很小的 JSON POST。只有服务端下发并批准升级时，设备才会 GET 下载完整固件。

#### 内存

OTA 已通过语音窗口和内存门槛降低 TLS 内存不足风险，但设备稳态内部内存仍然较紧。实测历史最低内部内存约 6.6 KB，虽然 `alloc_failures=0` 且没有崩溃，后续增加新网络功能时仍需关注内部 RAM、DMA 最大连续块和任务栈。

#### 服务可用性

固件下载期间本地唤醒和云端语音暂时不可用，下载完成后设备会直接重启。这是 OTA 的预期行为。后续如需改善用户体验，可以在升级前播放“系统升级中”提示音，但不能在下载过程中重新启动常驻音频任务。

#### 服务端契约

服务端必须保证以下内容稳定：

- 版本上报接口接受带 `ota:report` 权限的设备 JWT；
- 无更新返回 HTTP 204；
- 有更新返回完整且类型正确的字段；
- 固件 URL 使用 HTTPS；
- `sizeBytes` 与实际文件长度一致；
- `sha256` 是实际二进制文件的 SHA-256；
- 如果启用 HMAC，设备和服务端必须使用相同密钥、签名格式和时间容差。

#### 版本发布

每次发布新固件前必须更新 `version.txt`，生成固件后还应记录：

- 版本号；
- 文件字节数；
- SHA-256；
- 下载 URL；
- 是否强制升级；
- 灰度设备范围和回滚策略。

---

## 5. 最终评价

这两个提交形成了互补关系：

- 多媒体提交修复了原有的提示音、启停竞争和旧音频事件问题，使语音链路可以可靠地暂停和恢复。
- OTA 提交在此基础上实现了安全、可恢复、资源受控的固件升级流程。

当前验证结果说明“启动检查无更新”的主流程已经稳定运行。下一阶段最重要的验证是使用测试固件完成一次真实升级，覆盖以下场景：

1. 非强制更新、等待确认后升级；
2. 强制更新；
3. 下载中途断网；
4. 固件大小不一致；
5. SHA-256 不一致；
6. 新镜像启动失败后的自动回滚；
7. OTA 检查时设备正在对话，确认不会中断当前交互。