Skip to content

Commit 249aaa4

Browse files
neilyheneilyhe
committed
更新说明文档
1 parent b2cd710 commit 249aaa4

8 files changed

+4281
-0
lines changed

‎docs/OTA模块.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
**目录**
2+
3+
<!-- TOC -->
4+
5+
- [1. 功能介绍](#1-功能介绍)
6+
- [2. 使用流程](#2-使用流程)
7+
- [3. 接口参考](#3-接口参考)
8+
- [接口列表](#接口列表)
9+
- [接口描述](#接口描述)
10+
- [iv\_ota\_init](#iv_ota_init)
11+
- [iv\_ota\_exit](#iv_ota_exit)
12+
- [iv\_ota\_update\_progress](#iv_ota_update_progress)
13+
- [iv\_ota\_firmware\_update\_cb](#iv_ota_firmware_update_cb)
14+
- [iv\_ota\_prepare\_cb](#iv_ota_prepare_cb)
15+
- [iv\_ota\_download\_size\_cb](#iv_ota_download_size_cb)
16+
- [4. 数据结构](#4-数据结构)
17+
- [数据结构列表](#数据结构列表)
18+
- [数据结构描述](#数据结构描述)
19+
- [iv\_ota\_progress\_type\_e](#iv_ota_progress_type_e)
20+
- [iv\_ota\_fail\_type\_e](#iv_ota_fail_type_e)
21+
- [iv\_ota\_init\_parm\_s](#iv_ota_init_parm_s)
22+
- [5. 注意事项](#5-注意事项)
23+
24+
<!-- /TOC -->
25+
--------
26+
27+
# 1. 功能介绍
28+
本模块提供设备的OTA升级能力。
29+
30+
31+
# 2. 使用流程
32+
1. 在控制台上传固件，填写版本号等信息，并推送固件
33+
2. 调用 `iv_ota_init` 后，SDK会启动单独的OTA任务线程，并上报当前设备内正在运行的固件版本号
34+
3. 设备端发现有新版本固件后会调用`iv_ota_prepare_cb`通知用户，并告知新固件版本与大小，如果准备好升级请返回0，如未准备好或希望下次升级请返回非零值
35+
4. 设备端SDK在用户准备好升级后开始下载固件，下载的过程中会调用`iv_ota_download_size_cb`告知用户已下载的固件大小
36+
5. 当设备端SDK下载完固件并校验MD5正确之后，会通过回调 `iv_ota_firmware_update_cb` 通知用户，并告知固件保存地址及相关信息
37+
6. 如仅下载固件，暂不升级，可调用 `iv_ota_update_progress` 上报 IV_OTA_PROGRESS_TYPE_FAIL 消息
38+
7. 设备开始烧录前，请使用 `iv_ota_update_progress` 上报 IV_OTA_PROGRESS_TYPE_WRITE_FLASH 消息
39+
8. 烧录完成后，重启之前，请使用 `iv_ota_update_progress` 上报 IV_OTA_PROGRESS_TYPE_REBOOT 消息
40+
9. 重启完成且升级成功后，请使用 `iv_ota_update_progress` 上报 IV_OTA_PROGRESS_TYPE_SUCCESS 消息
41+
10. 固件升级过程中如发生错误，可使用 `iv_ota_update_progress` 上报 IV_OTA_PROGRESS_TYPE_FAIL 消息
42+
11. 当固件升级结束之后，或者发生异常需要退出的时候，请调用 `iv_ota_exit` 退出OTA模块，否则会循环上报版本并进行OTA过程
43+
44+
详细使用流程请参考例程代码。
45+
46+
47+
# 3. 接口参考
48+
49+
## 接口列表
50+
**该功能模块提供以下接口**
51+
* iv_ota_init() OTA模块初始化
52+
* iv_ota_exit() OTA模块销毁
53+
* iv_ota_update_progress() OTA状态上报
54+
55+
**用户需注册以下回调函数**
56+
* (*iv_ota_firmware_update_cb)() OTA升级烧录通知回调
57+
* (*iv_ota_prepare_cb)() OTA升级准备状态回调
58+
* (*iv_ota_download_size_cb)() OTA已下载固件大小回调
59+
60+
## 接口描述
61+
62+
### iv_ota_init
63+
64+
**功能描述**
65+
OTA模块初始化，函数内部会执行查询固件版本等操作。
66+
该接口为阻塞接口，阻塞时长视网络情况而定。
67+
68+
**函数原型**
69+
```
70+
int iv_ota_init(iv_ota_init_parm_s *pstInitParm)
71+
```
72+
73+
**参数说明**
74+
| 参数名称 | 类型 | 描述 | 输入/输出 |
75+
| ----------- | -------------------- | ------------- | --------- |
76+
| pstInitParm | iv_ota_init_parm_s * | OTA初始化参数 | 输入 |
77+
78+
**返回值**
79+
| 返回值 | 描述 |
80+
| ----------- | -------------------- |
81+
| IV_ERR_NONE | 成功 |
82+
| IV_ERR_* | 失败，对应相应错误码 |
83+
84+
85+
### iv_ota_exit
86+
87+
**功能描述**
88+
退出并销毁OTA模块。
89+
90+
**函数原型**
91+
```
92+
int iv_ota_exit(void)
93+
```
94+
95+
**参数说明**
96+
| 参数名称 | 类型 | 描述 | 输入/输出 |
97+
| -------- | ---- | ---- | --------- |
98+
| 无 | 无 | 无 | 无 |
99+
100+
**返回值**
101+
| 返回值 | 描述 |
102+
| ----------- | -------------------- |
103+
| IV_ERR_NONE | 成功 |
104+
| IV_ERR_* | 失败，对应相应错误码 |
105+
106+
107+
### iv_ota_update_progress
108+
109+
**功能描述**
110+
上报OTA升级的进度。
111+
使用本接口可以向后台上报当前设备处于OTA的何种状态，例如烧录中、重启中、升级成功、升级失败。
112+
113+
**函数原型**
114+
```
115+
int iv_ota_update_progress(iv_ota_progress_type_e type, int progress_value)
116+
```
117+
118+
**参数说明**
119+
| 参数名称 | 类型 | 描述 | 输入/输出 |
120+
| -------------- | ---------------------- | ---------------------------------------- | --------- |
121+
| type | iv_ota_progress_type_e | 当前的升级状态 | 输入 |
122+
| progress_value | int | 当前的升级状态的进度（仅预留，暂不支持） | 输入 |
123+
124+
**返回值**
125+
| 返回值 | 描述 |
126+
| ----------- | -------------------- |
127+
| IV_ERR_NONE | 成功 |
128+
| IV_ERR_* | 失败，对应相应错误码 |
129+
130+
131+
### iv_ota_firmware_update_cb
132+
133+
**功能描述**
134+
当固件下载完成时，SDK使用此回调函数告知用户固件保存的路径和大小，之后用户可以开始进行固件升级。
135+
136+
**函数原型**
137+
```
138+
void (* iv_ota_firmware_update_cb)(char * firmware_name, uint32_t firmware_len);
139+
```
140+
141+
**参数说明**
142+
| 参数名称 | 类型 | 描述 | 输入/输出 |
143+
| ------------- | -------- | ------------ | --------- |
144+
| firmware_name | char * | 固件保存路径 | 输出 |
145+
| firmware_len | uint32_t | 固件大小 | 输出 |
146+
147+
**返回值**
148+
| 返回值 | 描述 |
149+
| ------ | ---- |
150+
| 无 | 无 |
151+
152+
153+
### iv_ota_prepare_cb
154+
155+
**功能描述**
156+
OTA升级时，SDK使用此回调函数向用户查询是否准备好进行升级。
157+
158+
**函数原型**
159+
```
160+
int (* iv_ota_prepare_cb)(char *new_firmware_version, uint32_t new_firmware_size);
161+
```
162+
163+
**参数说明**
164+
| 参数名称 | 类型 | 描述 | 输入/输出 |
165+
| -------------------- | -------- | ---------- | --------- |
166+
| new_firmware_version | char* | 新固件名 | 输入 |
167+
| new_firmware_size | uint32_t | 新固件大小 | 输入 |
168+
169+
170+
**返回值**
171+
| 返回值 | 描述 |
172+
| ------ | ---------------- |
173+
| 0 | 已准备好进行升级 |
174+
| 非0 | 未准备好进行升级 |
175+
176+
177+
### iv_ota_download_size_cb
178+
179+
**功能描述**
180+
OTA下载固件过程中，SDK使用此回调函数向用户告知已下载固件大小。
181+
182+
**函数原型**
183+
```
184+
void (* iv_ota_download_size_cb)(uint32_t size);
185+
```
186+
187+
**参数说明**
188+
| 参数名称 | 类型 | 描述 | 输入/输出 |
189+
| -------- | -------- | ---------- | --------- |
190+
| size | uint32_t | 已下载大小 | 输入 |
191+
192+
193+
**返回值**
194+
| 返回值 | 描述 |
195+
| ------ | ---- |
196+
| 无 | 无 |
197+
198+
199+
# 4. 数据结构
200+
201+
## 数据结构列表
202+
**云存模块涉及以下数据结构**
203+
* iv_ota_progress_type_e OTA进度状态枚举
204+
* iv_ota_fail_type_e OTA失败原因枚举
205+
* iv_ota_init_parm_s OTA模块初始化参数
206+
207+
208+
## 数据结构描述
209+
210+
### iv_ota_progress_type_e
211+
212+
**功能描述**
213+
OTA进度状态枚举
214+
215+
**结构原型**
216+
```
217+
typedef enum
218+
{
219+
IV_OTA_PROGRESS_TYPE_WRITE_FLASH = 0,
220+
IV_OTA_PROGRESS_TYPE_REBOOT = 1,
221+
IV_OTA_PROGRESS_TYPE_SUCCESS = 2,
222+
IV_OTA_PROGRESS_TYPE_FAIL = 3,
223+
IV_OTA_PROGRESS_TYPE_BUTT
224+
}iv_ota_progress_type_e;
225+
```
226+
227+
**参数说明**
228+
| 成员名称 | 描述 | 取值 |
229+
| -------------------------------- | -------- | ---- |
230+
| IV_OTA_PROGRESS_TYPE_WRITE_FLASH | 烧录状态 | 0 |
231+
| IV_OTA_PROGRESS_TYPE_REBOOT | 重启状态 | 1 |
232+
| IV_OTA_PROGRESS_TYPE_SUCCESS | 升级成功 | 2 |
233+
| IV_OTA_PROGRESS_TYPE_FAIL | 升级失败 | 3 |
234+
| IV_OTA_PROGRESS_TYPE_BUTT | 枚举总数 | - |
235+
236+
237+
### iv_ota_fail_type_e
238+
239+
**功能描述**
240+
OTA失败原因枚举
241+
242+
**结构原型**
243+
```
244+
typedef enum
245+
{
246+
IV_OTA_FAIL_TYPE_OPEN_FILE = 0,
247+
IV_OTA_FAIL_TYPE_WRONG_SIZE = 1,
248+
IV_OTA_FAIL_TYPE_WRITE_FLASH = 2,
249+
IV_OTA_FAIL_TYPE_WRITE_BUTT
250+
}iv_ota_fail_type_e;
251+
```
252+
253+
**参数说明**
254+
| 成员名称 | 描述 | 取值 |
255+
| ---------------------------- | ------------ | ---- |
256+
| IV_OTA_FAIL_TYPE_OPEN_FILE | 打开文件失败 | 0 |
257+
| IV_OTA_FAIL_TYPE_WRONG_SIZE | 固件大小错误 | 1 |
258+
| IV_OTA_FAIL_TYPE_WRITE_FLASH | 固件烧录错误 | 2 |
259+
| IV_OTA_FAIL_TYPE_WRITE_BUTT | 枚举总数 | - |
260+
261+
262+
### iv_ota_init_parm_s
263+
264+
**功能描述**
265+
OTA模块初始化参数
266+
267+
**结构原型**
268+
```
269+
typedef struct iv_ota_init_parm_s
270+
{
271+
void (* iv_ota_firmware_update_cb)(char * firmware_name, uint32_t firmware_len);
272+
char firmware_path[IV_OTA_LOCAL_FILE_NAME_MAX_LEN];
273+
char firmware_version[IV_OTA_FIRMWARE_VERSION_MAX_LEN];
274+
int (* iv_ota_prepare_cb)(char *new_firmware_version, uint32_t new_firmware_size);
275+
void (* iv_ota_download_size_cb)(uint32_t size);
276+
}iv_ota_init_parm_s;
277+
```
278+
279+
**参数说明**
280+
| 成员名称 | 描述 | 取值 |
281+
| ------------------------- | ---------------------------------------------------------- | ---- |
282+
| iv_ota_firmware_update_cb | OTA升级烧录通知回调 | - |
283+
| firmware_path | 保存固件的路径，不含文件名，该路径下需要足够的空间 | - |
284+
| firmware_version | 设备当前正在运行的固件版本号，该版本号会上报至后台以便管理 | - |
285+
| iv_ota_prepare_cb | OTA升级准备状态回调 | - |
286+
| iv_ota_download_size_cb | OTA已下载固件大小回调 | - |
287+
288+
289+
# 5. 注意事项
290+
1. SDK会在用户提供的固件下载目录下面创建包含固件版本号的固件文件，某些平台对路径及文件名的长度有限制，在云端控制台创建固件版本号不宜过长。
291+
2. OTA功能支持断点续传，OTA模块初始化时若存在未下载完的固件则会继续下载。
292+
3. SDK会在用户提供的固件下载路径下创建配置文件保存OTA进度，如果固件下载路径下除了固件文件还存在一个文本文件，则说明固件下载还未完成，在固件下载完成并校验无误之后，SDK会自动删除文本描述文件。

0 commit comments

Comments
 (0)