文档

发起升级批次任务

更新时间:

本文介绍如何在物联网平台控制台,向设备批量推送升级包,进行OTA升级。

前提条件

  1. 如果OTA升级次数不足,需要购买有效OTA升级次数

  2. 添加升级包。如果添加升级包时,配置升级包是否需要平台验证,还需要验证升级包

操作步骤

  1. 登录物联网平台控制台

  2. 实例概览页签的全部环境下,找到对应的实例,单击实例卡片。

  3. 在左侧导航栏,选择监控运维 > OTA升级
    说明 为提供更好的服务,物联网平台改版了原OTA升级,新增了升级包版本统计功能。首次进入改版后的OTA升级页面时,您需要手动将之前上传的升级包与产品进行关联。升级包与产品一一对应,一个升级包只能关联一个产品。详情请参见控制台指引。
  4. 在升级包列表中,单击升级包对应的批量升级,完成升级范围配置,单击下一步

    升级范围

    参数

    描述

    升级方式

    可选:

    • 静态升级:对于选定的升级范围,仅升级当前满足升级条件的设备。

    • 动态升级:对于选定的升级范围,升级当前满足升级条件的设备,并且持续监测该范围内的设备。只要符合升级条件,物联网平台就会自动推送升级信息。包括但不限于以下设备:

      • 满足升级条件的后续新激活设备。

      • 当前上报的OTA模块版本号不满足升级条件,后续满足升级条件的设备。

    说明
    • 一个升级包下仅可有1个动态升级批次。若升级包下已有动态升级批次,将无法创建新的动态升级,如需创建请先取消原有动态升级批次。

    • 一个设备在一个基于待升级版本号的动态升级批次下只能匹配10次升级。超过10次后,即使后续满足动态升级匹配条件,物联网平台也不会再触发设备升级。

    升级范围

    可选:

    • 全部设备:升级该产品下满足升级条件的全部设备。

    • 定向升级:仅升级被选中的设备。

      选择为定向升级后,提供两种设备选择方式:

      • 手动勾选:从设备范围下拉列表选择要升级的设备。

        华东2(上海)、华北2(北京)、华南1(深圳)地域企业版实例中,您可以通过高级搜索搜索设备,还可下载已搜索设备的CSV格式文件。

      • 文件上传:下载模板,填写、上传CSV格式的设备列表文件。单次最多包含1,000,000条记录。

        若设备列表文件中有不合法的设备名称,将出现错误提示。请单击下载不合法列表,查看不合法的设备名称,修改设备列表文件,再重新上传。

    • 区域升级:升级实际地理位置在指定区域的设备。选择为区域升级后,下方出现指定区域的省份和城市选项框。

    • 灰度升级:即局部升级。升级方式为静态升级时出现的可选项。灰度升级的设备至少为1个。

      选择为灰度升级后,下方出现灰度范围输入框,需针对已选择的设备,设置灰度百分比。物联网平台根据设置的灰度百分进行计算,计算结果向下取整。

    • 分组升级

      • 升级方式静态升级时,分组列表展示当前实例下的所有静态分组,即所有父分组及其子分组。

      • 升级方式动态升级时,仅华东2(上海)地域下,管理实例终端节点下,显示该参数,分组列表展示当前实例下的所有动态分组。具体流程,请参见动态升级的分组升级流程

      静态设备分组和动态设备分组的创建方法,请参见设备分组

    待升级版本号

    升级后的版本号。配置说明如下:

    • 整包静态升级时,该参数为非必选配置;整包动态升级时,为必选配置。当升级范围为定向升级时,不配置该参数。

      下拉列表中,展示当前产品下所有设备的版本号(除升级目标版本号之外),选择一个或者多个待升级的版本。

      如不选择,表示对待升级设备OTA模块的当前版本不作限制。

    • 差分升级时,该参数默认为添加升级包时配置的待升级版本号。

      说明

      升级批次任务创建完成后,如果升级方式动态升级且升级批次状态为升级中,支持修改待升级版本号。

  5. 完成升级策略配置,单击完成,批量向设备推送升级通知。

    升级策略

    参数

    描述

    升级时间

    指定设备OTA升级的时间。

    • 立即升级:立即进行OTA升级。

    • 定时升级:设置升级开始时间、升级结束时间。升级开始时间距当前时间最少5分钟,最多7天。升级结束时间距开始时间最少1小时,最多为30天,可不设置,不设置表示不会强制结束。

      说明

      仅当升级方式为静态升级时,支持定时升级。

    云端主动推送升级包

    选择物联网平台是否主动向设备推送升级任务。

    • (默认):批次任务创建完成后,物联网平台主动将OTA升级任务,直接推送给升级范围内的在线设备。

      此模式下,设备仍可主动向物联网平台发起请求,来获取OTA升级任务信息。

    • :设备必须通过向物联网平台发起请求,来获取OTA升级任务信息。

    升级包推送速率

    设置每分钟向多少个设备推送升级包下载URL。可选恒定速率可变速率

    重要
    • 如果云端主动推送升级,无需设置此参数。

    • 目前仅企业版实例下支持配置可变速率

    参数说明如下:

    • 恒定速率:设置恒定推送速率,取值范围为10~10,000的整数。设置后,每分钟的推送速率始终不变。

      例如需紧急修复某个缺陷,希望尽快推送升级包给所有设备进行升级时,使用恒定推送速率比较合适(最大推送速率每分钟10,000个设备),能最快将升级包推送给待升级设备。

    • 可变速率:某种场景中期望开始推送速率小(例如每分钟1个设备),达到某种条件后推送速率不断进行增大时,可设置可变速率

      例如产品新增某个功能,希望能在升级前期慢慢推送给设备进行升级,观察设备的升级状况,之后推送速率慢慢增大,类似先灰度升级后全量升级,保障所有设备升级成功。

      可变速率中需设置以下参数:

      • 基础推送速率:指推送设备数或升级成功设备数未满足推送速率提高标准时,每分钟推送的设备数,取值范围为1~10,000的整数,且必须小于或等于最大推送速率

      • 增量因子:指推送设备数或升级成功设备数阈值满足推送速率提高标准之后,推送速率增加的因子数,取值范围为1.20~5.00,精确到两位小数。

      • 最大推送速率:每分钟推送设备数的最大值,取值范围为10~10,000的整数。当每分钟推送速率动态增大到最大推送速率后,推送速率不再发生变化,每分钟一直保持在最大推送速率。

      • 推送速率提高标准:设置推送设备数升级成功设备数阈值,取值范围为1~100,000的整数。推送设备数或升级成功设备数满足阈值后,开始根据增量因子变更推送速率。

      示例:

      • 可变速率设置:基础推送速率为50,增量因子为2,最大推送速率为10,000,推送速率提高标准中设置推送设备数为1,000。

      • 对应升级方式如下:OTA升级任务一开始以每分钟50的速率推送升级消息,并以该速率持续进行,直到给1,000 个设备推送升级消息后,每分钟推送速率会按照增量因子进行增大。

      • 具体变化趋势如下:

        1. 以每分钟50的速率推送升级消息,直到推送设备数为1,000,因为增量因子为2,所以推送速率从50提升至100;

        2. 以每分钟100的速率推送升级消息,直到推送到1000个设备后,即总推送设备数为2,000后,推送速率从100提升至200;

        3. 以每分钟200的速率推送升级消息,直到推送到1000个设备后,即总推送设备数为3,000后,推送速率从200提升至400;

        4. 以每分钟400的速率推送升级消息,直到推送到1000个设备后,即总推送设备数为4,000后,推送速率从400提升至800;

        5. 按照以上变化趋势类推,后续依次以每分钟800、1600、3200、6400的速率推送升级消息,直到总推送设备数达到8,000后,根据增量因子提升速率,此时推送速率为12,800,大于最大推送速率值10,000,因此不会以每分钟12,800的速率,而是以每分钟10,000的速率推送升级消息,且后续会一直保持以该速率推送升级消息。

    升级批次任务创建完成后,如果升级批次状态为升级中,支持修改已配置的升级包推送速率值。但不支持变更速率类型,即恒定速率可变速率不可互改。具体内容,请参见批次管理

    升级失败重试间隔

    如果升级失败,选择重试升级的时间。可选:

    • 不重试

    • 立即重试

    • 10分钟后重试

    • 30分钟后重试

    • 1小时后重试

    • 24小时后重试

    重要

    升级失败重试间隔需要小于设备升级超时时间。例如:

    • 设备升级超时时间为60分钟,升级失败重试间隔最大可设置为30分钟后重试

    • 设备升级超时时间为1440分钟,升级失败重试间隔最大可设置为1小时后重试

    升级失败重试间隔需设置为24小时后重试,建议不设置设备升级超时时间。因升级超时后,不会再触发升级重试。

    升级重试上限次数

    选择升级失败后,最多可重试几次。可选:

    • 1次

    • 2次

    • 5次

    设备升级超时时间

    设置单个设备的升级超时时间,即多长时间之后,升级未完成则为超时。可选值范围:1分钟~1,440分钟。

    说明

    从设备第一次上报升级进度开始计算升级时间。

    升级期间若设备多次上下线,触发物联网平台多次推送升级包,都始终以设备最开始的第一次上报升级进度时间作为开始时间。

    升级批次任务创建完成后,如果升级方式动态升级且升级批次状态为升级中,支持修改升级超时时间。具体操作,请参见批次管理

    设备支持多模块同时升级

    设置设备是否支持多模块同时升级。

    • :设备可同时执行多个不同模块的升级任务。

      此时,相同模块下的升级任务会被覆盖,但不覆盖升级中的任务。

    • (默认):设备不支持多模块同时升级。

    使用限制

    • 地域:华东2(上海)、华北2(北京)、华南1(深圳)、新加坡、日本(东京)

    • 支持的实例:企业版实例和新版公共实例

    • 设备端Link SDK:C语言4.x版本的Link SDK

    • 对于同一个设备,最多同时运行5个不同模块的升级任务。

    • 对于同一个产品

      • 设备支持多模块同时升级是否覆盖设备之前的升级任务不能同时选择。例如:在一个产品的一个或多个升级包下,先发起一个升级批次,选择设备支持多模块同时升级,后续又发起另一个升级批次,选择是否覆盖设备之前的升级任务。请勿使用以上场景。

      • 一个产品下相同模块的升级批次中,若设置设备支持多模块同时升级,对于同一个待升级版本号,基于该待升级版本号的动态升级和基于分组的动态升级不可混用。

    • 对于同一个动态分组

      • 发起的所有动态升级批次中,升级策略的设备支持多模块同时升级是否覆盖设备之前的升级任务设置必须保持一致。

        例如:分组对应的存量动态批次中,设备支持多模块同时升级选择,则基于该分组发起的新动态批次中设备支持多模块同时升级必须选择

      • 发起的动态升级批次中,若设备支持多模块同时升级选择,当设备上报一个模块的版本后:

        • 若同时匹配上不同的动态升级批次任务,例如有基于待升级版本号的动态升级和基于分组的动态升级,则优先匹配基于分组发起的最后一个动态升级批次。

        • 若没有基于该分组的动态升级,则优先匹配该设备下最后一次发起的动态批次。

    是否覆盖设备之前的升级任务

    如果一个设备同时处于多个升级批次中(即设备状态为待确认待推送已推送),是否按执行时间覆盖设备之前的升级任务。

    • :设备只执行新的升级任务,之前的升级任务会被取消。

    • (默认):若设备已有升级任务,则只执行已有任务。

    说明

    不覆盖升级中的任务,此时继续执行升级中的任务,不执行新的任务。

    是否仅对新上报版本的设备生效

    当升级方式选择为动态升级时的参数。可选:

    • :仅升级后续新上报版本号的设备。

    • (默认):升级当前满足升级条件的设备,并持续检查后续新上报版本号的设备是否满足升级条件。

    App确认升级

    如需自主控制设备OTA升级时,可以配置此参数,通过手机App来控制,设备是否可进行OTA升级。手机App需您自行开发。

    • :设备无法获取OTA升级任务,需App侧确认设备可进行OTA升级(即通过ConfirmOTATask接口,批量确认待确认状态的设备升级作业)后,才能按照云端主动推送升级包设置,获取OTA升级任务信息。

    • (默认):直接按照云端主动推送升级包设置,获取OTA升级任务信息。

    App确认升级的流程:

    1. 用户自行开发App,平台无法主动推送消息给设备,需要App主动查询。

    2. App侧调用ListOTAUnfinishedTaskByDevice,查询未完成状态的设备升级作业。

    3. App侧调用ConfirmOTATask,确认升级任务。

    升级包下载协议

    可选协议:HTTPSMQTT。设备端收到物联网平台推送的升级包下载信息后,通过此处设置的协议下载升级包。

    • HTTPS协议:

      • 支持单文件包下载、多文件包下载。通过HTTPS协议获取的是升级包的URL,有效期为24小时,超期后需要设备主动获取。

      • 单个文件最大为1,000 MB。如果需要更大的OTA升级包可提交工单。仅支持.bin.dav.tar.gz.zip.gzip.apk.tar.gz.tar.xz.pack格式的文件。

    • MQTT协议:

      • 支持单文件包下载、单文件包分段下载。通过MQTT协议获取的是升级包的id,长期有效。仅包含一个文件,且文件大小不超过16 MB。

      • MQTT协议下载仅支持中国的华东2(上海)、华北2(北京)和华南1(深圳)。必须使用物联网平台提供的C语言Link SDK,开发MQTT下载文件的能力。详细内容,请参见示例代码说明

    批次标签

    单击新增标签,在显示的输入框中,输入标签的标签Key标签Value

    升级批次任务创建完成后,如果升级批次状态为升级中,支持修改和新增标签。具体操作,请参见批次管理

    批次标签将在向设备推送升级通知时下发给设备。

    标签配置规则,可单击帮助图标帮助查看。

  6. 可选:升级包详情页面的批次管理列表中,找到动态升级批次,单击操作栏编辑,可在升级范围配置升级策略配置中修改待升级版本号设备升级超时时间(支持取消超时时间设置)。

    重要
    • 动态升级配置修改后:

      • 待升级版本号:若新增版本号,会对新增版本号对应的存量设备发起升级,也会对符合动态策略的新增设备发起升级;若删除版本号,对存量升级的设备无影响。

      • 设备升级超时时间:仅对新增设备的OTA动态升级生效,对存量设备的升级无影响。

    • 动态分组升级,不支持修改待升级版本号

