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` 对比截图/视频
|