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