On this page

Show all

Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Software and Firmware Upgrade/ Platform Delivering an Upgrade Event

Platform Delivering an Upgrade Event

Updated on 2024-12-02 GMT+08:00

View PDF

Function

This API is used by IoTDA to deliver an upgrade notification to a device.

Topic

Downstream: $oc/devices/{device_id}/sys/events/down

Parameters

Parameter	Mandatory/Optional	Type	Description
object_device_id	Optional	String	Explanation: For gateway child device: The value is the child device ID in the topic. For directly connected device: The value is the same that of device_id in the topic.
services	Optional	List<ServiceEvent>	Explanation: List of services that an event is about.

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

For gateway child device: The value is the child device ID in the topic.
For directly connected device: The value is the same that of device_id in the topic.

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: If the software or firmware is stored in IoTDA, the values of event_type are as follows: firmware_upgrade: firmware upgrade. software_upgrade: software upgrade. If the software or firmware is stored in OBS, the values of event_type are as follows: firmware_upgrade_v2: firmware upgrade. software_upgrade_v2: software upgrade.
event_time	Optional	String	Explanation: Event time. UTC time format: yyyyMMdd'T'HHmmss'Z'.
paras	Mandatory	Object	Explanation: Event parameters in JSON format.

Parameters when event_type is set to firmware_upgrade or software_upgrade

Parameter	Mandatory/Optional	Type	Description
version	Mandatory	String	Explanation: Software or firmware package version.
url	Mandatory	String	Explanation: Address for downloading the software or firmware package.
file_size	Mandatory	Integer	Explanation: Software or firmware package size.
file_name	Mandatory	String	Explanation: Name of an upgrade package file.
access_token	Optional	String	Explanation: Temporary token of the URL for downloading the software or firmware package.
expires	Optional	Integer	Explanation: Time when the access_token expires.
sign	Mandatory	String	Explanation: SHA-256 value of the software or firmware package.
custom_info	Optional	String	Explanation: Customized information pushed to devices.
task_id	Optional	String	Explanation: ID of a batch software/firmware upgrade task in gateway mode.
sub_device_count	Optional	Integer	Explanation: Number of child devices to be upgraded in a batch software/firmware upgrade task in gateway mode.
task_ext_info	Optional	Object	Explanation: Extended information added during software/firmware upgrade task creation.

Parameters when event_type is set to firmware_upgrade_v2 or software_upgrade_v2

Parameter	Mandatory/Optional	Type	Description
version	Mandatory	String	Explanation: Software or firmware package version.
url	Mandatory	String	Explanation: Software or firmware package download address (OBS address).
file_size	Mandatory	Integer	Explanation: Software or firmware package size.
file_name	Mandatory	String	Explanation: Name of an upgrade package file.
expires	Optional	Integer	Explanation: Time when the URL expires.
sign	Optional	String	Explanation: Upgrade package signature entered when the OBS upgrade package is uploaded. The signature is calculated using the SHA-256 algorithm.
custom_info	Optional	String	Explanation: Customized information pushed to devices.
task_id	Optional	String	Explanation: ID of a batch software/firmware upgrade task in gateway mode.
sub_device_count	Optional	Integer	Explanation: Number of child devices to be upgraded in a batch software/firmware upgrade task in gateway mode.
task_ext_info	Optional	Object	Explanation: Extended information added during software/firmware upgrade task creation.

Example 1

If the software or firmware is stored in IoTDA. During the upgrade, the device receives the following information:
Topic: $oc/devices/{device_id}/sys/events/down  
Data format:
{
    "object_device_id": "{object_device_id}",
    "services": [
        {
            "service_id": "$ota",
            "event_type": "firmware_upgrade",
            "event_time": "20151212T121212Z",
            "paras": {
                "version": "v1.2",
                "url": "https://100.93.28.202:8943/iodm/dev/v2.0/upgradefile/applications/******/devices/******/packages/******",
                "file_size": 81362928,
                "file_name": "upgrade.bin",
                "access_token": "595124473f866b033dfa1f",
                "expires": 86400,
                "sign": "595124473f866b033dfa1f7e831c8c99a12f6143f392dfa996a819010842c99d",
                "custom_info": "This upgrade package adds some new features.",
                "task_id": "65d31bf2581ed33a42a58d76",
                "sub_device_count": 2,
                "task_ext_info": {
                    "device_type": "DDC"
                }
            }
        }
    ]
}

Example 2

If the software or firmware is stored in OBS. During the upgrade, the device receives the following information:
Topic: $oc/devices/{device_id}/sys/events/down  
Data format:
{
    "object_device_id": "{object_device_id}",
    "services": [
        {
            "service_id": "$ota",
            "event_type": "firmware_upgrade_v2",
            "event_time": "20151212T121212Z",
            "paras": {
                "version": "v1.2",
                "url": "https://******.obs.cn-north-4.myhuaweicloud.com:443/test.bin?AccessKeyId=DX5G7W*********",
                "file_size": 81362928,
                "file_name": "upgrade.bin",
                "expires": 3600,
                "sign": "595124473f866b033dfa1f7e831c8c99a12f6143f392dfa996a819010842c99d",
                "custom_info": "This upgrade package adds some new features.",
                "task_id": "65d31bf2581ed33a42a58d76",
                "sub_device_count": 2,
                "task_ext_info": {
                    "device_type": "DDC"
                }
            }
        }
    ]
}

Downloading an Upgrade Package

After a device receives an upgrade notification, the device downloads the upgrade package based on the URL in the notification through HTTPS. For basic and standard editions, you are advised not to verify certificates to prevent download failures. If the exclusive edition requires certification verification, submit a service ticket for the back end personnel to configure the domain name.

Request Method

The request method for downloading the upgrade package is GET.

Request Header

You can add header fields, for example, fields required by a specific URI or HTTP method, to the request header. For example, to request authentication information, add Content-Type, which specifies the request body type.

Parameter	Description
Content-Type	Explanation: Media type of the message body. The default value is application/json.
Authorization	Explanation: Authentication information for accessing IoTDA. The value is Bearer {access_token}, in which {access_token} is the value of access_token in the received upgrade notification.

Parameter

Description

Content-Type

Explanation:

Media type of the message body. The default value is application/json.

Authorization

Explanation:

Authentication information for accessing IoTDA. The value is Bearer {access_token}, in which {access_token} is the value of access_token in the received upgrade notification.

Example

GET https://100.93.28.202:8943/iodm/dev/v2.0/upgradefile/applications/******/devices/******/packages/******
Content-Type: application/json 
Authorization: Bearer ******

CAUTION:

If event_type is set to firmware_upgrade_v2 or software_upgrade_v2, the request header does not need to be carried in the request for downloading the software or firmware package. An example request is as follows:

GET https://******.obs.cn-north-4.myhuaweicloud.com:443/test.bin?AccessKeyId=DX5G7W*********

Parent topic: Software and Firmware Upgrade

Previous topic: Device Reporting the Software and Firmware Versions

Next topic: Device Reporting the Upgrade Status

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot