124 lines
3.1 KiB
Markdown
124 lines
3.1 KiB
Markdown
# 远程 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` 对比截图/视频
|