升级指导

软件升级流程

软件（Software）一般分为系统软件和应用软件，系统软件实现设备最基本的功能，比如编译工具、系统文件管理等；应用软件可以根据设备的特点，提供不同的功能，比如采集数据、数据分析处理等。

软件升级又称为SOTA（SoftWare Over The Air），是指用户可以通过OTA的方式支持对LWM2M协议的设备进行软件升级（基于MQTT协议的设备的软件升级能力即将上线，敬请期待）。软件升级遵循的协议为PCP协议，设备侧需要遵循PCP协议进行软件升级的适配开发，适配方法请参考设备侧适配。SOTA流程如下图所示：

SOTA升级流程的详细说明：

1～2. 用户在设备管理服务的控制台上传软件包，并在控制台或者应用服务器上创建软件升级任务。

3. NB-IoT设备上报数据，平台感知设备上线，触发升级协商流程。

6. 物联网平台向设备订阅软件升级的状态。

10～12. 物联网平台通知设备有新的软件包版本，设备启动软件包的下载。软件包的下载按照分片的方式进行下载，支持断点续传功能，通过软件包分片中携带的“versionCheckCode”确定是否属于同一个软件包。下载完成后，设备知会物联网平台软件包已下载完毕。

13～14. 物联网平台向设备下发升级的命令，终端设备进行升级操作，升级完成后终端设备向物联网平台反馈升级的结果。

15. 物联网平台向控制台/应用服务器通知升级的结果。

检查设备软件升级的能力

对终端设备进行软件升级，需要检查设备对应的产品模型中，是否支持设备的软件升级能力。您可以通过如下方式检查和设置设备软件升级的能力

1. 登录园区物联网平台控制台，点击右上角“进入园区物联网平台服务”。
2. 选择“设备接入管理 > 产品模型”，在“产品模型”界面点击“详情”，进入“产品详情”界面。

   

3. 在“维护能力配置”界面中，检查软件升级的能力。协议为LWM2M的产品模型，将软件升级设置为“支持”，协议为PCP。协议为MQTT的产品模型，将软件升级设置为“支持”，不校验软件升级协议类型。
   

   该操作只是修改了产品模型的能力，该产品模型对应的终端设备也需要支持软件升级的能力。否则，当升级任务中选择了不支持软件升级的终端设备，会导致软件升级失败。

   

制作软件升级版本包

设备升级的软件包文件由各设备厂商提供，在物联网平台上传设备的软件升级包前，需要制作软件升级的版本包，用于修改软件包的描述文件，如软件版本、厂商名称、设备类型、产品模型等信息。下面将详细介绍版本包的制作方法。

1. 新建文件夹命名为“DM”，在DM文件夹下新建文件夹，命名为“linux”。
2. 使用Notepad++文本工具新建一个文本文件，拷贝如下内容到文本中，在Notepad++工具的“编码”菜单中选择“使用UTF-8编码”，然后将文本进行存储，存储路径选择步骤1中的“linux”文件夹，文件名称命名为“UpgradeDesc”，保存类型选择“.json”。

   {
       "specVersion": "",
       "fileName": "",
       "packageType": "",
       "version": "",
       "deviceType": "",
       "manufacturerName": "",
       "model": "",
       "protocolType":"",
       "description":"",
       "versionCheckCode":"",
       "deviceShard":"",
       "platform":"",
       "supportSourceVersionList":[],
       "date":""
   }

   

3. 打开创建的“UpgradeDesc.json”文件，修改软件升级描述文件，相关字段如下表所示。

   字段名	字段描述	是否必填
   specVersion	描述文件版本号，固定值：“1.0”。	是
   fileName	软件包文件名，例如：“ExamplePackage_V1.0.10.xx”。	是
   packageType	软件包类型，必须设置为：“softwarePackage”。	是
   version	软件包版本号长度不超过16个字节，例如：“V1.0.10”	是
   deviceType	设备类型，需要与产品模型保持一致。例如：“WaterMeter”。	是
   manufacturerName	制造商名称，需要与产品模型保持一致。例如：“TestUtf8ManuName”。	是
   model	产品型号，需要与产品模型保持一致。例如：“TestUtf8ModelM2M”。	是
   protocolType	设备接入协议类型，需要与产品模型保持一致。例如：“CoAP”。 说明： 设备接入的协议类型有三种：“CoAP”、“LWM2M”、“MQTT”。	是
   description	对软件包的自定义描述。	是
   versionCheckCode	软件升级包校验码，长度为4个字符。软件包下载时支持断点续传，根据该字段标识前后两次下载的软件包分片是否为同一个软件包。	否
   deviceShard	终端下载软件包的每个分片的大小，单位为byte，如果不设置默认为500byte。大小为32~500之间。	否
   platform	标识设备的操作系统，如linux。	否
   supportSourceVersionList	支持用于升级此版本包的设备源版本列表。 支持通配符配置，*代表匹配任意0~n个字符，?代表匹配单个任意字符，如果存在多个版本，请使用英文“;”隔开。	否
   date	出包时间，格式为：“yyyy-MM-dd”。	否

