juham-automation 0.0.12__py3-none-any.whl → 0.2.8__py3-none-any.whl

juham_automation/__init__.py

@@ -7,10 +7,11 @@ Juham - Juha's Ultimate Home Automation Masterpiece
 """
 
 from .automation import EnergyCostCalculator
-from .automation import PowerMeterSimulator
 from .automation import SpotHintaFi
 from .automation import WaterCirculator
-from .automation import HotWaterOptimizer
+from .automation import HeatingOptimizer
+from .automation import EnergyBalancer
+from .automation import LeakDetector
 from .ts import EnergyCostCalculatorTs
 from .ts import ForecastTs
 from .ts import LogTs
@@ -18,6 +19,7 @@ from .ts import PowerTs
 from .ts import PowerPlanTs
 from .ts import PowerMeterTs
 from .ts import ElectricityPriceTs
+from .ts import EnergyBalancerTs
 from .japp import JApp
 
 
@@ -25,7 +27,9 @@ __all__ = [
     "EnergyCostCalculator",
     "EnergyCostCalculatorTs",
     "ForecastTs",
-    "HotWaterOptimizer",
+    "HeatingOptimizer",
+    "EnergyBalancer",
+    "LeakDetector",
     "LogTs",
     "PowerTs",
     "PowerPlanTs",
@@ -33,6 +37,6 @@ __all__ = [
     "SpotHintaFi",
     "WaterCirculator",
     "JApp",
-    "PowerMeterSimulator",
     "ElectricityPriceTs",
+    "EnergyBalancerTs",
 ]

juham_automation/automation/__init__.py

@@ -9,13 +9,15 @@ Juham - Juha's Ultimate Home Automation classes
 from .energycostcalculator import EnergyCostCalculator
 from .spothintafi import SpotHintaFi
 from .watercirculator import WaterCirculator
-from .hotwateroptimizer import HotWaterOptimizer
-from .powermeter_simulator import PowerMeterSimulator
+from .heatingoptimizer import HeatingOptimizer
+from .energybalancer import EnergyBalancer
+from .leakdetector import LeakDetector
 
 __all__ = [
     "EnergyCostCalculator",
-    "HotWaterOptimizer",
+    "HeatingOptimizer",
     "SpotHintaFi",
     "WaterCirculator",
-    "PowerMeterSimulator",
+    "EnergyBalancer",
+    "LeakDetector",
 ]

juham_automation/automation/energybalancer.py

@@ -0,0 +1,281 @@
+import json
+from typing import Any
+from typing_extensions import override
+
+from juham_core import Juham, timestamp
+from masterpiece import MqttMsg
+
+
+class Consumer:
+    """Class representing a consumer.
+
+    This class is used to represent a consumer in the energy balancer.
+    It contains the name of the consumer and its power consumption.
+
+    """
+
+    def __init__(self, name: str, power: float, weight: float) -> None:
+        """Initialize the consumer
+
+        Args:
+            name (str): name of the consumer
+            power (float): power of the consumer in watts
+        """
+        self.name = name
+        self.power: float = power
+        self.start: float = 0.0
+        self.stop: float = 0.0
+        self.weight: float = weight
+
+
+class EnergyBalancer(Juham):
+    """The energy balancer monitors the balance between produced and consumed energy
+    within the balancing interval to determine if there is enough energy available for
+    a given energy-consuming device, such as heating radiators, to operate within the
+    remaining time of the interval.
+
+    Any number of energy-consuming devices can be connected to the energy balancer, with
+    without any restrictions on the power consumption. The energy balancer will monitor the
+    power consumption of the devices and determine if there is enough energy available for
+    the devices to operate within the remaining time of the balancing interval.
+
+    The energy balancer is used in conjunction with a power meter that reads
+    the total power consumption of the house. The energy balancer uses the power meter
+
+
+    """
+
+    #: Description of the attribute
+    energy_balancing_interval: int = 900
+    """The time interval in seconds for energy balancing."""
+
+    def __init__(self, name: str = "energybalancer") -> None:
+        """Initialize the energy balancer.
+
+        Args:
+            name (str): name of the heating radiator
+            power (float): power of the consumer in watts
+        """
+        super().__init__(name)
+
+        self.topic_in_consumers = self.make_topic_name("energybalance/consumers")
+        self.topic_out_status = self.make_topic_name("energybalance/status")
+        self.topic_out_diagnostics = self.make_topic_name("energybalance/diagnostics")
+        self.topic_in_power = self.make_topic_name("net_energy_balance")
+
+        self.net_energy_balance: float = 0.0  # Energy balance in joules (watt-seconds)
+        self.current_interval_ts: float = -1
+        self.needed_energy: float = 0.0  # Energy needed in joules (watt-seconds)
+        self.net_energy_balancing_mode: bool = False
+        self.consumers: dict[str, Consumer] = {}
+
+    @override
+    def on_connect(self, client: object, userdata: Any, flags: int, rc: int) -> None:
+        super().on_connect(client, userdata, flags, rc)
+        if rc == 0:
+            self.subscribe(self.topic_in_power)
+            self.subscribe(self.topic_in_consumers)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        ts: float = timestamp()
+
+        if msg.topic == self.topic_in_power:
+            self.on_power(json.loads(msg.payload.decode()), ts)
+        elif msg.topic == self.topic_in_consumers:
+            self.on_consumer(json.loads(msg.payload.decode()))
+        else:
+            super().on_message(client, userdata, msg)
+
+    def on_power(self, m: dict[str, Any], ts: float) -> None:
+        """Handle the power consumption. Read the current power balance and accumulate
+        to the net energy balance to reflect the  energy produced (or consumed) within the
+        current time slot.
+        Args:
+            m (dict[str, Any]): power consumption message
+            ts (float): current time
+        """
+        self.update_energy_balance(m["power"], ts)
+
+    def on_consumer(self, m: dict[str, Any]) -> None:
+        """Add consumer, e.g. heating radiator to be controlled.
+        Args:
+            m (dict[str, Any]): power consumer message
+            ts (float): current time
+        """
+        self.consumers[m["Unit"]] = Consumer(m["Unit"], m["Power"], m["Weight"])
+        self.info(
+            f"Consumer {m['Unit']} added, power: {m['Power']}, weight: {m['Weight']}"
+        )
+
+    def update_energy_balance(self, power: float, ts: float) -> None:
+        """Update the current net net energy balance. The change in the balance is calculate the
+        energy balance, which the time elapsed since the last update, multiplied by the
+        power. Positive energy balance means we have produced energy that can be consumed
+        at the end of the interval. The target is to use all the energy produced during the
+        balancing interval. This method is called  by the powermeter reading the
+        total power consumption of the house.
+
+        Args:
+            power (float): power reading from the powermeter. Positive value means
+                energy produced, negative value means energy consumed. The value of 0 means
+                the house is not consuming or producing energy.
+            ts (float): current time in utc seconds
+        """
+
+        # regardless of the mode, if we hit the end of the interval, reset the balance
+
+        interval_ts: float = ts % self.energy_balancing_interval
+        if self.current_interval_ts < 0 or interval_ts <= self.current_interval_ts:
+            # time runs backwards, must be a new interval
+            self.reset_net_energy_balance(interval_ts)
+        else:
+            # update the energy balance with the elapsed time and the power
+            elapsed_ts = interval_ts - self.current_interval_ts
+            balance: float = elapsed_ts * power  # joules i.e. watt-seconds
+            self.net_energy_balance = self.net_energy_balance + balance
+            self.current_interval_ts = interval_ts
+            self.needed_energy = self.calculate_needed_energy(interval_ts)
+            if self.net_energy_balancing_mode:
+                if self.net_energy_balance <= 0:
+                    # if we have used all the energy, disable the balancing mode
+                    self.reset_net_energy_balance(0.0)
+            else:
+                # consider enabling the balancing mode
+                # if we have enough energy to power the radiator for the rest of the time slot
+                if self.net_energy_balance >= self.needed_energy:
+                    self.net_energy_balancing_mode = True
+                    self.initialize_consumer_timelines(ts)
+        self.publish_energybalance(ts)
+
+    def calculate_needed_energy(self, interval_ts: float) -> float:
+        """Calculate the energy needed to power the consumer for the rest of the time slot.
+        Assumes consumers run one at a time in serialized manner and are evenly distributed over the time slot
+        to minimze the power peak.
+
+        Args:
+            interval_ts (float): current elapsed seconds within the balancing interval.
+
+        Returns:
+            float: energy needed in joules
+        """
+
+        required_power: float = 0.0
+        num_consumers: int = len(self.consumers)
+        if num_consumers == 0:
+            return 0.0
+        remaining_ts_consumer: float = (
+            self.energy_balancing_interval - interval_ts
+        ) / num_consumers
+        total_weight: float = 0.0
+        for consumer in self.consumers.values():
+            total_weight += consumer.weight
+        equal_weight: float = total_weight / num_consumers
+        for consumer in self.consumers.values():
+            required_power += (
+                (consumer.weight / equal_weight)
+                * consumer.power
+                * remaining_ts_consumer
+            )
+        return required_power
+
+    def initialize_consumer_timelines(self, ts: float) -> None:
+        """Initialize the list of active consumers with their start and stop times.
+
+        Args:
+            ts (float): current time.
+
+        Returns:
+            None
+        """
+        num_consumers: int = len(self.consumers)
+        if num_consumers == 0:
+            return  # If there are no consumers, we simply do nothing
+        interval_ts: float = ts % self.energy_balancing_interval
+        secs_per_consumer: float = (
+            self.energy_balancing_interval - interval_ts
+        ) / num_consumers
+
+        total_weight: float = 0.0
+        for consumer in self.consumers.values():
+            total_weight += consumer.weight
+        equal_weight: float = total_weight / num_consumers
+
+        for consumer in self.consumers.values():
+            consumer.start = interval_ts
+            consumer.stop = (
+                interval_ts + secs_per_consumer * consumer.weight / equal_weight
+            )
+            interval_ts += secs_per_consumer
+
+    def publish_energybalance(self, ts: float) -> None:
+        """Publish  diagnostics and status.
+
+        Args:
+            ts (float): current time.
+
+        Returns:
+            None
+        """
+
+        # publish diagnostics
+        m: dict[str, Any] = {
+            "EnergyBalancer": self.name,
+            "CurrentBalance": self.net_energy_balance,
+            "NeededBalance": self.needed_energy,
+            "Timestamp": ts,
+        }
+        self.publish(self.topic_out_diagnostics, json.dumps(m))
+
+        # publish consumer statuses to control consumers
+        num_consumers: int = len(self.consumers)
+        if num_consumers == 0:
+            return  # If there are no consumers, we simply do nothing
+        interval_ts = ts % self.energy_balancing_interval
+        for consumer in self.consumers.values():
+            m = {
+                "EnergyBalancer": self.name,
+                "Unit": consumer.name,
+                "Power": consumer.power,
+                "Mode": consumer.start <= interval_ts < consumer.stop,
+                "Weight": consumer.weight,
+                "Timestamp": ts,
+            }
+            self.publish(self.topic_out_status, json.dumps(m))
+
+    def detect_consumer_status(self, name: str, ts: float) -> bool:
+        """Detect consumer status
+
+        Args:
+            name (str): name of the consumer
+            ts (float): current time.
+
+        Returns:
+            True if the consumer is active, False otherwise
+        """
+        consumer: Consumer = self.consumers[name]
+        interval_ts = ts % self.energy_balancing_interval
+        return consumer.start <= interval_ts < consumer.stop
+
+    def reset_net_energy_balance(self, interval_ts: float) -> None:
+        """Reset the net energy balance at the end of the interval."""
+        self.net_energy_balance = 0.0
+        self.current_interval_ts = interval_ts
+        self.needed_energy = self.calculate_needed_energy(interval_ts)
+        self.net_energy_balancing_mode = False
+        for consumer in self.consumers.values():
+            consumer.start = 0.0
+            consumer.stop = 0.0
+
+    def activate_balancing_mode(self, ts: float) -> None:
+        """Activate balancing mode when enough energy is available."""
+        self.net_energy_balancing_mode = True
+        self.info(
+            f"{int(self.net_energy_balance/3600)} Wh is enough to supply the radiator, enable"
+        )
+
+    def deactivate_balancing_mode(self) -> None:
+        """Deactivate balancing mode when energy is depleted or interval ends."""
+        self.net_energy_balancing_mode = False
+        self.info("Balance used, or the end of the interval reached, disable")
+        self.net_energy_balance = 0.0  # Reset the energy balance at the interval's end

juham_automation/automation/energycostcalculator.py

@@ -6,19 +6,21 @@ from juham_core import Juham
 from juham_core.timeutils import (
     elapsed_seconds_in_day,
     elapsed_seconds_in_hour,
+    elapsed_seconds_in_interval,
     quantize,
     timestamp,
 )
 
 
 class EnergyCostCalculator(Juham):
-    """The EnergyCostCalculator class calculates the net energy balance between produced
-    and consumed energy for Time-Based Settlement (TBS). It performs the following functions:
+    """The EnergyCostCalculator class calculates the net energy balance and cost between produced
+    (or consumed) energy for Time-Based Settlement (TBS). It performs the following functions:
 
     * Subscribes to 'spot' and 'power' MQTT topics.
     * Calculates the net energy and the rate of change of the net energy per hour and per day (24h)
-    * Publishes the calculated values to the MQTT net energy balance topic.
-    * Stores the data in a time series database.
+    * Calculates the cost of energy consumed/produced based on the spot prices.
+    * Publishes the calculated values to the MQTT net energy balance and cost topics.
+
 
     This information helps other home automation components optimize energy usage and
     minimize electricity bills.
@@ -27,17 +29,20 @@ class EnergyCostCalculator(Juham):
     _kwh_to_joule_coeff: float = 1000.0 * 3600
     _joule_to_kwh_coeff: float = 1.0 / _kwh_to_joule_coeff
 
-    energy_balancing_interval: float = 3600
+    energy_balancing_interval: int = 900 # in seconds (15 minutes)
 
     def __init__(self, name: str = "ecc") -> None:
         super().__init__(name)
         self.current_ts: float = 0
+        self.total_balance_interval : float = 0
         self.total_balance_hour: float = 0
         self.total_balance_day: float = 0
+        self.net_energy_balance_cost_interval: float = 0
         self.net_energy_balance_cost_hour: float = 0
         self.net_energy_balance_cost_day: float = 0
-        self.net_energy_balance_start_hour = elapsed_seconds_in_hour(timestamp())
-        self.net_energy_balance_start_day = elapsed_seconds_in_day(timestamp())
+        self.net_energy_balance_start_interval : float = elapsed_seconds_in_interval(timestamp(), self.energy_balancing_interval)
+        self.net_energy_balance_start_hour : float = elapsed_seconds_in_hour(timestamp())
+        self.net_energy_balance_start_day : float = elapsed_seconds_in_day(timestamp())
         self.spots: list[dict[str, float]] = []
         self.init_topics()
 
@@ -64,13 +69,13 @@ class EnergyCostCalculator(Juham):
         elif msg.topic == self.topic_in_powerconsumption:
             self.on_powerconsumption(ts_now, m)
         else:
-            self.error(f"Unknown event {msg.topic}")
+            super().on_message(client, userdata, msg)
 
     def on_spot(self, spot: dict[Any, Any]) -> None:
-        """Stores the received per hour electricity prices to spots list.
+        """Stores the received per slot electricity prices to spots list.
 
         Args:
-            spot (list): list of hourly spot prices
+            spot (list): list of spot prices
         """
 
         for s in spot:
