feat: added configuration for standard target timeframes to determine minimum minutes for a slot to be evaluated (1 hour 30 minutes dev time)

Author: BottlecapDave

_docs/setup/target_timeframe.md

@@ -131,6 +131,14 @@ These settings can have undesired effects and are not recommended to be changed,
 
 By default, the target timeframe isn't calculated if there isn't enough data for the period of time being evaluated. For example, if you have a timeframe looking between 10pm and 2am, it's 9pm and you only have data up to midnight, then the next target timeframe will not be calculated. If you turn this setting on, then the sensor will attempt to look for data between 10pm and 2am if available, otherwise it will evaluate with whatever data is available (in this scenario 10pm to 12am).
 
+#### Minimum required minutes in slots
+
+By default, 30 minute slots that are part way through are not considered when evaluating target time frames. For example, if you are looking for the best slots between 10:00 to 12:00 and it's 10:01, then only slots between 10:30 to 12:00 will be evaluated. This threshold can be changed here to a lower value if you want to take account of slots that are partially in the past. For example if this was set to 29, then the previous example would evaluate slots between 10:00 to 12:00.
+
+!!! warn
+
+    Changing this can cause sensors to not come on for the correct amount of time by up to 30 minutes.
+
 ## Attributes
 
 The following attributes are available on each sensor
@@ -163,6 +171,7 @@ The following attributes are available on each sensor
 | `next_max_value` | `float` | The average value for the next continuous discovered period. This will only be populated if `target_times` has been calculated and at least one period/block is in the future. |
 | `target_times_last_evaluated` | datetime | The datetime the target times collection was last evaluated. This will occur if all previous target times are in the past and all values are available for the requested future time period. For example, if you are targeting 16:00 (day 1) to 16:00 (day 2), and you only have values up to 23:00 (day 1), then the target values won't be calculated. |
 | `calculate_with_incomplete_data` | boolean | Determines if calculations should occur when there isn't enough data to satisfy the look ahead hours |
+| `minimum_required_minutes_in_slot` | integer | Determines the configured minimum number of minutes to be present in a slot for it to be considered |
 
 ## Services
 

custom_components/target_timeframes/config/target_timeframe.py

@@ -11,6 +11,7 @@
   CONFIG_TARGET_HOURS_MODE_MINIMUM,
   CONFIG_TARGET_MAX_VALUE,
   CONFIG_TARGET_MIN_VALUE,
+  CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT,
   CONFIG_TARGET_NAME,
   CONFIG_TARGET_OFFSET,
   CONFIG_TARGET_START_TIME,
@@ -162,4 +163,19 @@ def validate_target_timeframe_config(data):
     if is_time_frame_long_enough(data[CONFIG_TARGET_HOURS], start_time, end_time) == False:
       errors[CONFIG_TARGET_HOURS] = "invalid_hours_time_frame"
 
+  minimum_required_minutes_in_slot: int | None = None
+  if CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT in data and data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] is not None:
+    if isinstance(data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT], int) == False:
+      matches = re.search(REGEX_VALUE, data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT])
+      if matches is None:
+        errors[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] = "invalid_integer"
+      else:
+        minimum_required_minutes_in_slot = float(data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT])
+        data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] = minimum_required_minutes_in_slot
+    else:
+      minimum_required_minutes_in_slot = data[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT]
+
+  if minimum_required_minutes_in_slot is not None and (minimum_required_minutes_in_slot < 1 or minimum_required_minutes_in_slot > 30):
+    errors[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] = "invalid_minimum_required_minutes_in_slot"
+
   return errors

custom_components/target_timeframes/const.py

@@ -40,6 +40,8 @@
 CONFIG_TARGET_TARGET_TIMES_EVALUATION_MODE_ALWAYS = "always"
 CONFIG_TARGET_DANGEROUS_SETTINGS = "dangerous_settings"
 CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA = "calculate_with_incomplete_data"
+CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT = "minimum_required_minutes_in_slot"
+CONFIG_TARGET_DEFAULT_MINIMUM_REQUIRED_MINUTES_IN_SLOT = 30
 
 CONFIG_ROLLING_TARGET_HOURS_LOOK_AHEAD = "look_ahead_hours"
 
@@ -123,6 +125,7 @@
     vol.Schema(
         {
             vol.Required(CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA, default=False): bool,
+            vol.Required(CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT, default=CONFIG_TARGET_DEFAULT_MINIMUM_REQUIRED_MINUTES_IN_SLOT): int,
         }
     ),
     {"collapsed": True},