执行结果

批量升级提交后,物联网平台根据您的设置向设备推送升级通知,您可在控制台查看目标设备的升级状态、升级包信息等,具体操作,请参见查看升级情况

动态升级的分组升级流程

使用限制

  • 仅华东2(上海)地域下,企业版实例和新版公共实例支持动态升级的分组升级。公共实例说明,请参见实例概述

  • 一个升级包只能发起一个动态升级的分组升级批次。可以使用不同升级包,对同一个待升级版本发起多个升级动态批次,但仅匹配最近的一个批次。

  • 最多可使用5个不同的升级包,对同一动态分组发起升级动态批次。其中,升级包所属产品可以相同,也可以不同。

  • 同一设备匹配到一个动态分组对应的多个升级批次时,物联网平台优先匹配最新发起的动态升级批次,下发给该设备。

    说明

    建议多个动态分组不要配置重复或相近的规则,避免设备一次行为同时加入多个动态分组,使设备无法匹配到最新发起的动态批次。

操作步骤

image
  1. 创建和使用动态分组

    • 如果动态分组通过OTA模块数据搜索设备,则ota_module.nameota_module.version必须同时使用。

    • 如果动态分组不通过OTA模块数据搜索设备,无需填写ota_module.nameota_module.version

  2. 发起OTA升级批次

    • 在物联网平台控制台对应实例下的监控运维 > OTA升级页面,找到对应升级包,进入升级包详情页面,其中目标设备总数,不会立刻与动态分组详情设备总数一致,最终会保持一致,请耐心等待。

  3. 根据分组中的设备状态,分为两种情况。

    • 发起OTA动态升级后,新增设备匹配进动态分组。仅当匹配上OTA升级条件时,新增设备才能被触发升级。例如差分包升级,当设备被加入到动态分组,但设备版本不符合差分包源版本时,不会触发OTA升级。

    • 发起OTA动态升级后,已经在动态分组中的设备。已在动态分组中的设备升级失败,接着离开动态分组,然后回到动态分组。因为设备的这次OTA升级任务状态是升级失败,所以会触发设备重新进行OTA升级。

  4. 可选:删除动态分组,不影响已存在的OTA升级任务。但是对于该动态分组,新增设备不再会被触发OTA升级。

相关API

API

描述

CreateOTAStaticUpgradeJob

创建静态升级批次。

CreateOTADynamicUpgradeJob

创建动态升级批次。

CancelOTAStrategyByJob

取消动态升级批次所关联的动态升级策略。

CancelOTATaskByDevice

取消指定升级包下状态为待升级的设备升级作业。

CancelOTATaskByJob

取消指定批次下的设备升级作业。

OTA相关API的更多信息,请参见OTA升级API

  • 本页导读 (1)
文档反馈