4. 在与“DM”同级目录下创建文件夹，命名为“linux”，该文件夹名称必须同步骤1中的文件夹命令保持一致，将厂商软件包（软件包格式无限制）置于该文件中。

   

5. 选中“DM”和“linux”文件夹，使用压缩工具打包成ZIP格式的压缩包，建议命令为“xx_package.zip”。
   

   • 文件“DM”和“linux”的命名是固定的。

   • “xx_package.zip”下不能包含package这层目录。

   • 仅支持ZIP格式的压缩包，不能压缩成其他格式后，例如rar，再手动修改文件类型为zip。

上传软件包

园区物联网平台服务的控制台，提供软件包的管理能力，您可以将需要升级的软件包统一上传到“软件包管理”界面上进行管理。在上传软件包到控制台前，需要对软件包进行签名。

软件包签名：

1. 登录园区物联网平台服务的控制台，在“软件库>工具”页面，下载“离线签名工具”。
2. 解压“signtool.zip”，双击“signtool.exe”，运行离线签名工具。
3. 在“生成数字签名公私钥对”区域，选择“签名算法”，设置“私钥加密口令”，点击“生成公私密钥”，在弹出的窗口中选择需要保存的目录，点击“确定”，保存生成的公钥文件和私钥文件。

   

4. 在“软件包数字签名”区域导入私钥文件并输入私钥加密口令（私钥加密口令为在步骤3中设置的“私钥加密口令”）后，点击“确定”。并选择需要签名的软件包（软件包格式只能为.zip格式），点击“进行数字签名”。

   数字签名成功后，将会在原软件包所在目录下生成名称为 “xxx_signed.zip”的带签名软件包。

   

5. 验证软件包数字签名是否成功，在“软件包签名验证”区域导入公钥文件后，并选择步骤4中签名的软件包，点击“进行软件包验签”。

   • 验证成功则弹出“验证签名成功！”提示框。

   • 验证失败则弹出“验签异常！”提示框。

     

     在进行软件包验签时，带签名软件包的存放路径不能包含中文字符。

     

上传软件包：

1. 登录园区物联网平台控制台，点击右上角“进入园区物联网平台服务”。
2. 在对应应用的“软件库 > 公钥管理”中，上传软件包签名生成的“公钥文件（public.pem）”，上传公钥时，需选择厂商名称，该名称为上传的产品模型中定义的厂商名称。

   

3. 在“软件库 > 软件包管理”界面中，选择“添加软件包”，将已经签名的软件包进行上传。
   在上传软件包时，需要填写如下信息：

   • 软件名称：选择已经签名的软件包。
   • 版本：软件包的版本，不能带中文字符，建议与软件包的名称保持一致。
   • 设备类型：选择对应设备的产品模型。
   • 厂商名称：需要与产品模型中定义的厂商名称保持一致。
   • 型号：需要与产品模型中定义的型号保持一致。
   • 协议：需要与产品模型中定于的协议保持一致，填写CoAP、LWM2M之一，区分大小写。
   • 支持设备源版本：手动输入，如需输入多个，可以在输入完一个版本后，点击“回车”按键，再输入下一个。

单个设备软件升级

用户对单个设备进行软件升级有两种方式：

