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