Merge remote-tracking branch 'Nostromo-energy/main'

alexcarnero97 · alexcarnero97 · commit 0e09490eb04d · 2024-05-09T11:26:41.000Z
diff --git a/.gitignore b/.gitignore
@@ -11,4 +11,5 @@ dist/
 .ipynb_checkpoints/
 static/
 .idea/
+.vscode/
 *.venv/
diff --git a/openleadr/client.py b/openleadr/client.py
@@ -19,6 +19,7 @@
 import logging
 import ssl
 from datetime import datetime, timedelta, timezone
+from dataclasses import asdict
 from functools import partial
 from http import HTTPStatus
 
@@ -42,9 +43,11 @@ class OpenADRClient:
     Main client class. Most of these methods will be called automatically, but
     you can always choose to call them manually.
     """
+
     def __init__(self, ven_name, vtn_url, debug=False, cert=None, key=None,
                  passphrase=None, vtn_fingerprint=None, show_fingerprint=True, ca_file=None,
-                 allow_jitter=True, ven_id=None, disable_signature=False, check_hostname=True):
+                 allow_jitter=True, ven_id=None, disable_signature=False, check_hostname=True,
+                 event_status_log_period=10, events_clean_up_period=300):
         """
         Initializes a new OpenADR Client (Virtual End Node)
 
