ShelfPowerSupply.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2025 Raritan Inc. All rights reserved.
 */
 
#ifndef __PDUMODEL_SHELF_POWER_SUPPLY_IDL__
#define __PDUMODEL_SHELF_POWER_SUPPLY_IDL__
 
#include <Controller.idl>
#include <EDevice.idl>
#include <NumericSensor.idl>
#include <Pole.idl>
 
/**
 * PDU Model
 */
module pdumodel {
 
    /** Shelf power supply interface */
    interface ShelfPowerSupply extends EDevice {
 
        constant int ERR_OPERATION_NOT_SUPPORTED = 1;
        constant int ERR_INVALID_ARGUMENT = 2;
 
        /** Power supply metadata */
        structure MetaData {
            string slotLabel;                   ///< Label of PSU slot the PSU is plugged into
            string manufacturer;                ///< PSU manufacturer
            string model;                       ///< PSU model
            string serialNumber;                ///< PSU serial number
            string firmwareVersion;             ///< PSU firmware version (in PSU specific format)
            string productionDate;              ///< Production date of PSU (in PSU specific format)
            string hardwareRevision;            ///< Hardware revision of PDU (in PSU specific format)
            int maxOutputPower;                 ///< Maximum output power of PSU (in W)
            boolean hotplugSupported;           ///< PSU can be removed or inserted while shelf is powered
            boolean powerControlSupported;      ///< PSU can be turned on or off
            boolean fanSpeedControlSupported;   ///< Fan speed of PSU can be controlled
            int ratedLoad;                      ///< Load (in percent) at which efficiency is determined (0 if unsupported)
            int efficiencyPercent;              ///< Efficiency (in percent) at rated load (0 if unsupported)
        };
 
        /** Power supply power state. Used both for switching and representing the current state */
        enumeration PowerState {
            PS_OFF,                             ///< Turn off / Power is off
            PS_ON                               ///< Turn on / Power is on
        };
 
        /** Power supply state */
        structure State {
            boolean available;                  ///< State reading is valid
            boolean isPresent;                  ///< PSU is plugged into the slot
            PowerState powerState;              ///< Current power state of PSU (always PS_ON if power control is not supported)
            int fanSpeedOverridePercent;        ///< Current PSU fan speed override (in %); 0 if fan speed is not overridden
            boolean hasPendingFault;            ///< Whether any of the fault sensors of this power supply reports a non-normal state
        };
 
        /* State values for fault state sensors */
        constant int FAULT_STATE_NO_FAULT = 0; ///< No fault is present
        constant int FAULT_STATE_WARNING  = 1; ///< Warning indicator active
        constant int FAULT_STATE_CRITICAL = 2; ///< Critical indicator active
 
        /** Power supply input (AC) sensors */
        structure InputSensors {
            sensors.NumericSensor voltage;                ///< RMS voltage sensor
            sensors.NumericSensor current;                ///< RMS current sensor
            sensors.NumericSensor peakCurrent;            ///< Peak current sensor
            sensors.NumericSensor unbalancedCurrent;      ///< Current unbalance sensor
            sensors.NumericSensor activePower;            ///< Active power sensor
            sensors.NumericSensor reactivePower;          ///< Reactive power sensor
            sensors.NumericSensor apparentPower;               ///< Apparent power sensor
            sensors.NumericSensor powerFactor;            ///< Power factor sensor
            sensors.NumericSensor displacementPowerFactor;///< Displacement power factor sensor
            sensors.NumericSensor activeEnergy;           ///< Active energy sensor
            sensors.NumericSensor apparentEnergy;             ///< Apparent energy sensor
            sensors.NumericSensor phaseAngle;             ///< Phase angle sensor
            sensors.NumericSensor lineFrequency;               ///< AC line frequency sensor
            sensors.NumericSensor crestFactor;           ///< Crest factor sensor
            sensors.NumericSensor voltageThd;             ///< Voltage total harmonic distortion sensor
            sensors.NumericSensor currentThd;             ///< Current total harmonic distortion sensor
            sensors.StateSensor overCurrentFault;         ///< Input over current fault (as reported by PSU) sensor
            sensors.StateSensor underVoltageFault;        ///< Input under voltage fault (as reported by PSU) sensor
            sensors.StateSensor overVoltageFault;         ///< Input over voltage fault (as reported by PSU) sensor
        };
 
