OTA(Over-the-Air Technology)即空中下载技术。物联网平台支持通过OTA方式进行设备升级。本文以MQTT协议下的OTA升级为例,介绍OTA升级流程、数据流转使用的Topic和数据格式。
OTA升级流程
MQTT协议下OTA升级流程如下图所示。

OTA升级说明
- 差分升级前,设备必须上报OTA模块版本。整包升级前,设备可不上报OTA模块版本。如不上报,配置批量升级时不能针对指定版本进行升级,具体说明,请参见发起升级批次任务。
如设备需要在首次升级前上报版本号,建议只在系统启动过程中上报一次,不需要周期循环上报。设备升级成功后,需要第一时间上报版本。
- 从物联网平台控制台发起批量升级后,设备升级操作记录状态是待升级。
实际升级从物联网平台OTA系统,接收到设备上报的升级进度开始。设备升级操作记录状态是升级中。
说明 设备端接收到物联网平台推送的升级通知后,可立即下载升级包进行升级,也可在业务空闲后,主动获取升级信息进行升级。 - 物联网平台根据设备端上报的版本号来判断设备端OTA升级是否成功。
- 设备离线时,不能接收服务端推送的升级消息。
通过MQTT协议接入物联网平台的设备再次上线后,物联网平台自动检测到设备上线,OTA服务端验证该设备是否需要升级。如果需要升级,物联网平台再次推送升级消息给设备,否则不推送消息。
数据格式说明
设备端OTA开发流程和代码示例,请参见Link SDK文档中,各语言SDK文档的设备OTA开发章节。
OTA升级流程及使用的Topic和数据格式如下:
- (可选)设备连接OTA服务,上报版本号。
设备端通过MQTT协议推送当前设备OTA模块版本号到Topic:
/ota/device/inform/${YourProductKey}/${YourDeviceName}
。消息格式如下:{ "id": "123", "params": { "version": "1.0.1", "module": "MCU" } }
表 1. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 version String OTA模块版本。 module String OTA模块名。 说明- 上报默认(default)模块的版本号时,可以不上报module参数。
- 设备的默认(default)模块的版本号代表整个设备的固件版本号。
- 在物联网平台控制台上,添加升级包、验证升级包并发起批量升级任务。
具体操作,请参见推送升级包到设备端。
- 您在控制台触发升级操作之后,设备会收到物联网平台OTA服务推送的升级包的URL地址。
设备端订阅Topic:
/ota/device/upgrade/${YourProductKey}/${YourDeviceName}
。物联网平台对设备发起OTA升级请求后,设备端会通过该Topic收到升级包的存储地址URL。消息格式如下:
{ "code": "1000", "data": { "size": 432945, "version": "2.0.0", "isDiff": 1, "url": "https://iotx-ota-pre.oss-cn-shanghai.aliyuncs.com/nopoll_0.4.4.tar.gz?Expires=1502955804&OSSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Signature=XfgJu7P6DWWejstKJgXJEH0qAKU%3D&security-token=CAISuQJ1q6Ft5B2yfSjIpK6MGsyN1Jx5jo6mVnfBglIPTvlvt5D50Tz2IHtIf3NpAusdsv03nWxT7v4flqFyTINVAEvYZJOPKGrGR0DzDbDasumZsJbo4f%2FMQBqEaXPS2MvVfJ%2BzLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B%2Fr6%2F5gdc9FcQSkL0B8ZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO1wEP4K%2BkkMqH8Uic3h%2Boy%2BgJt8H2PpHhd9NhXuV2WMzn2%2FdtJOiTknxR7ARasaBqhelc4zqA%2FPPlWgAKvkXba7aIoo01fV4jN5JXQfAU8KLO8tRjofHWmojNzBJAAPpYSSy3Rvr7m5efQrrybY1lLO6iZy%2BVio2VSZDxshI5Z3McKARWct06MWV9ABA2TTXXOi40BOxuq%2B3JGoABXC54TOlo7%2F1wTLTsCUqzzeIiXVOK8CfNOkfTucMGHkeYeCdFkm%2FkADhXAnrnGf5a4FbmKMQph2cKsr8y8UfWLC6IzvJsClXTnbJBMeuWIqo5zIynS1pm7gf%2F9N3hVc6%2BEeIk0xfl2tycsUpbL2FoaGk6BAF8hWSWYUXsv59d5Uk%3D", "md5": "93230c3bde425a9d7984a594ac55ea1e", "sign": "93230c3bde425a9d7984a594ac55****", "signMethod": "MD5", "module": "MCU", "extData":{ "key1":"value1", "key2":"value2" } }, "id": "1507707025", "message": "success" }
表 2. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 message String 结果信息。 code String 状态码。 version String 设备升级包的版本信息。 size Long 升级包大小,单位:字节。 url String 升级包在对象存储(OSS)上的存储地址。 isDiff Long 仅当升级包类型为差分时,消息包含此参数。 取值为1,表示仅包含新版本升级包与之前版本的差异部分,需要设备进行差分还原。
sign String 升级包签名。 signMethod String 签名方法。取值: - SHA256
- MD5
md5 String 当签名方法为MD5时,除了会给sign赋值外还会给md5赋值。 module String 升级包所属的模块名。 说明 模块名为default时,物联网平台不下发module参数。extData Object 升级批次标签列表。 单个标签格式:
"key":"value"
。 - (可选)设备端SDK接收到物联网平台推送的升级包URL后,若未在24小时内完成升级包下载,该URL失效。设备端可通过调用以下topic,重新向物联网平台主动请求获取升级任务。
设备端发起请求的Topic为
/sys/{productKey}/{deviceName}/thing/ota/firmware/get
,消息格式如下。{ "id": "123", "version": "1.0", "params": { "module": "MCU" }, "method": "thing.ota.firmware.get" }
表 3. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 version String Alink协议版本,目前协议版本号唯一取值为1.0。 params String 请求参数。 module String 升级包所属的模块名。 说明 不指定则表示请求默认(default)模块的升级包信息。method String 请求方法,取值thing.ota.firmware.get。 物联网平台收到请求后,通过响应Topic:
/sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply
,向设备端返回升级包信息。- 下发升级包信息。返回数据格式如下:
{ "id": "123", "code": 200, "data": { "size": 93796291, "sign": "f8d85b250d4d787a9f483d89a974****", "version": "1.0.1.9.20171112.1432", "isDiff": 1, "url": "https://the_firmware_url", "signMethod": "MD5", "md5": "f8d85b250d4d787a9f483d89a9747348", "module": "MCU", "extData":{ "key1":"value1", "key2":"value2" } } }
表 4. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 code Integer 状态码,200表示成功。 version String 设备升级包的版本信息。 isDiff Long 仅当升级包类型为差分时,消息包含此参数。 取值为1,表示仅包含新版本升级包与之前版本的差异部分,需要设备进行差分还原。
size Long 升级包大小,单位:字节。 url String 升级包在对象存储(OSS)上的存储地址。 sign String 升级包签名。 signMethod String 签名方法。取值: - SHA256
- MD5
md5 String 当签名方法为MD5时,除了会给sign赋值外还会给md5赋值。 module String 升级包所属的模块名。 说明 模块名为default时,物联网平台不下发module参数。extData Object 升级批次标签列表。 单个标签格式:
"key":"value"
。 - 无升级包信息下发。返回数据格式如下:
{ "id": "123", "code": 200, "data": { } }
- 下发升级包信息。返回数据格式如下:
- 设备端SDK收到物联网平台推送的升级包URL后,调用SDK提供的接口,通过HTTPS协议下载升级包。具体操作,请参见设备OTA。
说明 设备端无法自动下载升级包,可通过调用SDK中接口进行下载。下载须在升级包URL下发后的24小时内完成,否则该URL失效。
- 升级过程中,设备端向服务端推送升级进度到Topic:
/ota/device/progress/${YourProductKey}/${YourDeviceName}
。消息格式如下:{ "id": "123", "params": { "step": "-1", "desc": "OTA升级失败,请求不到升级包信息。", "module": "MCU" } }
表 5. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。 step String OTA升级进度信息。
取值范围:- 1~100的整数:升级进度百分比。
- -1:升级失败。
- -2:下载失败。
- -3:校验失败。
- -4:烧写失败。
desc String 当前步骤的描述信息,长度不超过128个字符。如果发生异常,此字段可承载错误信息。 module String 升级包所属的模块名。 说明 上报默认(default)模块的OTA升级进度时,可以不上报module参数。 - 设备端完成OTA升级后,推送最新的版本信息到Topic:
/ota/device/inform/${YourProductKey}/${YourDeviceName}
。如果上报的版本与OTA服务要求的版本一致就认为升级成功,反之失败。说明 升级成功的唯一判断标志是设备上报正确的版本号。即使升级进度上报为100%,如果不上报新的版本号,会因超时导致升级失败。设备升级完成时,建议立即重启设备,设备上线后,立即上报新的版本号。设备上线请求和上报版本请求间隔不能超过2秒。
常见下载升级包错误
- 签名错误。如果设备端获取的升级包的URL不全或者手动修改了URL内容,就会出现如下错误:
- 拒绝访问。URL过期导致。目前,URL有效期为24小时。