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

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