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

juham_automation/automation/leakdetector.py

@@ -0,0 +1,162 @@
+"""
+Leak Detector based on Motion Detection and Water Meter Monitoring.
+
+This class listens to water meter and motion sensor topics to detect potential water leaks.
+If a leak is detected, the system triggers a leak alarm.
+"""
+import json
+from datetime import datetime
+from typing import Any
+from typing_extensions import override
+from masterpiece.mqtt import MqttMsg
+from juham_core.timeutils import timestamp
+from juham_core import Juham
+
+
+class LeakDetector(Juham):
+    """
+    Water Leak Detector Class
+
+    Listens to water meter and motion sensor topics to identify potential water leaks.
+    If water consumption is detected without corresponding motion, or if water usage
+    remains constant for prolonged periods, a leak alarm is triggered.
+
+    Detection considers the time since the last motion detection and compares it to
+    the configured leak detection period, which is the maximum runtime of water-consuming
+    appliances.
+    """
+
+    _LEAKDETECTOR: str = "leakdetector"
+    _LEAKDETECTOR_ATTRS: list[str] = [
+        "watermeter_topic",
+        "motion_topic",
+        "motion_last_detected_ts",
+    ]
+
+    watermeter_topic: str = "watermeter"
+    motion_topic: str = "motion"
+    leak_detection_period: float = (
+        3 * 3600.0
+    )  # Maximum runtime for appliances, in seconds
+    location: str = "home"
+    conseq_zero_periods: int = (
+        60  # this many subsequent zero flow reports imply no leak
+    )
+
+    def __init__(self, name: str = "leakdetector") -> None:
+        """
+        Initialize the leak detector.
+
+        Args:
+            name (str, optional): Name of the detector instance. Defaults to "leakdetector".
+        """
+        super().__init__(name)
+        self.motion_last_detected_ts: float = timestamp()
+        self.watermeter_full_topic: str = self.make_topic_name(self.watermeter_topic)
+        self.motion_full_topic: str = self.make_topic_name(self.motion_topic)
+        self.leak_detected: bool = False
+        self.zero_usage_periods_count: int = 0
+
+    @override
+    def on_connect(self, client: object, userdata: Any, flags: int, rc: int) -> None:
+        """
+        Handle MQTT connection. Subscribe to water meter and motion topics.
+        """
+        super().on_connect(client, userdata, flags, rc)
+        if rc == 0:
+            self.subscribe(self.watermeter_full_topic)
+            self.subscribe(self.motion_full_topic)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        """
+        Process incoming MQTT messages for water meter and motion topics.
+        """
+        payload = json.loads(msg.payload.decode())
+        if msg.topic == self.watermeter_full_topic:
+            self.process_water_meter_data(payload)
+        elif msg.topic == self.motion_full_topic:
+            self.process_motion_data(payload)
+        else:
+            super().on_message(client, userdata, msg)
+
+    def detect_activity(self, current_ts: float) -> bool:
+        """
+        Check if activity (motion) has been detected within the leak detection period.
+
+        Args:
+            current_ts (float): Current timestamp.
+
+        Returns:
+            bool: True if activity detected within the period, False otherwise.
+        """
+        elapsed_time = current_ts - self.motion_last_detected_ts
+        return elapsed_time < self.leak_detection_period
+
+    def publish_leak_status(self, current_ts: float, leak_suspected: bool) -> None:
+        """
+        Publish the leak detection status.
+
+        Args:
+            current_ts (float): Current timestamp.
+            leak_suspected (bool): Whether a leak is suspected.
+        """
+        status : dict[str, Any] = {
+            "location": self.location,
+            "sensor": self.name,
+            "leak_suspected": leak_suspected,
+            "ts": current_ts,
+        }
+        payload = json.dumps(status)
+        self.publish(self.watermeter_full_topic, payload, qos=1, retain=False)
+
+    def process_water_meter_data(self, data: dict[str, float]) -> None:
+        """
+        Handle water meter data and apply leak detection logic.
+
+        Args:
+            data (dict): Water meter data containing flow rate and timestamp.
+        """
+        if "active_lpm" in data and "ts" in data:
+            flow_rate = data["active_lpm"]
+            current_ts = data["ts"]
+
+            if flow_rate > 0.0:
+                if not self.detect_activity(current_ts):
+                    if not self.leak_detected:
+                        self.leak_detected = True
+                        readable :str = datetime.fromtimestamp(self.motion_last_detected_ts).strftime("%Y-%m-%d %H:%M:%S")
+                        self.warning(f"LEAK SUSPECT", f"Flow {flow_rate} lpm, last detected motion {readable}")
+
+                self.zero_usage_periods_count = 0
+            else:
+                self.zero_usage_periods_count += 1
+                if self.zero_usage_periods_count > self.conseq_zero_periods:
+                    self.leak_detected = False
+                    self.motion_last_detected_ts = current_ts
+            self.publish_leak_status(current_ts, self.leak_detected)
+
+    def process_motion_data(self, data: dict[str, float]) -> None:
+        """
+        Update the last detected motion timestamp.
+
+        Args:
+            data (dict): Motion sensor data containing timestamp.
+        """
+        if "motion" in data and data["motion"]:
+            self.motion_last_detected_ts = data["ts"]
+
+    @override
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()
+        attributes = {attr: getattr(self, attr) for attr in self._LEAKDETECTOR_ATTRS}
+        data[self._LEAKDETECTOR] = attributes
+        return data
+
+    @override
+    def from_dict(self, data: dict[str, Any]) -> None:
+        super().from_dict(data)
+        if self._LEAKDETECTOR in data:
+            attributes = data[self._LEAKDETECTOR]
+            for attr in self._LEAKDETECTOR_ATTRS:
+                setattr(self, attr, attributes.get(attr, None))