@@ -65,6 +68,9 @@ def __init__(self, ven_name, vtn_url, debug=False, cert=None, key=None,
         :param str ven_id: The ID for this VEN. If you leave this blank,
                            a VEN_ID will be assigned by the VTN.
         :param bool disable_signature: Whether or not to sign outgoing messages using a public-private key pair in PEM format.
+        :param bool check_hostname: Whether or not to check hostname
+        :param int event_status_log_period: Setting the priod of status change logging
+        :param int events_clean_up_period: Setting the priod of not relevant events clean up
         """
 
         self.ven_name = ven_name
@@ -75,6 +81,8 @@ def __init__(self, ven_name, vtn_url, debug=False, cert=None, key=None,
         self.vtn_fingerprint = vtn_fingerprint
         self.debug = debug
         self.check_hostname = check_hostname
+        self.event_status_log_period = event_status_log_period
+        self.events_clean_up_period = events_clean_up_period
 
         self.reports = []
         self.report_callbacks = {}              # Holds the callbacks for each specific report
@@ -85,6 +93,7 @@ def __init__(self, ven_name, vtn_url, debug=False, cert=None, key=None,
         self.client_session = None
         self.report_queue_task = None
 
+        self.opts = []
         self.received_events = []               # Holds the events that we received.
         self.responded_events = {}              # Holds the events that we already saw.
 
@@ -162,9 +171,12 @@ async def run(self):
         self.scheduler.add_job(self._poll,
                                trigger='interval',
                                seconds=self.poll_frequency.total_seconds())
+        self.scheduler.add_job(self._event_status_log,
+                               trigger='interval',
+                               seconds=self.event_status_log_period)
         self.scheduler.add_job(self._event_cleanup,
                                trigger='interval',
-                               seconds=300)
+                               seconds=self.events_clean_up_period)
         self.scheduler.start()
 
     async def stop(self):
@@ -558,6 +570,104 @@ async def sync_events(self):
         if 'events' in response_payload and len(response_payload['events']) > 0:
             await self._on_event(response_payload)
 
+    ###########################################################################
+    #                                                                         #
+    #                                OPT METHODS                              #
+    #                                                                         #
+    ###########################################################################
+
+    async def create_opt(self, opt_type, opt_reason, targets, vavailability=None, event_id=None,
+                         modification_number=None, opt_id=None, request_id=None, market_context=None,
+                         signal_target_mrid=None):
+        """
+        Send a new opt to the VTN, either to communicate a temporary availability
+        schedule or to qualify the resources participating in an event.
+
+        :param str opt_type: An OpenADR opt type. (found in openleadr.enums.OPT)
+        :param str opt_reason: An OpenADR opt reason. (found in openleadr.enums.OPT_REASON)
+        :param targets: A list of target(s) that this opt is related to.
+        :param vavailability: The availability schedule to send
+        :param event_id: The id of the event this opt is referencing.
+        :param modification_number: The modification number of the event this opt is referencing.
+        :param str opt_id: A unique identifier for this opt message. Leave this blank for a
+                           random generated id, or fill it in if your VTN depends on
+                           this being a known value, or if it needs to be constant
+                           between restarts of the client.
+        :param str request_id: A unique identifier for this request. The same remarks apply
+                               as for the opt_id.
+        :param str market_context: The Market Context that this opt belongs to.
+        """
+
+        # Verify input
+        if opt_type not in enums.OPT.values:
+            raise ValueError(f"{opt_type} is not a valid opt type. Valid options are "
+                             f"{', '.join(enums.REPORT_NAME.values)}")
+        if opt_reason not in enums.OPT_REASON.values:
+            raise ValueError(f"{opt_reason} is not a valid opt reason. Valid options are "
+                             f"{', '.join(enums.REPORT_NAME.values)}")
+
+        # Save opt
+        opt_id = opt_id or utils.generate_id()
+        opt = objects.Opt(
+            opt_id=opt_id,
+            opt_type=opt_type,
+            opt_reason=opt_reason,
+            vavailability=vavailability,
+            event_id=event_id,
+            modification_number=modification_number,
+            targets=targets,
+            market_context=market_context,
+            signal_target_mrid=signal_target_mrid
+        )
+        self.opts.append(opt)
+
+        # Send opt
+        request_id = request_id or utils.generate_id()
+        payload = {
+            'request_id': request_id,
+            'ven_id': self.ven_id,
+            **asdict(opt)
+        }
+
+        service = 'EiOpt'
+        message = self._create_message('oadrCreateOpt', **payload)
+        response_type, response_payload = await self._perform_request(service, message)
+
+        if 'opt_id' in response_payload:
+            # VTN acknowledged the opt message
+            return response_payload['opt_id']
+
+        # TODO: what to do if the VTN sends an error or does not acknowledge the opt?
+
+    async def cancel_opt(self, opt_id):
+        """
+        Tell the VTN to cancel a previously acknowledged opt message
+
+        :param str opt_id: The id of the opt to cancel
+        """
+
+        # Check if this opt exists
+        opt = utils.find_by(
+            self.opts, 'opt_id', opt_id)
+        if not opt:
+            logger.error(f"A non-existant opt with opt_id "
+                         f"{opt_id} was requested for cancellation.")
+            return False
+
+        payload = {
+            'opt_id': opt_id,
+            'ven_id': self.ven_id
+        }
+
+        service = 'EiOpt'
+        message = self._create_message('oadrCancelOpt', **payload)
+        response_type, response_payload = await self._perform_request(service, message)
+
+        if 'opt_id' in response_payload:
+            # VTN acknowledged the opt cancelation
+            self.opts.remove(opt)
+            return True
+
     ###########################################################################
     #                                                                         #
     #                             REPORTING METHODS                           #
@@ -1020,7 +1130,6 @@ async def _execute_hooks(self, hook_name, *args, **kwargs):
                              f"{err.__class__.__name__}: {err}")
 
     async def _on_event(self, message):
-        logger.debug("The VEN received an event")
         events = message['events']
         invalid_vtn_id = False
         try:
@@ -1033,6 +1142,7 @@ async def _on_event(self, message):
                 event_id = event['event_descriptor']['event_id']
                 event_status = event['event_descriptor']['event_status']
                 modification_number = event['event_descriptor']['modification_number']
+                logger.info("The VEN received an event with event_id: %s, status: %s, modification_number: %s", event_id, event_status, modification_number) # change to debug
                 received_event = utils.find_by(self.received_events, 'event_descriptor.event_id', event_id)
                 if received_event:
                     if received_event['event_descriptor']['modification_number'] == modification_number:
@@ -1112,6 +1222,20 @@ async def _on_event(self, message):
         else:
             logger.info("Not sending any event responses, because a response was not required/allowed by the VTN.")
 
+    async def _event_status_log(self):
+        """
+        Periodic task that will log each event status change
+        """
+        for event in self.received_events:
+            # ignoring the cancelled case
+            if event['event_descriptor']['event_status'] == 'cancelled':
+                continue
+            
+            event_status = utils.determine_event_status(event['active_period'])
+            if event_status != event['event_descriptor']['event_status']:
+                event['event_descriptor']['event_status'] = event_status
+                logger.info("event_id: %s has new status: %s", event['event_descriptor']['event_id'], event_status) # change to debug
+
     async def _event_cleanup(self):
         """
         Periodic task that will clean up completed and cancelled events in our memory.
diff --git a/openleadr/objects.py b/openleadr/objects.py
@@ -309,3 +309,70 @@ class ReportSpecifier:
 class ReportRequest:
     report_request_id: str
     report_specifier: ReportSpecifier
+
+
+@dataclass
+class VavailabilityComponent:
+    dstart: datetime
+    duration: timedelta
+
+
+@dataclass
+class Vavailability:
+    components: List[VavailabilityComponent]
+
+
+@dataclass
+class Opt:
+    opt_type: str
+    opt_reason: str
+    opt_id: str = None
+    created_date_time: datetime = None
+
+    event_id: str = None
+    modification_number: int = None
+    vavailability: Vavailability = None
+    targets: List[Target] = None
+    targets_by_type: Dict = None
+    market_context: str = None
+    signal_target_mrid: str = None
+
+    def __post_init__(self):
+        if self.opt_type not in enums.OPT.values:
+            raise ValueError(f"""The opt_type must be one of '{"', '".join(enums.OPT.values)}', """
+                             f"""you specified: '{self.opt_type}'.""")
+        if self.opt_reason not in enums.OPT_REASON.values:
+            raise ValueError(f"""The opt_reason must be one of '{"', '".join(enums.OPT_REASON.values)}', """
+                             f"""you specified: '{self.opt_type}'.""")
+        if self.signal_target_mrid is not None and self.signal_target_mrid not in enums.SIGNAL_TARGET_MRID.values and not self.signal_target_mrid.startswith('x-'):
+            raise ValueError(f"""The signal_target_mrid must be one of '{"', '".join(enums.SIGNAL_TARGET_MRID.values)}', """
+                             f"""you specified: '{self.signal_target_mrid}'.""")
+        if self.event_id is None and self.vavailability is None:
+            raise ValueError(
+                "You must supply either 'event_id' or 'vavailability'.")
+        if self.event_id is not None and self.vavailability is not None:
+            raise ValueError(
+                "You supplied both 'event_id' and 'vavailability."
+                "Please supply either, but not both.")
+        if self.created_date_time is None:
+            self.created_date_time = datetime.now(timezone.utc)
+        if self.modification_number is None:
+            self.modification_number = 0
+        if self.targets is None and self.targets_by_type is None:
+            raise ValueError(
+                "You must supply either 'targets' or 'targets_by_type'.")
+        if self.targets_by_type is None:
+            list_of_targets = [asdict(target) if is_dataclass(
+                target) else target for target in self.targets]
+            self.targets_by_type = utils.group_targets_by_type(list_of_targets)
+        elif self.targets is None:
+            self.targets = [Target(
+                **target) for target in utils.ungroup_targets_by_type(self.targets_by_type)]
+        elif self.targets is not None and self.targets_by_type is not None:
+            list_of_targets = [asdict(target) if is_dataclass(
+                target) else target for target in self.targets]
+            if utils.group_targets_by_type(list_of_targets) != self.targets_by_type:
+                raise ValueError("You assigned both 'targets' and 'targets_by_type' in your event, "
+                                 "but the two were not consistent with each other. "
+                                 f"You supplied 'targets' = {self.targets} and "
+                                 f"'targets_by_type' = {self.targets_by_type}")
diff --git a/openleadr/service/opt_service.py b/openleadr/service/opt_service.py
@@ -14,9 +14,82 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from . import service, VTNService
+from . import service, handler, VTNService
+import logging
+logger = logging.getLogger('openleadr')
+
+# ╔══════════════════════════════════════════════════════════════════════════╗
+# ║                           OPT SERVICE                                    ║
+# ╚══════════════════════════════════════════════════════════════════════════╝
+# ┌──────────────────────────────────────────────────────────────────────────┐
+# │ The VEN can send an Opt-in / Opt-out schedule to the VTN:                │
+# │                                                                          │
+# │ ┌────┐                                                            ┌────┐ │
+# │ │VEN │                                                            │VTN │ │
+# │ └─┬──┘                                                            └─┬──┘ │
+# │   │───────────────────────────oadrCreateOpt()──────────────────────▶│    │
+# │   │                                                                 │    │
+# │   │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ oadrCreatedOpt()─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│    │
+# │   │                                                                 │    │
+# │                                                                          │
+# └──────────────────────────────────────────────────────────────────────────┘
+# ┌──────────────────────────────────────────────────────────────────────────┐
+# │ The VEN can cancel a sent Opt-in / Opt-out schedule:                │
+# │                                                                          │
+# │ ┌────┐                                                            ┌────┐ │
+# │ │VEN │                                                            │VTN │ │
+# │ └─┬──┘                                                            └─┬──┘ │
+# │   │───────────────────────────oadrCancelOpt()──────────────────────▶│    │
+# │   │                                                                 │    │
+# │   │◀ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ oadrCanceledOpt()─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │    │
+# │   │                                                                 │    │
+# │                                                                          │
+# └──────────────────────────────────────────────────────────────────────────┘
 
 
 @service('EiOpt')
 class OptService(VTNService):
-    pass
+
+    def __init__(self, vtn_id):
+        super().__init__(vtn_id)
+        self.created_opt_schedules = {}
+
+    @handler('oadrCreateOpt')
+    async def create_opt(self, payload):
+        """
+        Handle an opt schedule created by the VEN
+        """
+
+        pass  # TODO: call handler and return the result (oadrCreatedOpt)
+
+    def on_create_opt(self, payload):
+        """
+        Implementation of the on_create_opt handler, may be overwritten by the user.
+        """
+        ven_id = payload['ven_id']
+
+        if payload['ven_id'] not in self.created_opt_schedules:
+            self.created_opt_schedules[ven_id] = []
+
+        # TODO: internally create an opt schedule and save it, if this is an optional handler then make sure to handle None returns
+
+        return 'oadrCreatedOpt', {'opt_id': payload['opt_id']}
+
+    @handler('oadrCancelOpt')
+    async def cancel_opt(self, payload):
+        """
+        Cancel an opt schedule previously created by the VEN
+        """
+        ven_id = payload['ven_id']
+        opt_id = payload['opt_id']
+
+        pass  # TODO: call handler and return result (oadrCanceledOpt)
+
+    def on_cancel_opt(self, ven_id, opt_id):
+        """
+        Placeholder for the on_cancel_opt handler.
+        """
+
+        # TODO: implement cancellation of previously acknowledged opt schedule, if this is an optional handler make sure to hande None returns
+
+        return 'oadrCanceledOpt', {'opt_id': opt_id}
diff --git a/openleadr/templates/oadrCreateOpt.xml b/openleadr/templates/oadrCreateOpt.xml
@@ -7,14 +7,15 @@
     <emix:marketContext>{{ market_context }}</emix:marketContext>
     {% endif %}
     <ei:venID>{{ ven_id }}</ei:venID>
-    {% if vavailability is defined and vavalailability is not none %}
+    {% if vavailability is defined and vavailability is not none %}
     <xcal:vavailability>
       <xcal:components>
         {% for component in vavailability.components %}
         <xcal:available>
           <xcal:properties>
             <xcal:dtstart>
-              <xcal:date-time>{{ component.dtstart|datetimeformat }}</xcal:date-time></xcal:dtstart>
+              <xcal:date-time>{{ component.dtstart|datetimeformat }}</xcal:date-time>
+            </xcal:dtstart>
             <xcal:duration>
               <xcal:duration>{{ component.duration|timedeltaformat }}</xcal:duration>
             </xcal:duration>
@@ -33,5 +34,12 @@
     {% for target in targets %}
     {% include 'parts/eiTarget.xml' %}
     {% endfor %}
+    {% if signal_target_mrid is defined and signal_target_mrid is not none %}
+    <oadr:oadrDeviceClass>
+				<power:endDeviceAsset>
+					<power:mrid>{{ signal_target_mrid }}</power:mrid>
+				</power:endDeviceAsset>
+		</oadr:oadrDeviceClass>
+    {% endif %}
   </oadr:oadrCreateOpt>
 </oadr:oadrSignedObject>
diff --git a/openleadr/templates/oadrCreatedOpt.xml b/openleadr/templates/oadrCreatedOpt.xml
