ESI.idl

//------------------------------------------------------------------------------
// DER Challenge
//------------------------------------------------------------------------------
//        File: $RCSfile: ESI.idl,v $
//  Originator: pccourt
//        Date: Tue Aug 26 14:26:47 2018
// Application: ESI draft ideas
//      Module: ESI.idl
//       RCSID: $Id: $
//------------------------------------------------------------------------------
// Last Edited: $Author: $
//        Date: $Date: $
//    Revision: $Revision: $
//------------------------------------------------------------------------------
//
// Description : Psuedo IDL code for a draft ESI for the DER Challenge
//
// Assumptions : This is to be viewed as a logical description only, this will
//               be converted to the appropriate protocol/transport layer
//               technology when it is being implemented (likely to use MQTT or
//               gRPC).
//
//               This interface is intended to be a very low level first
//               principles API that contains full flexibilty for any business
//               model that might like to be implemented on top of it.  The
//               first principles approach is based on the concepts of time,
//               power, energy and money. It is a first draft that conveys
//               these ideas in a way suitable for a MVP demo, but expansion
//               of these ideas will likely be needed for a full production
//               ready v1.0 implementation to be completed.
//
//               This interface should also be viewed with the understanding
//               that an existing JSON protocol operates over https in parallel
//               with this one to provide timely data about power quality,
//               energy consumption and generation and future energy
//               predictions at particular locations within each DERF.
//               This provides a diffinitive historical account of events,
//               historical future expectations and evedence for responses
//               that occured onsite at each DERF for validation purposes.
//
// Dependencies: NONE (its intended to be IDL Psuedo code!)
//
//------------------------------------------------------------------------------

#ifndef ESI_IDL
#define ESI_IDL

//---- Library includes --------------------------------------------------------
//---- Core library includes ---------------------------------------------
#include <Pingable.idl>  //makes the interface pingable (useful for simple
                         //remote testing and measuring comms layer delays)

//---- Application includes ----------------------------------------------------
//---- Local includes ----------------------------------------------------------
//---- Interface Prototypes ----------------------------------------------------

module DER_CHALLENGE
{
/**
 * Encapsulates information about the functionality of an ESI.  Embodies the
 * communications gateways between the DER Facility (DERF) and the Interacting
 * Party with External Responsibility (IPER) e.g. Between a system operator
 * and a DER Facility.
 *
 * Communication between a DER Facility and its collection of DER Equipment is
 * NOT covered here. To see info on this, please check info on Plugins
 * which is covered on the SolarNetwork project's github wiki here:
 * https://github.com/SolarNetwork/solarnetwork/wiki/SolarNode-Development-Guide
 */
   module ESI
   {
      ///////////////////////////////////////////////////////////////////////
      //
      // The ESI API must statisfy all of the following...
      //
      // A : Fast and immediate responses
      // ----------------------------
      //  e.g.
      //  1) Spinning reserve (on standby)
      //  2) Frequency regulation (4 sec interval signal from system balancing
      //     authority)
      //  3) Ramping (on standby to rapidly increase/decrease load)
      //
      // B : Fast dynamic responses
      // ----------------------
      //  e.g.
      //  1) Artificial Inertia (i.e. complement the grids angular momentum)
      //  2) Voltage management (adjust local reactive and/or real power
      //     components to maintain specified voltage range)
      //
      // C : Slow planned responses
      // ----------------------
      //  e.g.
      //  1) Peak Capacity Management (as needed, OpenADR like...?)
      //  2) Contractual obligations (e.g. suppling capacity in the wholesale
      //     energy market, OpenADR like...?)
      //
      // D : Slow dynamic responses
      // ----------------------
      //  e.g.
      //  1) Market price response
      //
      ///////////////////////////////////////////////////////////////////////

      ///////////////////////////////////////////////////////////////////////
      //
      // Data Structs
      //
      // This section contains some basic data types used throughout this API
      //
      ///////////////////////////////////////////////////////////////////////

      //Common data types within the ESI
      typedef string Version_T;
      const Version_T VERSION="1.0";   //Version of the Interface being
                                       //implemented (allows backwards
                                       //compatibility logic to be introduced
                                       //at a later date if required)

      typedef float kWh;               //energy
      typedef float kW;                //power
      typedef float Dollars;           //USD
      typedef long MilliSeconds;       //msec
      typedef long Seconds;            //sec

