SHARE
TWEET

ESI.idl

pccourt Sep 6th, 2018 142 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. //------------------------------------------------------------------------------
  2. // DER Challenge
  3. //------------------------------------------------------------------------------
  4. //        File: $RCSfile: ESI.idl,v $
  5. //  Originator: pccourt
  6. //        Date: Tue Aug 26 14:26:47 2018
  7. // Application: ESI draft ideas
  8. //      Module: ESI.idl
  9. //       RCSID: $Id: $
  10. //------------------------------------------------------------------------------
  11. // Last Edited: $Author: $
  12. //        Date: $Date: $
  13. //    Revision: $Revision: $
  14. //------------------------------------------------------------------------------
  15. //
  16. // Description : Psuedo IDL code for a draft ESI for the DER Challenge
  17. //
  18. // Assumptions : This is to be viewed as a logical description only, this will
  19. //               be converted to the appropriate protocol/transport layer
  20. //               technology when it is being implemented (likely to use MQTT or
  21. //               gRPC).
  22. //
  23. //               This interface is intended to be a very low level first
  24. //               principles API that contains full flexibilty for any business
  25. //               model that might like to be implemented on top of it.  The
  26. //               first principles approach is based on the concepts of time,
  27. //               power, energy and money. It is a first draft that conveys
  28. //               these ideas in a way suitable for a MVP demo, but expansion
  29. //               of these ideas will likely be needed for a full production
  30. //               ready v1.0 implementation to be completed.
  31. //
  32. //               This interface should also be viewed with the understanding
  33. //               that an existing JSON protocol operates over https in parallel
  34. //               with this one to provide timely data about power quality,
  35. //               energy consumption and generation and future energy
  36. //               predictions at particular locations within each DERF.
  37. //               This provides a diffinitive historical account of events,
  38. //               historical future expectations and evedence for responses
  39. //               that occured onsite at each DERF for validation purposes.
  40. //
  41. // Dependencies: NONE (its intended to be IDL Psuedo code!)
  42. //
  43. //------------------------------------------------------------------------------
  44.  
  45. #ifndef ESI_IDL
  46. #define ESI_IDL
  47.  
  48. //---- Library includes --------------------------------------------------------
  49. //---- Core library includes ---------------------------------------------
  50. #include <Pingable.idl>  //makes the interface pingable (useful for simple
  51.                          //remote testing and measuring comms layer delays)
  52.  
  53. //---- Application includes ----------------------------------------------------
  54. //---- Local includes ----------------------------------------------------------
  55. //---- Interface Prototypes ----------------------------------------------------
  56.  
  57. module DER_CHALLENGE
  58. {
  59. /**
  60.  * Encapsulates information about the functionality of an ESI.  Embodies the
  61.  * communications gateways between the DER Facility (DERF) and the Interacting
  62.  * Party with External Responsibility (IPER) e.g. Between a system operator
  63.  * and a DER Facility.
  64.  *
  65.  * Communication between a DER Facility and its collection of DER Equipment is
  66.  * NOT covered here. To see info on this, please check info on Plugins
  67.  * which is covered on the SolarNetwork project's github wiki here:
  68.  * https://github.com/SolarNetwork/solarnetwork/wiki/SolarNode-Development-Guide
  69.  */
  70.    module ESI
  71.    {
  72.       ///////////////////////////////////////////////////////////////////////
  73.       //
  74.       // The ESI API must statisfy all of the following...
  75.       //
  76.       // A : Fast and immediate responses
  77.       // ----------------------------
  78.       //  e.g.
  79.       //  1) Spinning reserve (on standby)
  80.       //  2) Frequency regulation (4 sec interval signal from system balancing
  81.       //     authority)
  82.       //  3) Ramping (on standby to rapidly increase/decrease load)
  83.       //
  84.       // B : Fast dynamic responses
  85.       // ----------------------
  86.       //  e.g.
  87.       //  1) Artificial Inertia (i.e. complement the grids angular momentum)
  88.       //  2) Voltage management (adjust local reactive and/or real power
  89.       //     components to maintain specified voltage range)
  90.       //
  91.       // C : Slow planned responses
  92.       // ----------------------
  93.       //  e.g.
  94.       //  1) Peak Capacity Management (as needed, OpenADR like...?)
  95.       //  2) Contractual obligations (e.g. suppling capacity in the wholesale
  96.       //     energy market, OpenADR like...?)
  97.       //
  98.       // D : Slow dynamic responses
  99.       // ----------------------
  100.       //  e.g.
  101.       //  1) Market price response
  102.       //
  103.       ///////////////////////////////////////////////////////////////////////
  104.  
  105.       ///////////////////////////////////////////////////////////////////////
  106.       //
  107.       // Data Structs
  108.       //
  109.       // This section contains some basic data types used throughout this API
  110.       //
  111.       ///////////////////////////////////////////////////////////////////////
  112.  
  113.       //Common data types within the ESI
  114.       typedef string Version_T;
  115.       const Version_T VERSION="1.0";   //Version of the Interface being
  116.                                        //implemented (allows backwards
  117.                                        //compatibility logic to be introduced
  118.                                        //at a later date if required)
  119.  
  120.       typedef float kWh;               //energy
  121.       typedef float kW;                //power
  122.       typedef float Dollars;           //USD
  123.       typedef long MilliSeconds;       //msec
  124.       typedef long Seconds;            //sec
  125.  
  126.       //Basic electrical power data types
  127.       typedef float kVAR;     //Ractive Power = Q
  128.       typedef float kW;       //Real Power = P
  129.  
  130.       //kVA = S (Apparent Power)
  131.       struct kVA            
  132.       {
  133.          Version_T version;
  134.          kVAR Q;  //Reactive Power
  135.          kW P;    //Real Power
  136.       };
  137.  
  138.       // forward declarations
  139.  
  140.       //Interacting Party with External Responsibility (eg System Operator)
  141.       interface IPER;
  142.  
  143.       /**
  144.        * Interface: DERF
  145.        *
  146.        * The DER Facility (or a node that directly manages HW). Encapsulates
  147.        * information about the functionality of a DER Facility (DERF).
  148.        */
  149.       interface DERF:
  150.          Ecogy::Corba::Pingable
  151.       {
  152.  
  153.          // Base characteristics of the hardware present on site (or for the
  154.          // agregate devices below this DERF) In the final implementation,
  155.          // these data structures will be defined with ProtocolBuffers IDL and
  156.          // will inherently support backwards compatible extensions of these
  157.          // data structures if that is needed. ESI specific strategies for
  158.          // message or API versioning is easily acheived.
  159.          struct ResourceCharacteristics
  160.          {
  161.             Version_T version;
  162.             kWh      storage;   //How much usable electrical energy can be stored on site (includes heat energy and battery storage)
  163.             kW       consumptionMaxPower; //Limited by hardware present on site (-ve = consumption)
  164.             kW       consumptionMinPower; //Limited by hardware present on site (a value of zero indicates this DERF can swtich to zero load if requested)
  165.             kW       generationMaxPower; //Limited by hardware present on site (+ve = generation)
  166.             long     responseTime;    //Expected response time of resource (ms)
  167.             float    powerFactor;     //Expected power factor of these loads ???
  168.          };
  169.  
  170.          /**
  171.           * Method: getResourceCharacteristics
  172.           *
  173.           * Gets the default ResourceCharacteristics for this DERF.
  174.           * This provides a high level understanding to the IPER of what is
  175.           * available from this resource. It does not however provide info on
  176.           * how its services might vary over the immediate future (see
  177.           * TODO ???? get30MinPrediction for this type of info).
  178.           *
  179.           * Parameters: NONE
  180.           *
  181.           * Return:
  182.           *    ResourceCharacteristics - Characteristics for this DERF
  183.           */
  184.          ResourceCharacteristics getResourceCharacteristics()
  185.             raises( InternalErrorException );
  186.  
  187.  
  188.          // PriceMap - An element in a sparse matrix of the form fn(x, y, z)
  189.          // Note that S is actually a vector (rather than a single number),
  190.          // hence the the 4D fn(x, y, z) analogy is incorrect (its actually a
  191.          // 5D membrane). A PriceMap effectively defines a single physical
  192.          // capability (or a agregated set of similar capabilities) that the
  193.          // DERF has to offer.
  194.          struct PriceMap
  195.          {
  196.             Version_T version;
  197.             kVA S;  //Apparent Power ("change in" apparent power that is being offered in this PriceMap)
  198.             Seconds duration;
  199.             MilliSeconds responseTime; //how long will this DERF take to respond when requested to make this service immediately
  200.             Dollars price; //indicative price per kVAh of service with these parameters
  201.          };
  202.          typedef sequence< PriceMap > PriceMapSeq;
  203.  
  204.          /**
  205.           * Method: getPriceMap
  206.           *
  207.           * Presents an indicative price map to the IPER (using a sparse
  208.           * matrix, 4D surface). This sparse price map is easy to agregate
  209.           * for any entity that may be managing multiple DERFs or for the
  210.           * System Operator/Utility to do the same. For example the System
  211.           * Operator could explore this 4D surface looking for the best and
  212.           * most cost effective way to address the immediate or upcoming needs
  213.           * of the grid.
  214.           *
  215.           * For some elements not specifically listed in the sparse matrix,
  216.           * they are still available for request.  For example if the matrix
  217.           * states that a service with a duration of 10 minutes is available,
  218.           * then of course the IPER can request a similar service (with the
  219.           * same kVA and response time), but with a shorter duration.
  220.           *
  221.           * Parameters: NONE
  222.           *
  223.           * Return:
  224.           *    PriceMapSeq - The sparse matrix of pricing data
  225.           */
  226.          PriceMapSeq getPriceMap()
  227.             raises( InternalErrorException );
  228.        
  229.          //********************************************************************
  230.          // SECTION A : Fast and immediate responses
  231.          // SECTION C : Slow planned responses
  232.          //
  233.          // This section of API below supports both types A & C
  234.          //
  235.          //********************************************************************
  236.  
  237.          //
  238.          // OpenADR 2.0 should probably be supported in addition to APIs here
  239.          //
  240.  
  241.          // OfferResponse is a structure that the DERF passes back to the IPER
  242.          // after receiving an offer. Note that the counterOffer will only be
  243.          // populated if this response indicates that the orginal offer is not
  244.          // accepted, in this case this counterOffer sequence will contain one
  245.          // element.
  246.          struct OfferResponse
  247.          {
  248.             Version_T version;
  249.             boolean accept;  //Did we accept this offer (yes/no)?
  250.             GUID offerID;  //unique identifier of the Offer that is being accepted or rejected
  251.             PriceMapSeq counterOffer; //this sequence contains the counter offer (if one is made)
  252.          };
  253.  
  254.          /**
  255.           * Method: giveOffer (would possibly be better named requestService?)
  256.           *
  257.           * Called by the IPER to provide a price offer for service. The
  258.           * DERF is receiving an offer from the IPER when this happens.  
  259.           * Note: DERF to IPER relationships are many to one.
  260.           * Before calling this method, the IPER will have evaulated the
  261.           * PriceMapSeq and decided that it would like to engage the services
  262.           * of this DERF The IPER can match the requested pricing in the
  263.           * PriceMap, or make an offer. Hence this methods name "giveOffer".
  264.           *
  265.           * Parameters:
  266.           *    offerDetails - The details of the price being offered and the
  267.           *                   nature of the service to be provided.
  268.           *    when         - When the Service is requested (can also be NOW,
  269.           *                   i.e. an immediate request).
  270.           *    offerID      - A unique identifier of this offer (provided by
  271.           *                   the IPER for later reference).
  272.           *
  273.           * Return:
  274.           *    OfferResponse - Details of offer acceptance or counter offer
  275.           */
  276.          OfferResponse giveOffer(in PriceMap offerDetails, in DateTime_T when, in GUID offerID)
  277.             raises( InternalErrorException );
  278.  
  279.          // To report delivery of service i.e. the "is complete" message to the
  280.          // IPER, see the IPER interface at the end of this file...
  281.  
  282.          //Method used by the IPER to acknowledege successful reciept of the
  283.          //requested service
  284.          void confirmDelivery (in GUID offerID)
  285.             raises( InternalErrorException );
  286.  
  287.          //Method used by the IPER to dispute reciept of the requested service
  288.          void disputeDelivery (in GUID offerID)
  289.             raises( InternalErrorException );
  290.  
  291.          //Energy profiles
  292.          typedef kWh 24HrHourlyEnergy[24];  //24 hrs of predicted 'actual' future Energy needs (+ve = generation, -ve = consumption)
  293.          typedef 24HrHourlyEnergy OneWeekHourlyEnergyProfile[7]; //Monday to Sunday
  294.  
  295.          /**
  296.           * Method: getOneWeekHourlyEnergyProfile
  297.           *
  298.           * Gets predicted energy profile for the next 7 days.  Used by the
  299.           * IPER to statistically measure the accuracy of the DERFs predictions
  300.           * over time and to also verify any respose that the DERF may
  301.           * contractually provide.
  302.           *
  303.           * TODO IPER may require more granular or longer duration predictions?
  304.           *
  305.           * Parameters: NONE
  306.           *
  307.           * Return:
  308.           *    OneWeekHourlyEnergyProfile - One week (7 days) predicted energy
  309.           *                                 profile for this DERF.
  310.           */
  311.          OneWeekHourlyEnergyProfile getOneWeekHourlyEnergyProfile()
  312.             raises( InternalErrorException );
  313.  
  314.  
  315.          //********************************************************************
  316.          // SECTION B : Fast dynamic responses
  317.          //
  318.          // This section of API below supports type B responses
  319.          //
  320.          //********************************************************************
  321.          struct SafeParameterRange
  322.          {
  323.             Version_T            version;
  324.             string               name;   //Name of the paramter (e.g. Voltage or Frequency)
  325.             string               units;  //Engineering units of the paramter (e.g. V or Hz)
  326.             EngineeringUnits     maxCriticalLimit;   //Max value allowed (beyound this widespread grid failures are likely)
  327.             EngineeringUnits     minCriticalLimit;   //Max value allowed (beyound this widespread grid failures are likely)
  328.             EngineeringUnits     maxAcceptable;   //Acceptable safe upper limit
  329.             EngineeringUnits     minAcceptable;   //Acceptable safe lower limit
  330.             EngineeringUnits     target;   //Set point for this paramter
  331.          };
  332.  
  333.          struct GridMetricResponseVariables
  334.          {
  335.             Version_T            version;
  336.             SafeParameterRange   voltage;
  337.             SafeParameterRange   powerFactor;
  338.             SafeParameterRange   frequency;
  339.          };
  340.  
  341.          /**
  342.           * Method: getGridMetricResponseVariables
  343.           *
  344.           * Request info about how this DERF dynamically responds to grid
  345.           * parameters. This information informs the IPER as to the
  346.           * likely/expected response of this DERF to real time grid changes.
  347.           *
  348.           * Parameters: NONE
  349.           *
  350.           * Return:
  351.           *    GridMetricResponseVariables - info about grid parameter
  352.           *                                  sensitivity.
  353.           */
  354.          GridMetricResponseVariables getGridMetricResponseVariables()
  355.             raises( InternalErrorException );
  356.  
  357.          /**  
  358.           * Method: setGridMetricResponseVariables
  359.           *
  360.           * Attempt to define how this DERF dynamically responds to grid
  361.           * parameters (an authorized IPER can change these settings). This
  362.           * information controls how the DERF will respond to grid changes.
  363.           *
  364.           * This method is not currently showing a price offer parameter, but
  365.           * it should conceptually be designed to do this? Because if the DERF
  366.           * is in a non regulated situation, it may prefer not to respond to
  367.           * these constraints unless it is appropriately compensated?
  368.           *
  369.           * Parameters:
  370.           *    gmResponseVariables - the grid parameters to maintain
  371.           *
  372.           * Return:
  373.           *    true  - if update accepted (TODO maybe provide/offer a more
  374.           *            nuanced response?)
  375.           *    false - if it is NOT accepted.
  376.           */
  377.          boolean setGridMetricResponseVariables(in GridMetricResponseVariables gmResponseVariables)
  378.             raises( InternalErrorException );
  379.  
  380.  
  381.          //********************************************************************
  382.          // SECTION D : Slow dynamic responses (retail price behaviour drivers)
  383.          //
  384.          // This section of API below supports type D responses
  385.          //
  386.          //********************************************************************
  387.          struct PriceResponseVariables
  388.          {
  389.             Version_T mVersion;  //Its likely this data structure will become much more intricate and complex to meet the needs of the customer
  390.             Dollars       mAlwaysBuyPrice;   //Price below which the customer will always consume if they have a load running or scheduled to run
  391.             Dollars       mCarefulBuyPrice;  //Price below which the customer will be more selective about consumption (what this means will be customer and DER HW specific)
  392.             Dollars       mNeverBuyPrice;    //Price above which the customer will never consume (because it is too expensive) - suggests customer will use battery or shutdown
  393.          };
  394.  
  395.          /**
  396.           * Method: getPriceResponseVariables
  397.           *
  398.           * Request info about how this DERF responds to prices (only the DERF
  399.           * owner can change these settings).
  400.           * This information informs the IPER as to the likely/expected response
  401.           * of this DERF to real time price changes. These variables are
  402.           * generally set by the owner of the property or the company in charge
  403.           * of managing the DERs onsite on behalf of the owner (how these are
  404.           * actually set is out of scope of this API).
  405.           *
  406.           * Parameters: NONE
  407.           *
  408.           * Return:
  409.           *    PriceResponseVariables - info about price sensitivity
  410.           */
  411.          PriceResponseVariables getPriceResponseVariables()
  412.             raises( InternalErrorException );
  413.  
  414.  
  415.          //The types of programs offered/supported by this DERF
  416.          enum ProgramEnum_T {
  417.             Program_SPINING_RESERVE,
  418.             Program_FREQ_REGULATION,
  419.             Program_RAMPING,
  420.             Program_ARTIFICIAL_INERTIA,
  421.             Program_VOLTAGE_MANAGEMENT,
  422.             Program_PEAK_CAPACITY_MANAGEMENT,
  423.             Program_CONTRACTUAL_OBLIGATIONS,
  424.             Program_MARKET_PRICE_RESPONSE,
  425.             NUM_Program
  426.          };
  427.          typedef sequence< ProgramEnum_T > ProgramEnumSeq;
  428.          /**
  429.           * Gets the full set of services this DERF provides.
  430.           * For informational purposes only at this point... This concept
  431.           * does not directly tie in with any of the other methods defined here
  432.           * but its an easy way to communicate to the IPER what services
  433.           * the DERF intends to try to offer with its capabilities.
  434.           */
  435.          ProgramEnumSeq getProgramEnumSeq()
  436.             raises( InternalErrorException );
  437.  
  438.       }; // end of DERF
  439.  
  440.       /**
  441.        * Interface: IPER
  442.        *
  443.        * The Interfacing Party with External Responsibility (IPER) e.g. a System
  444.        * Operator. Encapsulates information about the functionality of an IPER
  445.        * that might be used by a DERF.
  446.        */
  447.       interface IPER:
  448.          Ecogy::Corba::Pingable
  449.       {
  450.  
  451.          //DERF calls this method on the IPER to confirm that the requested
  452.          //service has been delivered
  453.          void reportDeliveryComplete (in GUID offerID)
  454.             raises( InternalErrorException );
  455.  
  456.  
  457.          // Allows a DERF to drive its dynamic price dependant behaviour.
  458.          // TODO should also offer a broadcast service that DERFs can register
  459.          // with to recieve real time price changes.
  460.          Price getCurrentGridPrice(in string Location, in string derfID)
  461.             raises( InternalErrorException );
  462.  
  463.  
  464.          //============ Future Thinking ================
  465.  
  466.         // Not sure if we need the methods below (they imply another layer of
  467.         // rigidity to the API that may not be needed here - since this API is
  468.         // intended to be very generic, we can add this at another layer above
  469.         // this ESI if it is requried e.g. if local regulations dictate a
  470.         // certain shape to the smart grid programs, these specific structures
  471.         // could be built above this ESI). i.e. the IPER could be implemented
  472.         // in such a way that it only offered and accepted service engagements
  473.         // that matched the local regulations (programs), these could be
  474.         // implemented using the ESI interface documented here, but the
  475.         // functionality actually delivered by the DERF<->IPER relationships
  476.         // could be constrained by these programs...
  477.  
  478.         // registerForPrograms(in ProgramEnumSeq programs, in derfID)
  479.         //    raises( InternalErrorException );
  480.         // deregisterForPrograms(in ProgramEnumSeq programs, in derfID)
  481.         //    raises( InternalErrorException );
  482.  
  483.       }; // end of IPER
  484.    }; // end of ESI
  485. }; // end of DER_CHALLENGE
  486.  
  487. #endif // ESI_IDL
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand
 
Top