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

Loading...
Searching...
No Matches
PDU Data Model

The root object for the PDU data model is the pdumodel.Pdu interface which can be found at the well-known URI `/model/pdu/0`. The PDU object holds a number of inlets, overcurrent protectors, outlets, which can be retrieved with the getInlets, getOverCurrentProtectors and getOutlets methods. Alternatively those objects have well-known URIs like `/model/inlet/0`.

All data models have a similar set of properties:

- Metadata: Static (immutable) data describing the object, like labels, plug types or ratings. Can be retrieved with the getMetaData method.
- Settings: User-configurable settings like names or cycle delays. Can be retrieved with getSettings and written with setSettings.
- Sensors: A structure holding references to sensors measuring electrical quantities of the object, e.g. the actual current flow. Can be retrieved with getSensors.
- Poles: A list of structures holding references to sensors measuring electrical quantities of individual phases. Can be retrieved with getPoles.

# Relationships Between Objects

Objects in the PDU model are associated in various ways:

- The PDU holds lists of inlets, overcurrent protectors and outlets.
- An overcurrent protector is related to an inlet. This information can be important for models with multiple inlets and can be queried with getInlets. Also, in rare cases an overcurrent protector may be protected by a higher-level OCP. In this case this association can be queried with getOCP.
- An outlet is related to an inlet and, in most cases, protected by an OCP. Both references are returned by the getIOP method.

Note
  In case of models with transfer switch (PX3TS/PX4TS series), OCPs and outlets always reference the first inlet. The reference is not updated on transfer.

Additionally, inlets, OCPs and outlets implement the EDevice interface which defines a bi-directional parent-child relationship between devices, where being a parent means supplying power to another device. These relationships can be queried with the getParents and getChildren methods which both return vectors of other EDevice instances.

- Inlets never have parents (i.e., getParents returns an empty list) and have multiple children (typically OCPs, sometimes outlets).
- OCPs have exactly one parent and multiple children (typically outlets, sometimes other OCPs).
- Outlets have exactly one parent and no children.
- The only device with more than one parent is a TransferSwitch.

# Retrieving Sensor Readings

## Single-Phase Inlets and Outlets

All sensor references for single-phase inlets and outlets can be retrieved with the getSensors methods. They have no pole sensors for individual phases.

The following sensors are supported for inlets and metered outlets. Depending on the PDU model not all sensors may be available:

- voltage: RMS voltage (A)
- voltageThd: Voltage THD (%)
- lineFrequency: Line frequency (Hz)
- current: RMS current (V)
- currentThd: Current THD (%)
- activePower: Active power (W)
- reactivePower: Reactive power (var)
- apparentPower: Apparent power (VA)
- powerFactor: Total power factor (no unit)
- displacementPowerFactor: Power factor due to phase shift (no unit)
- crestFactor: Total crest factor (no unit)
- phaseAngle: Phase angle between voltage and current (degrees)
- activeEnergy: Active energy counter (Wh)
- apparentEnergy: Apparent energy counter (VAh)
- residualCurrent: Residual current (A)

# Python example: Display all outlet energy counters
import raritan.rpc.pdumodel
pdu = pdumodel.Pdu("/model/pdu/0", agent)
for outlet in pdu.getOutlets():
energy_sensor = outlet.getSensors().activeEnergy
print("%d Wh" % energy_sensor.getReading().value)
pdumodel::Pdu
Main PDU interface.
Definition Pdu.idl:29

## Three-Phase Inlets and Outlets

Three-phase inlets and outlets have both global sensors (getSensors) and individual phase sensors (getPoles). Readings for most global sensors are a combination of the phase readings:

- The inlet/outlet voltage reading is the minimum of the line-line voltages.
- The inlet/outlet current reading is the maximum of the line currents.
- Inlet/outlet power and energy readings are the sum of line powers and energy counters.
- unbalancedCurrent is the maximum difference (in percent) between the three phase current readings and the average current reading.

Poles of three phase inlets and outlets have two voltage sensors:

- voltage is the voltage between this phase and the next, e.g. the voltage sensor of the L1 pole returns the L1-L2 voltage.
- voltageLN is the voltage between the phase and the neutral/earth potential.

# Python example: Display three-phase inlet voltages
import raritan.rpc.pdumodel
inlet = pdumodel.Inlet("/model/inlet/0", agent)
poles = inlet.getPoles()
ll = [ pole.voltage.getReading().value for pole in poles[0:3] ]
print("L1-L2=%.1fV, L2-L3=%.1fV, L3-L1=%.1fV" % (ll[0], ll[1], ll[2]))
ln = [ pole.voltageLN.getReading().value for pole in poles[0:3] ]
print("L1-N=%.1fV, L2-N=%.1fV, L3-N=%.1fV" % (ln[0], ln[1], ln[2]))
pdumodel::Inlet
Inlet interface
Definition Inlet.idl:22

# Switching Outlets

Individual outlets can be switched or power-cycled using the following methods:

- Outlet.setPowerState: Switches an individual outlet on or off
- Outlet.cyclePowerState: Power-cycles an individual outlet
- Pdu.setMultipleOutletPowerStates: Switches a given list of outlets
- Pdu.cycleMultipleOutletPowerStates: Power-cycles a list of outlets
- Pdu.setAllOutletPowerStates: Switches all outlets
- Pdu.powerCycleAllOutletPowerStates: Power-cycles all outlet

## Sequencing

The outlet sequence defines the order in which multiple outlets are switched on and the interval between switch operations. The sequence is used with the following methods:

- setAllOutletPowerStates and cycleAllOutletPowerStates
- setMultipleOutletPowerStates and cycleMultipleOutletPowerStates, if the respectSequence parameter is `true`

The sequence is configured in the settings structures of the PDU and all outlets:

- The outletPowerStateSequence field in the PDU settings contains a list of 0-based outlet indexes and defines the order in which outlets are switched on. It can either be an empty list (no sequence defined) or a list that contains each outlet index exactly once.
- The sequenceDelay field in the outlet settings defines the interval to wait before advancing the sequence after switching that outlet.

# Python example: Switch outlets in reverse order with a 2-second delay
import raritan.rpc.pdumodel
pdu = pdumodel.Pdu("/model/pdu/0", agent)
outlets = pdu.getOutlets()
# Set outletPowerStateSequence to reverse outlet order:
sequence = range(0, len(outlets))
sequence.reverse()
pdu_settings = pdu.getSettings()
pdu_settings.outletPowerStateSequence = sequence
pdu.setSettings(pdu_settings)
# Set sequence delay for all outlets to 2000 milliseconds:
for outlet in outlets:
outlet_settings = outlet.getSettings()
outlet_settings.sequenceDelay = 2000
outlet.setSettings(outlet_settings)
# Power-cycle all outlets
pdu.cycleAllOutletPowerStates()