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

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
64 /* Bitmask values for switch fault sensors */
65 constant int SWITCH_FAULT_I1_SHORT = 1; ///< Inlet 1 switch is permanently closed
66 constant int SWITCH_FAULT_I1_OPEN = 2; ///< Inlet 1 switch is permanently open
67 constant int SWITCH_FAULT_I2_SHORT = 4; ///< Inlet 2 switch is permanently closed
68 constant int SWITCH_FAULT_I2_OPEN = 8; ///< Inlet 2 switch is permanently open
69
70 /** Transfer switch sensors */
71 structure Sensors {
72 sensors.StateSensor selectedSource; ///< Selected source sensor
73 sensors.StateSensor operationalState; ///< Operational state sensor (off, normal, standby)
74 sensors.NumericSensor sourceVoltagePhaseSyncAngle;
75 ///< Maximum phase difference between two sources
76 sensors.StateSensor overloadAlarm; ///< Overload alarm
77 sensors.StateSensor phaseSyncAlarm; ///< Source phases out of sync
78 sensors.StateSensor switchFault; ///< Switch fault (ok, open, short)
79 TransferSwitchBypassStateSensor bypassState;
80 };
81
82 /** Transfer switch settings */
83 [sparse_in]
84 structure Settings {
85 string name; ///< User-defined name
86
87 int preferredSource; ///< Preferred inlet
88 boolean autoRetransfer; ///< Enable automatic retransfer if power on active inlet is restored
89 boolean noAutoRetransferIfPhaseFault; ///< Don't automatically retransfer if inlet phases are out of sync
90 int autoRetransferWaitTime; ///< Time (in s) to delay retransfer after power restoration
91 boolean manualTransferEnabled; ///< Enable state of 'manual transfer' front panel button
92 boolean phaseSyncSensorEnabled; ///< False to force the 'phaseSyncAlarm' sensor to unavailable
93 };
94
95 /** Transfer switch statistics */
96 structure Statistics {
97 int transferCount; ///< Number of transfers since device startup
98 int powerFailDetectTime; ///< Detection time in us for the last inlet power failure
99 int relayOpenTime; ///< Time in us until all relays have opened during the last transfer
100 int totalTransferTime; ///< Total time in us for last transfer
101 };
102
103 /** Event: Transfer switch settings have been changed */
104 valueobject SettingsChangedEvent extends event.UserEvent {
105 Settings oldSettings; ///< Settings before change
106 Settings newSettings; ///< Settings after change
107 };
108
109 /**
110 * Retrieve the transfer switch metadata.
111 *
112 * @return Transfer switch metadata
113 */
114 MetaData getMetaData();
115
116 /**
117 * Get the transfer switch sensors.
118 *
119 * @return Transfer switch sensors
120 */
121 Sensors getSensors();
122
123 /**
124 * Get the list of transfer switch poles.
125 *
126 * @return List of poles
127 */
128 vector<ThrowPole> getPoles();
129
130 /**
131 * Retrieve the transfer switch settings.
132 *
133 * @return Transfer switch settings
134 */
135 Settings getSettings();
136
137 /**
138 * Change the transfer switch settings.
139 *
140 * @return 0 if OK
141 * @return 1 if any parameters are invalid
142 *
143 * @note The Settings structure can be "sparse"; fields missing in the
144 * JSON representation will remain unchanged.
145 */
146 int setSettings(in Settings settings);
147
148 /**
149 * Retrieve the transfer switch statistics.
150 *
151 * @return Transfer switch statistics
152 */
153 Statistics getStatistics();
154
155 /**
156 * Select the active inlet. If the new inlet is available,
157 * it will become both active and preferred.
158 *
159 * @param source New active inlet index
160 * @param faultOverride Force switch even if the phase sync angle
161 * between the inputs is too large
162 *
163 * @return 0 if OK
164 * @return ERR_INVALID_PARAM if the selected source is invalid
165 * @return ERR_SWITCH_PREVENTED if switching failed due to an alarm that may be overridden
166 * @return ERR_SWITCH_FAILED if switching failed and no override is possible
167 */
168 int transferToSource(in int source, in boolean faultOverride);
169
170 /**
171 * Get the reason for the last transfer.
172 *
173 * @return Last transfer reason
174 */
175 TransferReason getLastTransferReason();
176
177 /**
178 * Get the voltage and current waveforms during the last transfer.
179 *
180 * @return Waveform samples
181 */
182 Waveform getLastTransferWaveform();
183
184 /** Transfer log entry */
185 structure TransferLogEntry {
186 time timestamp; ///< Time of the transfer (UNIX timestamp, UTC)
187 int oldInlet; ///< Active inlet before transfer (0 for none)
188 int newInlet; ///< Active inlet after transfer (0 for none)
189 TransferReason reason; ///< Transfer reason
190 Waveform waveform; ///< Voltage and current waveforms
191 Statistics statistics; ///< Transfer statistics
192 int switchFault; ///< Switch fault status
193 };
194
195 /**
196 * Retrieve the transfer log.
197 *
198 * @return Transfer log
199 */
200 vector<TransferLogEntry> getTransferLog();
201
202 /**
203 * Transfer switch parameter map.
204 *
205 * The set of parameters, their meaning and allowed set of values are
206 * technology-dependent and subject to change. Do not modify any values
207 * without instruction from Raritan!
208 */
209 typedef map<string, int> Parameters;
210
211 /**
212 * Retrieve the transfer switch parameters.
213 *
214 * @return Parameters map
215 */
216 Parameters getParameters();
217
218 /**
219 * Update one or more transfer switch parameters.
220 *
221 * @param parameters Map of transfer switch parameters. Parameters
222 * which are not in the map remain unchanged.
223 *
224 * @return 0 if OK
225 * @return ERR_INVALID_PARAM if any parameter is invalid
226 */
227 int setParameters(in Parameters parameters);
228
229 };
230
231}
232
233#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:209
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 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: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:71
pdumodel::TransferSwitch::Sensors::operationalState
sensors::StateSensor operationalState
Operational state sensor (off, normal, standby)
Definition TransferSwitch.idl:73
pdumodel::TransferSwitch::Sensors::switchFault
sensors::StateSensor switchFault
Switch fault (ok, open, short)
Definition TransferSwitch.idl:78
pdumodel::TransferSwitch::Sensors::overloadAlarm
sensors::StateSensor overloadAlarm
Overload alarm.
Definition TransferSwitch.idl:76
pdumodel::TransferSwitch::Sensors::phaseSyncAlarm
sensors::StateSensor phaseSyncAlarm
Source phases out of sync.
Definition TransferSwitch.idl:77
pdumodel::TransferSwitch::Sensors::sourceVoltagePhaseSyncAngle
sensors::NumericSensor sourceVoltagePhaseSyncAngle
Maximum phase difference between two sources.
Definition TransferSwitch.idl:74
pdumodel::TransferSwitch::Sensors::selectedSource
sensors::StateSensor selectedSource
Selected source sensor.
Definition TransferSwitch.idl:72
pdumodel::TransferSwitch::SettingsChangedEvent
Event: Transfer switch settings have been changed.
Definition TransferSwitch.idl:104
pdumodel::TransferSwitch::SettingsChangedEvent::oldSettings
Settings oldSettings
Settings before change.
Definition TransferSwitch.idl:105
pdumodel::TransferSwitch::SettingsChangedEvent::newSettings
Settings newSettings
Settings after change.
Definition TransferSwitch.idl:106
pdumodel::TransferSwitch::Settings
Transfer switch settings.
Definition TransferSwitch.idl:84
pdumodel::TransferSwitch::Settings::autoRetransfer
boolean autoRetransfer
Enable automatic retransfer if power on active inlet is restored.
Definition TransferSwitch.idl:88
pdumodel::TransferSwitch::Settings::phaseSyncSensorEnabled
boolean phaseSyncSensorEnabled
False to force the 'phaseSyncAlarm' sensor to unavailable.
Definition TransferSwitch.idl:92
pdumodel::TransferSwitch::Settings::name
string name
User-defined name.
Definition TransferSwitch.idl:85
pdumodel::TransferSwitch::Settings::preferredSource
int preferredSource
Preferred inlet.
Definition TransferSwitch.idl:87
pdumodel::TransferSwitch::Settings::autoRetransferWaitTime
int autoRetransferWaitTime
Time (in s) to delay retransfer after power restoration.
Definition TransferSwitch.idl:90
pdumodel::TransferSwitch::Settings::manualTransferEnabled
boolean manualTransferEnabled
Enable state of 'manual transfer' front panel button.
Definition TransferSwitch.idl:91
pdumodel::TransferSwitch::Settings::noAutoRetransferIfPhaseFault
boolean noAutoRetransferIfPhaseFault
Don't automatically retransfer if inlet phases are out of sync.
Definition TransferSwitch.idl:89
pdumodel::TransferSwitch::Statistics
Transfer switch statistics.
Definition TransferSwitch.idl:96
pdumodel::TransferSwitch::Statistics::totalTransferTime
int totalTransferTime
Total time in us for last transfer.
Definition TransferSwitch.idl:100
pdumodel::TransferSwitch::Statistics::transferCount
int transferCount
Number of transfers since device startup.
Definition TransferSwitch.idl:97
pdumodel::TransferSwitch::Statistics::powerFailDetectTime
int powerFailDetectTime
Detection time in us for the last inlet power failure.
Definition TransferSwitch.idl:98
pdumodel::TransferSwitch::Statistics::relayOpenTime
int relayOpenTime
Time in us until all relays have opened during the last transfer.
Definition TransferSwitch.idl:99
pdumodel::TransferSwitch::TransferLogEntry
Transfer log entry.
Definition TransferSwitch.idl:185
pdumodel::TransferSwitch::TransferLogEntry::waveform
Waveform waveform
Voltage and current waveforms.
Definition TransferSwitch.idl:190
pdumodel::TransferSwitch::TransferLogEntry::oldInlet
int oldInlet
Active inlet before transfer (0 for none)
Definition TransferSwitch.idl:187
pdumodel::TransferSwitch::TransferLogEntry::switchFault
int switchFault
Switch fault status.
Definition TransferSwitch.idl:192
pdumodel::TransferSwitch::TransferLogEntry::newInlet
int newInlet
Active inlet after transfer (0 for none)
Definition TransferSwitch.idl:188
pdumodel::TransferSwitch::TransferLogEntry::reason
TransferReason reason
Transfer reason.
Definition TransferSwitch.idl:189
pdumodel::TransferSwitch::TransferLogEntry::timestamp
time timestamp
Time of the transfer (UNIX timestamp, UTC)
Definition TransferSwitch.idl:186
pdumodel::TransferSwitch::TransferLogEntry::statistics
Statistics statistics
Transfer statistics.
Definition TransferSwitch.idl:191
pdumodel::Waveform
Waveform data, including metadata.
Definition Waveform.idl:12