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