# 远程 HTTP OTA 部署说明（ESP32-C6，HTTP OTA）

本项目采用“远程服务器 HTTP OTA”方案（设备从 HTTP 服务器下载 `light.bin` 并写入 OTA 分区），不依赖 Matter 标准 OTA Provider。

交付目录相关文件：
- OTA 文件：`Deliverable/02_Firmware_Binaries/cct/ota/light.bin`
- 设备端触发命令：Matter shell 命令 `matter esp ota <http://...>`

---

## 1. OTA 文件与命名建议

建议按“产品/型号/版本号”组织目录，避免覆盖与混淆。

示例：

```
/ota/
  cct/
    2.1/
      light.bin
      sha256.txt
```

- `light.bin`：本次升级包
- `sha256.txt`（建议）：文件校验值（用于发布侧校验/人工核对）

> 备注：当前设备端实现为 HTTP OTA（非 HTTPS），因此建议仅在内网或受控网络环境使用；若后续要上公网，建议评估签名校验或改为 HTTPS。

---

## 2. 部署方式（最简单：静态 HTTP）

任何能提供静态文件下载的 HTTP 服务都可以，例如：
- Nginx
- Apache
- Python 简易 HTTP 服务（仅用于开发/演示）

### 2.1 示例：Python 简易 HTTP（演示用）

在放置 `light.bin` 的目录启动：

```powershell
# Windows PowerShell
python -m http.server 8000
```

访问 URL 示例：
- `http://<PC_IP>:8000/light.bin`

---

## 3. 设备端触发 OTA

### 3.1 触发命令

设备串口进入 Matter shell 后，执行：

```text
matter esp ota http://<SERVER_IP>:<PORT>/path/to/light.bin
```

示例：

```text
matter esp ota http://192.168.1.10:8000/light.bin
```

### 3.2 预期日志特征

升级过程中一般可看到：
- 下载进度（0% → 100%）
- 写入 OTA 分区成功
- 提示升级成功并延时重启
- 重启后从另一 OTA 分区启动（例如 `Loaded app from partition ...`）
- 启动日志中的 `App version` 更新

---

## 4. 版本管理建议

### 4.1 版本号两件事需要一致

- **固件内部版本号**（启动日志里的 `App version`）
- **OTA 镜像头版本字段**（用于升级判断与记录）

建议每次发布新固件时同步更新版本号（例如 2.0 → 2.1）。

### 4.2 服务器侧发布策略

- 不覆盖旧版本文件，按版本目录存放
- 用“latest”软链接/重定向（可选）
- 记录每次发布的：版本号、发布时间、文件 SHA256

---

## 5. 常见问题排查

### 5.1 设备提示 404/无法连接

- 检查 URL 是否可在 PC 浏览器直接下载
- 检查服务器与设备是否在同一网段、是否被防火墙拦截
- 确认端口未被占用

### 5.2 下载中断/升级失败

- 检查 Wi-Fi/Thread 网络稳定性（尤其是演示环境）
- 检查固件文件大小是否超出分区容量
- 确认分区表为双 OTA（`ota_0/ota_1/otadata`）

### 5.3 升级后版本号未变化

- 确认你上传的是新版本 `light.bin`
- 确认构建时已修改工程版本号（例如 `PROJECT_VER` / `PROJECT_VER_NUMBER`）

---

## 6. 交付说明（建议写在测试报告里）

建议在测试报告中附：
- 服务器目录与 URL 示例
- 设备执行 `matter esp ota` 的截图/视频
- 升级前后 `App version` 对比截图/视频