@@ -87,76 +92,91 @@ class EnergyCostCalculator(Juham):
         """
         return price * self._joule_to_kwh_coeff
 
-    def get_prices(self, ts_prev: float, ts_now: float) -> tuple[float, float]:
-        """Fetch the electricity prices for the given two subsequent time
-        stamps.
+
+    def get_price_at(self, ts: float) -> float:
+        """Return the spot price applicable at the given timestamp.
 
         Args:
-            ts_prev (float): previous time
-            ts_now (float): current time
+            ts (float): current time (epoch seconds)
+
         Returns:
-            Electricity prices for the given interval
+            float: PriceWithTax for the slot that contains ts. Returns the last
+                known price if ts is equal/after the last spot timestamp.
+                Returns 0.0 and logs an error if no matching slot is found.
         """
-        prev_price = None
-        current_price = None
+        if not self.spots:
+            self.error(f"PANIC: no spot prices available; lookup ts={ts}")
+            return 0.0
+
+        # ensure spots sorted by timestamp (defensive)
+        try:
+            # cheap check — assumes list of dicts with "Timestamp"
+            if any(self.spots[i]["Timestamp"] > self.spots[i + 1]["Timestamp"] for i in range(len(self.spots) - 1)):
+                self.spots.sort(key=lambda r: r["Timestamp"])
+        except Exception:
+            # if unexpected structure, still try safe path below and log
+            self.debug("get_price_at: spot list structure unexpected while checking sort order", "")
 
         for i in range(0, len(self.spots) - 1):
             r0 = self.spots[i]
             r1 = self.spots[i + 1]
             ts0 = r0["Timestamp"]
             ts1 = r1["Timestamp"]
-            if ts_prev >= ts0 and ts_prev <= ts1:
-                prev_price = r0["PriceWithTax"]
-            if ts_now >= ts0 and ts_now <= ts1:
-                current_price = r0["PriceWithTax"]
-            if prev_price is not None and current_price is not None:
-                return prev_price, current_price
-        self.error("PANIC: run out of spot prices")
-        return 0.0, 0.0
+            if ts >= ts0 and ts < ts1:
+                return r0["PriceWithTax"]
+
+        # If timestamp is exactly equal to the last spot timestamp or beyond
+        last = self.spots[-1]
+        if ts >= last["Timestamp"]:
+            return last["PriceWithTax"]
+
+        # If we get here, ts is before the first spot timestamp
+        first = self.spots[0]
+        self.error(
+            f"PANIC: Timestamp {ts} out of bounds for spot price lookup; "
+            f"first=(ts={first['Timestamp']}, price={first.get('PriceWithTax')}), "
+            f"last=(ts={last['Timestamp']}, price={last.get('PriceWithTax')}), "
+            f"len(spots)={len(self.spots)}"
+        )
+        return 0.0
+
+
 
     def calculate_net_energy_cost(
         self, ts_prev: float, ts_now: float, energy: float
     ) -> float:
-        """Given time interval as start and stop Calculate the cost over the
-        given time period. Positive values indicate revenue, negative cost.
+        """
+        Calculate the cost (or revenue) of energy consumed/produced over the given time interval.
+        Positive values indicate revenue, negative values indicate cost.
 
         Args:
