Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Software and Firmware Upgrade/ Device Reporting the Upgrade Status
Updated on 2024-12-02 GMT+08:00
View PDF
Share

Device Reporting the Upgrade Status

Function

This API is used by a device to report the upgrade status.

Topic

Upstream: $oc/devices/{device_id}/sys/events/up

Parameters

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

  • Mandatory when the child device reports data during the gateway device data reporting. Specify object_device_id as the child device ID of the device in the topic. Otherwise, the request fails.
  • When a directly connected device reports data, the value of object_device_id must be the same as that of device_id in the topic.
  • If this parameter is left blank, the value of this parameter is the same as that of device_id in the topic by default.

services

Optional

List<ServiceEvent>

Explanation:

List of services that an event is about.

ServiceEvent structure

Parameter

Mandatory/Optional

Type

Description

service_id

Mandatory

String

Explanation:

System field. The value is fixed to $ota.

event_type

Mandatory

String

Explanation:

System field. The value is fixed to upgrade_progress_report.

event_time

Optional

String

Explanation:

Event time. UTC time format: yyyyMMdd'T'HHmmss'Z'.

If this parameter is not carried in the reported data or is in incorrect format, the time when the platform receives the data is used.

paras

Mandatory

Object

Explanation:

Event parameters in JSON format.

paras structure

Parameter

Mandatory/Optional

Type

Description

result_code

Mandatory

Integer

Explanation:

Device upgrade status.

Value range:

Result codes definition:

  • 0: success
  • 1: device in use
  • 2: poor signal
  • 3: already the latest version
  • 4: low battery
  • 5: insufficient storage space
  • 6: download timeout
  • 7: upgrade package verification failure
  • 8: unsupported upgrade package type
  • 9: insufficient memory
  • 10: upgrade package installation failure
  • 255: internal exception

progress

Optional

Integer

Explanation:

Upgrade progress of a device.

Value range:

0 to 100.

version

Mandatory

String

Explanation:

Indicates the current version of the device. (The version reported after the upgrade must be the same as that set in IoTDA when you upload the software or firmware package.)

description

Optional

String

Explanation:

Description of the upgrade status, such as the cause for upgrade failure.

Example

Topic: $oc/devices/{device_id}/sys/events/up  
Data format:
{
    "object_device_id": "{object_device_id}",
    "services": [{
        "service_id": "$ota",
        "event_type": "upgrade_progress_report",
        "event_time": "20151212T121212Z",
        "paras": {
            "result_code": 0,
            "progress": 80,
            "version": "V2.0",
            "description": "upgrade processing"
        }
    }]
}