      //Basic electrical power data types
      typedef float kVAR;     //Ractive Power = Q
      typedef float kW;       //Real Power = P

      //kVA = S (Apparent Power)
      struct kVA
      {
         Version_T version;
         kVAR Q;  //Reactive Power
         kW P;    //Real Power
      };

      // forward declarations

      //Interacting Party with External Responsibility (eg System Operator)
      interface IPER;

      /**
       * Interface: DERF
       *
       * The DER Facility (or a node that directly manages HW). Encapsulates
       * information about the functionality of a DER Facility (DERF).
       */
      interface DERF:
         Ecogy::Corba::Pingable
      {

         // Base characteristics of the hardware present on site (or for the
         // agregate devices below this DERF) In the final implementation,
         // these data structures will be defined with ProtocolBuffers IDL and
         // will inherently support backwards compatible extensions of these
         // data structures if that is needed. ESI specific strategies for
         // message or API versioning is easily acheived.
         struct ResourceCharacteristics
         {
            Version_T version;
            kWh      storage;   //How much usable electrical energy can be stored on site (includes heat energy and battery storage)
            kW       consumptionMaxPower; //Limited by hardware present on site (-ve = consumption)
            kW       consumptionMinPower; //Limited by hardware present on site (a value of zero indicates this DERF can swtich to zero load if requested)
            kW       generationMaxPower; //Limited by hardware present on site (+ve = generation)
            long     responseTime;    //Expected response time of resource (ms)
            float    powerFactor;     //Expected power factor of these loads ???
         };

         /**
          * Method: getResourceCharacteristics
          *
          * Gets the default ResourceCharacteristics for this DERF.
          * This provides a high level understanding to the IPER of what is
          * available from this resource. It does not however provide info on
          * how its services might vary over the immediate future (see
          * TODO ???? get30MinPrediction for this type of info).
          *
          * Parameters: NONE
          *
          * Return:
          *    ResourceCharacteristics - Characteristics for this DERF
          */
         ResourceCharacteristics getResourceCharacteristics()
            raises( InternalErrorException );


         // PriceMap - An element in a sparse matrix of the form fn(x, y, z)
         // Note that S is actually a vector (rather than a single number),
         // hence the the 4D fn(x, y, z) analogy is incorrect (its actually a
         // 5D membrane). A PriceMap effectively defines a single physical
         // capability (or a agregated set of similar capabilities) that the
         // DERF has to offer.
         struct PriceMap
         {
            Version_T version;
            kVA S;  //Apparent Power ("change in" apparent power that is being offered in this PriceMap)
            Seconds duration;
            MilliSeconds responseTime; //how long will this DERF take to respond when requested to make this service immediately
            Dollars price; //indicative price per kVAh of service with these parameters
         };
         typedef sequence< PriceMap > PriceMapSeq;

         /**
          * Method: getPriceMap
          *
          * Presents an indicative price map to the IPER (using a sparse
          * matrix, 4D surface). This sparse price map is easy to agregate
          * for any entity that may be managing multiple DERFs or for the
          * System Operator/Utility to do the same. For example the System
          * Operator could explore this 4D surface looking for the best and
          * most cost effective way to address the immediate or upcoming needs
          * of the grid.
          *
          * For some elements not specifically listed in the sparse matrix,
          * they are still available for request.  For example if the matrix
          * states that a service with a duration of 10 minutes is available,
          * then of course the IPER can request a similar service (with the
          * same kVA and response time), but with a shorter duration.
          *
          * Parameters: NONE
          *
          * Return:
          *    PriceMapSeq - The sparse matrix of pricing data
          */
         PriceMapSeq getPriceMap()
            raises( InternalErrorException );

         //********************************************************************
         // SECTION A : Fast and immediate responses
         // SECTION C : Slow planned responses
         //
         // This section of API below supports both types A & C
         //
         //********************************************************************

         //
         // OpenADR 2.0 should probably be supported in addition to APIs here
         //

         // OfferResponse is a structure that the DERF passes back to the IPER
         // after receiving an offer. Note that the counterOffer will only be
         // populated if this response indicates that the orginal offer is not
         // accepted, in this case this counterOffer sequence will contain one
         // element.
         struct OfferResponse
         {
            Version_T version;
            boolean accept;  //Did we accept this offer (yes/no)?
            GUID offerID;  //unique identifier of the Offer that is being accepted or rejected
            PriceMapSeq counterOffer; //this sequence contains the counter offer (if one is made)
         };

         /**
          * Method: giveOffer (would possibly be better named requestService?)
          *
          * Called by the IPER to provide a price offer for service. The
          * DERF is receiving an offer from the IPER when this happens.
          * Note: DERF to IPER relationships are many to one.
          * Before calling this method, the IPER will have evaulated the
          * PriceMapSeq and decided that it would like to engage the services
          * of this DERF The IPER can match the requested pricing in the
          * PriceMap, or make an offer. Hence this methods name "giveOffer".
          *
          * Parameters:
          *    offerDetails - The details of the price being offered and the
          *                   nature of the service to be provided.
          *    when         - When the Service is requested (can also be NOW,
          *                   i.e. an immediate request).
          *    offerID      - A unique identifier of this offer (provided by
          *                   the IPER for later reference).
          *
          * Return:
          *    OfferResponse - Details of offer acceptance or counter offer
          */
         OfferResponse giveOffer(in PriceMap offerDetails, in DateTime_T when, in GUID offerID)
            raises( InternalErrorException );

         // To report delivery of service i.e. the "is complete" message to the
         // IPER, see the IPER interface at the end of this file...

         //Method used by the IPER to acknowledege successful reciept of the
         //requested service
         void confirmDelivery (in GUID offerID)
            raises( InternalErrorException );

         //Method used by the IPER to dispute reciept of the requested service
         void disputeDelivery (in GUID offerID)
            raises( InternalErrorException );

         //Energy profiles
         typedef kWh 24HrHourlyEnergy[24];  //24 hrs of predicted 'actual' future Energy needs (+ve = generation, -ve = consumption)
         typedef 24HrHourlyEnergy OneWeekHourlyEnergyProfile[7]; //Monday to Sunday

         /**
          * Method: getOneWeekHourlyEnergyProfile
          *
          * Gets predicted energy profile for the next 7 days.  Used by the
          * IPER to statistically measure the accuracy of the DERFs predictions
          * over time and to also verify any respose that the DERF may
          * contractually provide.
          *
          * TODO IPER may require more granular or longer duration predictions?
          *
          * Parameters: NONE
          *
          * Return:
          *    OneWeekHourlyEnergyProfile - One week (7 days) predicted energy
          *                                 profile for this DERF.
          */
         OneWeekHourlyEnergyProfile getOneWeekHourlyEnergyProfile()
            raises( InternalErrorException );


         //********************************************************************
         // SECTION B : Fast dynamic responses
         //
         // This section of API below supports type B responses
         //
         //********************************************************************
         struct SafeParameterRange
         {
            Version_T            version;
            string               name;   //Name of the paramter (e.g. Voltage or Frequency)
            string               units;  //Engineering units of the paramter (e.g. V or Hz)
            EngineeringUnits     maxCriticalLimit;   //Max value allowed (beyound this widespread grid failures are likely)
            EngineeringUnits     minCriticalLimit;   //Max value allowed (beyound this widespread grid failures are likely)
            EngineeringUnits     maxAcceptable;   //Acceptable safe upper limit
            EngineeringUnits     minAcceptable;   //Acceptable safe lower limit
            EngineeringUnits     target;   //Set point for this paramter
         };

         struct GridMetricResponseVariables
         {
            Version_T            version;
            SafeParameterRange   voltage;
            SafeParameterRange   powerFactor;
            SafeParameterRange   frequency;
         };

         /**
          * Method: getGridMetricResponseVariables
          *
          * Request info about how this DERF dynamically responds to grid
          * parameters. This information informs the IPER as to the
          * likely/expected response of this DERF to real time grid changes.
          *
          * Parameters: NONE
          *
          * Return:
          *    GridMetricResponseVariables - info about grid parameter
          *                                  sensitivity.
          */
         GridMetricResponseVariables getGridMetricResponseVariables()
            raises( InternalErrorException );

         /**
          * Method: setGridMetricResponseVariables
          *
          * Attempt to define how this DERF dynamically responds to grid
          * parameters (an authorized IPER can change these settings). This
          * information controls how the DERF will respond to grid changes.
          *
          * This method is not currently showing a price offer parameter, but
          * it should conceptually be designed to do this? Because if the DERF
          * is in a non regulated situation, it may prefer not to respond to
          * these constraints unless it is appropriately compensated?
          *
          * Parameters:
          *    gmResponseVariables - the grid parameters to maintain
          *
          * Return:
          *    true  - if update accepted (TODO maybe provide/offer a more
          *            nuanced response?)
          *    false - if it is NOT accepted.
          */
         boolean setGridMetricResponseVariables(in GridMetricResponseVariables gmResponseVariables)
            raises( InternalErrorException );


         //********************************************************************
         // SECTION D : Slow dynamic responses (retail price behaviour drivers)
         //
         // This section of API below supports type D responses
         //
         //********************************************************************
         struct PriceResponseVariables
         {
            Version_T mVersion;  //Its likely this data structure will become much more intricate and complex to meet the needs of the customer
            Dollars       mAlwaysBuyPrice;   //Price below which the customer will always consume if they have a load running or scheduled to run
            Dollars       mCarefulBuyPrice;  //Price below which the customer will be more selective about consumption (what this means will be customer and DER HW specific)
            Dollars       mNeverBuyPrice;    //Price above which the customer will never consume (because it is too expensive) - suggests customer will use battery or shutdown
         };

         /**
          * Method: getPriceResponseVariables
          *
          * Request info about how this DERF responds to prices (only the DERF
          * owner can change these settings).
          * This information informs the IPER as to the likely/expected response
          * of this DERF to real time price changes. These variables are
          * generally set by the owner of the property or the company in charge
          * of managing the DERs onsite on behalf of the owner (how these are
          * actually set is out of scope of this API).
          *
          * Parameters: NONE
          *
          * Return:
          *    PriceResponseVariables - info about price sensitivity
          */
         PriceResponseVariables getPriceResponseVariables()
            raises( InternalErrorException );


         //The types of programs offered/supported by this DERF
         enum ProgramEnum_T {
            Program_SPINING_RESERVE,
            Program_FREQ_REGULATION,
            Program_RAMPING,
            Program_ARTIFICIAL_INERTIA,
            Program_VOLTAGE_MANAGEMENT,
            Program_PEAK_CAPACITY_MANAGEMENT,
            Program_CONTRACTUAL_OBLIGATIONS,
            Program_MARKET_PRICE_RESPONSE,
            NUM_Program
         };
         typedef sequence< ProgramEnum_T > ProgramEnumSeq;
         /**
          * Gets the full set of services this DERF provides.
          * For informational purposes only at this point... This concept
          * does not directly tie in with any of the other methods defined here
          * but its an easy way to communicate to the IPER what services
          * the DERF intends to try to offer with its capabilities.
          */
         ProgramEnumSeq getProgramEnumSeq()
            raises( InternalErrorException );

      }; // end of DERF

