Legrand / Raritan / Server Technology Xerus™ JSON-RPC API

Loading...
Searching...
No Matches
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 */
11module 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 constant int STATE_INACTIVE = 30; ///< Bypass inactive
134 constant int STATE_I1_SELECTED = 31; ///< Inlet 1 selected
135 constant int STATE_I2_SELECTED = 32; ///< Inlet 2 selected
136 constant int STATE_I1_SELECTED_AND_ACTIVE = 33; ///< Inlet 1 selected and active
137 constant int STATE_I2_SELECTED_AND_ACTIVE = 34; ///< Inlet 2 selected and active
138 constant int STATE_BYPASS_ACTIVE = 35; ///< Operational state: bypass active
139
140 /**
141 * Retrieve a set of log record timestamps.
142 *
143 * @param timestamps Result: Log record timestamps
144 * @param recid First record id
145 * @param count Number of records
146 *
147 * @return 0 if OK
148 * @return 1 if any record id is invalid
149 */
150 int getTimeStamps(out vector<time> timestamps,
151 in int recid, in int count);
152
153 /** Sensor log record */
154 structure Record {
155 boolean available; ///< Sensor was available for at least one sample
156 int takenValidSamples; ///< Number of samples with a valid reading/state
157 int state; ///< Sensor state
158 double minValue; ///< Minimum sensor reading
159 double avgValue; ///< Average sensor reading
160 double maxValue; ///< Maximum sensor reading
161 };
162
163 /**
164 * Retrieve log records for a given sensor.
165 *
166 * @param recs Result: Sensor log records
167 * @param sensor Sensor reference
168 * @param recid First record id
169 * @param count Number of records
170 *
171 * @return 0 if OK
172 * @return 1 if any record id is invalid
173 */
174 int getSensorRecords(out vector<Record> recs, in sensors.Sensor sensor,
175 in int recid, in int count);
176
177 /**
178 * Retrieve log records for an peripheral device slot.
179 *
180 * @param recs Result: Sensor log records
181 * @param slot Peripheral device slot reference
182 * @param recid First record id
183 * @param count Number of records
184 *
185 * @return 0 if OK
186 * @return 1 if any record id is invalid
187 */
188 int getPeripheralDeviceRecords(out vector<Record> recs,
189 in peripheral.DeviceSlot slot,
190 in int recid, in int count);
191
192 /** Sensor log record with timestamp */
193 structure TimedRecord {
194 time timestamp; ///< UNIX timestamp (UTC)
195 Record record; ///< Log record
196 };
197
198 /**
199 * Retrieve log records with timestamps for a given sensor.
200 *
201 * @param recs Result: Sensor log records
202 * @param sensor Sensor reference
203 * @param recid First record id
204 * @param count Number of records
205 *
206 * @return 0 if OK
207 * @return 1 if any record id is invalid
208 */
209 int getSensorTimedRecords(out vector<TimedRecord> recs, in sensors.Sensor sensor,
210 in int recid, in int count);
211
212 /**
213 * Retrieve log records with timestamps for an peripheral device slot.
214 *
215 * @param recs Result: Sensor log records
216 * @param slot Peripheral device slot reference
217 * @param recid First record id
218 * @param count Number of records
219 *
220 * @return 0 if OK
221 * @return 1 if any record id is invalid
222 */
223 int getPeripheralDeviceTimedRecords(out vector<TimedRecord> recs,
224 in peripheral.DeviceSlot slot,
225 in int recid, in int count);
226
227 /**
228 * Retrieve the set of logged sensors.
229 *
230 * @return Set of logged sensors
231 */
232 SensorSet getLoggedSensors();
233
234 /**
235 * Change the set of logged sensors.
236 *
237 * @param sensors New set of sensors
238 *
239 * @return 0 if OK
240 * @return 1 if any sensor in the list is unknown
241 */
242 int setLoggedSensors(in SensorSet sensors);
243
244 /**
245 * Enable logging for one or more sensors or peripheral device slots.
246 *
247 * Sensors in the list that are already logged are ignored. Logged
248 * sensors not in the list remain enabled.
249 *
250 * @param sensors Sensors and slots to be logged
251 *
252 * @return 0 if OK
253 * @return 1 if any sensor in the list is unknown
254 */
255 int enableSensors(in SensorSet sensors);
256
257 /**
258 * Disable logging for one or more sensors or peripheral device slots.
259 *
260 * Sensors in the list that are not logged are ignored. Logged sensors
261 * not in the list remain enabled.
262 *
263 * @param sensors Sensors and slots to be disabled
264 *
265 * @return 0 if OK
266 * @return 1 if any sensor in the list is unknown
267 */
268 int disableSensors(in SensorSet sensors);
269
270 /**
271 * Check if logging is enabled for a given sensor.
272 *
273 * @param sensor Sensor to be checked
274 *
275 * @return \c true if sensor is logged, \c false otherwise
276 */
277 boolean isSensorEnabled(in sensors.Sensor sensor);
278
279 /**
280 * Check if logging is enabled for a given peripheral device slot.
281 *
282 * @param sensor Peripheral device slot to be checked
283 *
284 * @return \c true if slot is logged, \c false otherwise
285 */
286 boolean isSlotEnabled(in peripheral.DeviceSlot slot);
287
288 /**
289 * Enable logging for all PDU sensors.
290 */
291 void enableAllSensors();
292
293 /**
294 * Disable logging for all PDU sensors.
295 */
296 void disableAllSensors();
297
298 /**
299 * Get the time of the last sensor set modification.
300 *
301 * This can be used by clients which keep a cached copy of the sensor
302 * set to determine whether that copy is still up-to-date.
303 *
304 * @return Sensor set time stamp (UNIX timestamp, UTC)
305 */
306 time getSensorSetTimestamp();
307
308 /** One full log row */
309 structure LogRow {
310 /** Time of last sensor set modification (UNIX timestamp, UTC) */
311 time sensorSetTimestamp;
312 /** Log row time stamp (UNIX timestamp, UTC) */
313 time timestamp;
314 /** Sensor records; same order as in SensorSet::sensors */
315 vector<Record> sensorRecords;
316 /** Peripheral device records; same order as in SensorSet::slots */
317 vector<Record> peripheralDeviceRecords;
318 };
319
320 /**
321 * Get one full log row.
322 *
323 * @param row Result: Log row
324 * @param recid Record id
325 *
326 * @return 0 if OK
327 * @return 1 if the record id is invalid
328 */
329 int getLogRow(out LogRow row, in int recid);
330
331 };
332
333}
peripheral::DeviceSlot
Peripheral Device Slot.
Definition PeripheralDeviceSlot.idl:47
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:309
sensors::Logger::LogRow::timestamp
time timestamp
Log row time stamp (UNIX timestamp, UTC)
Definition SensorLogger.idl:313
sensors::Logger::LogRow::peripheralDeviceRecords
vector< Record > peripheralDeviceRecords
Peripheral device records; same order as in SensorSet::slots.
Definition SensorLogger.idl:317
sensors::Logger::LogRow::sensorSetTimestamp
time sensorSetTimestamp
Time of last sensor set modification (UNIX timestamp, UTC)
Definition SensorLogger.idl:311
sensors::Logger::LogRow::sensorRecords
vector< Record > sensorRecords
Sensor records; same order as in SensorSet::sensors.
Definition SensorLogger.idl:315
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:154
sensors::Logger::Record::available
boolean available
Sensor was available for at least one sample.
Definition SensorLogger.idl:155
sensors::Logger::Record::minValue
double minValue
Minimum sensor reading.
Definition SensorLogger.idl:158
sensors::Logger::Record::maxValue
double maxValue
Maximum sensor reading.
Definition SensorLogger.idl:160
sensors::Logger::Record::state
int state
Sensor state.
Definition SensorLogger.idl:157
sensors::Logger::Record::avgValue
double avgValue
Average sensor reading.
Definition SensorLogger.idl:159
sensors::Logger::Record::takenValidSamples
int takenValidSamples
Number of samples with a valid reading/state.
Definition SensorLogger.idl:156
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:193
sensors::Logger::TimedRecord::record
Record record
Log record.
Definition SensorLogger.idl:195
sensors::Logger::TimedRecord::timestamp
time timestamp
UNIX timestamp (UTC)
Definition SensorLogger.idl:194