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*********
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot