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)
71  ///< Maximum phase difference between two sources
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
int newInlet
Active inlet after transfer (0 for none)
Definition: TransferSwitch.idl:187
Static transfer switch (using SCRs as switch technology)
Definition: TransferSwitch.idl:28
Transfer log entry.
Definition: TransferSwitch.idl:184
Type type
Transfer switch type.
Definition: TransferSwitch.idl:50
New inlet provided better power quality.
Definition: TransferSwitch.idl:39
Type
Transfer switch type.
Definition: TransferSwitch.idl:27
boolean manualTransferEnabled
Enable state of &#39;manual transfer&#39; front panel button.
Definition: TransferSwitch.idl:85
Automatic retransfer.
Definition: TransferSwitch.idl:37
int relayOpenTime
Time in us until all relays have opened during the last transfer.
Definition: TransferSwitch.idl:92
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
Startup or return to normal conditions.
Definition: TransferSwitch.idl:35
sensors::StateSensor_4_0_3 operationalState
Operational state sensor (off, normal, standby)
Definition: TransferSwitch.idl:69
Settings newSettings
Settings after change.
Definition: TransferSwitch.idl:105
Transfer reason unknown.
Definition: TransferSwitch.idl:34
int powerFailDetectTime
Detection time in us for the last inlet power failure.
Definition: TransferSwitch.idl:91
Nameplate_2_0_0 namePlate
Nameplate information
Definition: TransferSwitch.idl:48
Component nameplate information.
Definition: Nameplate.idl:23
Sample of voltage and current waveform.
Definition: TransferSwitch.idl:97
double voltage
Voltage sample in Volts.
Definition: TransferSwitch.idl:98
Statistics statistics
Transfer statistics.
Definition: TransferSwitch.idl:190
Rating_2_0_0 rating
Numerical usage ratings.
Definition: TransferSwitch.idl:49
sensors::NumericSensor_4_0_3 sourceVoltagePhaseSyncAngle
Maximum phase difference between two sources.
Definition: TransferSwitch.idl:70
Transfer switch statistics.
Definition: TransferSwitch.idl:89
Switched off due to overload alarm.
Definition: TransferSwitch.idl:40
sensors::StateSensor_4_0_3 phaseSyncAlarm
Source phases out of sync.
Definition: TransferSwitch.idl:73
Switched off due to overheat alarm.
Definition: TransferSwitch.idl:41
string label
Transfer switch label.
Definition: TransferSwitch.idl:47
int totalTransferTime
Total time in us for last transfer.
Definition: TransferSwitch.idl:93
int sourceCount
Number of sources.
Definition: TransferSwitch.idl:51
sensors::StateSensor_4_0_3 selectedSource
Selected source sensor.
Definition: TransferSwitch.idl:68
double current
Current sample in Amperes.
Definition: TransferSwitch.idl:99
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
boolean autoRetransfer
Enable automatic retransfer if power on active inlet is restored.
Definition: TransferSwitch.idl:82
int autoRetransferWaitTime
Time (in s) to delay retransfer after power restoration.
Definition: TransferSwitch.idl:84
Transfer switch settings.
Definition: TransferSwitch.idl:78
PDU Model.
Definition: Ade.idl:12
TransferReason reason
Transfer reason.
Definition: TransferSwitch.idl:188
int preferredSource
Preferred inlet.
Definition: TransferSwitch.idl:81
Transfer switch sensors.
Definition: TransferSwitch.idl:67
int transferCount
Number of transfers since device startup.
Definition: TransferSwitch.idl:90
sensors::StateSensor_4_0_3 switchFault
Switch fault (ok, open, short)
Definition: TransferSwitch.idl:74
int oldInlet
Active inlet before transfer (0 for none)
Definition: TransferSwitch.idl:186
map< string, int > Parameters
Transfer switch parameter map.
Definition: TransferSwitch.idl:208
Manual transfer.
Definition: TransferSwitch.idl:36
sensors::StateSensor_4_0_3 overloadAlarm
Overload alarm.
Definition: TransferSwitch.idl:72
Asynchronous transfer switch (using relays)
Definition: TransferSwitch.idl:29
vector< WaveformSample > waveform
Voltage and current waveforms.
Definition: TransferSwitch.idl:189
A sensor with numeric readings.
Definition: NumericSensor.idl:17
TransferReason
Definition: TransferSwitch.idl:33
Numerical usage ratings.
Definition: Nameplate.idl:15
Sensor with discrete readings.
Definition: StateSensor.idl:43
boolean noAutoRetransferIfPhaseFault
Don&#39;t automatically retransfer if inlet phases are out of sync.
Definition: TransferSwitch.idl:83
time timestamp
Time of the transfer.
Definition: TransferSwitch.idl:185
Transfer switch interface.
Definition: TransferSwitch.idl:20
Transfer switch metadata.
Definition: TransferSwitch.idl:46
Previous inlet power failed.
Definition: TransferSwitch.idl:38
string name
User-defined name.
Definition: TransferSwitch.idl:79
int switchFault
Switch fault status.
Definition: TransferSwitch.idl:191