-            ts_prev (timestamp): beginning time stamp of the interval
-            ts_now (timestamp): end of the interval
-            energy (float): energy consumed during the time interval
+            ts_prev (float): Start timestamp of the interval
+            ts_now (float): End timestamp of the interval
+            energy (float): Energy consumed during the interval (in watts or Joules)
+
         Returns:
-            Cost or revenue
+            float: Total cost/revenue for the interval
         """
-        cost: float = 0
-        prev = ts_prev
-        while prev < ts_now:
-            elapsed_seconds: float = ts_now - prev
-            if elapsed_seconds > self.energy_balancing_interval:
-                elapsed_seconds = self.energy_balancing_interval
-            now = prev + elapsed_seconds
-            start_per_kwh, stop_per_kwh = self.get_prices(prev, now)
-            start_price = self.map_kwh_prices_to_joules(start_per_kwh)
-            stop_price = self.map_kwh_prices_to_joules(stop_per_kwh)
-            if abs(stop_price - start_price) < 1e-24:
-                cost = cost + energy * elapsed_seconds * start_price
-            else:
-                # interpolate cost over energy balancing interval boundary
-                elapsed = now - prev
-                if elapsed < 0.00001:
-                    return 0.0
-                ts_0 = quantize(self.energy_balancing_interval, now)
-                t1 = (ts_0 - prev) / elapsed
-                t2 = (now - ts_0) / elapsed
-                cost = (
-                    cost
-                    + energy
-                    * ((1.0 - t1) * start_price + t2 * stop_price)
-                    * elapsed_seconds
-                )
-
-            prev = prev + elapsed_seconds
+        cost = 0.0
+        current = ts_prev
+        interval = self.energy_balancing_interval
+
+        while current < ts_now:
+            next_ts = min(ts_now, current + interval)
+            # Get spot price at start and end of interval
+            price_start = self.map_kwh_prices_to_joules(self.get_price_at(current))
+            price_end = self.map_kwh_prices_to_joules(self.get_price_at(next_ts))
+
+            # Trapezoidal integration: average price over interval
+            avg_price = (price_start + price_end) / 2.0
+            dt = next_ts - current
+            cost += energy * avg_price * dt
+
+            current = next_ts
+
         return cost
 
+
     def on_powerconsumption(self, ts_now: float, m: dict[Any, Any]) -> None:
         """Calculate net energy cost and update the hourly consumption attribute
         accordingly.