        /** Power supply output (DC) sensors */
        structure OutputSensors {
            sensors.NumericSensor voltage;                ///< Voltage sensor
            sensors.NumericSensor current;                ///< Current sensor
            sensors.NumericSensor activePower;            ///< Active power sensor
            sensors.NumericSensor activeEnergy;           ///< Active energy sensor
            sensors.StateSensor overCurrentFault;         ///< Output over current fault (as reported by PSU) sensor
            sensors.StateSensor underVoltageFault;        ///< Output under voltage fault (as reported by PSU) sensor
            sensors.StateSensor overVoltageFault;         ///< Output over voltage fault (as reported by PSU) sensor
        };
 
        /** Power supply auxiliary sensors */
        structure PowerSupplySensors {
            sensors.NumericSensor fanSpeed;                   ///< PSU fan speed sensor
            sensors.NumericSensor inputTemperature;           ///< Temperature sensor at PSU input
            sensors.NumericSensor outputTemperature;          ///< Temperature sensor at PSU output
            sensors.NumericSensor hotspotTemperature;         ///< Temperature sensor at hotspot inside PSU
            sensors.StateSensor underTemperatureFault;        ///< Under temperature fault (as reported by PSU) sensor
            sensors.StateSensor overTemperatureFault;         ///< Over temperature fault (as reported by PSU) sensor
            sensors.StateSensor fanFault;                     ///< Fan fault (as reported by PSU) sensor
        };
 
         /** Event: Power control was initiated */
        valueobject PowerControlEvent extends event.UserEvent {
            PowerState state;                   ///< State the supply was switched to
        };
 
        /** Event: Fan speed target was set */
        valueobject FanSpeedControlEvent extends event.UserEvent {
            boolean overrideEnabled;            ///< Fan speed override is enabled
            int targetPercent;                  ///< Newly set fan speed target
        };
 
        /** Event: Fault states of PSU were cleared */
        valueobject FaultsClearedEvent extends event.UserEvent {
        };
 
        /** Event: Power supply state has changed */
        valueobject StateChangedEvent extends idl.Event {
            State oldState;                     ///< State before change
            State newState;                     ///< State after change
        };
 
        /** Event: Metadata has changed */
        valueobject MetaDataChangedEvent extends idl.Event {
            MetaData oldMetaData;               ///< Metadata before change
            MetaData newMetaData;               ///< Metadata after change
        };
 
        /**
         * Retrieve the power supply metadata.
         *
         * @return Metadata
         */
        MetaData getMetaData();
 
        /**
         * Get current PSU state
         *
         * @return Current state
         */
        State getState();
 
        /**
         * Get the input (AC side) sensors.
         *
         * @return sensors
         */
        InputSensors getInputSensors();
 
        /**
         * Get the output (DC side) sensors.
         *
         * @return sensors
         */
        OutputSensors getOutputSensors();
 
        /**
         * Get the auxiliary sensors.
         *
         * @return sensors
         */
        PowerSupplySensors getPowerSupplySensors();
 
        /**
         * Turn PSU on or off
         *
         * @param pstate  New power state
         *
         * @return 0 if OK
         * @return 1 if the PSU does not support power control
         */
        int setPowerState(in PowerState pstate);
 
        /**
         * Set PSU fan speed override
         *
         * @param enableOverride   true if fan speed should be overridden; false to operate fan in automatic mode
         * @param fanSpeedPercent  New fan speed target in %
         *
         * @return 0 if OK
         * @return 1 if fan speed control is not supported
         * @return 2 if the supplied target is out of range (1..100%)
         */
        int setFanSpeedOverride(in boolean enableOverride, in int fanSpeedPercent);
 
        /**
         * Clear any PSU internal fault states
         *
         * This includes input and output related faults as well as temperature and fan faults.
         */
        void clearFaults();
 
        /**
         * Get the input (AC side) poles
         *
         * @return List of poles
         */
        vector<Pole> getInputPoles();
 
        /**
         * Get the output (DC side) poles
         *
         * @return List of poles
         */
         vector<Pole> getOutputPoles();
 
        /**
         * Get the controller for this power supply.
         *
         * @return Sub controller reference
         */
        Controller getController();
    };
 
}
 
#endif