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_3_7 {
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  */
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_4 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; ///< UNIX timestamp (UTC)
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_4 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  */
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  */
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  */
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  */
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  */
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  */
260 
261  /**
262  * Enable logging for all PDU sensors.
263  */
265 
266  /**
267  * Disable logging for all PDU sensors.
268  */
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 (UNIX timestamp, UTC)
278  */
280 
281  /** One full log row */
282  structure LogRow {
283  /** Time of last sensor set modification (UNIX timestamp, UTC) */
285  /** Log row time stamp (UNIX timestamp, UTC) */
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 }
Peripheral Device Slot.
Definition: PeripheralDeviceSlot.idl:65
Sensor logger interface.
Definition: SensorLogger.idl:31
boolean isSlotEnabled(in peripheral::DeviceSlot_4_0_0 slot)
Check if logging is enabled for a given peripheral device slot.
int getSensorTimedRecords(out vector< TimedRecord > recs, in sensors::Sensor_4_0_4 sensor, in int recid, in int count)
Retrieve log records with timestamps for a given sensor.
time getSensorSetTimestamp()
Get the time of the last sensor set modification.
int getTimeStamps(out vector< time > timestamps, in int recid, in int count)
Retrieve a set of log record timestamps.
int enableSensors(in SensorSet sensors)
Enable logging for one or more sensors or peripheral device slots.
Settings newSettings
Settings after change.
Definition: SensorLogger.idl:54
int getPeripheralDeviceTimedRecords(out vector< TimedRecord > recs, in peripheral::DeviceSlot_4_0_0 slot, in int recid, in int count)
Retrieve log records with timestamps for an peripheral device slot.
int getPeripheralDeviceRecords(out vector< Record > recs, in peripheral::DeviceSlot_4_0_0 slot, in int recid, in int count)
Retrieve log records for an peripheral device slot.
boolean isSensorEnabled(in sensors::Sensor_4_0_4 sensor)
Check if logging is enabled for a given sensor.
int setLoggedSensors(in SensorSet sensors)
Change the set of logged sensors.
Settings getSettings()
Retrieve the sensor logger settings.
SensorSet newSensors
Sensor set after change.
Definition: SensorLogger.idl:60
void enableAllSensors()
Enable logging for all PDU sensors.
int setSettings(in boolean isEnabled, in int samplesPerRecord)
Change the sensor logger settings.
int getSensorRecords(out vector< Record > recs, in sensors::Sensor_4_0_4 sensor, in int recid, in int count)
Retrieve log records for a given sensor.
SensorSet getLoggedSensors()
Retrieve the set of logged sensors.
int disableSensors(in SensorSet sensors)
Disable logging for one or more sensors or peripheral device slots.
int getLogRow(out LogRow row, in int recid)
Get one full log row.
void disableAllSensors()
Disable logging for all PDU sensors.
Sensor interface
Definition: Sensor.idl:15
Peripheral Devices.
Definition: PeripheralDeviceManager.idl:18
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
One full log row.
Definition: SensorLogger.idl:282
vector< Record > sensorRecords
Sensor records; same order as in SensorSet::sensors.
Definition: SensorLogger.idl:288
vector< Record > peripheralDeviceRecords
Peripheral device records; same order as in SensorSet::slots.
Definition: SensorLogger.idl:290
time sensorSetTimestamp
Time of last sensor set modification (UNIX timestamp, UTC)
Definition: SensorLogger.idl:284
time timestamp
Log row time stamp (UNIX timestamp, UTC)
Definition: SensorLogger.idl:286
Sensor log record.
Definition: SensorLogger.idl:127
double minValue
Minimum sensor reading.
Definition: SensorLogger.idl:131
int state
Sensor state.
Definition: SensorLogger.idl:130
int takenValidSamples
Number of samples with a valid reading/state.
Definition: SensorLogger.idl:129
double avgValue
Average sensor reading.
Definition: SensorLogger.idl:132
boolean available
Sensor was available for at least one sample.
Definition: SensorLogger.idl:128
double maxValue
Maximum sensor reading.
Definition: SensorLogger.idl:133
Set of logged sensors.
Definition: SensorLogger.idl:44
vector< sensors::Sensor_4_0_4 > sensors
List of numeric or state sensors.
Definition: SensorLogger.idl:46
vector< peripheral::DeviceSlot_4_0_0 > slots
List of peripheral device slots.
Definition: SensorLogger.idl:48
Sensor logger settings.
Definition: SensorLogger.idl:34
int samplePeriod
Sensor scan interval in milliseconds.
Definition: SensorLogger.idl:36
int newestRecId
ID of newest record in buffer (0 if empty)
Definition: SensorLogger.idl:39
boolean isEnabled
true if sensor logging is enabled
Definition: SensorLogger.idl:35
int samplesPerRecord
Number of samples per log record.
Definition: SensorLogger.idl:37
int logCapacity
Maximum number of log records in buffer.
Definition: SensorLogger.idl:40
int oldestRecId
ID of oldest record in buffer (0 if empty)
Definition: SensorLogger.idl:38
Sensor log record with timestamp.
Definition: SensorLogger.idl:166
Record record
Log record.
Definition: SensorLogger.idl:168
time timestamp
UNIX timestamp (UTC)
Definition: SensorLogger.idl:167