Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

Loading...
Searching...
No Matches
Firmware.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2009 Raritan Inc. All rights reserved.
4 */
5
6#include <UserEvent.idl>
7#include <Event.idl>
8
9/**
10 * %Firmware Management
11 */
12module firmware {
13
14 /**
15 * %Firmware update history status
16 */
17 enumeration UpdateHistoryStatus {
18 SUCCESSFUL, ///< The update was successfully completed
19 FAILED, ///< The update failed
20 INCOMPLETE ///< The update was not completed
21 };
22
23 /**
24 * %Firmware update history entry
25 * TODO: implement CR# 45668 on next interface change
26 * add comment field based on firmware tag "char tag[64];"
27 * to improve firmware update history entries without rootfs images
28 */
29 structure UpdateHistoryEntry {
30 time timestamp; ///< UNIX timestamp (UTC) when the update was started
31 string oldVersion; ///< Previous firmware version
32 string imageVersion; ///< Firmware version of update image
33 string imageMD5; ///< MD5 hash of update image
34 UpdateHistoryStatus status; ///< Update status
35 };
36
37 /**
38 * Image upload/download state
39 */
40 enumeration ImageState {
41 NONE, ///< No firmware image has been uploaded/downloaded
42 UPLOADING, ///< A firmware image is currently being uploaded
43 UPLOAD_FAILED, ///< There was a problem uploading an image to the device
44 DOWNLOADING, ///< The device is downloading a firmware image from a URL
45 DOWNLOAD_FAILED, ///< There was a problem downloading the image from a URL
46 COMPLETE ///< A complete image has been successfully uploaded/downloaded
47 };
48
49 /**
50 * Image upload/download status
51 */
52 structure ImageStatus {
53 ImageState state; ///< Image upload/download state
54 string error_message; ///< Error message; empty if there was no error
55 time time_started; ///< UNIX timestamp (UTC) of the last state change (if available)
56 int size_total; ///< Total size of the image (if available)
57 int size_done; ///< Progress of the running upload or download (if available)
58 };
59
60 /**
61 * %Firmware image information
62 */
63 structure ImageInfo {
64 boolean valid; ///< The file is a valid firmware image
65
66 string version; ///< %Firmware image version
67 string min_required_version; ///< Minimum running firmware version for image
68 string min_downgrade_version; ///< Minimum image version for running firmware
69
70 string product; ///< Product name
71 string platform; ///< Platform name
72 string oem; ///< OEM name
73 string hwid_whitelist; ///< Hardware ID whitelist
74 string hwid_blacklist; ///< Hardware ID blacklist
75
76 boolean compatible; ///< \c true if the image is compatible with this device
77
78 boolean signature_present; ///< \c true if the image is signed
79 string signed_by; ///< Signature issuer
80 boolean signature_good; ///< \c true if the signature is valid
81 string certified_by; ///< Key certificate issuer
82 boolean certificate_good; ///< \c true if the key certificate is valid
83
84 boolean model_list_present; ///< \c true if the image includes a supported models list
85 boolean model_supported; ///< \c true if the model is found on the support list
86 };
87
88 /**
89 * Flags for startUpdate() method
90 */
91 enumeration UpdateFlags {
92 CROSS_OEM, ///< Ignore version, product and OEM constraints
93 CROSS_HW, ///< Ignore hardware constraints
94 ALLOW_UNTRUSTED ///< Allow untrusted firmwares (ignored when secure boot is active)
95 };
96
97 /** Event: System startup finished */
98 valueobject SystemStartupEvent extends idl.Event {};
99 /** Event: System shutdown started */
100 valueobject SystemShutdownEvent extends event.UserEvent {
101 boolean resettingToFactoryDefaults;
102 };
103
104 /** Event: Firmware validation failed */
105 valueobject FirmwareValidationFailedEvent extends event.UserEvent {};
106
107 /** Event: Firmware update base event */
108 valueobject FirmwareUpdateEvent extends event.UserEvent {
109 string oldVersion; ///< Firmware version the device is being upgraded from
110 string newVersion; ///< Firmware version the device is being upgraded to
111 };
112
113 /** Event: Firmware update started */
114 valueobject FirmwareUpdateStartedEvent extends FirmwareUpdateEvent {};
115 /** Event: Firmware updated successfully */
116 valueobject FirmwareUpdateCompletedEvent extends FirmwareUpdateEvent {};
117 /** Event: Firmware update failed */
118 valueobject FirmwareUpdateFailedEvent extends FirmwareUpdateEvent {};
119
120 /**
121 * %Firmware management methods
122 */
123 interface Firmware {
124
125 /** %Firmware information */
126 structure Info {
127 string product; ///< %Firmware product type
128 string platform; ///< Hardware platform
129 string version; ///< %Firmware version number
130 };
131
132 /**
133 * Retrieve the firmware information.
134 *
135 * @return %Firmware information
136 */
137 Info getInfo();
138
139 /**
140 * Reboot the device.
141 *
142 * This function will fail if a firmware update is in progress.
143 */
144 void reboot();
145
146 /**
147 * Reset the device configuration to factory defaults.
148 */
149 void factoryReset();
150
151 /**
152 * Reset all device data to factory defaults. This includes energy
153 * counters, firmware update history and reliability data.
154 *
155 * @note This command is only available during manufacturing!
156 *
157 * @return 0 if OK
158 * @return 1 if not in production mode
159 */
160 int hardFactoryReset();
161
162 /**
163 * Semi-hard factory reset for manufacturing.
164 *
165 * This command clears both the user and system configuration layer,
166 * but keeps the ETO cache and subcontroller security association.
167 *
168 * @note This command is only available during manufacturing!
169 *
170 * @return 0 if OK
171 * @return 1 if not in production mode
172 */
173 int manufacturingReset();
174
175 /**
176 * Returns the currently installed firmware version.
177 *
178 * @return %Firmware version
179 */
180 string getVersion();
181
182 /**
183 * Fetch the firmware update history.
184 *
185 * @return Vector of firmware update history entries
186 */
187 vector<UpdateHistoryEntry> getUpdateHistory();
188
189 /**
190 * Get the current firmware image upload/download status.
191 *
192 * @return Image status structure.
193 */
194 ImageStatus getImageStatus();
195
196 /**
197 * Discard the currently uploaded firmware image, cancel the update.
198 */
199 void discardImage();
200
201 /**
202 * Return information about a currently uploaded firmware image.
203 *
204 * @param info %Firmware image information
205 *
206 * @return \c true if a firmware image is uploaded, \c false otherwise.
207 */
208 boolean getImageInfo(out ImageInfo info);
209
210 /**
211 * Launch the firmware update process. The device will stop handling
212 * RPC requests shortly after this method has been successfully called.
213 * The client should poll the fwupdate_progress.cgi page to monitor the
214 * update progress.
215 *
216 * @param flags List of firmware update flags; may be empty
217 */
218 void startUpdate(in vector<UpdateFlags> flags);
219 };
220
221}
firmware::Firmware
Firmware management methods
Definition Firmware.idl:123
firmware::Firmware::getInfo
Info getInfo()
Retrieve the firmware information.
firmware::Firmware::getVersion
string getVersion()
Returns the currently installed firmware version.
firmware::Firmware::getImageStatus
ImageStatus getImageStatus()
Get the current firmware image upload/download status.
firmware::Firmware::factoryReset
void factoryReset()
Reset the device configuration to factory defaults.
firmware::Firmware::startUpdate
void startUpdate(in vector< UpdateFlags > flags)
Launch the firmware update process.
firmware::Firmware::manufacturingReset
int manufacturingReset()
Semi-hard factory reset for manufacturing.
firmware::Firmware::discardImage
void discardImage()
Discard the currently uploaded firmware image, cancel the update.
firmware::Firmware::hardFactoryReset
int hardFactoryReset()
Reset all device data to factory defaults.
firmware::Firmware::reboot
void reboot()
Reboot the device.
firmware::Firmware::getUpdateHistory
vector< UpdateHistoryEntry > getUpdateHistory()
Fetch the firmware update history.
firmware::Firmware::getImageInfo
boolean getImageInfo(out ImageInfo info)
Return information about a currently uploaded firmware image.
firmware
Firmware Management
Definition CimFirmwareUpdateStatus.idl:5
firmware::UpdateFlags
UpdateFlags
Flags for startUpdate() method.
Definition Firmware.idl:91
firmware::CROSS_OEM
@ CROSS_OEM
Ignore version, product and OEM constraints.
Definition Firmware.idl:92
firmware::ALLOW_UNTRUSTED
@ ALLOW_UNTRUSTED
Allow untrusted firmwares (ignored when secure boot is active)
Definition Firmware.idl:94
firmware::CROSS_HW
@ CROSS_HW
Ignore hardware constraints.
Definition Firmware.idl:93
firmware::UpdateHistoryStatus
UpdateHistoryStatus
Firmware update history status
Definition Firmware.idl:17
firmware::FAILED
@ FAILED
The update failed.
Definition Firmware.idl:19
firmware::INCOMPLETE
@ INCOMPLETE
The update was not completed.
Definition Firmware.idl:20
firmware::SUCCESSFUL
@ SUCCESSFUL
The update was successfully completed.
Definition Firmware.idl:18
firmware::ImageState
ImageState
Image upload/download state.
Definition Firmware.idl:40
firmware::UPLOADING
@ UPLOADING
A firmware image is currently being uploaded.
Definition Firmware.idl:42
firmware::COMPLETE
@ COMPLETE
A complete image has been successfully uploaded/downloaded.
Definition Firmware.idl:46
firmware::UPLOAD_FAILED
@ UPLOAD_FAILED
There was a problem uploading an image to the device.
Definition Firmware.idl:43
firmware::DOWNLOADING
@ DOWNLOADING
The device is downloading a firmware image from a URL.
Definition Firmware.idl:44
firmware::DOWNLOAD_FAILED
@ DOWNLOAD_FAILED
There was a problem downloading the image from a URL.
Definition Firmware.idl:45
firmware::NONE
@ NONE
No firmware image has been uploaded/downloaded.
Definition Firmware.idl:41
idl
Basic IDL definitions.
Definition Event.idl:10
firmware::FirmwareUpdateCompletedEvent
Event: Firmware updated successfully.
Definition Firmware.idl:116
firmware::FirmwareUpdateEvent
Event: Firmware update base event.
Definition Firmware.idl:108
firmware::FirmwareUpdateEvent::newVersion
string newVersion
Firmware version the device is being upgraded to.
Definition Firmware.idl:110
firmware::FirmwareUpdateEvent::oldVersion
string oldVersion
Firmware version the device is being upgraded from.
Definition Firmware.idl:109
firmware::FirmwareUpdateFailedEvent
Event: Firmware update failed.
Definition Firmware.idl:118
firmware::FirmwareUpdateStartedEvent
Event: Firmware update started.
Definition Firmware.idl:114
firmware::FirmwareValidationFailedEvent
Event: Firmware validation failed.
Definition Firmware.idl:105
firmware::Firmware::Info
Firmware information
Definition Firmware.idl:126
firmware::Firmware::Info::version
string version
Firmware version number
Definition Firmware.idl:129
firmware::Firmware::Info::product
string product
Firmware product type
Definition Firmware.idl:127
firmware::Firmware::Info::platform
string platform
Hardware platform.
Definition Firmware.idl:128
firmware::ImageInfo
Firmware image information
Definition Firmware.idl:63
firmware::ImageInfo::signature_present
boolean signature_present
true if the image is signed
Definition Firmware.idl:78
firmware::ImageInfo::hwid_blacklist
string hwid_blacklist
Hardware ID blacklist.
Definition Firmware.idl:74
firmware::ImageInfo::version
string version
Firmware image version
Definition Firmware.idl:66
firmware::ImageInfo::model_list_present
boolean model_list_present
true if the image includes a supported models list
Definition Firmware.idl:84
firmware::ImageInfo::min_downgrade_version
string min_downgrade_version
Minimum image version for running firmware.
Definition Firmware.idl:68
firmware::ImageInfo::signature_good
boolean signature_good
true if the signature is valid
Definition Firmware.idl:80
firmware::ImageInfo::oem
string oem
OEM name.
Definition Firmware.idl:72
firmware::ImageInfo::hwid_whitelist
string hwid_whitelist
Hardware ID whitelist.
Definition Firmware.idl:73
firmware::ImageInfo::signed_by
string signed_by
Signature issuer.
Definition Firmware.idl:79
firmware::ImageInfo::model_supported
boolean model_supported
true if the model is found on the support list
Definition Firmware.idl:85
firmware::ImageInfo::compatible
boolean compatible
true if the image is compatible with this device
Definition Firmware.idl:76
firmware::ImageInfo::product
string product
Product name.
Definition Firmware.idl:70
firmware::ImageInfo::certificate_good
boolean certificate_good
true if the key certificate is valid
Definition Firmware.idl:82
firmware::ImageInfo::platform
string platform
Platform name.
Definition Firmware.idl:71
firmware::ImageInfo::certified_by
string certified_by
Key certificate issuer.
Definition Firmware.idl:81
firmware::ImageInfo::valid
boolean valid
The file is a valid firmware image.
Definition Firmware.idl:64
firmware::ImageInfo::min_required_version
string min_required_version
Minimum running firmware version for image.
Definition Firmware.idl:67
firmware::ImageStatus
Image upload/download status.
Definition Firmware.idl:52
firmware::ImageStatus::size_done
int size_done
Progress of the running upload or download (if available)
Definition Firmware.idl:57
firmware::ImageStatus::error_message
string error_message
Error message; empty if there was no error.
Definition Firmware.idl:54
firmware::ImageStatus::state
ImageState state
Image upload/download state.
Definition Firmware.idl:53
firmware::ImageStatus::time_started
time time_started
UNIX timestamp (UTC) of the last state change (if available)
Definition Firmware.idl:55
firmware::ImageStatus::size_total
int size_total
Total size of the image (if available)
Definition Firmware.idl:56
firmware::SystemShutdownEvent
Event: System shutdown started.
Definition Firmware.idl:100
firmware::SystemStartupEvent
Event: System startup finished.
Definition Firmware.idl:98
firmware::UpdateHistoryEntry
Firmware update history entry TODO: implement CR# 45668 on next interface change add comment field ba...
Definition Firmware.idl:29
firmware::UpdateHistoryEntry::oldVersion
string oldVersion
Previous firmware version.
Definition Firmware.idl:31
firmware::UpdateHistoryEntry::imageMD5
string imageMD5
MD5 hash of update image.
Definition Firmware.idl:33
firmware::UpdateHistoryEntry::imageVersion
string imageVersion
Firmware version of update image.
Definition Firmware.idl:32
firmware::UpdateHistoryEntry::status
UpdateHistoryStatus status
Update status.
Definition Firmware.idl:34
firmware::UpdateHistoryEntry::timestamp
time timestamp
UNIX timestamp (UTC) when the update was started.
Definition Firmware.idl:30
idl::Event
Common base for all events.
Definition Event.idl:13