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

Raritan / Server Technology Xerus™ PDU JSON-RPC API

TransferSwitch.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3 * Copyright 2012 Raritan Inc. All rights reserved.
4 */
5
6 #ifndef __PDUMODEL_TRANSFERSWITCH_IDL__
7 #define __PDUMODEL_TRANSFERSWITCH_IDL__
8
9 #include <EDevice.idl>
10 #include <Nameplate.idl>
11 #include <Pole.idl>
12 #include <StateSensor.idl>
13 #include <Waveform.idl>
14
15 /**
16 * PDU Model
17 */
18 module pdumodel {
19
20 /** Transfer switch interface */
21 interface TransferSwitch extends EDevice {
22
23 constant int ERR_INVALID_PARAM = 1; ///< Invalid parameters
24 constant int ERR_SWITCH_PREVENTED = 2; ///< Switching failed due to an alarm that may be overridden
25 constant int ERR_SWITCH_FAILED = 3; ///< Switching failed, no override possible
26
27 /** Transfer switch type */
28 enumeration Type {
29 STS, ///< Static transfer switch (using SCRs as switch technology)
30 ATS, ///< Asynchronous transfer switch (using relays)
31 HTS ///< Hybrid transfer switch (relays plus SCRs)
32 };
33
34 enumeration TransferReason {
35 REASON_UNKNOWN, ///< Transfer reason unknown
36 REASON_STARTUP, ///< Startup or return to normal conditions
37 REASON_MANUAL_TRANSFER, ///< Manual transfer
38 REASON_AUTO_RETRANSFER, ///< Automatic retransfer
39 REASON_POWER_FAILURE, ///< Previous inlet power failed
40 REASON_POWER_QUALITY, ///< New inlet provided better power quality
41 REASON_OVERLOAD, ///< Switched off due to overload alarm
42 REASON_OVERHEAT, ///< Switched off due to overheat alarm
43 REASON_INTERNAL_FAILURE ///< Transferred because of hardware failure (e.g. switch fault)
44 };
45
46 /** Transfer switch metadata */
47 structure MetaData {
48 string label; ///< Transfer switch label
49 Nameplate namePlate; ///< %Nameplate information
50 Rating rating; ///< Numerical usage ratings
51 Type type; ///< Transfer switch type
52 int sourceCount; ///< Number of sources
53 };
54
55 /* Values for operational state sensor */
56 constant int OPERATIONAL_STATE_OFF = 0; ///< Both inlets are off
57 constant int OPERATIONAL_STATE_NORMAL = 1; ///< Active inlet equals preferred inlet
58 constant int OPERATIONAL_STATE_STANDBY = 2; ///< Active inlet and preferred inlet are different
59 constant int OPERATIONAL_STATE_NON_REDUNDANT = 3; ///< Active inlet equals preferred inlet, standby power critical
60
61 /* Bitmask values for switch fault sensors */
62 constant int SWITCH_FAULT_I1_SHORT = 1; ///< Inlet 1 switch is permanently closed
63 constant int SWITCH_FAULT_I1_OPEN = 2; ///< Inlet 1 switch is permanently open
64 constant int SWITCH_FAULT_I2_SHORT = 4; ///< Inlet 2 switch is permanently closed
65 constant int SWITCH_FAULT_I2_OPEN = 8; ///< Inlet 2 switch is permanently open
66
67 /** Transfer switch sensors */
68 structure Sensors {
69 sensors.StateSensor selectedSource; ///< Selected source sensor
70 sensors.StateSensor operationalState; ///< Operational state sensor (off, normal, standby)
71 sensors.NumericSensor sourceVoltagePhaseSyncAngle;
72 ///< Maximum phase difference between two sources
73 sensors.StateSensor overloadAlarm; ///< Overload alarm
74 sensors.StateSensor phaseSyncAlarm; ///< Source phases out of sync
75 sensors.StateSensor switchFault; ///< Switch fault (ok, open, short)
76 sensors.StateSensor selectedBypassSource; ///< Selected source in bypass module
77 };
78
79 /** Transfer switch settings */
80 [sparse_in]
81 structure Settings {
82 string name; ///< User-defined name
83
84 int preferredSource; ///< Preferred inlet
85 boolean autoRetransfer; ///< Enable automatic retransfer if power on active inlet is restored
86 boolean noAutoRetransferIfPhaseFault; ///< Don't automatically retransfer if inlet phases are out of sync
87 int autoRetransferWaitTime; ///< Time (in s) to delay retransfer after power restoration
88 boolean manualTransferEnabled; ///< Enable state of 'manual transfer' front panel button
89 boolean phaseSyncSensorEnabled; ///< False to force the 'phaseSyncAlarm' sensor to unavailable
90 };
91
92 /** Transfer switch statistics */
93 structure Statistics {
94 int transferCount; ///< Number of transfers since device startup
95 int powerFailDetectTime; ///< Detection time in us for the last inlet power failure
96 int relayOpenTime; ///< Time in us until all relays have opened during the last transfer
97 int totalTransferTime; ///< Total time in us for last transfer
98 };
99
100 /** Event: Transfer switch settings have been changed */
101 valueobject SettingsChangedEvent extends event.UserEvent {
102 Settings oldSettings; ///< Settings before change
103 Settings newSettings; ///< Settings after change
104 };
105
106 /**
107 * Retrieve the transfer switch metadata.
108 *
109 * @return Transfer switch metadata
110 */
111 MetaData getMetaData();
112
113 /**
114 * Get the transfer switch sensors.
115 *
116 * @return Transfer switch sensors
117 */
118 Sensors getSensors();
119
120 /**
121 * Get the list of transfer switch poles.
122 *
123 * @return List of poles
124 */
125 vector<ThrowPole> getPoles();
126
127 /**
128 * Retrieve the transfer switch settings.
129 *
130 * @return Transfer switch settings
131 */
132 Settings getSettings();
133
134 /**
135 * Change the transfer switch settings.
136 *
137 * @return 0 if OK
138 * @return 1 if any parameters are invalid
139 *
140 * @note The Settings structure can be "sparse"; fields missing in the
141 * JSON representation will remain unchanged.
142 */
143 int setSettings(in Settings settings);
144
145 /**
146 * Retrieve the transfer switch statistics.
147 *
148 * @return Transfer switch statistics
149 */
150 Statistics getStatistics();
151
152 /**
153 * Select the active inlet. If the new inlet is available,
154 * it will become both active and preferred.
155 *
156 * @param source New active inlet index
157 * @param faultOverride Force switch even if the phase sync angle
158 * between the inputs is too large
159 *
160 * @return 0 if OK
161 * @return ERR_INVALID_PARAM if the selected source is invalid
162 * @return ERR_SWITCH_PREVENTED if switching failed due to an alarm that may be overridden
163 * @return ERR_SWITCH_FAILED if switching failed and no override is possible
164 */
165 int transferToSource(in int source, in boolean faultOverride);
166
167 /**
168 * Get the reason for the last transfer.
169 *
170 * @return Last transfer reason
171 */
172 TransferReason getLastTransferReason();
173
174 /**
175 * Get the voltage and current waveforms during the last transfer.
176 *
177 * @return Waveform samples
178 */
179 Waveform getLastTransferWaveform();
180
181 /** Transfer log entry */
182 structure TransferLogEntry {
183 time timestamp; ///< Time of the transfer (UNIX timestamp, UTC)
184 int oldInlet; ///< Active inlet before transfer (0 for none)
185 int newInlet; ///< Active inlet after transfer (0 for none)
186 TransferReason reason; ///< Transfer reason
187 Waveform waveform; ///< Voltage and current waveforms
188 Statistics statistics; ///< Transfer statistics
189 int switchFault; ///< Switch fault status
190 };
191
192 /**
193 * Retrieve the transfer log.
194 *
195 * @return Transfer log
196 */
197 vector<TransferLogEntry> getTransferLog();
198
199 /**
200 * Transfer switch parameter map.
201 *
202 * The set of parameters, their meaning and allowed set of values are
203 * technology-dependent and subject to change. Do not modify any values
204 * without instruction from Raritan!
205 */
206 typedef map<string, int> Parameters;
207
208 /**
209 * Retrieve the transfer switch parameters.
210 *
211 * @return Parameters map
212 */
213 Parameters getParameters();
214
215 /**
216 * Update one or more transfer switch parameters.
217 *
218 * @param parameters Map of transfer switch parameters. Parameters
219 * which are not in the map remain unchanged.
220 *
221 * @return 0 if OK
222 * @return ERR_INVALID_PARAM if any parameter is invalid
223 */
224 int setParameters(in Parameters parameters);
225
226 };
227
228 }
229
230 #endif
pdumodel::EDevice
Common base interface for any kind of electrical device that is used in the PDU model,...
Definition: EDevice.idl:27
pdumodel::TransferSwitch
Transfer switch interface.
Definition: TransferSwitch.idl:21
pdumodel::TransferSwitch::Type
Type
Transfer switch type.
Definition: TransferSwitch.idl:28
pdumodel::TransferSwitch::ATS
@ ATS
Asynchronous transfer switch (using relays)
Definition: TransferSwitch.idl:30
pdumodel::TransferSwitch::STS
@ STS
Static transfer switch (using SCRs as switch technology)
Definition: TransferSwitch.idl:29
pdumodel::TransferSwitch::getLastTransferReason
TransferReason getLastTransferReason()
Get the reason for the last transfer.
pdumodel::TransferSwitch::getSettings
Settings getSettings()
Retrieve the transfer switch settings.
pdumodel::TransferSwitch::getStatistics
Statistics getStatistics()
Retrieve the transfer switch statistics.
pdumodel::TransferSwitch::setParameters
int setParameters(in Parameters parameters)
Update one or more transfer switch parameters.
pdumodel::TransferSwitch::getParameters
Parameters getParameters()
Retrieve the transfer switch parameters.
pdumodel::TransferSwitch::getPoles
vector< ThrowPole > getPoles()
Get the list of transfer switch poles.
pdumodel::TransferSwitch::getSensors
Sensors getSensors()
Get the transfer switch sensors.
pdumodel::TransferSwitch::transferToSource
int transferToSource(in int source, in boolean faultOverride)
Select the active inlet.
pdumodel::TransferSwitch::getLastTransferWaveform
Waveform getLastTransferWaveform()
Get the voltage and current waveforms during the last transfer.
pdumodel::TransferSwitch::getMetaData
MetaData getMetaData()
Retrieve the transfer switch metadata.
pdumodel::TransferSwitch::Parameters
map< string, int > Parameters
Transfer switch parameter map.
Definition: TransferSwitch.idl:206
pdumodel::TransferSwitch::TransferReason
TransferReason
Definition: TransferSwitch.idl:34
pdumodel::TransferSwitch::REASON_STARTUP
@ REASON_STARTUP
Startup or return to normal conditions.
Definition: TransferSwitch.idl:36
pdumodel::TransferSwitch::REASON_POWER_QUALITY
@ REASON_POWER_QUALITY
New inlet provided better power quality.
Definition: TransferSwitch.idl:40
pdumodel::TransferSwitch::REASON_UNKNOWN
@ REASON_UNKNOWN
Transfer reason unknown.
Definition: TransferSwitch.idl:35
pdumodel::TransferSwitch::REASON_OVERLOAD
@ REASON_OVERLOAD
Switched off due to overload alarm.
Definition: TransferSwitch.idl:41
pdumodel::TransferSwitch::REASON_MANUAL_TRANSFER
@ REASON_MANUAL_TRANSFER
Manual transfer.
Definition: TransferSwitch.idl:37
pdumodel::TransferSwitch::REASON_POWER_FAILURE
@ REASON_POWER_FAILURE
Previous inlet power failed.
Definition: TransferSwitch.idl:39
pdumodel::TransferSwitch::REASON_OVERHEAT
@ REASON_OVERHEAT
Switched off due to overheat alarm.
Definition: TransferSwitch.idl:42
pdumodel::TransferSwitch::REASON_AUTO_RETRANSFER
@ REASON_AUTO_RETRANSFER
Automatic retransfer.
Definition: TransferSwitch.idl:38
pdumodel::TransferSwitch::getTransferLog
vector< TransferLogEntry > getTransferLog()
Retrieve the transfer log.
pdumodel::TransferSwitch::setSettings
int setSettings(in Settings settings)
Change the transfer switch settings.
sensors::NumericSensor
A sensor with numeric readings.
Definition: NumericSensor.idl:17
sensors::StateSensor
Sensor with discrete readings.
Definition: StateSensor.idl:43
pdumodel
PDU Model.
Definition: Ade.idl:12
sensors
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
pdumodel::Nameplate
Component nameplate information.
Definition: Nameplate.idl:23
pdumodel::Rating
Numerical usage ratings.
Definition: Nameplate.idl:15
pdumodel::TransferSwitch::MetaData
Transfer switch metadata.
Definition: TransferSwitch.idl:47
pdumodel::TransferSwitch::MetaData::namePlate
Nameplate namePlate
Nameplate information
Definition: TransferSwitch.idl:49
pdumodel::TransferSwitch::MetaData::type
Type type
Transfer switch type.
Definition: TransferSwitch.idl:51
pdumodel::TransferSwitch::MetaData::rating
Rating rating
Numerical usage ratings.
Definition: TransferSwitch.idl:50
pdumodel::TransferSwitch::MetaData::label
string label
Transfer switch label.
Definition: TransferSwitch.idl:48
pdumodel::TransferSwitch::MetaData::sourceCount
int sourceCount
Number of sources.
Definition: TransferSwitch.idl:52
pdumodel::TransferSwitch::Sensors
Transfer switch sensors.
Definition: TransferSwitch.idl:68
pdumodel::TransferSwitch::Sensors::operationalState
sensors::StateSensor operationalState
Operational state sensor (off, normal, standby)
Definition: TransferSwitch.idl:70
pdumodel::TransferSwitch::Sensors::switchFault
sensors::StateSensor switchFault
Switch fault (ok, open, short)
Definition: TransferSwitch.idl:75
pdumodel::TransferSwitch::Sensors::overloadAlarm
sensors::StateSensor overloadAlarm
Overload alarm.
Definition: TransferSwitch.idl:73
pdumodel::TransferSwitch::Sensors::selectedBypassSource
sensors::StateSensor selectedBypassSource
Selected source in bypass module.
Definition: TransferSwitch.idl:76
pdumodel::TransferSwitch::Sensors::phaseSyncAlarm
sensors::StateSensor phaseSyncAlarm
Source phases out of sync.
Definition: TransferSwitch.idl:74
pdumodel::TransferSwitch::Sensors::sourceVoltagePhaseSyncAngle
sensors::NumericSensor sourceVoltagePhaseSyncAngle
Maximum phase difference between two sources.
Definition: TransferSwitch.idl:71
pdumodel::TransferSwitch::Sensors::selectedSource
sensors::StateSensor selectedSource
Selected source sensor.
Definition: TransferSwitch.idl:69
pdumodel::TransferSwitch::SettingsChangedEvent
Event: Transfer switch settings have been changed.
Definition: TransferSwitch.idl:101
pdumodel::TransferSwitch::SettingsChangedEvent::oldSettings
Settings oldSettings
Settings before change.
Definition: TransferSwitch.idl:102
pdumodel::TransferSwitch::SettingsChangedEvent::newSettings
Settings newSettings
Settings after change.
Definition: TransferSwitch.idl:103
pdumodel::TransferSwitch::Settings
Transfer switch settings.
Definition: TransferSwitch.idl:81
pdumodel::TransferSwitch::Settings::autoRetransfer
boolean autoRetransfer
Enable automatic retransfer if power on active inlet is restored.
Definition: TransferSwitch.idl:85
pdumodel::TransferSwitch::Settings::phaseSyncSensorEnabled
boolean phaseSyncSensorEnabled
False to force the 'phaseSyncAlarm' sensor to unavailable.
Definition: TransferSwitch.idl:89
pdumodel::TransferSwitch::Settings::name
string name
User-defined name.
Definition: TransferSwitch.idl:82
pdumodel::TransferSwitch::Settings::preferredSource
int preferredSource
Preferred inlet.
Definition: TransferSwitch.idl:84
pdumodel::TransferSwitch::Settings::autoRetransferWaitTime
int autoRetransferWaitTime
Time (in s) to delay retransfer after power restoration.
Definition: TransferSwitch.idl:87
pdumodel::TransferSwitch::Settings::manualTransferEnabled
boolean manualTransferEnabled
Enable state of 'manual transfer' front panel button.
Definition: TransferSwitch.idl:88
pdumodel::TransferSwitch::Settings::noAutoRetransferIfPhaseFault
boolean noAutoRetransferIfPhaseFault
Don't automatically retransfer if inlet phases are out of sync.
Definition: TransferSwitch.idl:86
pdumodel::TransferSwitch::Statistics
Transfer switch statistics.
Definition: TransferSwitch.idl:93
pdumodel::TransferSwitch::Statistics::totalTransferTime
int totalTransferTime
Total time in us for last transfer.
Definition: TransferSwitch.idl:97
pdumodel::TransferSwitch::Statistics::transferCount
int transferCount
Number of transfers since device startup.
Definition: TransferSwitch.idl:94
pdumodel::TransferSwitch::Statistics::powerFailDetectTime
int powerFailDetectTime
Detection time in us for the last inlet power failure.
Definition: TransferSwitch.idl:95
pdumodel::TransferSwitch::Statistics::relayOpenTime
int relayOpenTime
Time in us until all relays have opened during the last transfer.
Definition: TransferSwitch.idl:96
pdumodel::TransferSwitch::TransferLogEntry
Transfer log entry.
Definition: TransferSwitch.idl:182
pdumodel::TransferSwitch::TransferLogEntry::waveform
Waveform waveform
Voltage and current waveforms.
Definition: TransferSwitch.idl:187
pdumodel::TransferSwitch::TransferLogEntry::oldInlet
int oldInlet
Active inlet before transfer (0 for none)
Definition: TransferSwitch.idl:184
pdumodel::TransferSwitch::TransferLogEntry::switchFault
int switchFault
Switch fault status.
Definition: TransferSwitch.idl:189
pdumodel::TransferSwitch::TransferLogEntry::newInlet
int newInlet
Active inlet after transfer (0 for none)
Definition: TransferSwitch.idl:185
pdumodel::TransferSwitch::TransferLogEntry::reason
TransferReason reason
Transfer reason.
Definition: TransferSwitch.idl:186
pdumodel::TransferSwitch::TransferLogEntry::timestamp
time timestamp
Time of the transfer (UNIX timestamp, UTC)
Definition: TransferSwitch.idl:183
pdumodel::TransferSwitch::TransferLogEntry::statistics
Statistics statistics
Transfer statistics.
Definition: TransferSwitch.idl:188
pdumodel::Waveform
Waveform data, including metadata.
Definition: Waveform.idl:12