custom_components/target_timeframes/entities/__init__.py

@@ -43,7 +43,7 @@ def is_target_timeframe_complete_in_period(current_date: datetime, start_time: d
     target_timeframes[-1]["end"] <= current_date
   )
 
-def get_start_and_end_times(current_date: datetime, target_start_time: str, target_end_time: str, start_time_not_in_past = True, context: str = None):
+def get_start_and_end_times(current_date: datetime, target_start_time: str, target_end_time: str, minimum_slot_minutes = None, context: str = None):
   if (target_start_time is not None):
     target_start = parse_datetime(current_date.strftime(f"%Y-%m-%dT{target_start_time}:00%z"))
   else:
@@ -64,10 +64,15 @@ def get_start_and_end_times(current_date: datetime, target_start_time: str, targ
     else:
       target_end = target_end + timedelta(days=1)
 
-  # If our start date has passed, reset it to current_date to avoid picking a slot in the past
-  if (start_time_not_in_past == True and target_start < current_date and current_date < target_end):
-    _LOGGER.debug(f'{context} - Rolling target and {target_start} is in the past. Setting start to {current_date}')
-    target_start = current_date
+  if (minimum_slot_minutes is not None and target_start < current_date and current_date < target_end):
+    current_date_start = current_date.replace(minute=30 if current_date.minute >= 30 else 0, second=0, microsecond=0)
+    minutes_remaining_in_current_slot = 30 - ((current_date.replace(second=0, microsecond=0) - current_date_start).total_seconds() / 60)
+    if (minutes_remaining_in_current_slot >= minimum_slot_minutes):
+      _LOGGER.debug(f'{context} - Current slot is sufficient for minimum slot minutes, so using current date start: {current_date_start}')
+      target_start = current_date_start
+    else:
+      target_start = current_date_start + timedelta(minutes=30)
+      _LOGGER.debug(f'{context} - Current slot is not sufficient for minimum slot minutes, so using next slot start: {target_start}')
 
   # If our start and end are both in the past, then look to the next day
   if (target_start < current_date and target_end < current_date):

custom_components/target_timeframes/entities/target_timeframe.py

@@ -22,6 +22,8 @@
 from ..const import (
   CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA,
   CONFIG_TARGET_DANGEROUS_SETTINGS,
+  CONFIG_TARGET_DEFAULT_MINIMUM_REQUIRED_MINUTES_IN_SLOT,
+  CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT,
   CONFIG_TARGET_TARGET_TIMES_EVALUATION_MODE,
   CONFIG_TARGET_TARGET_TIMES_EVALUATION_MODE_ALL_IN_PAST,
   CONFIG_TARGET_HOURS_MODE,
@@ -164,7 +166,13 @@ async def async_update(self):
         if CONFIG_TARGET_DANGEROUS_SETTINGS in self._config and CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA in self._config[CONFIG_TARGET_DANGEROUS_SETTINGS]:
           calculate_with_incomplete_data = self._config[CONFIG_TARGET_DANGEROUS_SETTINGS][CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA]
 
-        target_start, target_end = get_start_and_end_times(current_local_date, start_time, end_time, True, self._config[CONFIG_TARGET_NAME])
+        target_start, target_end = get_start_and_end_times(
+          current_local_date,
+          start_time,
+          end_time,
+          self._config[CONFIG_TARGET_DANGEROUS_SETTINGS][CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] if CONFIG_TARGET_DANGEROUS_SETTINGS in self._config and CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT in self._config[CONFIG_TARGET_DANGEROUS_SETTINGS] else CONFIG_TARGET_DEFAULT_MINIMUM_REQUIRED_MINUTES_IN_SLOT,
+          self._config[CONFIG_TARGET_NAME]
+        )
         applicable_time_periods = get_fixed_applicable_time_periods(
           target_start,
           target_end,
@@ -174,7 +182,7 @@ async def async_update(self):
         )
 
         # Make sure we haven't already completed for the current target timeframe
-        applicable_target_start, applicable_target_end = get_start_and_end_times(current_local_date, start_time, end_time, False, self._config[CONFIG_TARGET_NAME])
+        applicable_target_start, applicable_target_end = get_start_and_end_times(current_local_date, start_time, end_time, None, self._config[CONFIG_TARGET_NAME])
         is_target_timeframe_complete = is_rolling_target == False and is_target_timeframe_complete_in_period(
           current_local_date,
           applicable_target_start,
@@ -368,4 +376,10 @@ def update_default_attributes(self):
     if CONFIG_TARGET_DANGEROUS_SETTINGS in self._config and CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA in self._config[CONFIG_TARGET_DANGEROUS_SETTINGS]:
       calculate_with_incomplete_data = self._config[CONFIG_TARGET_DANGEROUS_SETTINGS][CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA]
       del self._attributes[CONFIG_TARGET_DANGEROUS_SETTINGS]
-    self._attributes[CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA] = calculate_with_incomplete_data
+    self._attributes[CONFIG_TARGET_CALCULATE_WITH_INCOMPLETE_DATA] = calculate_with_incomplete_data
+
+    minimum_required_minutes_in_slot = CONFIG_TARGET_DEFAULT_MINIMUM_REQUIRED_MINUTES_IN_SLOT
+    if CONFIG_TARGET_DANGEROUS_SETTINGS in self._config and CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT in self._config[CONFIG_TARGET_DANGEROUS_SETTINGS]:
+      minimum_required_minutes_in_slot = self._config[CONFIG_TARGET_DANGEROUS_SETTINGS][CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT]
+      del self._attributes[CONFIG_TARGET_DANGEROUS_SETTINGS]
+    self._attributes[CONFIG_TARGET_MINIMUM_REQUIRED_MINUTES_IN_SLOT] = minimum_required_minutes_in_slot

custom_components/target_timeframes/translations/en.json

@@ -63,7 +63,11 @@
               "name": "Dangerous settings",
               "description": "These settings can have undesired consequences if changed. Change at your own risk.",
               "data": {
-                "calculate_with_incomplete_data": "Calculate with incomplete data"
+                "calculate_with_incomplete_data": "Calculate with incomplete data",
+                "minimum_required_minutes_in_slot": "Minimum required minutes in slot"
+              },
+              "data_description": {
+                "minimum_required_minutes_in_slot": "The minimum number of minutes that must be present in a slot for it to be considered. Changing this can cause chosen slots to be partially in the past and therefore turn on for less than the desired time."
               }
             }
           }
@@ -98,7 +102,11 @@
               "name": "Dangerous settings",
               "description": "These settings can have undesired consequences if changed. Change at your own risk.",
               "data": {
-                "calculate_with_incomplete_data": "Calculate with incomplete data"
+                "calculate_with_incomplete_data": "Calculate with incomplete data",
+                "minimum_required_minutes_in_slot": "Minimum required minutes in slot"
+              },
+              "data_description": {
+                "minimum_required_minutes_in_slot": "The minimum number of minutes that must be present in a slot for it to be considered. Changing this can cause chosen slots to be partially in the past and therefore turn on for less than the desired time."
               }
             }
           }
