8910DM：FOTA 升级指导

1.OpenCPU FOTA简介
使用此种方式升级，需要先将升级包放到设备上，可以通过很多方式，如http、ftp、或UART等。调用升级API，设备自行检测升级包，验证通过后进行版本升级。升级过程支持断电异常处理，不会导致启动失败情况发生。
升级包有两种类型：整包，差分包
整包只使用新版本pac包制作，分为：系统固件，APP
差分包使用新、旧pac包制作，分为；系统固件，APP，整机（系统固件与应用可以统一升级，避免单独升级可能出现的不兼容问题）

2.工具简介
您需要获取支持linux和 windows的差分包制作工具dtools，该工具分别在SDK包的./tools/linux/， ./tools/windows/目录下。两种工具支持的环境不同，使用方式大致相同，制作出的包没有差别。

3.整包
该升级方式无需旧版本，使用新版本制作出的升级包可直接升级为新版本。系统固件/APP都支持该方式升级。

注：系统固件的整包比较大，内置FLASH无法满足，需要外挂FLASH的支持。

3.1 Windows下制作流程
1）将新版本的PAC包放入sdk\tools\win32\下，此处以new.pac为例；
2）通过快捷键WIN+R，运行CMD，打开命令行窗口，用cd命令进入到sdk\tools\win32目录下；
3）执行命令
dtools.exe fotacreate2 --single-pac new.pac,setting/fota8910.xml up.pack
其中up.pack为生成的整包名字，执行完毕即可得到整包。

3.2 Linux下制作流程
1）将新版本的PAC包放入sdk/tools/linux/下，此处以new.pac为例；
2）在shell命令环境下，用cd命令进入到sdk/tools/linux/下；
3）执行命令
dtools fotacreate2 --single-pac new.pac,setting/fota8910.xml up.pack
其中up.pack为生成的整包名字，执行完毕即可得到整包。

4.系统固件差分包
使用新、旧版本制作系统固件的差分包
4.1 Window下制作流程
1）获取dtools工具；
2）将新、旧版本的PAC包一起放入到dtools目录下，此处以old.pac new.pac为例；
3）通过快捷键WIN+R，运行CMD，打开命令行窗口，用CD命令进入到解压出的目录下；
4）执行命令
dtools.exe fotacreate2 --pac old.pac,new.pac,setting\fota8910.xml up.pack
其中up.pack为生成的差分包名字，执行完毕即可得到差分包。

注：新旧版本间要加逗号并且不能有空格，否则会失败。

4.2 Linux下制作流程
1）获取dtools工具；
2）将新、旧版本的PAC包一起放入到dtools目录下，此处以old.pac new.pac为例；
3）在shell命令环境下，用cd命令进入到解压出的目录下；
4）执行命令
dtools fotacreate2 --pac old.pac,new.pac,setting/fota8910.xml up.pack
其中up.pack为生成的差分包名字，执行完毕即可得到差分包。

注：新旧版本间要加逗号并且不能有空格，否则会失败。

5.APP差分包
使用新、旧版本制作APP的差分包
5.1 Windows下制作流程
1）将新、旧版本的PAC包一起放入sdk\tools\win32\下，此处以old.pac new.pac为例；
2）通过快捷键WIN+R，运行CMD，打开命令行窗口，用cd命令进入到sdk\tools\win32目录下；
3）执行命令
dtools.exe fotacreate2 --pac old.pac,new.pac,fota8910_appimg_flash.xml up.pack
其中up.pack为生成的差分包名字，执行完毕即可得到差分包。

注：新旧版本间要加逗号并且不能有空格，否则会失败。

5.2 Linux下制作流程
1）将新、旧版本的PAC包一起放入sdk/tools/linux/下，此处以old.pac new.pac为例；
2）在shell命令环境下，用cd命令进入到sdk/tools/linux/下；
3）执行命令
dtools fotacreate2 --pac old.pac,new.pac,fota8910_appimg_flash.xml up.pack
其中up.pack为生成的差分包名字，执行完毕即可得到差分包
注：新旧版本间要加逗号且不能有空格，否则会失败