juham_automation/automation/spothintafi.py

@@ -0,0 +1,140 @@
+from datetime import datetime
+import time
+import json
+from typing import Any, Dict, Optional, cast
+from typing_extensions import override
+
+from masterpiece.mqtt import Mqtt, MqttMsg
+from juham_core import JuhamCloudThread, JuhamThread
+
+
+class SpotHintaFiThread(JuhamCloudThread):
+    """Thread running SpotHinta.fi.
+
+    Periodically fetches the spot electricity prices and publishes them
+    to 'spot' topic.
+    """
+
+    _spot_topic: str = ""
+    _url: str = ""
+    _interval: float = 12 * 3600
+    grid_cost_day: float = 0.0314
+    grid_cost_night: float = 0.0132
+    grid_cost_tax: float = 0.028272
+
+    def __init__(self, client: Optional[Mqtt] = None) -> None:
+        super().__init__(client)
+        self._interval = 60
+
+    def init(self, topic: str, url: str, interval: float) -> None:
+        self._spot_topic = topic
+        self._url = url
+        self._interval = interval
+
+    @override
+    def make_weburl(self) -> str:
+        return self._url
+
+    @override
+    def update_interval(self) -> float:
+        return self._interval
+
+    @override
+    def process_data(self, rawdata: Any) -> None:
+        """Publish electricity price message to Juham topic.
+
+        Args:
+            rawdata (dict): electricity prices
+        """
+
+        super().process_data(rawdata)
+        data = rawdata.json()
+
+        spot = []
+        for e in data:
+            dt = datetime.fromisoformat(e["DateTime"])  # Correct timezone handling
+            ts = int(dt.timestamp())  # Ensure integer timestamps like in the test
+
+            hour = dt.strftime("%H")  # Correctly extract hour
+
+            if 6 <= int(hour) < 22:
+                grid_cost = self.grid_cost_day
+            else:
+                grid_cost = self.grid_cost_night
+
+            total_price = round(e["PriceWithTax"] + grid_cost + self.grid_cost_tax, 6)
+            grid_cost_total = round(grid_cost + self.grid_cost_tax, 6)
+
+            h = {
+                "Timestamp": ts,
+                "hour": hour,
+                "Rank": e["Rank"],
+                "PriceWithTax": total_price,
+                "GridCost": grid_cost_total,
+            }
+            spot.append(h)
+
+        self.publish(self._spot_topic, json.dumps(spot), 1, True)
+        # self.info(f"Spot electricity prices published for the next {len(spot)} days")
+
+
+class SpotHintaFi(JuhamThread):
+    """Spot electricity price for reading hourly electricity prices from
+    https://api.spot-hinta.fi site.
+    """
+
+    _SPOTHINTAFI: str = "_spothintafi"
+    worker_thread_id = SpotHintaFiThread.get_class_id()
+    url = "https://api.spot-hinta.fi/TodayAndDayForward"
+    update_interval = 12 * 3600
+
+    def __init__(self, name: str = "rspothintafi") -> None:
+        super().__init__(name)
+        self.active_liter_lpm = -1
+        self.update_ts = None
+        self.spot_topic = self.make_topic_name("spot")
+
+    @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.spot_topic)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        if msg.topic == self.spot_topic:
+            em = json.loads(msg.payload.decode())
+            self.on_spot(em)
+        else:
+            super().on_message(client, userdata, msg)
+
+    def on_spot(self, m: dict[Any, Any]) -> None:
+        """Write hourly spot electricity prices to time series database.
+
+        Args:
+            m (dict): holding hourly spot electricity prices
+        """
+        pass
+
+    @override
+    def run(self) -> None:
+        self.worker = cast(SpotHintaFiThread, self.instantiate(self.worker_thread_id))
+        self.worker.init(self.spot_topic, self.url, self.update_interval)
+        super().run()
+
+    @override
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = super().to_dict()
+        data[self._SPOTHINTAFI] = {
+            "topic": self.spot_topic,
+            "url": self.url,
+            "interval": self.update_interval,
+        }
+        return data
+
+    @override
+    def from_dict(self, data: Dict[str, Any]) -> None:
+        super().from_dict(data)
+        if self._SPOTHINTAFI in data:
+            for key, value in data[self._SPOTHINTAFI].items():
+                setattr(self, key, value)