1. 应用服务器通过调用的“创建软件升级任务”API接口，创建单个设备的升级任务，详情请参考创建软件升级任务。
2. 通过控制台，创建单个设备的软件升级任务。
   

   • 设备升级前，请在“设备详情 > 命令”中，检查是否存在还在执行的命令，若存在，需要先等待所有命令执行后或是取消等待执行的命令，才可以创建设备升级任务。

   • 在设备软件升级期间，应用侧不要向设备下发其他命令消息，否则可能会导致设备升级失败。

下面将重点介绍通过控制台创建单个设备的软件升级任务。

1. 登录园区物联网平台控制台，点击右上角“进入园区物联网平台服务”。
2. 进入对应应用的“设备维护管理 > 列表设备”页面。在设备列表中选择需要升级的设备，进入“设备详情 > 软件”页面，点击当前软件版本右侧的“升级”按钮。
   

   需要在检查设备软件升级的能力中，打开软件升级支持的开关，才会在“软件”界面显示软件信息和“升级”按钮。

   

3. 在弹出的界面中，选择需要升级的软件版本对应的软件包，单击“确定”，提示创建软件升级任务成功。

   

4. 在“设备详情 > 操作记录中”，可以查看软件升级任务的状态。操作类型需要选择“软件升级”。

   

   软件升级任务的状态说明：

   • 等待：等待任务的执行，创建完升级任务后，在10秒内为该状态，10秒后变更为“运行中”。
   • 运行中：表示正在进行升级操作，包括等待设备上线、设备升级操作期间均为该状态。
   • 停止：手动停止正在“运行中”的升级任务。
   • 成功：终端设备反馈升级任务执行成功。
   • 失败：设备升级失败，如下载升级包超时、升级响应超时、设备反馈升级结果失败等原因。

批量设备软件升级

用户对批量设备进行软件升级有两种方式：

1. 应用服务器通过调用的“创建软件升级任务”API接口，创建单个设备的升级任务，详情请参考创建软件升级任务。
2. 通过控制台，创建批量设备的软件升级任务。

下面将重点介绍通过控制台创建单个设备的软件升级任务。

• 设备升级前，请在“设备详情 > 命令”中，检查是否存在还在执行的命令，若存在，需要先等待所有命令执行后或是取消等待执行的命令，才可以创建设备升级任务。

• 在设备升级期间，应用侧不要向设备下发其他命令消息，否则可能会导致设备升级失败。

1. 登录园区物联网平台控制台，点击右上角“进入园区物联网平台服务”。
2. 进入对应应用的“设备维护管理 > 列表设备”页面，在“软件升级”页面，点击“创建”按钮，创建批量软件升级任务。

   

3. 设置“任务信息”，填写执行类型、任务名称、重试策略、App确认等信息。
   • 重试策略可：如果选择了“自定义”，可以设置重试的次数和重试间隔，重试间隔表示升级的设备在升级失败后，隔多长时间进行重试。
   • APP确认：

   

4. 选择需要升级的软件包。

   

5. 选择需要升级的设备或者设备群组，然后点击“提交”。

   设备群组可以参考管理群组与标签创建需要升级的设备群组，并绑定对应的设备。

   

6. 创建完批量升级任务后，可以在任务列表中查看批量任务的执行结果。点击任务名称，可以在“执行详情”界面查看每个设备的升级结果。
   

   如果升级任务正在执行中，是不允许删除任务的，如需删除，请先在任务列表中，手动停止任务后，再删除升级任务。

   

相关API接口

• 查询版本包列表
• 查询指定版本包
• 删除指定版本包
• 创建软件升级任务
• 查询指定任务信息
• 查询指定任务的子任务详情
• 查询任务列表

PCP协议介绍

平台升级协议（PCP协议）规定了设备和平台之间升级的通信内容与格式。

本协议规定设备和IoT平台（以下简称“平台”）之间的应用层升级协议（简称“PCP协议”），用于实现设备的升级。

通讯方式

1. PCP协议运行在应用层，底层可以是LWM2M/CoAP/MQTT或者其他非流式协议。
2. 由于PCP协议消息没有使用单独的端口号，并且不依赖于底层协议，为了和设备业务消息区分，PCP协议固定以0XFFFE作为起始字节。因此要求设备的业务消息的前两个字节不能是0XFFFE。
3. 本协议消息采用一问一答模式，所有请求消息都有一个响应消息。

数据类型

本协议采用网络序来传输WORD和DWORD。

消息结构

