QQ物联-OTA升级

gaoxianqu

OTA升级是什么
OTA升级模块用来实现通过手机QQ控制设备进行固件/apk升级。
配置平台可配置强制升级和非强制升级，强制升级会在手机QQ控制界面弹窗强制用户升级设备，一般用于修复重大安全隐患的更新，非强制升级以小红点的方式提示用户设备有升级信息。
前后台流程.

（1）开发者在物联配置平台上传升级包并配置升级信息
（2）手机QQ在进入设备控制界面后自动去配置平台检测升级信息，根据设备初始化时填入的productVersion参数作为当前设备版本与配置平台配置的目标版本做比较确定是否需要升级
（3）手机QQ检测到升级信息通知设备下载升级文件
（4）设备下载升级文件，下载由sdk完成，sdk会给出相应事件的回调
（5）设备进行升级操作
（6）设备升级完成上报升级结果给手机QQ，这一步是必须的，否则手机QQ会报超时给用户
用户操作体验
下图分别为手机QQ中的非强制升级提示界面，强制升级提示界面，升级操作界面


Linux设备代码对接
在Linux设备中接入OTA模块首先需要在设备sdk初始化的时候一并初始化升级模块：
/**
* 有设备可用的新固件版本，手机会将查询到的固件包信息通知给设备
* param: pkg_size 新的升级固件包的大小，单位为字节
* param：title + desc 升级描述信息，如果您的智能设备没有显示屏，可以忽略
* param: target_version 目标版本的版本号
* return: 如果返回0，sdk将会开始启动升级包下载
* 如果返回1 会提示用户设备端拒绝升级（一般是磁盘剩余空间问题）
*/
int on_new_pkg_come(unsigned long long from, unsigned long long pkg_size, const char * title, const char * desc, unsigned int target_version)
{
    //todo
    return 0;
}

/**
* 设备下载升级文件，并且实时地将进度通知给手机QQ，单位为字节
* param：download_size 当前已经下载到的文件大小
* param: total_size文件总计大小，您可以用  download_size/total_size 来计算百分比
*/
void on_download_progress(unsigned long long download_size, unsigned long long total_size)
{
    //todo
}

/**
* param: ret_code  0表示下载成功，其它表示失败
* 0   成功
* 2   未知错误
* 3   当前请求需要用户验证401
* 4   下载文件写失败，没有写权限/空间不足/文件路径不正确
* 5   网络异常
* 7   升级文件包不存在404
* 8   服务器当前无法处理请求503
* 9   下载被手q用户中止
* 10  参数错误，url不合法
* 11  升级包md5值校验失败，下载可能被劫持
*/
void on_download_complete(int ret_code)
{
    //todo
}

/**
* 手机等设备将文件下载完成后，会有一个最后的用户确认才会开始更新固件，因为替换文件可能需要一些时间，
* 之后也有可能要重启设备，一个手机端的确认界面能给用户以心理上的等待预期。
*
* 所以您需要在收到这个通知以后，再开始启动固件升级
*/
void on_update_confirm()
{
    //todo 在这里执行升级操作
}

...
tx_ota_notify otaNotify = {0};
otaNotify.on_new_pkg_come = on_new_pkg_come;
otaNotify.on_download_progress = on_download_progress;
otaNotify.on_download_complete = on_download_complete;
otaNotify.on_update_confirm = on_update_confirm;

/**
* 初始化OTA模块
* param: replace_timeout 您希望手机APP最多等待多少时间提示升级超时，您需要保证绝大多数情况下：
*文件替换 + 设备重启的时间 < replace_timeout, 时间单位:秒
* param: target_pathname 您希望我们把升级包下载到哪个目录下的哪个文件，需要填写带文件名的完整路径
*/
tx_init_ota(&otaNotify, 5*60 , "/tmp/ota.apk");
最后在设备升级完成之后，无论成功失败请务必给手机QQ一个结果：
/**
*  设备完成升级，需要给手机一个升级结果的反馈，告知手机是否升级成功了,否则手q会在一段时间
*            之后告知用户升级超时，所以请务必实现此接口（如果设备重启，需要在设备上线之后调用）
*  param: ret_code  0表示成功；1表示失败
*  param: err_msg   升级失败的描述文案，升级失败时填写
*/
tx_ack_ota_result(0, "success");

