联犀开发者文档

OTA升级

约 1017 字大约 3 分钟

2025-03-03

升级步骤

  1. 管理员在控制台创建升级包：如果是主动推送，则会根据设定的规则主动推送给设备；如果是被动升级，设备通过物模型协议中的设备基础信息上报后符合升级规则就会下发升级包
  2. 用户确认：如果是需要C端用户确认的，则用户确认后升级包才会生效
  3. 升级完成：云端推送升级包后，设备升级中可以上报升级的进度，升级完成后上报新的版本（需要与固件版本一致），则升级完成

注意：设备上报固件版本需要参考：物模型协议-设备基础信息上报

参数说明

  • {productID}：产品ID。
  • {deviceName}：设备ID。
  • 通用请求参数
参数类型必填说明
msgTokenString是用于上下行消息配对标识
sys.noAskbool否云端是否回复设备
sys.retMsgbool否是否返回错误信息,字段为msg
示例:
{
  "method": "reportInfo",
  "msgToken": "1234567",
  "sys": {
    "noAsk": false,
    "retMsg": true
  }
}

固件升级推送

  1. 云端推送升级包：云端会主动或在设备上报版本号后推送升级包给设备，平台为设备行为的处理设定了默认的 Topic：

    • 设备订阅云端Topic获取云端推送的升级包信息： $ota/down/upgrade/{ProductID}/{DeviceName}

  2. 请求示例

    单文件升级：

    {
  "msgToken": "123",
  "method": "upgrade",
  "timestamp": 1677762028638,
  "data": {
    "size": 93796291,
    "signature": "f8d85b250d4d787a9f483d89a974***",
    "version": "10.0.1.9.20171112.1432",
    "isDiff": 1,
    "name": "xxx.bin",
    "fileUrl": "https://the_firmware_url",
    "signMethod": "MD5",
    "fileMd5": "f8d85b250d4d787a9f48***",
    "extData": ""
  }
}

    多文件升级：

    {
  "msgToken": "123",
  "method": "upgrade",
  "timestamp": 1677762028638,
  "data": {
    "signature": "f8d85b250d4d787a9f483d89a974***",
    "version": "10.0.1.9.20171112.1432",
    "isDiff": 1,
    "extData": "",
    "files": [
      {
        "size": 93796291,
        "signature": "f8d85b250d4d787a9f483d89a974***",
        "version": "10.0.1.9.20171112.1432",
        "isDiff": 1,
        "name": "xxx.bin",
        "fileUrl": "https://the_firmware_url",
        "signMethod": "MD5",
        "fileMd5": "f8d85b250d4d787a9f48***"
      }
    ]
  }
}

  3. 请求参数说明

参数类型说明
methodStringaction 表示是调用设备的某个行为
msgTokenString消息Id，回复的消息将会返回该数据，用于请求响应消息的对比
timestampInteger行为调用的当前时间，不填写则默认为调用行为的当前系统时间，单位为毫秒
data.versionString固件版本
data.isDiffInteger是否是差分升级（1:是，2:否）
data.signMethodString签名方式，只支持MD5
data.extraString额外自定义信息
data.sizeInteger固件大小
data.nameString固件名
data.fileUrlString固件下载URL
data.fileMd5String固件MD5
data.signatureString固件签名（MD5）

注意：如果设备收到的 fileUrl 是 localhost 地址（如 http://localhost:7777/oss/...）或相对路径，说明 OssCustomHost 环境变量未正确配置，设备将无法下载固件。请按以下步骤修改：

  1. 打开 Docker Compose 配置目录下的 .env 文件（路径：deploy/docker/run-all/.env）
  2. 找到 OssCustomHost 配置项，将 localhost 替换为服务器的外网 IP 或域名：
    # 修改前
OssCustomHost=http://localhost:7777/oss
# 修改后（替换为实际的外网IP或域名）
OssCustomHost=http://your-server-ip:7777/oss
  3. 修改后重启服务即可生效。也可以直接修改系统环境变量，效果相同。

设备上报升级进度

  1. 上报Topic：OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比：

    • 上报 Topic： $ota/up/progress/{ProductID}/{DeviceName}

  2. 请求示例

    远程控制请求消息格式：

    {
  "msgToken": "123",
  "params": {
    "step": -1,
    "desc": "OTA升级失败，请求不到升级包信息。",
    "module": "MCU"
  }
}

  3. 请求参数说明

参数类型是否必填说明
msgTokenString否用于上下行消息配对标识
timestampInteger否上报的时间，格式为UNIX系统时间戳，不填写该字段表示默认为当前系统时间，单位为毫秒
params.stepInteger是OTA升级进度
取值范围：
1~100的整数：升级进度百分比
-1：升级失败
-2：下载失败
-3：校验失败
-4：烧写失败
params.descString否当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息
params.moduleString否升级包所属的模块名

更新日志

2026/8/4 07:04
查看所有更新日志
  • 7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于
  • 74397-docs: 更新OTA升级文档添加OssCustomHost环境变量说明，更新数据权限和http协议接入文档于
  • bddea-docs: 更新文档结构、添加新内容并优化现有文档于
  • 2804a-doc于
  • 92119-doc于
  • 706e5-doc于
  • 6fa0c-doc于
  • 51ff0-doc于
  • 80b39-doc于
  • d4fa0-doc: 更换皮肤到最新版于
  • 82830-doc于
  • f4a75-doc: 完善文档于
  • 4066c-doc: 完善文档于
  • d999f-初始化于
  • 7c298-初始化于
  • 8794f-feat: 完善项目`于
  • df9b4-初始化于