juham_automation/automation/watercirculator.py

@@ -0,0 +1,140 @@
+from typing import Any
+from typing_extensions import override
+import json
+
+from masterpiece.mqtt import MqttMsg
+from juham_core import Juham
+from juham_core.timeutils import timestamp
+
+
+class WaterCirculator(Juham):
+    """Hot Water Circulation Automation
+
+    This system monitors motion sensor data to detect home occupancy.
+
+    - **When motion is detected**: The water circulator pump is activated, ensuring hot water is
+        instantly available when the tap is turned on.
+    - **When no motion is detected for a specified period (in seconds)**: The pump automatically
+        switches off to conserve energy.
+
+    Future improvement idea
+    ------------------------
+
+    In cold countries, such as Finland, energy conservation during the winter season may not be a priority.
+    In this case, an additional temperature sensor measuring the outside temperature could be used to determine whether
+    the circulator should be switched off at all. The circulating water could potentially act as an additional heating radiator.
+
+    Points to consider
+    ------------------
+
+    - Switching the pump on and off may affect its lifetime.
+    - Keeping the pump running with hot water could impact the lifespan of the pipes, potentially causing
+      corrosion due to constant hot water flow.
+
+    """
+
+    uptime = 1800  # half an hour
+    min_temperature = 37
+
+    def __init__(self, name: str, temperature_sensor: str) -> None:
+        super().__init__(name)
+
+        # input topics
+        self.motion_topic = self.make_topic_name("motion")  # motion detection
+        self.temperature_topic = self.make_topic_name(temperature_sensor)
+
+        # relay to be controlled
+        self.topic_power = self.make_topic_name("power")
+
+        # for the pump controlling logic
+        self.current_motion: bool = False
+        self.relay_started_ts: float = 0
+        self.water_temperature: float = 0
+        self.water_temperature_updated: float = 0
+        self.initialized = False
+
+    @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.motion_topic)
+            self.subscribe(self.temperature_topic)
+            # reset the relay to make sure the initial state matches the state of us
+            self.publish_relay_state(0)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        if msg.topic == self.temperature_topic:
+            m = json.loads(msg.payload.decode())
+            self.on_temperature_sensor(m, timestamp())
+        elif msg.topic == self.motion_topic:
+            m = json.loads(msg.payload.decode())
+            self.on_motion_sensor(m, timestamp())
+        else:
+            super().on_message(client, userdata, msg)
+
+    def on_temperature_sensor(self, m: dict[str, Any], ts_utc_now: float) -> None:
+        """Handle message from the hot water pipe temperature sensor.
+        Records the temperature and updates the water_temperature_updated attribute.
+
+        Args:
+            m (dict): temperature reading from the hot water blump sensor
+            ts_utc_now (float): _current utc time
+        """
+
+        self.water_temperature = m["temperature"]
+        self.water_temperature_updated = ts_utc_now
+
+    def on_motion_sensor(self, m: dict[str, dict[str, Any]], ts_utc_now: float) -> None:
+        """Control the water cirulator bump.
+
+        Given message from the motion sensor consider switching the
+        circulator bump on.
+
+        Args:
+            msg (dict): directionary holding motion sensor data
+            ts_utc_now (float): current time stamp
+        """
+        sensor = m["sensor"]
+        vibration: bool = bool(m["vibration"])
+        motion: bool = bool(m["motion"])
+
+        if motion or vibration:
+            if not self.current_motion:
+                if self.water_temperature > self.min_temperature:
+                    self.publish_relay_state(0)
+                else:
+                    self.current_motion = True
+                    self.relay_started_ts = ts_utc_now
+                    self.publish_relay_state(1)
+                    self.initialized = True
+                    self.info(
+                        f"Circulator pump started, will run for {int(self.uptime / 60)} minutes "
+                    )
+            else:
+                self.publish_relay_state(1)
+                self.relay_started_ts = ts_utc_now
+        else:
+            if self.current_motion or not self.initialized:
+                elapsed: float = ts_utc_now - self.relay_started_ts
+                if elapsed > self.uptime:
+                    self.publish_relay_state(0)
+                    self.info(
+                        f"Circulator  pump stopped, no motion in {int(elapsed/60)} minutes detected",
+                        "",
+                    )
+                    self.current_motion = False
+                    self.initialized = True
+                else:
+                    self.publish_relay_state(1)
+            else:
+                self.publish_relay_state(0)
+
+    def publish_relay_state(self, state: int) -> None:
+        """Publish power status.
+
+        Args:
+            state (int): 1 for on, 0 for off, as defined by Juham 'power' topic
+        """
+        heat = {"Unit": self.name, "Timestamp": timestamp(), "State": state}
+        self.publish(self.topic_power, json.dumps(heat), 1, False)

