Raritan / Server Technology Xerus™ PDU JSON-RPC API: SensorLogger.idl Source File

Raritan / Server Technology Xerus™ PDU JSON-RPC API

SensorLogger.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2009 Raritan Inc. All rights reserved.
4 */
5
6 #include <Sensor.idl>
7 #include <PeripheralDeviceSlot.idl>
8 #include <UserEvent.idl>
9
10 /** Sensors Model */
11 module sensors {
12
13 /**
14 * Sensor logger interface.
15 *
16 * The sensor log stores a fixed number of log records for each
17 * enabled sensor. Log records hold the minimum, maximum and average
18 * reading of all samples within the period as well as the most
19 * critical state.
20 *
21 * Record IDs start at 1 and grow continuously without wrap-around. To
22 * avoid race conditions it is allowed to request records that are no
23 * longer available, i.e. have rotated out of the log. Unavailable
24 * records come back empty (available = false, timestamp = 0). It is
25 * not OK to read past newestRecId.
26 *
27 * Log record periods are synchronized with the system time, so all
28 * devices with the same log settings and proper time configuration
29 * move to a new record simultaneously.
30 */
31 interface Logger {
32
33 /** Sensor logger info */
34 structure Info {
35 int samplePeriod; ///< Sample interval in milliseconds
36 int maxTotalRecords; ///< Maximum supported number of log records (number of
37 ///< logged sensors multiplied by log capacity)
38 int effectiveCapacity; ///< Effective log capacity; may be lower than the
39 ///< setting to meet the maxTotalRecords limit.
40 int oldestRecId; ///< ID of oldest record in buffer (0 if empty)
41 int newestRecId; ///< ID of newest record in buffer (0 if empty)
42 };
43
44 /** Sensor logger settings */
45 structure Settings {
46 boolean isEnabled; ///< \c true if sensor logging is enabled
47 int samplesPerRecord; ///< Number of samples per log record
48 int logCapacity; ///< Maximum number of log records in buffer
49 boolean backupEnabled; ///< \c true if backup to external storage is enabled
50 };
51
52 /** Set of logged sensors */
53 structure SensorSet {
54 /** List of numeric or state sensors */
55 vector<sensors.Sensor> sensors;
56 /** List of peripheral device slots */
57 vector<peripheral.DeviceSlot> slots;
58 };
59
60 /** Event: Sensor logger info has changed */
61 valueobject InfoChangedEvent extends idl.Event {
62 Info oldInfo; ///< Info before change
63 Info newInfo; ///< Info after change
64 };
65
66 /** Event: Sensor logger settings have been changed */
67 valueobject SettingsChangedEvent extends event.UserEvent {
68 Settings oldSettings; ///< Settings before change
69 Settings newSettings; ///< Settings after change
70 };
71
72 /** Event: Set of logged sensors has been changed */
73 valueobject LoggedSensorsChangedEvent extends event.UserEvent {
74 SensorSet oldSensors; ///< Sensor set before change
75 SensorSet newSensors; ///< Sensor set after change
76 };
77
78 /**
79 * Retrieve the sensor logger info.
80 *
81 * @return Sensor logger info
82 */
83 Info getInfo();
84
85 /**
86 * Retrieve the sensor logger settings.
87 *
88 * @return Sensor logger settings
89 */
90 Settings getSettings();
91
92 /**
93 * Change the sensor logger settings.
94 *
95 * @param settings New settings
96 *
97 * @return 0 if OK
98 * @return 1 if any parameters are invalid
99 */
100 int setSettings(in Settings settings);
101
102 /** Sensor state in log record */
103 constant int STATE_UNAVAILABLE = 0; ///< Unavailable
104 constant int STATE_OPEN = 1; ///< Circuit breaker open
105 constant int STATE_CLOSE = 2; ///< Circuit breaker closed
106 constant int STATE_BELOW_LOWER_CRITICAL = 3; ///< Numeric sensor below lower critical threshold
107 constant int STATE_BELOW_LOWER_WARNING = 4; ///< Numeric sensor below lower warning threshold
108 constant int STATE_NORMAL = 5; ///< Numeric sensor in normal range; normal operation
109 constant int STATE_ABOVE_UPPER_WARNING = 6; ///< Numeric sensor above upper warning threshold
110 constant int STATE_ABOVE_UPPER_CRITICAL = 7; ///< Numeric sensor above upper critical threshold
111 constant int STATE_ON = 8; ///< Power state on
112 constant int STATE_OFF = 9; ///< Power state off
113 constant int STATE_ALARMED = 10; ///< Alarmed
114 constant int STATE_OK = 11; ///< OK
115 constant int STATE_MARGINAL = 12; ///< Marginal
116 constant int STATE_FAIL = 13; ///< Fail
117 constant int STATE_YES = 14; ///< Yes
118 constant int STATE_NO = 15; ///< No
119 constant int STATE_STANDBY = 16; ///< Standby operation
120 constant int STATE_ONE = 17; ///< First source active
121 constant int STATE_TWO = 18; ///< Second source active
122 constant int STATE_IN_SYNC = 19; ///< Phases are in sync
123 constant int STATE_OUT_OF_SYNC = 20; ///< Phases are out of sync
124 constant int STATE_FAULT = 21; ///< Fault
125 constant int STATE_SELF_TEST = 22; ///< Sensor is currently testing itself
126 constant int STATE_I1_OPEN_FAULT = 23; ///< Inlet 1 switch open fault
127 constant int STATE_I1_SHORT_FAULT = 24; ///< Inlet 1 switch short fault
128 constant int STATE_I2_OPEN_FAULT = 25; ///< Inlet 2 switch open fault
129 constant int STATE_I2_SHORT_FAULT = 26; ///< Inlet 2 switch short fault
130 constant int STATE_WARNING = 27; ///< Warning
131 constant int STATE_CRITICAL = 28; ///< Critical
132 constant int STATE_NON_REDUNDANT = 29; ///< Non-redundant operation
133
134 /**
135 * Retrieve a set of log record timestamps.
136 *
137 * @param timestamps Result: Log record timestamps
138 * @param recid First record id
139 * @param count Number of records
140 *
141 * @return 0 if OK
142 * @return 1 if any record id is invalid
143 */
144 int getTimeStamps(out vector<time> timestamps,
145 in int recid, in int count);
146
147 /** Sensor log record */
148 structure Record {
149 boolean available; ///< Sensor was available for at least one sample
150 int takenValidSamples; ///< Number of samples with a valid reading/state
151 int state; ///< Sensor state
152 double minValue; ///< Minimum sensor reading
153 double avgValue; ///< Average sensor reading
154 double maxValue; ///< Maximum sensor reading
155 };
156
157 /**
158 * Retrieve log records for a given sensor.
159 *
160 * @param recs Result: Sensor log records
161 * @param sensor Sensor reference
162 * @param recid First record id
163 * @param count Number of records
164 *
165 * @return 0 if OK
166 * @return 1 if any record id is invalid
167 */
168 int getSensorRecords(out vector<Record> recs, in sensors.Sensor sensor,
169 in int recid, in int count);
170
171 /**
172 * Retrieve log records for an peripheral device slot.
173 *
174 * @param recs Result: Sensor log records
175 * @param slot Peripheral device slot reference
176 * @param recid First record id
177 * @param count Number of records
178 *
179 * @return 0 if OK
180 * @return 1 if any record id is invalid
181 */
182 int getPeripheralDeviceRecords(out vector<Record> recs,
183 in peripheral.DeviceSlot slot,
184 in int recid, in int count);
185
186 /** Sensor log record with timestamp */
187 structure TimedRecord {
188 time timestamp; ///< UNIX timestamp (UTC)
189 Record record; ///< Log record
190 };
191
192 /**
193 * Retrieve log records with timestamps for a given sensor.
194 *
195 * @param recs Result: Sensor log records
196 * @param sensor Sensor reference
197 * @param recid First record id
198 * @param count Number of records
199 *
200 * @return 0 if OK
201 * @return 1 if any record id is invalid
202 */
203 int getSensorTimedRecords(out vector<TimedRecord> recs, in sensors.Sensor sensor,
204 in int recid, in int count);
205
206 /**
207 * Retrieve log records with timestamps for an peripheral device slot.
208 *
209 * @param recs Result: Sensor log records
210 * @param slot Peripheral device slot reference
211 * @param recid First record id
212 * @param count Number of records
213 *
214 * @return 0 if OK
215 * @return 1 if any record id is invalid
216 */
217 int getPeripheralDeviceTimedRecords(out vector<TimedRecord> recs,
218 in peripheral.DeviceSlot slot,
219 in int recid, in int count);
220
221 /**
222 * Retrieve the set of logged sensors.
223 *
224 * @return Set of logged sensors
225 */
226 SensorSet getLoggedSensors();
227
228 /**
229 * Change the set of logged sensors.
230 *
231 * @param sensors New set of sensors
232 *
233 * @return 0 if OK
234 * @return 1 if any sensor in the list is unknown
235 */
236 int setLoggedSensors(in SensorSet sensors);
237
238 /**
239 * Enable logging for one or more sensors or peripheral device slots.
240 *
241 * Sensors in the list that are already logged are ignored. Logged
242 * sensors not in the list remain enabled.
243 *
244 * @param sensors Sensors and slots to be logged
245 *
246 * @return 0 if OK
247 * @return 1 if any sensor in the list is unknown
248 */
249 int enableSensors(in SensorSet sensors);
250
251 /**
252 * Disable logging for one or more sensors or peripheral device slots.
253 *
254 * Sensors in the list that are not logged are ignored. Logged sensors
255 * not in the list remain enabled.
256 *
257 * @param sensors Sensors and slots to be disabled
258 *
259 * @return 0 if OK
260 * @return 1 if any sensor in the list is unknown
261 */
262 int disableSensors(in SensorSet sensors);
263
264 /**
265 * Check if logging is enabled for a given sensor.
266 *
267 * @param sensor Sensor to be checked
268 *
269 * @return \c true if sensor is logged, \c false otherwise
270 */
271 boolean isSensorEnabled(in sensors.Sensor sensor);
272
273 /**
274 * Check if logging is enabled for a given peripheral device slot.
275 *
276 * @param sensor Peripheral device slot to be checked
277 *
278 * @return \c true if slot is logged, \c false otherwise
279 */
280 boolean isSlotEnabled(in peripheral.DeviceSlot slot);
281
282 /**
283 * Enable logging for all PDU sensors.
284 */
285 void enableAllSensors();
286
287 /**
288 * Disable logging for all PDU sensors.
289 */
290 void disableAllSensors();
291
292 /**
293 * Get the time of the last sensor set modification.
294 *
295 * This can be used by clients which keep a cached copy of the sensor
296 * set to determine whether that copy is still up-to-date.
297 *
298 * @return Sensor set time stamp (UNIX timestamp, UTC)
299 */
300 time getSensorSetTimestamp();
301
302 /** One full log row */
303 structure LogRow {
304 /** Time of last sensor set modification (UNIX timestamp, UTC) */
305 time sensorSetTimestamp;
306 /** Log row time stamp (UNIX timestamp, UTC) */
307 time timestamp;
308 /** Sensor records; same order as in SensorSet::sensors */
309 vector<Record> sensorRecords;
310 /** Peripheral device records; same order as in SensorSet::slots */
311 vector<Record> peripheralDeviceRecords;
312 };
313
314 /**
315 * Get one full log row.
316 *
317 * @param row Result: Log row
318 * @param recid Record id
319 *
320 * @return 0 if OK
321 * @return 1 if the record id is invalid
322 */
323 int getLogRow(out LogRow row, in int recid);
324
325 };
326
327 }
peripheral::DeviceSlot
Peripheral Device Slot.
Definition: PeripheralDeviceSlot.idl:66
sensors::Logger
Sensor logger interface.
Definition: SensorLogger.idl:31
sensors::Logger::getTimeStamps
int getTimeStamps(out vector< time > timestamps, in int recid, in int count)
Retrieve a set of log record timestamps.
sensors::Logger::getLogRow
int getLogRow(out LogRow row, in int recid)
Get one full log row.
sensors::Logger::isSensorEnabled
boolean isSensorEnabled(in sensors::Sensor sensor)
Check if logging is enabled for a given sensor.
sensors::Logger::getSensorSetTimestamp
time getSensorSetTimestamp()
Get the time of the last sensor set modification.
sensors::Logger::getPeripheralDeviceRecords
int getPeripheralDeviceRecords(out vector< Record > recs, in peripheral::DeviceSlot slot, in int recid, in int count)
Retrieve log records for an peripheral device slot.
sensors::Logger::disableAllSensors
void disableAllSensors()
Disable logging for all PDU sensors.
sensors::Logger::enableSensors
int enableSensors(in SensorSet sensors)
Enable logging for one or more sensors or peripheral device slots.
sensors::Logger::getPeripheralDeviceTimedRecords
int getPeripheralDeviceTimedRecords(out vector< TimedRecord > recs, in peripheral::DeviceSlot slot, in int recid, in int count)
Retrieve log records with timestamps for an peripheral device slot.
sensors::Logger::enableAllSensors
void enableAllSensors()
Enable logging for all PDU sensors.
sensors::Logger::setSettings
int setSettings(in Settings settings)
Change the sensor logger settings.
sensors::Logger::getSettings
Settings getSettings()
Retrieve the sensor logger settings.
sensors::Logger::setLoggedSensors
int setLoggedSensors(in SensorSet sensors)
Change the set of logged sensors.
sensors::Logger::disableSensors
int disableSensors(in SensorSet sensors)
Disable logging for one or more sensors or peripheral device slots.
sensors::Logger::getSensorRecords
int getSensorRecords(out vector< Record > recs, in sensors::Sensor sensor, in int recid, in int count)
Retrieve log records for a given sensor.
sensors::Logger::isSlotEnabled
boolean isSlotEnabled(in peripheral::DeviceSlot slot)
Check if logging is enabled for a given peripheral device slot.
sensors::Logger::getSensorTimedRecords
int getSensorTimedRecords(out vector< TimedRecord > recs, in sensors::Sensor sensor, in int recid, in int count)
Retrieve log records with timestamps for a given sensor.
sensors::Logger::getInfo
Info getInfo()
Retrieve the sensor logger info.
sensors::Logger::getLoggedSensors
SensorSet getLoggedSensors()
Retrieve the set of logged sensors.
sensors::Sensor
Sensor interface
Definition: Sensor.idl:15
idl
Basic IDL definitions.
Definition: Event.idl:10
peripheral
Peripheral Devices.
Definition: GatewaySensorManager.idl:17
sensors
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
idl::Event
Common base for all events.
Definition: Event.idl:13
sensors::Logger::InfoChangedEvent
Event: Sensor logger info has changed.
Definition: SensorLogger.idl:61
sensors::Logger::InfoChangedEvent::oldInfo
Info oldInfo
Info before change.
Definition: SensorLogger.idl:62
sensors::Logger::InfoChangedEvent::newInfo
Info newInfo
Info after change.
Definition: SensorLogger.idl:63
sensors::Logger::Info
Sensor logger info.
Definition: SensorLogger.idl:34
sensors::Logger::Info::samplePeriod
int samplePeriod
Sample interval in milliseconds.
Definition: SensorLogger.idl:35
sensors::Logger::Info::newestRecId
int newestRecId
ID of newest record in buffer (0 if empty)
Definition: SensorLogger.idl:41
sensors::Logger::Info::oldestRecId
int oldestRecId
ID of oldest record in buffer (0 if empty)
Definition: SensorLogger.idl:40
sensors::Logger::Info::maxTotalRecords
int maxTotalRecords
Maximum supported number of log records (number of logged sensors multiplied by log capacity)
Definition: SensorLogger.idl:36
sensors::Logger::Info::effectiveCapacity
int effectiveCapacity
Effective log capacity; may be lower than the setting to meet the maxTotalRecords limit.
Definition: SensorLogger.idl:38
sensors::Logger::LogRow
One full log row.
Definition: SensorLogger.idl:303
sensors::Logger::LogRow::timestamp
time timestamp
Log row time stamp (UNIX timestamp, UTC)
Definition: SensorLogger.idl:307
sensors::Logger::LogRow::peripheralDeviceRecords
vector< Record > peripheralDeviceRecords
Peripheral device records; same order as in SensorSet::slots.
Definition: SensorLogger.idl:311
sensors::Logger::LogRow::sensorSetTimestamp
time sensorSetTimestamp
Time of last sensor set modification (UNIX timestamp, UTC)
Definition: SensorLogger.idl:305
sensors::Logger::LogRow::sensorRecords
vector< Record > sensorRecords
Sensor records; same order as in SensorSet::sensors.
Definition: SensorLogger.idl:309
sensors::Logger::LoggedSensorsChangedEvent
Event: Set of logged sensors has been changed.
Definition: SensorLogger.idl:73
sensors::Logger::LoggedSensorsChangedEvent::oldSensors
SensorSet oldSensors
Sensor set before change.
Definition: SensorLogger.idl:74
sensors::Logger::LoggedSensorsChangedEvent::newSensors
SensorSet newSensors
Sensor set after change.
Definition: SensorLogger.idl:75
sensors::Logger::Record
Sensor log record.
Definition: SensorLogger.idl:148
sensors::Logger::Record::available
boolean available
Sensor was available for at least one sample.
Definition: SensorLogger.idl:149
sensors::Logger::Record::minValue
double minValue
Minimum sensor reading.
Definition: SensorLogger.idl:152
sensors::Logger::Record::maxValue
double maxValue
Maximum sensor reading.
Definition: SensorLogger.idl:154
sensors::Logger::Record::state
int state
Sensor state.
Definition: SensorLogger.idl:151
sensors::Logger::Record::avgValue
double avgValue
Average sensor reading.
Definition: SensorLogger.idl:153
sensors::Logger::Record::takenValidSamples
int takenValidSamples
Number of samples with a valid reading/state.
Definition: SensorLogger.idl:150
sensors::Logger::SensorSet
Set of logged sensors.
Definition: SensorLogger.idl:53
sensors::Logger::SensorSet::slots
vector< peripheral::DeviceSlot > slots
List of peripheral device slots.
Definition: SensorLogger.idl:57
sensors::Logger::SensorSet::sensors
vector< sensors::Sensor > sensors
List of numeric or state sensors.
Definition: SensorLogger.idl:55
sensors::Logger::SettingsChangedEvent
Event: Sensor logger settings have been changed.
Definition: SensorLogger.idl:67
sensors::Logger::SettingsChangedEvent::newSettings
Settings newSettings
Settings after change.
Definition: SensorLogger.idl:69
sensors::Logger::SettingsChangedEvent::oldSettings
Settings oldSettings
Settings before change.
Definition: SensorLogger.idl:68
sensors::Logger::Settings
Sensor logger settings.
Definition: SensorLogger.idl:45
sensors::Logger::Settings::logCapacity
int logCapacity
Maximum number of log records in buffer.
Definition: SensorLogger.idl:48
sensors::Logger::Settings::backupEnabled
boolean backupEnabled
true if backup to external storage is enabled
Definition: SensorLogger.idl:49
sensors::Logger::Settings::samplesPerRecord
int samplesPerRecord
Number of samples per log record.
Definition: SensorLogger.idl:47
sensors::Logger::Settings::isEnabled
boolean isEnabled
true if sensor logging is enabled
Definition: SensorLogger.idl:46
sensors::Logger::TimedRecord
Sensor log record with timestamp.
Definition: SensorLogger.idl:187
sensors::Logger::TimedRecord::record
Record record
Log record.
Definition: SensorLogger.idl:189
sensors::Logger::TimedRecord::timestamp
time timestamp
UNIX timestamp (UTC)
Definition: SensorLogger.idl:188