电信物联网平台SOTA升级（软件升级）的全流程说明

  中国电信物联网开放平台（以下简称“平台”）提供了基于LWM2M的固件升级功能，用于模组的固件升级。但是由于多数模组并未提供升级接口给MCU，所以MCU升级只能基于应用层来实现升级，为了避免和模组的升级混淆，我们把MCU的升级称为软件升级。

1. 总体流程

  要在电信平台上执行软件升级功能，基本需要完成如下步骤：
  1、在电信开发者平台上制作“编解码插件”，并通过电信的认证，取得认证证书之后，才能将“编解码插件”部署到电信的正式平台（测试平台不需要证书验证）。
“编解码插件”的制作方式及电信平台的认证方式均不在该文档的讲解范围内。
  2、通过离线签名工具制作“公私钥”文件，并将其部署电信平台。
  3、制作软件升级包，并将其部署到电信平台。
  4、在电信平台创建“软件升级任务”，执行软件升级流程。

  下面分别逐流程详细进行介绍。

2. 开发者平台开发插件

  该部分内容详见《电信物联网平台插件开发流程》总结。若已经完成“插件”的开发，可以忽略此步骤。

3. 生成公私钥文件

3.1 公私钥文件制作

  制作公私钥文件的步骤如下：
  1、使用浏览器登录电信云平台，如下图所示，下载离线签名工具。

  2、下载完成后，解压，进入signtool文件夹，运行“signtool.exe”，操作界面如下图所示。
  3、生成数字签名公私钥对。
  根据实际情况选择签名算法，目前仅提供里一种签名算法ECDSA_256K1+SHA256。
  设置“私钥加密口令”，特别说明：
   （a）口令长度至少6个字符；
   （b）口令必须包含以下至少两种的字符的组合：至少一个小写字母；至少一个大写字母；至少一个数字；至少一个特殊字符（`~!@#$%^&*()-_=+|[{}];:'",<.>/？和空格）。
  4、单击“生成公私密钥”，在弹出的窗口中选择需要保存的目录，单击“确定”。可在保存的目录下查看生成的公私密钥文件（公钥文件：public.pem、私钥文件：private.pem）。

3.2 公私钥文件上传

   登陆SP Portal，设备管理中选择具体的某一个应用，点击进入对应的应用下，在软件库的公钥管理中上传公钥。

4. 制作软件升级包

  平台对升级的软件有格式要求，厂商需要根据软件包制作规范制作软件包，并上传到平台。

4.1 软件包制作

  1、准备升级软件包文件
  软件升级包是设备厂商自己制作的包，需要将所有要在升级时传给设备的软件版本文件都打成一个升级文件。
  注意：软件包文件名称不支持包含中文字符，且制作升级包的文件路径不能包含中文。
  制作升级包的步骤如下：
  步骤1：新建文件夹命名为"DM"，在DM文件夹下创建设备系统类型文件夹，例如嵌入式设备通常采用"linux"，将厂商发布的软件包描述文件"UpgradeDesc.json"文件至于"linux"目录下，参见下图：

UpgradeDesc.json文件字段说明参见下表，文件编码格式为UTF-8无BOM。

字段名	字段描述	是否必填
specVersion	描述文件版本号，固定值：“1.0”	是
fileName	软件包文件名，例如：ExamplePackage_V1.0.xx	是
version	软件包版本号（升级协议类型为PCP的设备软件版本号长度不超过16个字节）	是
deviceType	设备类型	是
manufacturerName	制造商名称	是
model	产品型号	是
packageType	软件包必须设置为：“softwarePackage”	是
date	出包时间，格式为：“yyyy-MM-dd”	否
description	对软件包的自定义描述	否
supportSourceVersionList	List支持用于升级此版本包的设备源版本列表。不配置该字段说明该版本可用于任意源版本进行升级（具体见下表）	否
versionCheckCode	设备厂商出包时用于版本包校验的校验码（用户自定义字段，2个字符，如果配置该字段，在平台通知设备做版本下载时会将该字段作为参数发送给设备，由设备侧自行进行版本校验）	否
UpgradeDesc.json文件模板如下：
{
“specVersion”: “1.0”, （此处为固定值）
“fileName”: “E10RT_APP_V7.00_20201023.bin”, （此处需要与我们升级文件名保持一致）
“packageType”: “softwarePackage”, （此处为固定值）
“version”: “V7.0”, （升级.bin文件的实际版本）
“deviceType”: “WaterMeter”, （与下图的产品模型中的保持一致）
“manufacturerName”: “Huawei”, （与下图的产品模型中的保持一致）
“model”: “NBIoTDeviceDev”, （与下图的产品模型中的保持一致）
“protocolType”:“CoAP”, （与下图的产品模型中的保持一致）
“description”:“This is E10RT Ver7.0 APP”,
“versionCheckCode”:“D3”, （通过格西CRC计算器计算）
“date”:“2020-10-23”
}

  通过格西CRC计算检验和的方式如下：

  步骤2：在与"DM"同级目录下创建平台类型文件夹，例如"linux"，该文件夹名称必须同步骤1中的平台类型文件夹一致，将厂商软件包至于该目录，参见下图：

  步骤3：选中"DM"和"linux"文件夹，使用winRAR等压缩工具打包成ZIP格式的压缩包package.zip（注意package.zip下不能包含package这层目录，如图 8-1-3所示。不能压缩成其他格式例如rar然后在手动修改文件类型为zip）。

  步骤4：对升级包进行离线签名，执行步骤如下。
  注意：离线签名工具只能对.zip格式的压缩包进行数字签名。
  1）在“软件包数字签名”区域，单击“导入私钥文件”，选择“3.生成公私钥文件”章节中生成的私钥文件，单击“打开”。
  2）在弹出的对话框中，输入“3.生成公私钥文件”章节中设置的口令，单击“确定”。
  3）在“需要数字签名的软件包”区域，选择需要进行数字签名的升级包。单击“打开”。
  4）单击“进行数字签名”。
  5）签名成功后，在原软件包所在目录生成名为“XXX_signed.XXX”的带签名的升级包。
  6）升级包签名验证。
  7）在“软件包签名验证”区域，单击“导入公钥文件”，选择步骤5.3中生成的公钥文件，单击“打开”。
  8）在“需要验签的软件包”区域，选择步骤6中生成的名为“XXX_signed.XXX”的带签名的升级包。单击“打开”。
  9）单击“进行软件包验签”。
  10）验证成功则弹出“验证签名成功！”提示框。
  11）验证失败则弹出“验签异常！”提示框。

4.2 软件包上传

  登陆SP Portal，在设备管理页面，选择对应的应用，点击“软件库”，在“软件包管理”页面点击添加软件包，选择签名后的软件包，点击“确认”执行软件包上传。

4.3 Profile

  如果设备需要软件升级，需要在设备profile里增加软件升级能力的定义，可以在开发者中心勾选软件升级协议“PCP”。

5.创建升级任务

  电信正式平台的IP：https://device.local.ct10649.com:8843/

  登陆电信平台，如上图所示，选择“设备管理”，选择具体的某一个应用，然后选择左侧列表中的“批量任务”，点“批量软固件升级”，进入软固件升级界面，选择“软件升级”
点“创建”，创建软件升级任务，进入下图界面。

  填写“任务名称”（可以按照自己的规则编写一个名称），执行类型勾选“设备在线时”（由于终端多数情况都处于离线状态，为了避免升级任务超时，这里选择设备在线时升级），“重试策略”和“APP确认”保持默认值即可。点“下一步”，如下图所示。

  选择升级所需的升级包（升级包是我们提前制作好上传到电信平台的）。选择升级包之后，点“下一步”，进入选择设备界面（下图）。

  可以选择具体的一个设备，也可以选择一个群组。选择设备就是对某一个具体的终端进行升级，而选择群组就是对某一群设备进行升级（群组的创建可以参考电信的相关说明），选择完设备之后，点“提交”就完成了升级任务的创建工作。
  任务创建成功之后，可以查询任务的执行情况，点“任务ID”进入如下界面，可以查看任务的基本信息，也可以查看执行详情，如下图所示。

  基本信息：

  执行详情：

  至此，在电信平台创建软件升级任务的全流程基本全部包含。