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 */
47  /** List of peripheral device 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,
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,
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 */
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 }
time sensorSetTimestamp
Time of last sensor set modification.
Definition: SensorLogger.idl:284
SensorSet newSensors
Sensor set after change.
Definition: SensorLogger.idl:60
double avgValue
Average sensor reading.
Definition: SensorLogger.idl:132
One full log row.
Definition: SensorLogger.idl:282
boolean available
Sensor was available for at least one sample.
Definition: SensorLogger.idl:128
int takenValidSamples
Number of samples with a valid reading/state.
Definition: SensorLogger.idl:129
Sensor log record.
Definition: SensorLogger.idl:127
Peripheral Devices.
Definition: PeripheralDeviceManager.idl:17
int oldestRecId
ID of oldest record in buffer (0 if empty)
Definition: SensorLogger.idl:38
Record record
Log record.
Definition: SensorLogger.idl:168
int newestRecId
ID of newest record in buffer (0 if empty)
Definition: SensorLogger.idl:39
vector< peripheral::DeviceSlot_2_0_3 > slots
List of peripheral device slots.
Definition: SensorLogger.idl:48
int samplesPerRecord
Number of samples per log record.
Definition: SensorLogger.idl:37
vector< sensors::Sensor_4_0_3 > sensors
List of numeric or state sensors.
Definition: SensorLogger.idl:46
time timestamp
Log row time stamp.
Definition: SensorLogger.idl:286
Settings newSettings
Settings after change.
Definition: SensorLogger.idl:54
double minValue
Minimum sensor reading.
Definition: SensorLogger.idl:131
int logCapacity
Maximum number of log records in buffer.
Definition: SensorLogger.idl:40
int state
Sensor state.
Definition: SensorLogger.idl:130
Sensor interface
Definition: Sensor.idl:15
Peripheral Device Slot.
Definition: PeripheralDeviceSlot.idl:60
boolean isEnabled
true if sensor logging is enabled
Definition: SensorLogger.idl:35
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
Set of logged sensors.
Definition: SensorLogger.idl:44
vector< Record > sensorRecords
Sensor records; same order as in SensorSet::sensors.
Definition: SensorLogger.idl:288
Sensor logger interface.
Definition: SensorLogger.idl:31
vector< Record > peripheralDeviceRecords
Peripheral device records; same order as in SensorSet::slots.
Definition: SensorLogger.idl:290
Sensor log record with timestamp.
Definition: SensorLogger.idl:166
int samplePeriod
Sensor scan interval in milliseconds.
Definition: SensorLogger.idl:36
time timestamp
Timestamp.
Definition: SensorLogger.idl:167
double maxValue
Maximum sensor reading.
Definition: SensorLogger.idl:133
Sensor logger settings.
Definition: SensorLogger.idl:34