消息码定义：

消息定义

• 查询设备版本

  方向：平台->设备

  字段	数据类型	描述及要求

  无数据区

  响应消息：

  字段	数据类型	描述及要求
  结果码	BYTE	“0X00”处理成功
  当前版本号	BYTE[16]	当前版本号，由ASCII字符组成，位数不足时，后补“0X00”。

  

  • 正常处理：平台根据版本号判断设备是否需要升级，如果需要，下发请求升级。
  • 异常处理：如果响应超时，平台中止升级任务。
• 新版本通知

  方向：平台->设备

  字段	数据类型	描述及要求
  目的版本号	BYTE[16]	目的版本号，由ASCII字符组成，位数不足时，后补“0X00”。
  升级包分片大小	WORD	每个分片的大小
  升级包分片总数	WORD	升级包分片总数
  升级包校验码	WORD	升级包校验码。用户上传升级包时，需要在升级包描述文件里填写校验码

  应答消息：

  字段	数据类型	描述及要求
  结果码	BYTE	“0X00”允许升级 “0X01”设备使用中 “0X02”信号质量差 “0X03”已经是最新版本 “0X04”电量不足 “0X05”剩余空间不足 “0X09”内存不足 “0X7F”内部异常

  

  • 正常处理：如果设备不允许升级，平台中止升级任务。
  • 异常处理：如果响应超时，而且没收到请求升级包消息，平台中止升级任务。
  • 请求升级包

    方向：设备->平台

    字段	数据类型	描述及要求
    目的版本号	BYTE[16]	目的版本号，由ASCII字符组成，位数不足时，后补“0X00”。
    分片序号	WORD	表示请求获取的分片序号，从0开始计算。设备可以保存已经收到的分片，下次直接从缺失的分片开始请求，达到断点续传的效果。

    响应消息：

    字段	数据类型	描述及要求
    结果码	BYTE	0X00处理成功。 0X80升级任务不存在。 0X81指定的分片不存在。
    分片序号	WORD	表示返回的分片序号。
    分片数据	BYTE[n]	分片的内容，n为实际的分片大小。如果错误码不为0，则不带此字段。

  • 上报升级包下载状态

    方向：设备->平台

    字段	数据类型	描述及要求
    下载状态	BYTE	0X00下载成功。 0X05剩余空间不足。 0X06下载超时。 0X07升级包校验失败。 0X08升级包类型不支持。

    响应消息：

    字段	数据类型	描述及要求
    结果码	BYTE	0X00处理成功。 0X80升级任务不存在。

  • 执行升级

    方向：平台->设备

    字段	数据类型	描述及要求

    无数据区

    响应消息：

    字段	数据类型	描述及要求
    结果码	BYTE	0X00处理成功。 0X01设备使用中。 0X04电量不足。 0X05剩余空间不足。 0X09内存不足。

    方向：设备->平台

    字段	数据类型	描述及要求
    结果码	BYTE	0X00升级成功。 0X01设备使用中。 0X04电量不足。 0X05剩余空间不足。 0X09内存不足。 0X0A安装升级包失败。 0X7F内部异常。
    当前版本号	BYTE[16]	设备当前版本号。

    响应消息：

    字段	数据类型	描述及要求
    结果码	BYTE	0X00处理成功。 0X80升级任务不存在。

    PCP协议消息的识别

    由于PCP协议消息和设备业务消息共用一个端口和URL通讯，平台收到设备的消息时，按照如下步骤判断是PCP协议消息还是业务消息：

    1. 检查设备是否支持软件升级（根据设备profile的omCapability.upgradeCapability定义），如果不支持，则认为是业务消息。
    2. 检查设备软件升级协议是否是PCP，如果不是，则认为是业务消息。
    3. 检查消息前两个字节是否为0XFFFE，如果不是，则认为是业务消息。
    4. 检查版本号是否合法，如果不合法，则认为是业务消息。
    5. 检查消息码是否合法，如果不合法，则认为是业务消息。
    6. 检查校验码是否正确，如果不正确，则认为是业务消息。
    7. 检查数据区长度是否正确，如果不正确，则认为是业务消息。
    8. 如果以上检查都通过，认为是PCP协议消息。
    

    对设备的要求：需要设备保证业务消息的起始字节不是0XFFFE。