Platform Delivering an Upgrade Event

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 or Optional	Type	Description
object_device_id	Optional	String	Indicates the device that the event is about. If this parameter is not carried, the device specified in the topic is considered to be the device involved.
services	Optional	List<ServiceEvent>	Indicates a list of services that the event is about.

ServiceEvent structure

Parameter	Mandatory or Optional	Type	Description
service_id	Mandatory	String	System field. The value is fixed to $ota.
event_type	Mandatory	String	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	Indicates the time when the event occurs.
paras	Mandatory	Object	Indicates the event parameters in JSON format.

Parameters when event_type is set to firmware_upgrade or software_upgrade

Parameter	Mandatory or Optional	Type	Description
version	Mandatory	String	Indicates the software or firmware package version.
url	Mandatory	String	Indicates the address for downloading the software or firmware package.
file_size	Mandatory	Integer	Indicates the software or firmware package size.
access_token	Optional	String	Indicates the temporary token of the URL for downloading the software or firmware package.
expires	Optional	Integer	Indicates the time when the token expires.
sign	Mandatory	String	Indicates the SHA-256 value of the software or firmware package.
custom_info	Optional	String	Indicates the custom information pushed to a device.

Parameters when event_type is set to firmware_upgrade_v2 or software_upgrade_v2

Parameter	Mandatory or Optional	Type	Description
version	Mandatory	String	Indicates the software or firmware package version.
url	Mandatory	String	Indicates the software or firmware package download address (OBS address)
expires	Optional	Integer	Indicates the time when the URL expires.
custom_info	Optional	String	Indicates the custom information pushed to a device.

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://10.1.1.1:8943/iodm/inner/v1.3.0/firmwarefiles/ca1d954771ae61e5098c7f83",
            "file_size": 81362928,
            "access_token": "595124473f866b033dfa1f",
            "expires": 86400,
            "sign": "595124473f866b033dfa1f7e831c8c99a12f6143f392dfa996a819010842c99d",
            "custom_info":"This upgrade package adds some new features."
        }
    }]
}

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*********",
            "expires": 3600,
            "custom_info":"This upgrade package adds some new features."
        }
    }]
}

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	Media type of the message body. The default value is application/json.
Authorization	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://10.1.1.1:8943/iodm/inner/v1.3.0/firmwarefiles/ca1d954771ae61e5098c7f83
Content-Type: application/json 
Authorization: Bearer ******

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