Android设备代码对接
在Android设备中接入OTA模块首先需要在设备sdk初始化的时候一并初始化升级模块：

/**
* 初始化OTA模块
* param: replaceTimeout 您希望手机APP最多等待多少时间提示升级超时，您需要保证绝大多数情况下：
*文件替换 + 设备重启的时间 < replace_timeout, 时间单位:秒
* param: targetPathName 您希望我们把升级包下载到哪个目录下的哪个文件，需要填写带文件名的完整路径
*/

public static native void initOTA(int replaceTimeout, String targetPathName);

/**
*  设备完成升级，需要给手机一个升级结果的反馈，告知手机是否升级成功了,否则手q会在一段时间
*            之后告知用户升级超时，所以请务必实现此接口（如果设备重启，需要在设备上线之后调用）
*  param: resultCode  0表示成功；1表示失败
*  param: errorMsg   升级失败的描述文案，升级失败时填写
*/
public static native void ackOtaResult(int resultCode, String errorMsg);

...

initOTA(10*50, this.getCacheDir().getAbsolutePath()+"/ota1");
然后实现一些回调以便SDK给设备一些关键事件的通知：

  /*** 有设备可用的新固件版本，手机会将查询到的固件包信息通知给设备
* param: pkgSize 新的升级固件包的大小
* param：title + desc 升级描述信息，如果您的智能设备没有显示屏，可以忽略
* param: targetVer 目标版本的版本号
* return: 如果返回0，sdk将会开始启动升级包下载
* 如果返回1 会提示用户设备端拒绝升级（一般是磁盘剩余空间问题）
*/
  private int onNewPkgCome(long from, long pkgSize, String title, String desc, int targetVer) {         
    return 0;
  }

/**
* 设备下载升级文件，并且实时地将进度通知给手机QQ,单位为字节
* param：currentProgress 当前已经下载到的文件大小
* param: maxProgress，您可以用  download_size/total_size 来计算百分比
*/
  private void onDownloadProgress(long currentProgress, long maxProgress) {

  }

  /**
* param: resultCode  0表示下载成功，其它表示失败
* 0   成功
* 2   未知错误
* 3   当前请求需要用户验证401
* 4   下载文件写失败，没有写权限/空间不足/文件路径不正确
* 5   网络异常
* 7   升级文件包不存在404
* 8   服务器当前无法处理请求503
* 9   下载被手q用户中止
* 10  参数错误，url不合法
* 11  升级包md5值校验失败，下载可能被劫持
*/
  private void onDownloadComplete(int resultCode) {

  }

/**
* 手机等设备将文件下载完成后，会有一个最后的用户确认才会开始更新固件，因为替换文件可能需要一些时间，
* 之后也有可能要重启设备，一个手机端的确认界面能给用户以心理上的等待预期。
*
* 所以您需要在收到这个通知以后，再开始启动固件升级
*/

  private void onUpdateConfirm() {
      //设备在这里实现升级操作
  }
最后在设备升级完成之后，无论成功失败请务必给手机QQ一个结果：
ackOtaResult(0, "success");
该接口需要在在线状态下调用，所以如果设备升级中发生重启则需要在上线之后调用。

验证流程
（1）首先准备升级的固件包，注意设备初始化时填入的productVersion参数是设备的当前版本号(int型），升级流程会以此版本号与配置平台配置的目标版本号对比确认是否需要升级。
（2）接下来配置升级信息，配置的版本号要大于需要升级的设备的版本号，该版本号以下的设备均会收到升级通知：

（3）接下来可以到手机QQ控制界面进行测试，见用户操作体验栏中的示例图
说明：如果配置强制升级，用户进入手机QQ设备控制界面会以弹窗提示升级，如果配置非强制升级，只会在菜单中以小红点提示用户有升级信息。

注意事项
OTA升级中需要注意如下事项：
（1）以设备初始化时填入的productVersion为当前设备的版本号来判断升级
（2）指定升级包下载位置的时候需要填写包括文件名在内的全路径，目录要有读写权限空间足够，如果下载失败请查看下载完成回调中的错误码
（3）设备升级完成之后无论成功失败请务必调用上报结果给手机QQ的接口