juham-watermeter 0.0.4__py3-none-any.whl

juham_watermeter/__init__.py

@@ -0,0 +1,21 @@
+"""
+Description
+===========
+
+Web-camera based watermeter classes with leak detector
+
+"""
+
+from .webcamera import WebCamera
+from .watermeter_ocr import WaterMeterOCR
+from .watermeter_imgdiff import WaterMeterImgDiff
+from .watermeter_ts import WaterMeterTs
+from .leakdetector import LeakDetector
+
+__all__ = [
+    "WebCamera",
+    "WaterMeterOCR",
+    "WaterMeterImgDiff",
+    "WaterMeterTs",
+    "LeakDetector",
+]

juham_watermeter/leakdetector.py

@@ -0,0 +1,170 @@
+"""
+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 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 = {
+            "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
+                        # Optionally trigger external alarm here (e.g., email notification)
+                        self.warning(
+                            f"LEAK SUSPECT",
+                            "Flow {flow_rate} lpm, last detected motion {self.amotion_last_detected_tss}",
+                        )
+
+                self.zero_usage_periods_count = 0
+                # self.debug(f"LeakDetector: flow {flow_rate} liters per minute detected")
+            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.debug(
+                    #    f"Leak status reset after {self.zero_usage_periods_count} subsequent reports with no flow"
+                    # )
+            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.debug(f"Leak detection period reset, motion detected")
+            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_watermeter/py.typed

@@ -0,0 +1 @@
+

juham_watermeter/watermeter_imgdiff.py

@@ -0,0 +1,328 @@
+"""Web camera based optical watermeter based on differences between subsequent frames. 
+
+"""
+
+import json
+import os
+import subprocess
+import tempfile
+import time
+import cv2
+import numpy as np
+from typing import Any, Optional, Union, cast
+from typing_extensions import override
+from masterpiece.mqtt import Mqtt
+
+from juham_core.timeutils import timestamp
+from .webcamera import WebCameraThread, WebCamera
+
+
+class WaterMeterThreadImgDiff(WebCameraThread):
+    """Asynchronous thread for capturing and processing images of web camera.
+    Uploads three images to sftp server for inspection: the original watermeter
+    image, the image holding differences between the last captured watermeter image,
+    and  processed image with noise eliminated, and differences scaled up for maximum
+    image contrast: white pixels represent areas. The more white pixels, the bigger the
+    water consumption.
+    """
+
+    # class attributes
+    _watermeter_topic: str = ""
+    _expected_image_size: int = 640 * 480
+    _save_images: bool = True
+    _calibration_factor: float = 1000.0  # img diff to liters
+    _max_change_area: float = 0.1  # difference can't be greater than this
+    ftp_site: str = ""
+    ftp_user: str = ""
+    ftp_pw: str = ""
+
+    def __init__(self, client: Optional[Mqtt] = None):
+        """Construct with the given mqtt client.
+
+        Args:
+            client (object, optional): MQTT client. Defaults to None.
+        """
+        super().__init__(client)
+        self.sensor_name = "watermeter_imgdiff"
+        self.mqtt_client: Optional[Mqtt] = client
+        self.total_liter: float = 0.0
+        self.active_liter_lpm: float = 0.0
+        self._prev_image: np.ndarray = np.zeros((1, 1, 3), dtype=np.uint8)
+        self._prev_image_initialized = False
+        self._prev_time: float = 0.0
+
+        # total cumulative diff between two consequtive images
+        self._wm_start_seconds: float = 0.0
+
+        # temp filenames for saving the original and processed images, for debugging purposes
+        self._temp_filename1: str = ""
+        self._temp_filename2: str = ""
+
+    def init_watermeter_imgdiff(
+        self,
+        interval: float,
+        location: str,
+        camera: int,
+        topic: str,
+        save_images: bool,
+    ) -> None:
+        """Initialize the  data acquisition thread
+
+        Args:
+            topic (str): mqtt topic to publish the acquired system info
+            interval (float): update interval in seconds
+            location (str): geographic location
+            camera(int) : ordinal specifying the camera to be used (0, 1)
+            save_images (bool) : true to enable saving of captured images, for debugging
+        """
+        super().init(interval, location, camera)
+        self._watermeter_topic = topic
+        self._save_images = save_images
+        # temp filenames for saving the original and processed images, for debugging purposes
+        tmpdir: str = tempfile.mkdtemp()
+        self._temp_filename1 = os.path.join(tmpdir, f"{self.sensor_name}_wm_1.png")
+        self._temp_filename2 = os.path.join(tmpdir, f"{self.sensor_name}_wm_2.png")
+
+    def upload_image(self, file: str, img: np.ndarray) -> None:
+        """Save the image to the given file and upload the file to the FTP server.
+
+        Args:
+            file (str): The filename where the image will be saved.
+            img (np.ndarray): The image to be saved and uploaded.
+        """
+        # Save the image to the specified file
+        cv2.imwrite(file, img)
+
+        try:
+            # Upload the file to the FTP server
+            self.upload_file(file)
+
+            # If the upload is successful, remove the file
+            os.remove(file)
+            print(f"File {file} uploaded and deleted successfully.")
+
+        except Exception as e:
+            # Handle any errors that occurred during upload
+            self.error(f"Error during file upload: {e}")
+
+    def compare_images(
+        self,
+        np_prev: np.ndarray,
+        np_current: np.ndarray,
+        threshold: int = 20,
+    ) -> float:
+        """
+        Compares two images and returns a float value representing the level of differences.
+
+        Parameters:
+            np_prev (np.ndarray): The previous image.
+            np_current (np.ndarray): The current image.
+            threshold (int): Threshold value to filter noise in the difference image.
+
+        Returns:
+            float: A value between 0.0 and 1.0 indicating the level of difference.
+                0.0 means identical, 1.0 means maximally different.
+        """
+        # Ensure both images are the same size and type
+        if np_prev.shape != np_current.shape:
+            self.error("Images have different shapes or dimensions.")
+            return -1.0  # Error value for different shapes
+
+        # Step 1: Calculate the absolute difference between the two images
+        diff_image = cv2.absdiff(np_prev, np_current)
+
+        # Step 2: Filter small differences (noise) using a binary threshold
+        _, binary_diff = cv2.threshold(diff_image, threshold, 255, cv2.THRESH_BINARY)
+
+        # Step 3: Calculate the proportion of changed pixels
+        change_area: float = np.count_nonzero(binary_diff) / binary_diff.size
+
+        if change_area > 0.0:
+            print(f"Watermeter change {change_area}, uploading")
+            self.upload_images(np_current, binary_diff)
+
+        # Return a value between 0.0 (identical) and 1.0 (maximally different)
+        return min(max(change_area, 0.0), 1.0)
+
+    @override
+    def update_interval(self) -> float:
+        return self._interval
+
+    def upload_file(self, filename: str) -> None:
+        """Upload the given filename to the ftp server, if the server is configured.
+
+        Args:
+            filename (str): _description_
+        """
+        if len(self.ftp_site) > 0 and len(self.ftp_user) > 0 and len(self.ftp_pw) > 0:
+
+            # Build the curl command for uploading the file
+            curl_command = [
+                "curl",
+                f"-u{self.ftp_user}:{self.ftp_pw}",
+                "--retry",
+                "3",
+                "--retry-delay",
+                "5",
+                "-T",
+                filename,
+                self.ftp_site,
+            ]
+
+            # Execute the curl command
+            try:
+                subprocess.run(curl_command, check=True)
+            except subprocess.CalledProcessError as e:
+                self.error(f"Error during image upload: {e}")
+
+    def upload_images(self, np_watermeter: np.ndarray, np_diff: np.ndarray) -> None:
+        """Upload captured grayscale watermeter image, and the diff image to ftp site
+
+        Parameters:
+            np_watermeter (np.ndarray): Watermeter image in grayscale
+            np_diff (np.ndarray): The diff image reflecting consumed water
+        """
+        self.upload_image(self._temp_filename1, np_watermeter)
+        self.upload_image(self._temp_filename2, np_diff)
+
+    @override
+    def update(self) -> bool:
+        change_area: float = -1
+        captured_image = self.capture_image()
+        if captured_image.size < self._expected_image_size:
+            return False
+        grayscale_image = self.process_image(captured_image)
+        if grayscale_image.size < self._expected_image_size:
+            return False
+        processed_image = self.enhance_contrast(grayscale_image)
+        if processed_image.size < self._expected_image_size:
+            return False
+
+        if self._prev_image.size == self._expected_image_size:
+            change_area = self.compare_images(self._prev_image, processed_image)
+        else:
+            self._prev_image = processed_image
+            return True
+
+        lpm: float = 0.0
+
+        if change_area > 0.0:
+            # to capture even the smallest leaks, update the previous image
+            # only when difference is found
+            self._prev_image = processed_image
+            wm_elapsed_seconds: float = time.time() - self._wm_start_seconds
+            self._wm_start_seconds = time.time()
+
+            # image change_area factor to consumed water in liters
+            liters = change_area * self._calibration_factor
+
+            # update cumulative water consumption
+            self.total_liter += liters / 1000.0
+
+            # scale liters to flow (liters per minute)
+            lpm = liters / (wm_elapsed_seconds / 60.0)
+
+        watermeter: dict[str, Union[float, str]] = {
+            "location": self._location,
+            "sensor": self.sensor_name,
+            "total_liter": self.total_liter,
+            "active_lpm": lpm,
+            "ts": timestamp(),
+        }
+
+        msg = json.dumps(watermeter)
+        self.publish(self._watermeter_topic, msg, qos=0, retain=False)
+        return True
+
+
+class WaterMeterImgDiff(WebCamera):
+    """WebCamera based optical watermeter. Needs a low-cost web camera and a spot
+    light to illuminate the watermeter. Captures images with specified interval (the default
+    is 1 minute) and computes a factor that represents the level of difference, 0.0 being no
+    differences and 1.0 corresponding to the maximum difference (all pixels different with
+    maximum contrast e.g. 0 vs 255).
+    The more two consequtive images differ, the higher the water consumption. Cannot give any absolute water consumption
+    measurements as liters, but suits well for leak detection purposes - the greater
+    the difference the creater the water consumption.
+
+    """
+
+    _WATERMETER: str = "watermeter_imgdiff"
+    _WATERMETER_ATTRS: list[str] = [
+        "topic",
+        "update_interval",
+        "location",
+        "camera",
+        "save_images",
+    ]
+
+    _workerThreadId: str = WaterMeterThreadImgDiff.get_class_id()
+    update_interval: float = 30
+    topic = "watermeter"
+    location = "home"
+    camera: int = 0
+    save_images: bool = True
+
+    def __init__(self, name="watermeter_imgdiff") -> None:
+        """Constructs system status automation object for acquiring and publishing
+        system info e.g. available memory and CPU loads.
+
+        Args:
+            name (str, optional): name of the object.
+        """
+        super().__init__(name)
+        self.worker: Optional[WaterMeterThreadImgDiff] = None
+        self.watermeter_topic: str = self.make_topic_name(self.topic)
+
+    @override
+    def initialize(self) -> None:
+        # let the super class to initialize database first so that we can read it
+        super().initialize()
+
+        # read the latest known value from
+        last_value: dict[str, float] = self.read_last_value(
+            "watermeter",
+            {"sensor": self.name, "location": self.location},
+            ["total_liter"],
+        )
+        worker: WaterMeterThreadImgDiff = cast(WaterMeterThreadImgDiff, self.worker)
+        if "total_liter" in last_value:
+            worker.total_liter = last_value["total_liter"]
+            self.info(f"Total liters {worker.total_liter} read from the database")
+        else:
+            self.warning("no previous database value for total_liter found")
+
+    @override
+    def run(self) -> None:
+        # create, initialize and start the asynchronous thread for acquiring forecast
+
+        self.worker = cast(
+            WaterMeterThreadImgDiff, self.instantiate(WaterMeterImgDiff._workerThreadId)
+        )
+        self.worker.sensor_name = self.name
+
+        self.worker.init_watermeter_imgdiff(
+            self.update_interval,
+            self.location,
+            self.camera,
+            self.watermeter_topic,
+            self.save_images,
+        )
+        super().run()
+
+    @override
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()  # Call parent class method
+        watermeter_data = {}
+        for attr in self._WATERMETER_ATTRS:
+            watermeter_data[attr] = getattr(self, attr)
+        data[self._WATERMETER] = watermeter_data
+        return data
+
+    @override
+    def from_dict(self, data: dict[str, Any]) -> None:
+        super().from_dict(data)  # Call parent class method
+        if self._WATERMETER in data:
+            watermeter_data = data[self._WATERMETER]
+            for attr in self._WATERMETER_ATTRS:
+                setattr(self, attr, watermeter_data.get(attr, None))

juham_watermeter/watermeter_ocr.py

@@ -0,0 +1,273 @@
+"""Optical Character Recognition based water meter
+Note: tested and works, but needs more work to be reliable
+
+"""
+
+import json
+import time
+import cv2
+import numpy as np
+from typing import Any, Optional, Union, cast
+from typing_extensions import override
+import pytesseract  # type: ignore
+from PIL import Image
+from masterpiece.mqtt import Mqtt
+from juham_core.timeutils import timestamp
+from .webcamera import WebCameraThread, WebCamera
+
+
+class WaterMeterThreadOCR(WebCameraThread):
+    """Asynchronous thread for capturing and processing images of web camera."""
+
+    # class attributes
+    _watermeter_topic: str = ""
+    _expected_image_size: int = 640 * 480
+    _crop_x: int = 195
+    _crop_y: int = 157
+    _crop_width: int = 640
+    _crop_height: int = 480
+    _save_images: bool = True
+    _num_digits: int = 5
+
+    def __init__(self, client: Optional[Mqtt] = None):
+        """Construct with the given mqtt client.
+
+        Args:
+            client (object, optional): MQTT client. Defaults to None.
+        """
+        super().__init__(client)
+        self.mqtt_client: Optional[Mqtt] = client
+        self.total_liter: float = 0.0
+        self.active_liter_lpm: float = 0.0
+        self._prev_time: float = (
+            0.0  # for computing momentary consumption (liters per hour)
+        )
+
+    def init_watermeter_ocr(
+        self,
+        topic: str,
+        interval: float,
+        location: str,
+        camera: int,
+        crop_x: int,
+        crop_y: int,
+        crop_width: int,
+        crop_height: int,
+        save_images: bool,
+        num_digits: int,
+    ) -> None:
+        """Initialize the  data acquisition thread
+
+        Args:
+            topic (str): mqtt topic to publish the acquired system info
+            interval (float): update interval in seconds
+            location (str): geographic location
+            camera(int) : ordinal specifying the camera to be used (0, 1)
+            crop_x, crop_y, crop_width, crop_height (int): crop box
+            save_images (bool) : true to enable saving of captured images, for debugging
+            num_digits (int) : number of digits in the watermeter
+        """
+        super().init(interval, location, camera)
+        self._watermeter_topic = topic
+        self._crop_x = crop_x
+        self._crop_y = crop_y
+        self._crop_width = crop_width
+        self._crop_height = crop_height
+        self._save_images = save_images
+        self._num_digits = num_digits
+
+    @override
+    def update_interval(self) -> float:
+        return self._interval
+
+    @override
+    def update(self) -> bool:
+        captured_image = self.capture_image()
+        if captured_image.size < self._expected_image_size:
+            return False
+        processed_image = self.process_image(captured_image)
+        if processed_image.size < self._expected_image_size:
+            return False
+
+        value: float = self.recognize_text(processed_image)
+        if value < self.total_liter:
+            self.warning("Invalid watermeter reading {value} skipped")
+
+        self.total_liter = value
+        current_time: float = time.time()
+        elapsed_seconds: float = current_time - self._prev_time
+        self._prev_time = current_time
+        liters_per_minute = value / (60 * elapsed_seconds)
+        watermeter: dict[str, Union[float, str]] = {
+            "location": self._location,
+            "sensor": self.name,
+            "total_liter": self.total_liter,
+            "active_lpm": liters_per_minute,
+            "ts": timestamp(),
+        }
+
+        msg = json.dumps(watermeter)
+        self.publish(self._watermeter_topic, msg, qos=0, retain=False)
+        self.debug(f"Watermeter published to {self._watermeter_topic}", msg)
+        return True
+
+    def evaluate_text(self, text: str) -> float:
+        # make sure we got all the digits
+        num_lines: int = len(text.splitlines())
+        if num_lines != 2:
+            print(f"{text} has invalid number of lines {num_lines}")
+            return 0.0
+        first_line = text.splitlines()[0]
+        num_digits: int = len(first_line)
+
+        if num_digits != self._num_digits:
+            print(
+                f"{text} has invalid number of digits {num_digits}, expected {self._num_digits}"
+            )
+            return 0.0
+        try:
+            num = float(first_line)
+            self.debug(f"Evaluated string {first_line} as {num}")
+            print(f"Evaluated string {first_line} as {num}")
+            return num
+        except ValueError:
+            self.warning(f"Cannot evaluate string {first_line}")
+            print(f"Cannot evaluated string {first_line}")
+
+        return 0.0
+
+    def recognize_text(self, greyscale_image: np.ndarray) -> float:
+        """Recognize numerical digits from the given greyscale image.
+
+        Args:
+            greyscale_image (np.ndarray): image to be recognized
+
+        Returns:
+            float: recognized value.
+        """
+
+        # cv2.imwrite("full.jpg", greyscale_image)
+
+        # Apply a mask to focus only on the digits
+        mask = np.zeros_like(greyscale_image)
+        cv2.rectangle(
+            mask,
+            (self._crop_x, self._crop_y),
+            (self._crop_x + self._crop_width, self._crop_y + self._crop_height),
+            255,
+            -1,
+        )  # White rectangle for the ROI
+        masked_image = cv2.bitwise_and(greyscale_image, mask)
+        # cv2.imwrite("masked.jpg", masked_image)
+
+        # Crop the ROI for OCR
+        cropped_roi = masked_image[
+            self._crop_y : self._crop_y + self._crop_height,
+            self._crop_x : self._crop_x + self._crop_width,
+        ]
+
+        # Step 1: Apply a Gaussian blur to smooth out small details
+        blurred_image = cv2.GaussianBlur(cropped_roi, (5, 5), 0)
+
+        # Step 2: Apply adaptive thresholding for better OCR
+        thresholded_image = cv2.adaptiveThreshold(
+            blurred_image, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2
+        )
+
+        # Step 3: Use morphological operations to remove thin vertical lines
+        kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (2, 2))
+        morph_image = cv2.morphologyEx(thresholded_image, cv2.MORPH_CLOSE, kernel)
+
+        # Save the intermediate image for debugging
+        # cv2.imwrite("preprocessed.jpg", morph_image)
+
+        # Convert to PIL image for pytesseract
+        pil_image = Image.fromarray(morph_image)
+
+        # Perform OCR with digits only
+        text = pytesseract.image_to_string(
+            pil_image, config="--psm 6 -c tessedit_char_whitelist=0123456789"
+        )
+
+        return self.evaluate_text(text)
+
+
+class WaterMeterOCR(WebCamera):
+    """Constructs a data acquisition thread for reading system status
+    info, e.g. available disk space and publishes the data to the watermeter topic.
+
+    """
+
+    _WATERMETER: str = "watermeter_ocr"
+    _WATERMETER_ATTRS: list[str] = [
+        "topic",
+        "update_interval",
+        "location",
+        "crop_x",
+        "crop_y",
+        "crop_width",
+        "crop_height",
+        "save_images",
+        "num_digits",
+    ]
+
+    _workerThreadId: str = WaterMeterThreadOCR.get_class_id()
+    update_interval: float = 60
+    topic = "watermeter"
+    location = "home"
+    camera: int = 0
+    crop_x: int = 0
+    crop_y: int = 0
+    crop_width: int = 640
+    crop_height: int = 480
+    save_images: bool = True
+    num_digits: int = 5
+
+    def __init__(self, name="watermeter_ocr") -> None:
+        """Constructs system status automation object for acquiring and publishing
+        system info e.g. available memory and CPU loads.
+
+        Args:
+            name (str, optional): name of the object.
+        """
+        super().__init__(name)
+        self.worker: Optional[WaterMeterThreadOCR] = None
+        self.watermeter_topic: str = self.make_topic_name(self.topic)
+
+    @override
+    def run(self) -> None:
+        # create, initialize and start the asynchronous thread for acquiring forecast
+
+        self.worker = cast(
+            WaterMeterThreadOCR, self.instantiate(WaterMeterOCR._workerThreadId)
+        )
+        self.worker.name = self.name
+
+        self.worker.init_watermeter_ocr(
+            self.watermeter_topic,
+            self.update_interval,
+            self.location,
+            self.camera,
+            self.crop_x,
+            self.crop_y,
+            self.crop_width,
+            self.crop_height,
+            self.save_images,
+            self.num_digits,
+        )
+        super().run()
+
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()  # Call parent class method
+        watermeter_data = {}
+        for attr in self._WATERMETER_ATTRS:
+            watermeter_data[attr] = getattr(self, attr)
+        data[self._WATERMETER] = watermeter_data
+        return data
+
+    def from_dict(self, data: dict[str, Any]) -> None:
+        super().from_dict(data)  # Call parent class method
+        if self._WATERMETER in data:
+            watermeter_data = data[self._WATERMETER]
+            for attr in self._WATERMETER_ATTRS:
+                setattr(self, attr, watermeter_data.get(attr, None))

juham_watermeter/watermeter_ts.py

@@ -0,0 +1,100 @@
+"""Water meter time series recorder
+
+"""
+
+import json
+
+from typing import Any
+from typing_extensions import override
+from masterpiece.mqtt import MqttMsg
+
+from juham_core.timeutils import epoc2utc
+from juham_core import JuhamTs
+
+
+class WaterMeterTs(JuhamTs):
+    """Watermeter timeseries recorder. Listens the watermeter MQTT topic
+    and writes the measurements to timeseries database.
+
+    """
+
+    _WATERMETER: str = "watermeter_ts"
+    _WATERMETER_ATTRS: list[str] = [
+        "topic",
+    ]
+
+    topic = "watermeter"  # topic to listen
+
+    def __init__(self, name="watermeter_ts") -> None:
+        """Watermeter recorder, for listening watermeter MQTT topic and saving
+        measurements to timeseries database.
+
+        Args:
+            name (str, optional): name of the object.
+        """
+        super().__init__(name)
+        self.watermeter_topic: str = self.make_topic_name(self.topic)
+
+    @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.watermeter_topic)
+
+    @override
+    def on_message(self, client: object, userdata: Any, msg: MqttMsg) -> None:
+        if msg.topic == self.watermeter_topic:
+            em = json.loads(msg.payload.decode())
+            self.record(em)
+        else:
+            super().on_message(client, userdata, msg)
+
+    def record(self, info: dict[str, float]) -> None:
+        """Writes system info to the time series database
+
+        Args:
+            ts (float): utc time
+            em (dict): water meter message
+        """
+
+        try:
+            if "leak_suspected" in info:
+                self.write_point(
+                    "watermeter",
+                    {"sensor": info["sensor"], "location": info["location"]},
+                    {
+                        "leak_suspected": info["leak_suspected"],
+                        "ts": info["ts"],
+                    },
+                    epoc2utc(info["ts"]),
+                )
+            elif "active_lpm" in info:
+                self.write_point(
+                    "watermeter",
+                    {"sensor": info["sensor"], "location": info["location"]},
+                    {
+                        "total_liter": info["total_liter"],
+                        "active_lpm": info["active_lpm"],
+                        "ts": info["ts"],
+                    },
+                    epoc2utc(info["ts"]),
+                )
+        except Exception as e:
+            self.error(f"Writing memory to influx failed {str(e)}")
+
+    @override
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()  # Call super class method
+        watermeter_data = {}
+        for attr in self._WATERMETER_ATTRS:
+            watermeter_data[attr] = getattr(self, attr)
+        data[self._WATERMETER] = watermeter_data
+        return data
+
+    @override
+    def from_dict(self, data: dict[str, Any]) -> None:
+        super().from_dict(data)  # Call super class method
+        if self._WATERMETER in data:
+            watermeter_data = data[self._WATERMETER]
+            for attr in self._WATERMETER_ATTRS:
+                setattr(self, attr, watermeter_data.get(attr, None))

juham_watermeter/webcamera.py

@@ -0,0 +1,174 @@
+"""Web camera with basic image processing features.
+
+"""
+
+import cv2
+import numpy as np
+from typing import Any, Optional
+from typing_extensions import override
+from masterpiece.mqtt import Mqtt
+from masterpiece import MasterPieceThread
+from juham_core import JuhamThread
+from juham_core.timeutils import timestamp
+
+
+class WebCameraThread(MasterPieceThread):
+    """Asynchronous thread for capturing and processing images of web camera."""
+
+    # class attributes
+    _interval: float = 60  # seconds
+    _location = "unknown"
+    _camera: int = 0  # e.g. 0 built-in, 1 external camera
+    _expected_image_size: int = 640 * 480
+
+    def __init__(self, client: Optional[Mqtt] = None):
+        """Construct with the given mqtt client.  Initializes minimal 1x1 image
+        with timestamp 0.0, which are updated to actual image size and timestamp
+        with each captured image, for sub classes to process.
+
+        Args:
+            client (object, optional): MQTT client. Defaults to None.
+        """
+        super().__init__(client)
+        self.mqtt_client: Optional[Mqtt] = client
+        self.image: np.ndarray = np.zeros((1, 1, 3), dtype=np.uint8)
+        self.image_timestamp: float = 0.0
+
+    def init(
+        self,
+        interval: float,
+        location: str,
+        camera: int,
+    ) -> None:
+        """Initialize the  data acquisition thread
+
+        Args:
+            interval (float): update interval in seconds
+            location (str): geographic location
+            camera(int) : ordinal specifying the camera to be used (0, 1)
+
+        """
+        self._interval = interval
+        self._location = location
+        self._camera = camera
+
+    def capture_image(self) -> np.ndarray:
+        """
+        Captures an image from the webcam and returns the image as a numpy array.
+
+        Returns:
+            np.ndarray: The captured image in the form of a NumPy array.
+        """
+        # Initialize the webcam (0 for the built-in camera or 1 for the USB webcam)
+        cap = cv2.VideoCapture(self._camera)
+
+        # Check if the webcam is opened correctly
+        if not cap.isOpened():
+            print("CANNOT ACCESS THE CAMERA")
+            self.error(f"Could not access the camera {self._camera}.")
+            return np.zeros(
+                (1, 1, 3), dtype=np.uint8
+            )  # Return an empty array if the camera isn't accessible
+
+        # Capture a frame
+        try:
+            ret, frame = cap.read()
+
+            if not ret:
+                print("WTF, Camera failed again")
+                self.error("Could not capture image.")
+                frame = np.zeros(
+                    (1, 1, 3), dtype=np.uint8
+                )  # Return 1x1 array if capture failed
+        finally:
+            cap.release()
+            print("Camera released")
+        return frame  # Return the captured image
+
+    def process_image(self, image: np.ndarray) -> np.ndarray:
+        """
+        Processes the captured image by converting it to grayscale and applying thresholding.
+
+        Args:
+            image (np.ndarray): The input image to process.
+
+        Returns:
+            np.ndarray: The processed image after grayscale conversion and thresholding.
+        """
+        if image.size < self._expected_image_size:  # Check if the image is empty
+            self.error("Received an empty image for processing.")
+            return image
+
+        # Convert the image to grayscale
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+        return gray
+
+    def enhance_contrast(self, image: np.ndarray) -> np.ndarray:
+        """
+        Enhances the contrast of a grayscale image while suppressing noise.
+
+        Args:
+            image (np.ndarray): The input grayscale image.
+
+        Returns:
+            np.ndarray: The contrast-enhanced image with reduced noise amplification.
+        """
+        if image.ndim != 2:  # Ensure the image is grayscale
+            self.error("Contrast enhancement requires a grayscale image.")
+            return image
+
+        # Apply a slight Gaussian blur to reduce noise before enhancing contrast
+        blurred = cv2.GaussianBlur(image, (3, 3), 0)
+
+        # Apply CLAHE with conservative parameters to avoid over-enhancement
+        clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+        contrast_enhanced = clahe.apply(blurred)
+
+        return contrast_enhanced
+
+    @override
+    def update_interval(self) -> float:
+        return self._interval
+
+    @override
+    def update(self) -> bool:
+        self.image = self.capture_image()
+        self.image_timestamp = timestamp()
+        return self.image.size == self._expected_image_size
+
+
+class WebCamera(JuhamThread):
+    """Base class for web camera."""
+
+    _WEBCAMERA: str = "webcamera"
+    _WEBCAMERA_ATTRS: list[str] = ["location", "camera"]
+
+    _workerThreadId: str = WebCameraThread.get_class_id()
+    update_interval: float = 60
+    location = "home"
+    camera: int = 0
+
+    def __init__(self, name="webcam") -> None:
+        """Constructs system status automation object for acquiring and publishing
+        system info e.g. available memory and CPU loads.
+
+        Args:
+            name (str, optional): name of the object.
+        """
+        super().__init__(name)
+        self.worker: Optional[WebCameraThread] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        data = super().to_dict()  # Call parent class method
+        webcam_data = {}
+        for attr in self._WEBCAMERA_ATTRS:
+            webcam_data[attr] = getattr(self, attr)
+        data[self._WEBCAMERA] = webcam_data
+        return data
+
+    def from_dict(self, data: dict[str, Any]) -> None:
+        super().from_dict(data)  # Call parent class method
+        if self._WEBCAMERA in data:
+            webcam_data = data[self._WEBCAMERA]
+            for attr in self._WEBCAMERA_ATTRS:
+                setattr(self, attr, webcam_data.get(attr, None))

juham_watermeter-0.0.4.dist-info/LICENSE.rst

@@ -0,0 +1,22 @@
+MIT License
+===========
+
+Copyright (c) 2024, Juha Meskanen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+

juham_watermeter-0.0.4.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.2
+Name: juham-watermeter
+Version: 0.0.4
+Summary: Built-in Test plugin
+Author-email: J Meskanen <juham.api@gmail.com>
+Maintainer-email: "J. Meskanen" <juham.api@gmail.com>
+Project-URL: Homepage, https://meskanen.com
+Project-URL: Bug Reports, https://meskanen.com
+Project-URL: Funding, https://meskanen.com
+Project-URL: Say Thanks!, http://meskanen.com
+Project-URL: Source, https://meskanen.com
+Keywords: object-oriented,plugin,framework,watermeter,home automation
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.rst
+Requires-Dist: juham-automation>=0.0.2
+Requires-Dist: opencv-python-headless>=4.10.0
+Requires-Dist: numpy
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: Pillow>=10.4.0
+Provides-Extra: dev
+Requires-Dist: check-manifest; extra == "dev"

juham_watermeter-0.0.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+juham_watermeter/__init__.py,sha256=kFVTpeSgFaXsJJ-uxxYf656Os-zVVVriEx5yAjY1XhE,412
+juham_watermeter/leakdetector.py,sha256=bJV7Pfy4WDbcaMsxMyaoEkM1Z_pOMIeuyPOL4L5fib8,6539
+juham_watermeter/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+juham_watermeter/watermeter_imgdiff.py,sha256=voLqypb11uOt4N_vNyENSypsplcPQE61b1yinYZYLDI,12534
+juham_watermeter/watermeter_ocr.py,sha256=cicU40snCt5KU5Kvrd17DS5hLRMX2mhV-P0xwm9XXy0,9378
+juham_watermeter/watermeter_ts.py,sha256=t5EOc2KFyZZdLECfD1gfNIjmlpEzd0TG92k-LacXRpU,3346
+juham_watermeter/webcamera.py,sha256=GLXmB9VRjYTiQUCR8tIkHS4RgzQFoS8H2rteTtpLJdE,6066
+juham_watermeter-0.0.4.dist-info/LICENSE.rst,sha256=P7_vqs6bCezlTgOp6YsAiFOc71hUF10u4zP5ohL8h5s,1096
+juham_watermeter-0.0.4.dist-info/METADATA,sha256=wXiIyD_J4zrUC4m7XXnXbqHJr_YesnmxNTyf3MM6rTU,1071
+juham_watermeter-0.0.4.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+juham_watermeter-0.0.4.dist-info/entry_points.txt,sha256=4KQZ-XUjd026JX-9dLAvw6e5XE6kdshWYE4pqDgeYtE,252
+juham_watermeter-0.0.4.dist-info/top_level.txt,sha256=kvbS5ION4k6uJwlJuWRNHIKPrOvpVldiWeNLWbqH2X0,17
+juham_watermeter-0.0.4.dist-info/RECORD,,

juham_watermeter-0.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

juham_watermeter-0.0.4.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[juham.plugins]
+imgdiff_plugin = juham_watermeter:WaterMeterImgDiff
+leakdetector_plugin = juham_watermeter:LeakDetector
+ocr_plugin = juham_watermeter:WaterMeterOCR
+ts_plugin = juham_watermeter:WaterMeterTs
+webcamera_plugin = juham_watermeter:WebCamera

juham_watermeter-0.0.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+juham_watermeter