rpi2home-assistant 2.3.0__py2.py3-none-any.whl

raspy2mqtt/main.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+
+#
+# Author: fmontorsi
+# Created: Feb 2024
+# License: Apache license
+#
+# TODO: add HomeAssistant discovery messages
+
+import argparse
+import os
+import fcntl
+import sys
+import asyncio
+import gpiozero
+import subprocess
+import signal
+from .stats import StatsCollector
+from .constants import SeqMicroHatConstants, MiscAppDefaults
+from .config import AppConfig
+from .optoisolated_inputs_handler import OptoIsolatedInputsHandler
+from .gpio_inputs_handler import GpioInputsHandler
+from .gpio_outputs_handler import GpioOutputsHandler
+from .homeassistant_status_tracker import HomeAssistantStatusTracker
+
+# =======================================================================================================
+# GLOBALs
+# =======================================================================================================
+
+# sets to True when the application was asked to exit:
+g_stop_requested = False
+
+
+# =======================================================================================================
+# MAIN HELPERS
+# =======================================================================================================
+
+
+def parse_command_line():
+    """Parses the command line and returns the configuration as dictionary object."""
+    parser = argparse.ArgumentParser(
+        description=f"Utility to expose the {SeqMicroHatConstants.MAX_CHANNELS} digital inputs read by Raspberry over MQTT, to ease their integration as (binary) sensors in Home Assistant."
+    )
+
+    # Optional arguments
+    # NOTE: we cannot add required=True to --output option otherwise it's impossible to invoke this tool with just --version
+    parser.add_argument(
+        "-c",
+        "--config",
+        help=f"YAML file specifying the software configuration. Defaults to '{MiscAppDefaults.CONFIG_FILE}'",
+        default=MiscAppDefaults.CONFIG_FILE,
+    )
+    parser.add_argument(
+        "-d",
+        "--disable-hw",
+        help="This is mostly a debugging option; it disables interactions with HW components to ease integration tests",
+        action="store_true",
+        default=False,
+    )
+    parser.add_argument("-v", "--verbose", help="Be verbose.", action="store_true", default=False)
+    parser.add_argument(
+        "-V",
+        "--version",
+        help="Print version and exit",
+        action="store_true",
+        default=False,
+    )
+
+    if "COLUMNS" not in os.environ:
+        os.environ["COLUMNS"] = "120"  # avoid too many line wraps
+    args = parser.parse_args()
+
+    if args.version:
+        cfg = AppConfig()
+        print(f"Version: {cfg.app_version}")
+        sys.exit(0)
+
+    return args
+
+
+def instance_already_running(label="default"):
+    """
+    Detect if an an instance with the label is already running, globally
+    at the operating system level.
+
+    Using `os.open` ensures that the file pointer won't be closed
+    by Python's garbage collector after the function's scope is exited.
+
+    The lock will be released when the program exits, or could be
+    released if the file pointer were closed.
+    """
+
+    try:
+        lock_file_pointer = os.open(f"/tmp/instance_{label}.lock", os.O_WRONLY | os.O_CREAT)
+    except PermissionError as e:
+        print(f"Not enough permissions to write files under /tmp. Run this application as root: {e}")
+        sys.exit(4)
+
+    try:
+        # LOCK_NB = lock non-blocking
+        # LOCK_EX = exclusive lock
+        fcntl.lockf(lock_file_pointer, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        already_running = False
+    except IOError:
+        already_running = True
+
+    return already_running
+
+
+def shutdown():
+    print("!! Detected long-press on the Sequent Microsystem button. Triggering clean shutdown of the Raspberry PI !!")
+    subprocess.call(["sudo", "shutdown", "-h", "now"])
+
+
+def init_hardware(cfg: AppConfig):
+    if cfg.disable_hw:
+        return []
+
+    # setup GPIO connected to the pushbutton (input) and
+    # assign the when_held function to be called when the button is held for more than 5 seconds
+    # (NOTE: the way gpiozero works is that a new thread is spawned to listed for this event on the Raspy GPIO)
+    if "GPIOZERO_PIN_FACTORY" in os.environ:
+        print(f"GPIO factory backend is: {os.environ['GPIOZERO_PIN_FACTORY']}")
+    else:
+        print(
+            "GPIO factory backend is the default one. This might fail on newer Raspbian versions with Linux kernel >= 6.6.20"
+        )
+
+    try:
+        gpiozero.Device.ensure_pin_factory()
+    except gpiozero.exc.BadPinFactory:
+        print("Unable to load a gpiozero pin factory. Typically this happens if you don't have pigpio installed.")
+        print("Alternatively you can run this software for basic testing exporting the env variable DISABLE_HW.")
+
+    buttons = []
+    print("Initializing SequentMicrosystem GPIO shutdown button")
+    b = gpiozero.Button(SeqMicroHatConstants.SHUTDOWN_BUTTON_GPIO, hold_time=5)
+    b.when_held = shutdown
+    buttons.append(b)
+
+    return buttons
+
+
+# =======================================================================================================
+# ASYNC HELPERS
+# =======================================================================================================
+
+
+async def signal_handler(sig: signal.Signals) -> None:
+    global g_stop_requested
+    g_stop_requested = True
+    print(f"Received signal {sig.name}... stopping all async tasks")
+
+
+async def main_loop():
+    global g_stop_requested
+
+    cfg = AppConfig()
+    print(f"{MiscAppDefaults.THIS_APP_NAME} version {cfg.app_version} starting")
+
+    args = parse_command_line()
+
+    if not cfg.load(args.config):
+        return 1  # invalid config file... abort with failure exit code
+
+    cfg.merge_options_from_cli(args)
+    cfg.merge_options_from_env_vars()
+    cfg.print_config_summary()
+
+    # install signal handler
+    loop = asyncio.get_running_loop()
+    for sig in [signal.SIGINT, signal.SIGTERM]:
+        loop.add_signal_handler(sig, lambda: asyncio.create_task(signal_handler(sig)))
+
+    # initialize handlers
+    opto_inputs_handler = OptoIsolatedInputsHandler()
+    gpio_inputs_handler = GpioInputsHandler()
+    gpio_outputs_handler = GpioOutputsHandler()
+    homeassistant_status_tracker = HomeAssistantStatusTracker()
+    stats_collector = StatsCollector([opto_inputs_handler, gpio_inputs_handler, gpio_outputs_handler])
+
+    button_instances = init_hardware(cfg)
+    button_instances += opto_inputs_handler.init_hardware(cfg)
+    button_instances += gpio_inputs_handler.init_hardware(cfg, loop)
+    gpio_outputs_handler.init_hardware(cfg)
+
+    homeassistant_status_tracker.set_discovery_publish_coroutines(
+        [
+            opto_inputs_handler.homeassistant_discovery_message_publish,
+            gpio_outputs_handler.homeassistant_discovery_message_publish,
+        ]
+    )
+
+    # wrap with error-handling code the main loop
+    exit_code = 0
+    print("Starting main loop")
+    while not g_stop_requested:
+        # the double-nested 'try' is the only way I found in Python 3.11.2 to catch properly
+        # both exception groups (using the 'except*' syntax) and also have a default catch-all
+        # label using regular 'except' syntax.
+
+        # NOTE: unfortunately we cannot use a taskgroup: the problem is the function
+        # subscribe_and_activate_outputs() which uses the aiomqtt.Client.messages generator
+        # which does not allow to easily stop the 'waiting for next message' operation.
+        # This means we need to create each task manually with asyncio.EventLoop.create_task()
+        # and cancel() them whenever a SIGTERM is received.
+        #
+        # async with asyncio.TaskGroup() as tg:
+        #     tg.create_task(print_stats_periodically(cfg))
+        #     # inputs:
+        #     tg.create_task(publish_optoisolated_inputs(cfg))
+        #     tg.create_task(process_gpio_inputs_queue_and_publish(cfg))
+        #     # outputs:
+        #     tg.create_task(subscribe_and_activate_outputs(cfg))
+        #     tg.create_task(publish_outputs_state(cfg))
+
+        # launch all coroutines:
+        loop = asyncio.get_running_loop()
+        tasks = [
+            loop.create_task(stats_collector.print_stats_periodically(cfg)),
+            loop.create_task(opto_inputs_handler.publish_optoisolated_inputs(cfg)),
+            loop.create_task(gpio_inputs_handler.process_gpio_inputs_queue_and_publish(cfg)),
+            loop.create_task(gpio_outputs_handler.subscribe_and_activate_outputs(cfg)),
+            loop.create_task(gpio_outputs_handler.publish_outputs_state(cfg)),
+        ]
+
+        if cfg.homeassistant_discovery_messages_enable:
+            # subscribe to HomeAssistant status notification and eventually trigger MQTT discovery messages
+            loop.create_task(homeassistant_status_tracker.subscribe_status(cfg)),
+
+        # this main coroutine will simply wait till a SIGTERM arrives and
+        # we get g_stop_requested=True:
+        while not g_stop_requested:
+            await asyncio.sleep(1)
+
+        print("Main coroutine is now cancelling all sub-tasks (coroutines)")
+        GpioInputsHandler.stop_requested = True
+        GpioOutputsHandler.stop_requested = True
+        OptoIsolatedInputsHandler.stop_requested = True
+        for t in tasks:
+            t.cancel()
+
+        print("Waiting cancellation of all tasks")
+        for t in tasks:
+            # Wait for the task to be cancelled
+            try:
+                await t
+            except asyncio.CancelledError:
+                pass
+
+    print("Printing stats for the last time:")
+    stats_collector.print_stats()
+
+    print(f"Exiting gracefully with exit code {exit_code}...")
+    return exit_code
+
+
+def entrypoint():
+    if instance_already_running(MiscAppDefaults.THIS_APP_NAME):
+        print(
+            "Sorry, detected another instance of this daemon is already running. Using the same I2C bus from 2 sofware programs is not recommended. Aborting."
+        )
+        sys.exit(3)
+
+    try:
+        sys.exit(asyncio.run(main_loop()))
+    except KeyboardInterrupt:
+        print("Stopping due to CTRL+C")
+
+
+# =======================================================================================================
+# MAIN
+# =======================================================================================================
+
+if __name__ == "__main__":
+    entrypoint()

raspy2mqtt/optoisolated_inputs_handler.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+
+import lib16inpind
+import time
+import asyncio
+import gpiozero
+import json
+import sys
+import aiomqtt
+import threading
+from .constants import MqttQOS, SeqMicroHatConstants
+from .config import AppConfig
+from .circular_buffer import CircularBuffer
+
+#
+# Author: fmontorsi
+# Created: May 2024
+# License: Apache license
+#
+
+# =======================================================================================================
+# OptoIsolatedInputsHandler
+# =======================================================================================================
+
+
+class OptoIsolatedInputsHandler:
+    """
+    This class handles sampling inputs from the
+    [Sequent Microsystem 16 opto-insulated inputs HAT](https://sequentmicrosystems.com/collections/all-io-cards/products/16-universal-inputs-card-for-raspberry-pi)
+    and publishing the results to MQTT.
+    It exposes a coroutine that can be 'await'ed, which handles publishing.
+    """
+
+    # the stop-request is not related to a particular instance of this class... it applies to any instance
+    stop_requested = False
+
+    # the MQTT client identifier
+    client_identifier = "_optoisolated_publisher"
+    client_identifier_discovery_pub = "_optoisolated_discovery_publisher"
+
+    buffer_num_samples = 64
+
+    def __init__(self):
+        # last reading of the 16 digital opto-isolated inputs
+        self.optoisolated_inputs_sampled_values = []
+        for i in range(SeqMicroHatConstants.MAX_CHANNELS):
+            self.optoisolated_inputs_sampled_values.append(CircularBuffer(OptoIsolatedInputsHandler.buffer_num_samples))
+
+        self.lock = threading.Lock()
+
+        self.stats = {
+            "num_readings": 0,
+            "num_connections_publish": 0,
+            "num_mqtt_messages": 0,
+            "num_connections_discovery_publish": 0,
+            "num_mqtt_discovery_messages_published": 0,
+            "ERROR_no_stable_samples": 0,
+            "ERROR_num_connections_lost": 0,
+        }
+
+    def init_hardware(self, cfg: AppConfig) -> list[gpiozero.Button]:
+        buttons = []
+        if cfg.disable_hw:
+            print("Skipping optoisolated inputs HW initialization (--disable-hw was given)")
+
+            timestamp = int(time.time())
+            with self.lock:
+                for i in range(SeqMicroHatConstants.MAX_CHANNELS):
+                    self.optoisolated_inputs_sampled_values[i].push_sample(timestamp, False)
+        else:
+            # check if the opto-isolated input board from Sequent Microsystem is indeed present:
+            try:
+                _ = lib16inpind.readAll(SeqMicroHatConstants.STACK_LEVEL)
+            except FileNotFoundError as e:
+                print(f"Could not read from the Sequent Microsystem opto-isolated input board: {e}. Aborting.")
+                return 2
+            except OSError as e:
+                print(f"Error while reading from the Sequent Microsystem opto-isolated input board: {e}. Aborting.")
+                return 2
+            except BaseException as e:
+                print(f"Error while reading from the Sequent Microsystem opto-isolated input board: {e}. Aborting.")
+                return 2
+
+            print("Initializing SequentMicrosystem GPIO interrupt line")
+            b = gpiozero.Button(SeqMicroHatConstants.INTERRUPT_GPIO, pull_up=True)
+            b.when_held = self.sample_optoisolated_inputs
+            buttons.append(b)
+
+            # do first sampling operation immediately:
+            self.sample_optoisolated_inputs()
+
+        return buttons
+
+    def sample_optoisolated_inputs(self):
+        """
+        This function is invoked when the SequentMicrosystem hat triggers an interrupt saying
+        "hey there is some change in my inputs"... so we read all the 16 digital inputs
+        """
+
+        # NOTE0: since this routine is invoked by the gpiozero library, it runs on a secondary OS thread
+        #        so we must use a mutex when writing to the 'optoisolated_inputs_sampled_values' array
+        # NOTE1: this is a blocking call that will block until the 16 inputs are sampled
+        # NOTE2: this might raise a TimeoutError exception in case the I2C bus transaction fails
+        packed_sample = lib16inpind.readAll(SeqMicroHatConstants.STACK_LEVEL)
+        timestamp = int(time.time())
+
+        with self.lock:
+            for i in range(SeqMicroHatConstants.MAX_CHANNELS):
+                # Extract the bit at position i-th using bitwise AND operation
+                self.optoisolated_inputs_sampled_values[i].push_sample(timestamp, bool(packed_sample & (1 << i)))
+
+        self.stats["num_readings"] += 1
+
+        # FIXME: right now, it's hard to force-wake the coroutine
+        # which handles publishing to MQTT
+        # the reason is that we should be using
+        #   https://docs.python.org/3/library/asyncio-sync.html#asyncio.Event
+        # which is not thread-safe. And this function executes in GPIOzero secondary thread :(
+        # This means that if an input changes rapidly from 0 to 1 and then back to 0, we might not
+        # publish this to MQTT (depends on the MQTT publish frequency... nyquist frequency)
+
+    async def publish_optoisolated_inputs(self, cfg: AppConfig):
+        """
+        Publishes over MQTT the status of all opto-isolated inputs.
+        This function has a particularity: it's designed to continuously publish over MQTT the status of
+        the input channels. This is a safety feature designed mostly for alarm systems: thanks to this continuous
+        updates, the subscriber can trigger the burglar alarm if the stream of input sensor updates stops for some reason.
+        """
+        print(
+            f"Connecting to MQTT broker with identifier {OptoIsolatedInputsHandler.client_identifier} to publish OPTOISOLATED INPUT states"
+        )
+        self.stats["num_connections_publish"] += 1
+        while True:
+            try:
+                async with cfg.create_aiomqtt_client(OptoIsolatedInputsHandler.client_identifier) as client:
+                    while not OptoIsolatedInputsHandler.stop_requested:
+                        # Publish each sampled value as a separate MQTT topic
+                        update_loop_start_sec = time.perf_counter()
+                        timestamp_now = int(time.time())
+                        for i in range(SeqMicroHatConstants.MAX_CHANNELS):
+                            # convert from zero-based index 'i' to 1-based index, as used in the config file
+                            input_cfg = cfg.get_optoisolated_input_config(1 + i)
+                            if input_cfg is None:
+                                continue
+
+                            # acquire last sampled value for the i-th input
+                            with self.lock:
+                                filter_min_duration = input_cfg["filter"]["stability_threshold_sec"]
+                                if filter_min_duration == 0:
+                                    # filtering disabled -- just pick the most updated sample and use it
+                                    sample = self.optoisolated_inputs_sampled_values[i].get_last_sample()
+                                    assert (
+                                        sample is not None
+                                    )  # this should be impossible as buffer is always initialized with 1 sample at least
+                                else:
+                                    # filtering enabled -- choose sensor status:
+                                    sample = self.optoisolated_inputs_sampled_values[i].get_stable_sample(
+                                        timestamp_now, filter_min_duration
+                                    )
+                                    if sample is None:
+                                        # failed to find a 'stable' sample -- assume the input is malfunctioning
+                                        self.stats["ERROR_no_stable_samples"] += 1
+                                        sample = (0, False)
+
+                            # sample is a tuple (TIMESTAMP;VALUE), extract just the value:
+                            bit_value = sample[1]
+                            if input_cfg["active_low"]:
+                                logical_value = not bit_value
+                                # input_type = "active low"
+                            else:
+                                logical_value = bit_value
+                                # input_type = "active high"
+
+                            payload = (
+                                input_cfg["mqtt"]["payload_on"] if logical_value else input_cfg["mqtt"]["payload_off"]
+                            )
+                            # print(f"From INPUT#{i+1} [{input_type}] read {int(bit_value)} -> {int(logical_value)}; publishing on mqtt topic [{topic}] the payload: {payload}")
+
+                            await client.publish(input_cfg["mqtt"]["topic"], payload, qos=MqttQOS.AT_LEAST_ONCE)
+                            self.stats["num_mqtt_messages"] += 1
+
+                        update_loop_duration_sec = time.perf_counter() - update_loop_start_sec
+                        # print(f"Updating all sensors on MQTT took {update_loop_duration_sec} secs")
+
+                        # Now sleep a little bit before repeating
+                        actual_sleep_time_sec = cfg.homeassistant_publish_period_sec
+                        if actual_sleep_time_sec > update_loop_duration_sec:
+                            # adjust for the time it took to update on MQTT broker all topics
+                            actual_sleep_time_sec -= update_loop_duration_sec
+
+                        await asyncio.sleep(actual_sleep_time_sec)
+            except aiomqtt.MqttError as err:
+                print(f"Connection lost: {err}; reconnecting in {cfg.mqtt_reconnection_period_sec} seconds ...")
+                self.stats["ERROR_num_connections_lost"] += 1
+                await asyncio.sleep(cfg.mqtt_reconnection_period_sec)
+            except Exception as err:
+                print(f"EXCEPTION: [{err}]. Exiting with code 99.")
+                sys.exit(99)
+
+    async def homeassistant_discovery_message_publish(self, cfg: AppConfig):
+        """
+        Publishes over MQTT a so-called 'discovery' message that allows HomeAssistant to automatically
+        detect the binary_sensors associated with the GPIO inputs.
+        See https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery
+        """
+        print(
+            f"Connecting to MQTT broker with identifier {OptoIsolatedInputsHandler.client_identifier_discovery_pub} to publish OPTOISOLATED INPUT discovery messages"
+        )
+        self.stats["num_connections_discovery_publish"] += 1
+
+        try:
+            async with cfg.create_aiomqtt_client(OptoIsolatedInputsHandler.client_identifier_discovery_pub) as client:
+                print("Publishing DISCOVERY messages for OPTOISOLATED INPUTs")
+                for entry in cfg.get_all_optoisolated_inputs():
+                    mqtt_prefix = cfg.homeassistant_discovery_topic_prefix
+                    mqtt_platform = entry["home_assistant"]["platform"]
+                    assert mqtt_platform == "binary_sensor"  # the only supported value for now
+                    mqtt_node_id = cfg.homeassistant_discovery_topic_node_id
+                    mqtt_discovery_topic = f"{mqtt_prefix}/{mqtt_platform}/{mqtt_node_id}/{entry['name']}/config"
+
+                    # NOTE: the HomeAssistant unique_id is what appears in the config file as "name"
+                    mqtt_payload_dict = {
+                        "unique_id": entry["name"],
+                        "name": entry["description"],
+                        "state_topic": entry["mqtt"]["topic"],
+                        "payload_on": entry["mqtt"]["payload_on"],
+                        "payload_off": entry["mqtt"]["payload_off"],
+                        "device_class": entry["home_assistant"]["device_class"],
+                        "expire_after": entry["home_assistant"]["expire_after"],
+                        "device": cfg.get_device_dict(),
+                    }
+                    if entry["home_assistant"]["icon"] is not None:
+                        # add icon to the config of the entry:
+                        mqtt_payload_dict["icon"] = entry["home_assistant"]["icon"]
+                    mqtt_payload = json.dumps(mqtt_payload_dict)
+                    await client.publish(mqtt_discovery_topic, mqtt_payload, qos=MqttQOS.AT_LEAST_ONCE)
+                    self.stats["num_mqtt_discovery_messages_published"] += 1
+        except aiomqtt.MqttError as err:
+            print(f"Connection lost: {err}; reconnecting in {cfg.mqtt_reconnection_period_sec} seconds ...")
+            self.stats["ERROR_num_connections_lost"] += 1
+            await asyncio.sleep(cfg.mqtt_reconnection_period_sec)
+        except Exception as err:
+            print(f"EXCEPTION: {err}")
+            sys.exit(99)
+
+    def print_stats(self):
+        print(">> OPTO-ISOLATED INPUTS:")
+        print(f">>   Num (re)connections to the MQTT broker [publish channel]: {self.stats['num_connections_publish']}")
+        print(f">>   Num MQTT messages published to the broker: {self.stats['num_mqtt_messages']}")
+        print(f">>   Num actual readings of optoisolated inputs: {self.stats['num_readings']}")
+        print(">>   OPTO-ISOLATED DISCOVERY messages:")
+        print(f">>     Num MQTT discovery messages published: {self.stats['num_mqtt_discovery_messages_published']}")
+        print(f">>     Num (re)connections to the MQTT broker: {self.stats['num_connections_discovery_publish']}")
+        print(f">>   ERROR: unstable samples found: {self.stats['ERROR_no_stable_samples']}")
+        print(f">>   ERROR: MQTT connections lost: {self.stats['ERROR_num_connections_lost']}")

raspy2mqtt/stats.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+import time
+import asyncio
+
+# from raspy2mqtt.constants import *
+from .config import AppConfig
+
+#
+# Author: fmontorsi
+# Created: Apr 2024
+# License: Apache license
+#
+
+# =======================================================================================================
+# StatsCollector
+# =======================================================================================================
+
+
+class StatsCollector:
+    """
+    This class handles collecting stats from other objects of the application and periodically
+    show them on the stdout
+    """
+
+    # the stop-request is not related to a particular instance of this class... it applies to any instance
+    stop_requested = False
+
+    def __init__(self, objs_with_stats: list):
+        self.start_time = time.time()
+        self.counter = 1
+        self.objs_with_stats = objs_with_stats
+
+    async def print_stats_periodically(self, cfg: AppConfig):
+        if cfg.stats_log_period_sec == 0:
+            return  # the user requested to NOT print periodically the stats
+        next_stat_time = time.time() + cfg.stats_log_period_sec
+        while not StatsCollector.stop_requested:
+            # Print out stats to help debugging
+            if time.time() >= next_stat_time:
+                self.print_stats()
+                next_stat_time = time.time() + cfg.stats_log_period_sec
+
+            await asyncio.sleep(0.25)
+
+    def print_stats(self):
+        print(f">> STAT REPORT #{self.counter}")
+
+        uptime_sec = time.time() - self.start_time
+        m, s = divmod(uptime_sec, 60)
+        h, m = divmod(m, 60)
+        h = int(h)
+        m = int(m)
+        s = int(s)
+        print(f">> Uptime: {h}:{m:02}:{s:02}")
+
+        for x in self.objs_with_stats:
+            x.print_stats()
+
+        self.counter += 1