一、描述

OTA（Over-the-Air Technology）即空中下载技术，是设备平台的一项基础功能。您可使用云鲸设备平台的OTA升级功能，对分布在全球各地的IoT设备进行OTA升级。

二、数据交互图

设备端定时版本检测

APP触发立即更新固件版本

三、通讯协议

3.1 通讯方式

3.2 Topic定义

3.3 method 枚举

四、场景示例

4.1 设备获取固件升级任务

设备自检测（定时、启动）进行检查是否有固件升级，尝试下发ota固件升级消息到

Topic:/${productId}/${deviceId}/iot/ota/up

发送到该Topic的JSON格式如下：

{
    "method": "get",
    "data": {
        "version": "v01.01.01.11"
    }
}

字段说明：

ota服务收到设备固件检测更新消息后，尝试下发ota固件升级回复消息到

Topic:/${productId}/${deviceId}/iot/ota/up/reply

1）如若有升级任务，发送到该Topic的JSON格式如下：

{
    "code": 0,
    "msg": "success",
    "method": "get",
    "result": {
        "autoUpgrade": true,
        "forceUpgrade": false,
        "ignoreBattery": false,
        "robotApkSize": 1024000,
        "robotDownloadUrl": "https://narwal-test-public-cdn.narwal.com/DX8_UP_v00.06.01.12_CN.tar.gz",
        "robotSign": "KyefoaF/fnG/Locv3X4kJMesWwz/kZ1FHsGMIZVNIDmoXEZH",
        "robotUpgradeType": 2,
        "robotVersion": "v00.06.01.12",
        "upgradeDescribe": "version describe",
        "source":1
  }
}

2）如若没有升级任务，发送到该Topic的JSON格式如下：

{
    "code": 0,
    "msg": "success",
    "method": "get",
    "result": {
        "autoUpgrade": null,
        "forceUpgrade": null,
        "ignoreBattery": null,
        "robotApkSize": null,
        "robotDownloadUrl": "",
        "robotUpgradeType": null,
        "robotVersion": null,
        "upgradeDescribe": null,
        "source":null
  }
}

字段说明：

4.2 设备上报升级状态

设备在进行固件升级时，尝试下发ota升级状态消息到

Topic:/${productId}/${deviceId}/iot/ota/up

发送到该Topic的JSON格式如下：

{
         "seqId": 157889065989,
         "method": "process",
        "data": {
              "sourceVersion": "v01.01.01.00",
              "targetVersion": "v01.01.01.11",
              "failReason": "error description",
              "errorCode": 100,
              "status": 1,
              "startTime": 1735625711，
              "endTime": 1735629311
    }
}

字段说明：

ota服务收到设备固件升级状态消息后，尝试下发ota固件升级状态回复消息到
Topic:/${productId}/${deviceId}/iot/ota/up/reply
发送到该Topic的JSON格式如下：

{
    "code": 0,
    "msg": "success",
    "result": {}
}

4.3 云端通知设备进行固件升级

ota服务在判断需要通知设备进行固件升级，将尝试下发固件升级消息到

Topic:/${productId}/${deviceId}/iot/ota/down,如 应用在线 并订阅了该Topic，则需要回复消息并进行固件升级。

发送到该Topic的JSON格式如下：

{
     "method": "upgrade"
    "data": {
        "autoUpgrade": true,
        "forceUpgrade": false,
        "ignoreBattery": false,
        "robotApkSize": 1024000,
        "robotDownloadUrl": "https://narwal-test-public-cdn.narwal.com/DX8_UP_v00.06.01.12_2024-12-26-21-25_CN.tar.gz",
        "robotSign": "KyefoaF/fnG/Locv3X4kJMeOz44AMM/hHHLGIIlFHsGMIZVNIDmoXEZH",
        "robotUpgradeType": 2,
        "robotVersion": "v00.06.01.12",,
        "upgradeDescribe": "version describe",
        "source":1
  }
}

字段说明：

设备收到固件升级消息后，将尝试回复升级固件消息到

Topic:/${productId}/${deviceId}/iot/ota/down/reply

发送到该Topic的JSON格式如下：

{
    "code": 0,
    "msg": "success",
    "result": {}
}

五、错误码枚举