Raritan PX2/PX3 JSON-RPC API
Outlet.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3  * Copyright 2009 Raritan Inc. All rights reserved.
4  */
5 
6 #ifndef __PDUMODEL_OUTLET_IDL__
7 #define __PDUMODEL_OUTLET_IDL__
8 
9 #include <Nameplate.idl>
10 #include <NumericSensor.idl>
11 #include <StateSensor.idl>
12 #include <Pole.idl>
13 #include <Inlet.idl>
14 #include <OverCurrentProtector.idl>
15 #include <Controller.idl>
16 
17 /**
18  * PDU Model
19  */
20 module pdumodel {
21 
22  /** %Outlet statistics */
23  structure OutletStatistic {
24  int relayCycleCnt; ///< Relay switch count
25  int relayFailCnt; ///< Relay failure count
26  };
27 
28  /** %Outlet interface */
29  interface Outlet_2_1_9 extends EDevice {
30 
31  constant int ERR_OUTLET_NOT_SWITCHABLE = 1; ///< Outlet is not switchable
32  constant int ERR_LOAD_SHEDDING_ACTIVE = 2; ///< Load-shedding is enabled (deprecated)
33  constant int ERR_OUTLET_DISABLED = 3; ///< Outlet is disabled
34  constant int ERR_OUTLET_NOT_OFF = 4; ///< Outlet is on or in power-cylce; unstick not possible
35 
36  constant int ERR_INVALID_PARAM = 1; ///< Invalid parameters
37 
38  /** %Outlet metadata */
39  structure MetaData {
40  string label; ///< %Outlet label
41  string receptacleType; ///< Receptacle type
42  Nameplate_2_0_0 namePlate; ///< %Nameplate information
43  Rating_2_0_0 rating; ///< Numerical usage ratings
44  boolean isSwitchable; ///< \c true if the outlet is switchable
45  boolean isLatching; ///< \c true if the outlet is able to keep its state after power loss
46  int maxRelayCycleCnt; ///< Maximum relay cycle count
47  };
48 
49  /** %Outlet power state. Used both for switching and representing the current state */
50  enumeration PowerState {
51  PS_OFF, ///< Switch off / Power is off
52  PS_ON ///< Switch on / Power is on
53  };
54 
55  /** %Outlet LED state */
56  structure LedState {
57  boolean red; ///< \c true if the red LED is enabled
58  boolean green; ///< \c true if the green LED is enabled
59  boolean blinking; ///< \c true if the LED is blinking
60  };
61 
62  /** %Outlet state */
63  structure State {
64  boolean available; ///< powerState is available
65  PowerState powerState; ///< Current power state of outlet
66  ///< (represented by the control state of the relay, which
67  ///< was set by the last command sent to it)
68  boolean switchOnInProgress; ///< \c true if the outlet is pending to be switched on
69  ///< after the sequencing delay has passed.
70  boolean cycleInProgress; ///< \c if a power-cycle is in progress. The outlet will
71  ///< be switched on after the cycle delay has passed.
72  boolean isLoadShed; ///< \c true if the outlet is currently switched off due
73  ///< to being non-critical and load shedding being active
74  LedState ledState; ///< LED state
75  time lastPowerStateChange; ///< Time of last power state change (UNIX timestamp, UTC)
76  };
77 
78  /** %Outlet power state on device startup */
79  enumeration StartupState {
80  SS_ON, ///< %Outlet will be switched on
81  SS_OFF, ///< %Outlet will be switched off
82  SS_LASTKNOWN, ///< Last known power state will be restored
83  SS_PDUDEF ///< Use default state as defined in PDU settings
84  };
85 
86  /** %Outlet settings */
87  structure Settings {
88  string name; ///< User-defined name
89  StartupState startupState; ///< Power state on device startup
90  boolean usePduCycleDelay; ///< \c true to use power-cycle delay as defined in PDU settings
91  int cycleDelay; ///< %Outlet-specific power-cycle delay
92  boolean nonCritical; ///< \c true if outlet is non-critical (for load shedding)
93  int sequenceDelay; ///< Delay in ms after this outlet when switching multiple outlets on
94  };
95 
96  /** %Outlet sensors */
97  structure Sensors {
98  sensors.NumericSensor_4_0_4 voltage; ///< RMS voltage sensor
99  sensors.NumericSensor_4_0_4 current; ///< RMS current sensor
100  sensors.NumericSensor_4_0_4 peakCurrent; ///< Peak current sensor
101  sensors.NumericSensor_4_0_4 maximumCurrent; ///< Maximum current sensor
102  sensors.NumericSensor_4_0_4 unbalancedCurrent; ///< Current unbalance sensor
103  sensors.NumericSensor_4_0_4 activePower; ///< Active power sensor
104  sensors.NumericSensor_4_0_4 reactivePower; ///< Reactive power sensor
105  sensors.NumericSensor_4_0_4 apparentPower; ///< Apparent power sensor
106  sensors.NumericSensor_4_0_4 powerFactor; ///< Power factor sensor
107  sensors.NumericSensor_4_0_4 displacementPowerFactor;///< Displacement power factor sensor
108  sensors.NumericSensor_4_0_4 activeEnergy; ///< Active energy sensor
109  sensors.NumericSensor_4_0_4 apparentEnergy; ///< Apparent energy sensor
110  sensors.NumericSensor_4_0_4 phaseAngle; ///< Phase angle sensor
111  sensors.NumericSensor_4_0_4 lineFrequency; ///< AC line frequency sensor
112  sensors.NumericSensor_4_0_4 crestFactor; ///< Crest factor sensor
113  sensors.StateSensor_4_0_4 outletState; ///< %Outlet power state sensor
114  };
115 
116  /** Event: Power control was initiated */
117  valueobject PowerControlEvent extends event.UserEvent {
118  PowerState state; ///< State the outlet was switched to (if cycle is false)
119  boolean cycle; ///< Whether the outlet was cycled
120  };
121 
122  /** Event: Outlet state has changed */
123  valueobject StateChangedEvent extends idl.Event {
124  State oldState; ///< State before change
125  State newState; ///< State after change
126  };
127 
128  /** Event: Outlet settings have been changed */
129  valueobject SettingsChangedEvent extends event.UserEvent {
130  Settings oldSettings; ///< Settings before change
131  Settings newSettings; ///< Settings after change
132  };
133 
134  /**
135  * Retrieve the outlet metadata.
136  *
137  * @return %Outlet metadata
138  */
140 
141  /**
142  * Get the outlet sensors.
143  *
144  * @return %Outlet sensors
145  */
147 
148  /**
149  * Retrieve the outlet state.
150  *
151  * @return %Outlet state
152  */
154 
155  /**
156  * Switch the outlet.
157  *
158  * @param pstate New power state
159  *
160  * @return 0 if OK
161  * @return 1 if the outlet is not switchable
162  * @return 3 if the outlet is disabled
163  */
164  int setPowerState(in PowerState pstate);
165 
166  /**
167  * Power-cycle the outlet.
168  *
169  * @return 0 if OK
170  * @return 1 if the outlet is not switchable
171  * @return 3 if the outlet is disabled
172  */
174 
175  /**
176  * Retrieve the outlet settings.
177  *
178  * @return %Outlet settings
179  */
181 
182  /**
183  * Change the outlet settings.
184  *
185  * @param settings New outlet settings
186  *
187  * @return 0 if OK
188  * @return 1 if any parameters are invalid
189  */
190  int setSettings(in Settings settings);
191 
192  /**
193  * Get inlet, overcurrent protector and poles.
194  *
195  * @param i Result: %Inlet reference
196  * @param o Result: Overcurrent protector reference
197  * @param p Result: List of poles
198  */
199  void getIOP(out Inlet_2_0_7 i, out OverCurrentProtector_3_0_8 o, out vector<Pole_7_0_0> p);
200 
201  /**
202  * Get the controller for this outlet.
203  *
204  * @return Slave controller reference
205  */
207 
208  /**
209  * Trigger an attempt to un-stick sticking relay contacts
210  *
211  * Tries repairing relay contacts that are sticked together due to wear
212  * by switching the relay in a certain pattern.
213  * Prior to running this method, the outlet must be in 'off' state
214  * to acknowledge that loads were disconnected.
215  *
216  * @return 0 if unsticking was triggered successfully
217  * @return 1 if outlet is not switchable
218  * @return 3 if the outlet is disabled
219  * @return 4 if relay is in a power cycle or on
220  */
221  int unstick();
222  };
223 
224 }
225 
226 #endif
Slave controller interface.
Definition: Controller.idl:26
Common base interface for any kind of electrical device that is used in the PDU model,...
Definition: EDevice.idl:24
Inlet interface
Definition: Inlet.idl:22
Outlet interface
Definition: Outlet.idl:29
void getIOP(out Inlet_2_0_7 i, out OverCurrentProtector_3_0_8 o, out vector< Pole_7_0_0 > p)
Get inlet, overcurrent protector and poles.
State newState
State after change.
Definition: Outlet.idl:125
PowerState
Outlet power state.
Definition: Outlet.idl:50
@ PS_OFF
Switch off / Power is off.
Definition: Outlet.idl:51
Settings newSettings
Settings after change.
Definition: Outlet.idl:131
boolean cycle
Whether the outlet was cycled.
Definition: Outlet.idl:119
Controller_4_0_1 getController()
Get the controller for this outlet.
StartupState
Outlet power state on device startup
Definition: Outlet.idl:79
@ SS_LASTKNOWN
Last known power state will be restored.
Definition: Outlet.idl:82
@ SS_OFF
Outlet will be switched off
Definition: Outlet.idl:81
@ SS_ON
Outlet will be switched on
Definition: Outlet.idl:80
int setSettings(in Settings settings)
Change the outlet settings.
Sensors getSensors()
Get the outlet sensors.
State getState()
Retrieve the outlet state.
int cyclePowerState()
Power-cycle the outlet.
MetaData getMetaData()
Retrieve the outlet metadata.
int unstick()
Trigger an attempt to un-stick sticking relay contacts.
Settings getSettings()
Retrieve the outlet settings.
int setPowerState(in PowerState pstate)
Switch the outlet.
Overcurrent protector interface.
Definition: OverCurrentProtector.idl:27
A sensor with numeric readings.
Definition: NumericSensor.idl:17
Sensor with discrete readings.
Definition: StateSensor.idl:43
Basic IDL definitions.
Definition: Event.idl:10
PDU Model.
Definition: Ade.idl:12
Sensors Model.
Definition: AccumulatingNumericSensor.idl:13
Component nameplate information.
Definition: Nameplate.idl:23
Outlet statistics
Definition: Outlet.idl:23
int relayFailCnt
Relay failure count.
Definition: Outlet.idl:25
int relayCycleCnt
Relay switch count.
Definition: Outlet.idl:24
Outlet LED state
Definition: Outlet.idl:56
boolean blinking
true if the LED is blinking
Definition: Outlet.idl:59
boolean green
true if the green LED is enabled
Definition: Outlet.idl:58
boolean red
true if the red LED is enabled
Definition: Outlet.idl:57
Outlet metadata
Definition: Outlet.idl:39
string label
Outlet label
Definition: Outlet.idl:40
int maxRelayCycleCnt
Maximum relay cycle count.
Definition: Outlet.idl:46
Rating_2_0_0 rating
Numerical usage ratings.
Definition: Outlet.idl:43
boolean isSwitchable
true if the outlet is switchable
Definition: Outlet.idl:44
string receptacleType
Receptacle type.
Definition: Outlet.idl:41
Nameplate_2_0_0 namePlate
Nameplate information
Definition: Outlet.idl:42
boolean isLatching
true if the outlet is able to keep its state after power loss
Definition: Outlet.idl:45
Outlet sensors
Definition: Outlet.idl:97
sensors::NumericSensor_4_0_4 powerFactor
Power factor sensor.
Definition: Outlet.idl:106
sensors::StateSensor_4_0_4 outletState
Outlet power state sensor
Definition: Outlet.idl:113
sensors::NumericSensor_4_0_4 current
RMS current sensor.
Definition: Outlet.idl:99
sensors::NumericSensor_4_0_4 displacementPowerFactor
Displacement power factor sensor.
Definition: Outlet.idl:107
sensors::NumericSensor_4_0_4 apparentEnergy
Apparent energy sensor.
Definition: Outlet.idl:109
sensors::NumericSensor_4_0_4 unbalancedCurrent
Current unbalance sensor.
Definition: Outlet.idl:102
sensors::NumericSensor_4_0_4 phaseAngle
Phase angle sensor.
Definition: Outlet.idl:110
sensors::NumericSensor_4_0_4 crestFactor
Crest factor sensor.
Definition: Outlet.idl:112
sensors::NumericSensor_4_0_4 apparentPower
Apparent power sensor.
Definition: Outlet.idl:105
sensors::NumericSensor_4_0_4 peakCurrent
Peak current sensor.
Definition: Outlet.idl:100
sensors::NumericSensor_4_0_4 maximumCurrent
Maximum current sensor.
Definition: Outlet.idl:101
sensors::NumericSensor_4_0_4 activePower
Active power sensor.
Definition: Outlet.idl:103
sensors::NumericSensor_4_0_4 voltage
RMS voltage sensor.
Definition: Outlet.idl:98
sensors::NumericSensor_4_0_4 reactivePower
Reactive power sensor.
Definition: Outlet.idl:104
sensors::NumericSensor_4_0_4 lineFrequency
AC line frequency sensor.
Definition: Outlet.idl:111
sensors::NumericSensor_4_0_4 activeEnergy
Active energy sensor.
Definition: Outlet.idl:108
Outlet settings
Definition: Outlet.idl:87
StartupState startupState
Power state on device startup.
Definition: Outlet.idl:89
int sequenceDelay
Delay in ms after this outlet when switching multiple outlets on.
Definition: Outlet.idl:93
boolean nonCritical
true if outlet is non-critical (for load shedding)
Definition: Outlet.idl:92
int cycleDelay
Outlet-specific power-cycle delay
Definition: Outlet.idl:91
boolean usePduCycleDelay
true to use power-cycle delay as defined in PDU settings
Definition: Outlet.idl:90
string name
User-defined name.
Definition: Outlet.idl:88
Outlet state
Definition: Outlet.idl:63
boolean available
powerState is available
Definition: Outlet.idl:64
time lastPowerStateChange
Time of last power state change (UNIX timestamp, UTC)
Definition: Outlet.idl:75
boolean cycleInProgress
if a power-cycle is in progress.
Definition: Outlet.idl:70
boolean switchOnInProgress
true if the outlet is pending to be switched on after the sequencing delay has passed.
Definition: Outlet.idl:68
PowerState powerState
Current power state of outlet (represented by the control state of the relay, which was set by the la...
Definition: Outlet.idl:65
boolean isLoadShed
true if the outlet is currently switched off due to being non-critical and load shedding being active
Definition: Outlet.idl:72
LedState ledState
LED state.
Definition: Outlet.idl:74
Numerical usage ratings.
Definition: Nameplate.idl:15