6.整机差分包
该升级方式是先将系统固件/APP合并为一个总包后，再对总包制作差分包，达到系统固件/APP同时升级的目的。
6.1 Windows下制作流程
1）将同一版本(升级前/升级后）的系统和应用的PAC包一起放入sdk/tools/win32/下，此处以sys_old.pac app_old.pac为例；
2）在shell命令环境下，用cd命令进入到sdk/tools/win32/下；
3）执行命令
dtools.exe pacmerge --id APPIMG,PS sys_old.pac app_old.pac old.pac
即可得到旧的总包old.pac，同理可做出新的总包new.pack
4）对制作出的新、旧总包，执行命令
dtools.exe fotacreate2 --pac old.pac,new.pac,setting\fota8910.xml up.pack
就能得到最终的差分包up.pack

6.2 Linux下制作流程
1）将同一版本(升级前/升级后）的系统和应用的PAC包一起放入sdk/tools/linux/下，此处以sys_old.pac app_old.pac为例；
2）在shell命令环境下，用cd命令进入到sdk/tools/linux/下；
3）执行命令
dtools pacmerge --id APPIMG,PS sys_old.pac app_old.pac old.pac
即可得到旧的总包old.pac，同理可做出新的总包new.pack
4）对制作出的新、旧总包，执行命令
dtools fotacreate2 --pac old.pac,new.pac,setting\fota8910.xml up.pack
就能得到最终的差分包up.pack

7.FOTA升级
7.1升级过程
FOTA升级过程分为两个部分：
第一部分下载差分包；差分包可以通过网络或UART获取，然后写入文件系统。
注：网络方式有FTP和HTTP，
第二部分使用差分包升级系统。调用升级API后，系统将检验差分包，如匹配，待重新启动时将自动执行升级过程。
正在运行的版本称为“旧版本”，将要升级的版本称为“新版本”，通过新旧版本生成差分包，确保当前运行的版本为旧版本，这样差分包才能匹配，升级后运行在新版本上。

7.2 FOTA 升级API

bool MG_updateFirmware(char* updatename)

updatename 	 差分包文件的路径/名字
return
失败则返回false
成功则系统将自动重启，并完成升级

bool MG_updateFirmwareV2(char* updatename)
updatename 	 差分包文件的路径/名字
return
失败则返回false
成功则返回true，需手动设置重启，才能完成升级。

注：如果差分包的路径为”/fota/fota.pack”，则不进行拷贝动作，可节省空间。否则函数内部会先将差分包拷贝到/fota/目录下，原差分包文件仍保留，较占用空间。
注：调用OTA API会自动创建/fota文件夹，其中会产生临时文件。可在失败或重启升级完成后调用函数删除该文件夹及其下文件。

示例：

char *fota = "update.pack";
if(!MG_updateFirmware(fota))
{
    MG_osiTracePrintf(LOG_TAG, "mg update failed");
}

---

char *name1 = "/fota/fota.stage";
char *name2 = "/fota/fota.pack";
char *name3 = "/fota/fota.tmp";
char *path = "/fota";
vfs_unlink(name1);
vfs_unlink(name2);    
vfs_unlink(name3); 
vfs_rmdir(path);   

7.3升级成功
检查升级成功情况：
调用API后，系统将自动执行检查及升级过程，重新启动并升级成功后，运行的是“新版本”。

7.4异常情况处理
7.4.1检查升级包不匹配
如果升级包不匹配当前运行的版本，OTA API将会返回false.

7.4.2 异常断电情况
当在升级过程中出现掉电情况时，有以下三种场景：
发送文件时断电，导致发送文件失败，没有其他影响
已调用API，生成临时文件时断电，导致检测差分包无效，没有其他影响
在执行升级过程中断电，上电后会继续进程，直到完成升级过程，保证系统正常运行