@@ -117,7 +125,9 @@
         "weighting_not_supported_for_type": "Weighting is only supported for continuous target values",
         "weighting_not_supported_for_hour_mode": "Weighting is not supported for this hour mode",
         "minimum_or_maximum_value_not_specified": "Either minimum and/or maximum value must be specified for minimum hours mode",
-        "minimum_value_not_less_than_maximum_value": "Minimum value must be less or equal to the maximum value if both are specified"
+        "minimum_value_not_less_than_maximum_value": "Minimum value must be less or equal to the maximum value if both are specified",
+        "invalid_integer": "Value must be a number with no decimal places",
+        "invalid_minimum_required_minutes_in_slot": "Value must be between 1 and 30"
       }
     },
     "rolling_target_time_period": {
@@ -192,7 +202,9 @@
         "weighting_not_supported_for_type": "Weighting is only supported for continuous target values",
         "weighting_not_supported_for_hour_mode": "Weighting is not supported for this hour mode",
         "minimum_or_maximum_value_not_specified": "Either minimum and/or maximum value must be specified for minimum hours mode",
-        "minimum_value_not_less_than_maximum_value": "Minimum value must be less or equal to the maximum value if both are specified"
+        "minimum_value_not_less_than_maximum_value": "Minimum value must be less or equal to the maximum value if both are specified",
+        "invalid_integer": "Value must be a number with no decimal places",
+        "invalid_minimum_required_minutes_in_slot": "Value must be between 1 and 30"
       }
     }
   },