juham_automation/japp.py

@@ -1,55 +1,53 @@
-from masterpiece import Application
-from juham_core import Juham
-from juham_systemstatus import SystemStatus
-
-from .ts.forecast_ts import ForecastTs
-from .ts.power_ts import PowerTs
-from .ts.powerplan_ts import PowerPlanTs
-from .ts.powermeter_ts import PowerMeterTs
-from .ts.log_ts import LogTs
-from .ts.energycostcalculator_ts import EnergyCostCalculatorTs
-from .ts.electricityprice_ts import ElectricityPriceTs
-from .automation.spothintafi import SpotHintaFi
-from .automation.energycostcalculator import EnergyCostCalculator
-
-
-class JApp(Application):
-    """Juham home automation application base class. Registers new plugin
-    group 'juham' on which general purpose Juham plugins can be written on.
-    """
-
-    def __init__(self, name: str) -> None:
-        """Creates home automation application with the given name.
-        If --enable_plugins is False create hard coded configuration
-        by calling instantiate_classes() method.
-
-        Args:
-            name (str): name for the application
-        """
-        super().__init__(name, Juham(name))
-
-    def instantiate_classes(self) -> None:
-        """Instantiate automation classes .
-
-        Returns:
-            None
-        """
-        self.add(ForecastTs())
-        self.add(PowerTs())
-        self.add(PowerPlanTs())
-        self.add(PowerMeterTs())
-        self.add(LogTs())
-        self.add(SpotHintaFi())
-        self.add(EnergyCostCalculator())
-        self.add(EnergyCostCalculatorTs())
-        self.add(ElectricityPriceTs())
-
-        # install plugins
-        self.add(self.instantiate_plugin_by_name("SystemStatus"))
-        self.add(self.instantiate_plugin_by_name("VisualCrossing"))
-        self.add(self.instantiate_plugin_by_name("OpenWeatherMap"))
-
-    @classmethod
-    def register(cls) -> None:
-        """Register plugin group `juham`."""
-        Application.register_plugin_group("juham")
+from juham_automation.automation.energybalancer import EnergyBalancer
+from masterpiece import Application
+from juham_core import Juham
+
+from .ts import ForecastTs
+from .ts import PowerTs
+from .ts import PowerPlanTs
+from .ts import PowerMeterTs
+from .ts import EnergyBalancerTs
+from .ts import LogTs
+from .ts import EnergyCostCalculatorTs
+from .ts import ElectricityPriceTs
+from .automation import SpotHintaFi
+from .automation import EnergyCostCalculator
+
+
+class JApp(Application):
+    """Juham home automation application base class. Registers new plugin
+    group 'juham' on which general purpose Juham plugins can be written on.
+    """
+
+    def __init__(self, name: str) -> None:
+        """Creates home automation application with the given name.
+        If --enable_plugins is False create hard coded configuration
+        by calling instantiate_classes() method.
+
+        Args:
+            name (str): name for the application
+        """
+        super().__init__(name, Juham(name))
+
+    def instantiate_classes(self) -> None:
+        """Instantiate automation classes .
+
+        Returns:
+            None
+        """
+        self.add(ForecastTs())
+        self.add(PowerTs())
+        self.add(PowerPlanTs())
+        self.add(PowerMeterTs())
+        self.add(LogTs())
+        self.add(SpotHintaFi())
+        self.add(EnergyCostCalculator())
+        self.add(EnergyCostCalculatorTs())
+        self.add(ElectricityPriceTs())
+        self.add(EnergyBalancer())
+        self.add(EnergyBalancerTs())
+
+    @classmethod
+    def register(cls) -> None:
+        """Register plugin group `juham`."""
+        Application.register_plugin_group("juham")