      /**
       * Interface: IPER
       *
       * The Interfacing Party with External Responsibility (IPER) e.g. a System
       * Operator. Encapsulates information about the functionality of an IPER
       * that might be used by a DERF.
       */
      interface IPER:
         Ecogy::Corba::Pingable
      {

         //DERF calls this method on the IPER to confirm that the requested
         //service has been delivered
         void reportDeliveryComplete (in GUID offerID)
            raises( InternalErrorException );


         // Allows a DERF to drive its dynamic price dependant behaviour.
         // TODO should also offer a broadcast service that DERFs can register
         // with to recieve real time price changes.
         Price getCurrentGridPrice(in string Location, in string derfID)
            raises( InternalErrorException );


         //============ Future Thinking ================

        // Not sure if we need the methods below (they imply another layer of
        // rigidity to the API that may not be needed here - since this API is
        // intended to be very generic, we can add this at another layer above
        // this ESI if it is requried e.g. if local regulations dictate a
        // certain shape to the smart grid programs, these specific structures
        // could be built above this ESI). i.e. the IPER could be implemented
        // in such a way that it only offered and accepted service engagements
        // that matched the local regulations (programs), these could be
        // implemented using the ESI interface documented here, but the
        // functionality actually delivered by the DERF<->IPER relationships
        // could be constrained by these programs...

        // registerForPrograms(in ProgramEnumSeq programs, in derfID)
        //    raises( InternalErrorException );
        // deregisterForPrograms(in ProgramEnumSeq programs, in derfID)
        //    raises( InternalErrorException );

      }; // end of IPER
   }; // end of ESI
}; // end of DER_CHALLENGE

#endif // ESI_IDL