@@ -169,21 +189,29 @@ class EnergyCostCalculator(Juham):
         if not self.spots:
             self.info("Waiting for electricity prices...")
         elif self.current_ts == 0:
+            self.net_energy_balance_cost_interval = 0.0
             self.net_energy_balance_cost_hour = 0.0
             self.net_energy_balance_cost_day = 0.0
             self.current_ts = ts_now
-            self.net_energy_balance_start_hour = quantize(
+            self.net_energy_balance_start_interval = quantize(
                 self.energy_balancing_interval, ts_now
             )
+            self.net_energy_balance_start_hour = quantize(
+                3600, ts_now
+            )
         else:
             # calculate cost of energy consumed/produced
             dp: float = self.calculate_net_energy_cost(self.current_ts, ts_now, power)
+            self.net_energy_balance_cost_interval = self.net_energy_balance_cost_interval + dp
             self.net_energy_balance_cost_hour = self.net_energy_balance_cost_hour + dp
             self.net_energy_balance_cost_day = self.net_energy_balance_cost_day + dp
 
             # calculate and publish energy balance
             dt = ts_now - self.current_ts  # time elapsed since previous call
             balance = dt * power  # energy consumed/produced in this slot in Joules
+            self.total_balance_interval = (
+                self.total_balance_interval + balance * self._joule_to_kwh_coeff
+            )
             self.total_balance_hour = (
                 self.total_balance_hour + balance * self._joule_to_kwh_coeff
             )
@@ -194,16 +222,32 @@ class EnergyCostCalculator(Juham):
             self.publish_energy_cost(
                 ts_now,
                 self.name,
+                self.net_energy_balance_cost_interval,
                 self.net_energy_balance_cost_hour,
                 self.net_energy_balance_cost_day,
             )
 
             # Check if the current energy balancing interval has ended
             # If so, reset the net_energy_balance attribute for the next interval
-            if (
-                ts_now - self.net_energy_balance_start_hour
-                > self.energy_balancing_interval
-            ):
+            if ts_now - self.net_energy_balance_start_interval > self.energy_balancing_interval:
+                # publish average energy cost per hour
+                if abs(self.total_balance_interval) > 0:
+                    msg = {
+                        "name": self.name,
+                        "average_interval": self.net_energy_balance_cost_interval
+                        / self.total_balance_interval,
+                        "ts": ts_now,
+                    }
+                    self.publish(self.topic_out_energy_cost, json.dumps(msg), 0, False)
+
+                # reset for the next hour
+                self.total_balance_interval = 0
+                self.net_energy_balance_cost_interval = 0.0
+                self.net_energy_balance_start_interval = ts_now
+
+            # Check if the current energy balancing interval has ended
+            # If so, reset the net_energy_balance attribute for the next interval
+            if ts_now - self.net_energy_balance_start_hour > 3600:
                 # publish average energy cost per hour
                 if abs(self.total_balance_hour) > 0:
                     msg = {
@@ -252,9 +296,9 @@ class EnergyCostCalculator(Juham):
         self.publish(self.topic_out_net_energy_balance, json.dumps(msg), 1, True)
 
     def publish_energy_cost(
-        self, ts_now: float, site: str, cost_hour: float, cost_day: float
+        self, ts_now: float, site: str, cost_interval : float, cost_hour: float, cost_day: float
     ) -> None:
-        """Publish daily and hourly energy cost/revenue
+        """Publish daily, hourly and per interval energy cost/revenue
 
         Args:
             ts_now (float): timestamp
@@ -262,5 +306,5 @@ class EnergyCostCalculator(Juham):
             cost_hour (float): cost or revenue per hour.
             cost_day (float) : cost or revenue per day
         """
-        msg = {"name": site, "cost_hour": cost_hour, "cost_day": cost_day, "ts": ts_now}
+        msg = {"name": site, "cost_interval": cost_interval, "cost_hour": cost_hour, "cost_day": cost_day, "ts": ts_now}
         self.publish(self.topic_out_energy_cost, json.dumps(msg), 1, True)