juham_automation/ts/__init__.py

@@ -0,0 +1,27 @@
+"""
+Description
+===========
+
+Time series recorders for Juha's Ultimate Home Automation classes.
+
+"""
+
+from .energycostcalculator_ts import EnergyCostCalculatorTs
+from .log_ts import LogTs
+from .power_ts import PowerTs
+from .powerplan_ts import PowerPlanTs
+from .powermeter_ts import PowerMeterTs
+from .electricityprice_ts import ElectricityPriceTs
+from .forecast_ts import ForecastTs
+from .energybalancer_ts import EnergyBalancerTs
+
+__all__ = [
+    "EnergyCostCalculatorTs",
+    "ForecastTs",
+    "LogTs",
+    "PowerTs",
+    "PowerPlanTs",
+    "PowerMeterTs",
+    "ElectricityPriceTs",
+    "EnergyBalancerTs",
+]

juham_automation/ts/electricityprice_ts.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+import time
+import json
+from typing import Any, Dict, Optional, cast
+from typing_extensions import override
+
+from masterpiece.mqtt import Mqtt, MqttMsg
+from juham_core.timeutils import epoc2utc
+from juham_core import JuhamTs
+
+
+class ElectricityPriceTs(JuhamTs):
+    """Spot electricity price for reading hourly electricity prices from"""
+
+    def __init__(self, name: str = "electricityprice_ts") -> None:
+        super().__init__(name)
+
+        self.spot_topic = self.make_topic_name("spot")
+
+    @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.spot_topic)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        if msg.topic == self.spot_topic:
+            em = json.loads(msg.payload.decode())
+            self.on_spot(em)
+        else:
+            super().on_message(client, userdata, msg)
+
+    def on_spot(self, m: dict[Any, Any]) -> None:
+        """Write spot electricity prices to time series database.
+
+        Args:
+            m (dict): holding hourlys spot electricity prices
+        """
+        grid_cost : float
+        for h in m:
+            if "GridCost" in h:
+                grid_cost = h["GridCost"]
+                point = (
+                    self.measurement("spot")
+                    .tag("hour", h["Timestamp"])
+                    .field("value", h["PriceWithTax"])
+                    .field("grid", grid_cost)
+                    .time(epoc2utc(h["Timestamp"]))
+                )
+                self.write(point)