mmrelay 1.0__py3-none-any.whl

mmrelay/plugin_loader.py

@@ -0,0 +1,336 @@
+# trunk-ignore-all(bandit)
+import hashlib
+import importlib.util
+import os
+import subprocess
+import sys
+
+from mmrelay.config import get_app_path, get_base_dir
+from mmrelay.log_utils import get_logger
+
+# Global config variable that will be set from main.py
+config = None
+
+logger = get_logger(name="Plugins")
+sorted_active_plugins = []
+plugins_loaded = False
+
+
+def get_custom_plugin_dirs():
+    """
+    Returns a list of directories to check for custom plugins in order of priority:
+    1. User directory (~/.mmrelay/plugins/custom)
+    2. Local directory (plugins/custom) for backward compatibility
+    """
+    dirs = []
+
+    # Check user directory first (preferred location)
+    user_dir = os.path.join(get_base_dir(), "plugins", "custom")
+    os.makedirs(user_dir, exist_ok=True)
+    dirs.append(user_dir)
+
+    # Check local directory (backward compatibility)
+    local_dir = os.path.join(get_app_path(), "plugins", "custom")
+    dirs.append(local_dir)
+
+    return dirs
+
+
+def get_community_plugin_dirs():
+    """
+    Returns a list of directories to check for community plugins in order of priority:
+    1. User directory (~/.mmrelay/plugins/community)
+    2. Local directory (plugins/community) for backward compatibility
+    """
+    dirs = []
+
+    # Check user directory first (preferred location)
+    user_dir = os.path.join(get_base_dir(), "plugins", "community")
+    os.makedirs(user_dir, exist_ok=True)
+    dirs.append(user_dir)
+
+    # Check local directory (backward compatibility)
+    local_dir = os.path.join(get_app_path(), "plugins", "community")
+    dirs.append(local_dir)
+
+    return dirs
+
+
+def clone_or_update_repo(repo_url, tag, plugins_dir):
+    # Extract the repository name from the URL
+    repo_name = os.path.splitext(os.path.basename(repo_url.rstrip("/")))[0]
+    repo_path = os.path.join(plugins_dir, repo_name)
+    if os.path.isdir(repo_path):
+        try:
+            subprocess.check_call(["git", "-C", repo_path, "fetch"])
+            subprocess.check_call(["git", "-C", repo_path, "checkout", tag])
+            subprocess.check_call(["git", "-C", repo_path, "pull", "origin", tag])
+            logger.info(f"Updated repository {repo_name} to {tag}")
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Error updating repository {repo_name}: {e}")
+            logger.error(
+                f"Please manually git clone the repository {repo_url} into {repo_path}"
+            )
+            sys.exit(1)
+    else:
+        try:
+            os.makedirs(plugins_dir, exist_ok=True)
+            subprocess.check_call(
+                ["git", "clone", "--branch", tag, repo_url], cwd=plugins_dir
+            )
+            logger.info(f"Cloned repository {repo_name} from {repo_url} at {tag}")
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Error cloning repository {repo_name}: {e}")
+            logger.error(
+                f"Please manually git clone the repository {repo_url} into {repo_path}"
+            )
+            sys.exit(1)
+    # Install requirements if requirements.txt exists
+    requirements_path = os.path.join(repo_path, "requirements.txt")
+    if os.path.isfile(requirements_path):
+        try:
+            # Use pip to install the requirements.txt
+            subprocess.check_call(
+                [sys.executable, "-m", "pip", "install", "-r", requirements_path]
+            )
+            logger.info(f"Installed requirements for plugin {repo_name}")
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Error installing requirements for plugin {repo_name}: {e}")
+            logger.error(
+                f"Please manually install the requirements from {requirements_path}"
+            )
+            sys.exit(1)
+
+
+def load_plugins_from_directory(directory, recursive=False):
+    plugins = []
+    if os.path.isdir(directory):
+        for root, _dirs, files in os.walk(directory):
+            for filename in files:
+                if filename.endswith(".py"):
+                    plugin_path = os.path.join(root, filename)
+                    module_name = (
+                        "plugin_"
+                        + hashlib.sha256(plugin_path.encode("utf-8")).hexdigest()
+                    )
+                    spec = importlib.util.spec_from_file_location(
+                        module_name, plugin_path
+                    )
+                    plugin_module = importlib.util.module_from_spec(spec)
+                    try:
+                        spec.loader.exec_module(plugin_module)
+                        if hasattr(plugin_module, "Plugin"):
+                            plugins.append(plugin_module.Plugin())
+                        else:
+                            logger.warning(
+                                f"{plugin_path} does not define a Plugin class."
+                            )
+                    except Exception as e:
+                        logger.error(f"Error loading plugin {plugin_path}: {e}")
+            if not recursive:
+                break
+    else:
+        if not plugins_loaded:  # Only log the missing directory once
+            logger.debug(f"Directory {directory} does not exist.")
+    return plugins
+
+
+def load_plugins(passed_config=None):
+    global sorted_active_plugins
+    global plugins_loaded
+    global config
+
+    if plugins_loaded:
+        return sorted_active_plugins
+
+    logger.info("Checking plugin config...")
+
+    # Update the global config if a config is passed
+    if passed_config is not None:
+        config = passed_config
+
+    # Check if config is available
+    if config is None:
+        logger.error("No configuration available. Cannot load plugins.")
+        return []
+
+    # Import core plugins
+    from mmrelay.plugins.debug_plugin import Plugin as DebugPlugin
+    from mmrelay.plugins.drop_plugin import Plugin as DropPlugin
+    from mmrelay.plugins.health_plugin import Plugin as HealthPlugin
+    from mmrelay.plugins.help_plugin import Plugin as HelpPlugin
+    from mmrelay.plugins.map_plugin import Plugin as MapPlugin
+    from mmrelay.plugins.mesh_relay_plugin import Plugin as MeshRelayPlugin
+    from mmrelay.plugins.nodes_plugin import Plugin as NodesPlugin
+    from mmrelay.plugins.ping_plugin import Plugin as PingPlugin
+    from mmrelay.plugins.telemetry_plugin import Plugin as TelemetryPlugin
+    from mmrelay.plugins.weather_plugin import Plugin as WeatherPlugin
+
+    # Initial list of core plugins
+    core_plugins = [
+        HealthPlugin(),
+        MapPlugin(),
+        MeshRelayPlugin(),
+        PingPlugin(),
+        TelemetryPlugin(),
+        WeatherPlugin(),
+        HelpPlugin(),
+        NodesPlugin(),
+        DropPlugin(),
+        DebugPlugin(),
+    ]
+
+    plugins = core_plugins.copy()
+
+    # Process and load custom plugins
+    custom_plugins_config = config.get("custom-plugins", {})
+    custom_plugin_dirs = get_custom_plugin_dirs()
+
+    active_custom_plugins = [
+        plugin_name
+        for plugin_name, plugin_info in custom_plugins_config.items()
+        if plugin_info.get("active", False)
+    ]
+
+    if active_custom_plugins:
+        logger.debug(
+            f"Loading active custom plugins: {', '.join(active_custom_plugins)}"
+        )
+
+    # Only load custom plugins that are explicitly enabled
+    for plugin_name in active_custom_plugins:
+        plugin_found = False
+
+        # Try each directory in order
+        for custom_dir in custom_plugin_dirs:
+            plugin_path = os.path.join(custom_dir, plugin_name)
+            if os.path.exists(plugin_path):
+                logger.debug(f"Loading custom plugin from: {plugin_path}")
+                plugins.extend(
+                    load_plugins_from_directory(plugin_path, recursive=False)
+                )
+                plugin_found = True
+                break
+
+        if not plugin_found:
+            logger.warning(
+                f"Custom plugin '{plugin_name}' not found in any of the plugin directories"
+            )
+
+    # Process and download community plugins
+    community_plugins_config = config.get("community-plugins", {})
+    community_plugin_dirs = get_community_plugin_dirs()
+
+    # Get the first directory for cloning (prefer user directory)
+    community_plugins_dir = community_plugin_dirs[
+        -1
+    ]  # Use the user directory for new clones
+
+    # Create community plugins directory if needed
+    active_community_plugins = [
+        plugin_name
+        for plugin_name, plugin_info in community_plugins_config.items()
+        if plugin_info.get("active", False)
+    ]
+
+    if active_community_plugins:
+        # Ensure all community plugin directories exist
+        for dir_path in community_plugin_dirs:
+            os.makedirs(dir_path, exist_ok=True)
+
+        logger.debug(
+            f"Loading active community plugins: {', '.join(active_community_plugins)}"
+        )
+
+    # Only process community plugins if config section exists and is a dictionary
+    if isinstance(community_plugins_config, dict):
+        for plugin_name, plugin_info in community_plugins_config.items():
+            if not plugin_info.get("active", False):
+                logger.debug(
+                    f"Skipping community plugin {plugin_name} - not active in config"
+                )
+                continue
+
+            repo_url = plugin_info.get("repository")
+            tag = plugin_info.get("tag", "master")
+            if repo_url:
+                # Clone to the user directory by default
+                clone_or_update_repo(repo_url, tag, community_plugins_dir)
+            else:
+                logger.error("Repository URL not specified for a community plugin")
+                logger.error("Please specify the repository URL in config.yaml")
+                sys.exit(1)
+
+    # Only load community plugins that are explicitly enabled
+    for plugin_name in active_community_plugins:
+        plugin_info = community_plugins_config[plugin_name]
+        repo_url = plugin_info.get("repository")
+        if repo_url:
+            # Extract repository name from URL
+            repo_name = os.path.splitext(os.path.basename(repo_url.rstrip("/")))[0]
+
+            # Try each directory in order
+            plugin_found = False
+            for dir_path in community_plugin_dirs:
+                plugin_path = os.path.join(dir_path, repo_name)
+                if os.path.exists(plugin_path):
+                    logger.debug(f"Loading community plugin from: {plugin_path}")
+                    plugins.extend(
+                        load_plugins_from_directory(plugin_path, recursive=True)
+                    )
+                    plugin_found = True
+                    break
+
+            if not plugin_found:
+                logger.warning(
+                    f"Community plugin '{repo_name}' not found in any of the plugin directories"
+                )
+        else:
+            logger.error(
+                f"Repository URL not specified for community plugin: {plugin_name}"
+            )
+
+    # Filter and sort active plugins by priority
+    active_plugins = []
+    for plugin in plugins:
+        plugin_name = getattr(plugin, "plugin_name", plugin.__class__.__name__)
+
+        # Determine if the plugin is active based on the configuration
+        if plugin in core_plugins:
+            # Core plugins: default to inactive unless specified otherwise
+            plugin_config = config.get("plugins", {}).get(plugin_name, {})
+            is_active = plugin_config.get("active", False)
+        else:
+            # Custom and community plugins: default to inactive unless specified
+            if plugin_name in config.get("custom-plugins", {}):
+                plugin_config = config.get("custom-plugins", {}).get(plugin_name, {})
+            elif plugin_name in community_plugins_config:
+                plugin_config = community_plugins_config.get(plugin_name, {})
+            else:
+                plugin_config = {}
+
+            is_active = plugin_config.get("active", False)
+
+        if is_active:
+            plugin.priority = plugin_config.get(
+                "priority", getattr(plugin, "priority", 100)
+            )
+            active_plugins.append(plugin)
+            try:
+                plugin.start()
+            except Exception as e:
+                logger.error(f"Error starting plugin {plugin_name}: {e}")
+
+    sorted_active_plugins = sorted(active_plugins, key=lambda plugin: plugin.priority)
+
+    # Log all loaded plugins
+    if sorted_active_plugins:
+        plugin_names = [
+            getattr(plugin, "plugin_name", plugin.__class__.__name__)
+            for plugin in sorted_active_plugins
+        ]
+        logger.info(f"Plugins loaded: {', '.join(plugin_names)}")
+    else:
+        logger.info("Plugins loaded: none")
+
+    plugins_loaded = True  # Set the flag to indicate that plugins have been load

mmrelay/plugins/__init__.py

@@ -0,0 +1,3 @@
+"""
+Plugin system for Meshtastic Matrix Relay.
+"""

mmrelay/plugins/base_plugin.py

@@ -0,0 +1,212 @@
+import threading
+import time
+from abc import ABC, abstractmethod
+
+import markdown
+import schedule
+
+from mmrelay.db_utils import (
+    delete_plugin_data,
+    get_plugin_data,
+    get_plugin_data_for_node,
+    store_plugin_data,
+)
+from mmrelay.log_utils import get_logger
+
+# Global config variable that will be set from main.py
+config = None
+
+
+class BasePlugin(ABC):
+    # Class-level default attributes
+    plugin_name = None  # Must be overridden in subclasses
+    max_data_rows_per_node = 100
+    priority = 10
+
+    @property
+    def description(self):
+        return ""
+
+    def __init__(self) -> None:
+        # IMPORTANT NOTE FOR PLUGIN DEVELOPERS:
+        # When creating a plugin that inherits from BasePlugin, you MUST set
+        # self.plugin_name in your __init__ method BEFORE calling super().__init__()
+        # Example:
+        #   def __init__(self):
+        #       self.plugin_name = "your_plugin_name"  # Set this FIRST
+        #       super().__init__()                     # Then call parent
+        #
+        # Failure to do this will cause command recognition issues and other problems.
+
+        super().__init__()
+
+        # Verify plugin_name is properly defined
+        if not hasattr(self, "plugin_name") or self.plugin_name is None:
+            raise ValueError(
+                f"{self.__class__.__name__} is missing plugin_name definition. "
+                f"Make sure to set self.plugin_name BEFORE calling super().__init__()"
+            )
+
+        self.logger = get_logger(f"Plugin:{self.plugin_name}")
+        self.config = {"active": False}
+        global config
+        plugin_levels = ["plugins", "community-plugins", "custom-plugins"]
+
+        # Check if config is available
+        if config is not None:
+            for level in plugin_levels:
+                if level in config and self.plugin_name in config[level]:
+                    self.config = config[level][self.plugin_name]
+                    break
+
+            # Get the list of mapped channels
+            self.mapped_channels = [
+                room.get("meshtastic_channel")
+                for room in config.get("matrix_rooms", [])
+            ]
+
+        # Get the channels specified for this plugin, or default to all mapped channels
+        self.channels = self.config.get("channels", self.mapped_channels)
+
+        # Ensure channels is a list
+        if not isinstance(self.channels, list):
+            self.channels = [self.channels]
+
+        # Validate the channels
+        invalid_channels = [
+            ch for ch in self.channels if ch not in self.mapped_channels
+        ]
+        if invalid_channels:
+            self.logger.warning(
+                f"Plugin '{self.plugin_name}': Channels {invalid_channels} are not mapped in configuration."
+            )
+
+        # Get the response delay from the meshtastic config only
+        self.response_delay = 3  # Default value
+        if config is not None:
+            self.response_delay = config.get("meshtastic", {}).get(
+                "plugin_response_delay", self.response_delay
+            )
+
+    def start(self):
+        if "schedule" not in self.config or (
+            "at" not in self.config["schedule"]
+            and "hours" not in self.config["schedule"]
+            and "minutes" not in self.config["schedule"]
+        ):
+            self.logger.debug(f"Started with priority={self.priority}")
+            return
+
+        # Schedule the background job based on the configuration
+        if "at" in self.config["schedule"] and "hours" in self.config["schedule"]:
+            schedule.every(self.config["schedule"]["hours"]).hours.at(
+                self.config["schedule"]["at"]
+            ).do(self.background_job)
+        elif "at" in self.config["schedule"] and "minutes" in self.config["schedule"]:
+            schedule.every(self.config["schedule"]["minutes"]).minutes.at(
+                self.config["schedule"]["at"]
+            ).do(self.background_job)
+        elif "hours" in self.config["schedule"]:
+            schedule.every(self.config["schedule"]["hours"]).hours.do(
+                self.background_job
+            )
+        elif "minutes" in self.config["schedule"]:
+            schedule.every(self.config["schedule"]["minutes"]).minutes.do(
+                self.background_job
+            )
+
+        # Function to execute the scheduled tasks
+        def run_schedule():
+            while True:
+                schedule.run_pending()
+                time.sleep(1)
+
+        # Create a thread for executing the scheduled tasks
+        schedule_thread = threading.Thread(target=run_schedule)
+
+        # Start the thread
+        schedule_thread.start()
+        self.logger.debug(f"Scheduled with priority={self.priority}")
+
+    # trunk-ignore(ruff/B027)
+    def background_job(self):
+        pass  # Implement in subclass if needed
+
+    def strip_raw(self, data):
+        if isinstance(data, dict):
+            data.pop("raw", None)
+            for k, v in data.items():
+                data[k] = self.strip_raw(v)
+        elif isinstance(data, list):
+            data = [self.strip_raw(item) for item in data]
+        return data
+
+    def get_response_delay(self):
+        return self.response_delay
+
+    # Modified method to accept is_direct_message parameter
+    def is_channel_enabled(self, channel, is_direct_message=False):
+        if is_direct_message:
+            return True  # Always respond to DMs if the plugin is active
+        else:
+            return channel in self.channels
+
+    def get_matrix_commands(self):
+        return [self.plugin_name]
+
+    async def send_matrix_message(self, room_id, message, formatted=True):
+        from mmrelay.matrix_utils import connect_matrix
+
+        matrix_client = await connect_matrix()
+
+        return await matrix_client.room_send(
+            room_id=room_id,
+            message_type="m.room.message",
+            content={
+                "msgtype": "m.text",
+                "format": "org.matrix.custom.html" if formatted else None,
+                "body": message,
+                "formatted_body": markdown.markdown(message) if formatted else None,
+            },
+        )
+
+    def get_mesh_commands(self):
+        return []
+
+    def store_node_data(self, meshtastic_id, node_data):
+        data = self.get_node_data(meshtastic_id=meshtastic_id)
+        data = data[-self.max_data_rows_per_node :]
+        if isinstance(node_data, list):
+            data.extend(node_data)
+        else:
+            data.append(node_data)
+        store_plugin_data(self.plugin_name, meshtastic_id, data)
+
+    def set_node_data(self, meshtastic_id, node_data):
+        node_data = node_data[-self.max_data_rows_per_node :]
+        store_plugin_data(self.plugin_name, meshtastic_id, node_data)
+
+    def delete_node_data(self, meshtastic_id):
+        return delete_plugin_data(self.plugin_name, meshtastic_id)
+
+    def get_node_data(self, meshtastic_id):
+        return get_plugin_data_for_node(self.plugin_name, meshtastic_id)
+
+    def get_data(self):
+        return get_plugin_data(self.plugin_name)
+
+    def matches(self, event):
+        from mmrelay.matrix_utils import bot_command
+
+        # Pass the entire event to bot_command
+        return bot_command(self.plugin_name, event)
+
+    @abstractmethod
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        pass  # Implement in subclass
+
+    @abstractmethod
+    async def handle_room_message(self, room, event, full_message):
+        pass  # Implement in subclass

mmrelay/plugins/debug_plugin.py

@@ -0,0 +1,17 @@
+from mmrelay.plugins.base_plugin import BasePlugin
+
+
+class Plugin(BasePlugin):
+    plugin_name = "debug"
+    priority = 1
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        packet = self.strip_raw(packet)
+
+        self.logger.debug(f"Packet received: {packet}")
+        return False
+
+    async def handle_room_message(self, room, event, full_message):
+        return False

mmrelay/plugins/drop_plugin.py

@@ -0,0 +1,120 @@
+import re
+
+from haversine import haversine
+
+from mmrelay.meshtastic_utils import connect_meshtastic
+from mmrelay.plugins.base_plugin import BasePlugin
+
+
+class Plugin(BasePlugin):
+    plugin_name = "drop"
+    special_node = "!NODE_MSGS!"
+
+    def __init__(self):
+        self.plugin_name = "drop"
+        super().__init__()
+
+    def get_position(self, meshtastic_client, node_id):
+        for _node, info in meshtastic_client.nodes.items():
+            if info["user"]["id"] == node_id:
+                if "position" in info:
+                    return info["position"]
+                else:
+                    return None
+        return None
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        meshtastic_client = connect_meshtastic()
+        nodeInfo = meshtastic_client.getMyNodeInfo()
+
+        # Attempt message drop to packet originator if not relay
+        if "fromId" in packet and packet["fromId"] != nodeInfo["user"]["id"]:
+            position = self.get_position(meshtastic_client, packet["fromId"])
+            if position and "latitude" in position and "longitude" in position:
+                packet_location = (
+                    position["latitude"],
+                    position["longitude"],
+                )
+
+                self.logger.debug(f"Packet originates from: {packet_location}")
+                messages = self.get_node_data(self.special_node)
+                unsent_messages = []
+                for message in messages:
+                    # You cannot pickup what you dropped
+                    if (
+                        "originator" in message
+                        and message["originator"] == packet["fromId"]
+                    ):
+                        unsent_messages.append(message)
+                        continue
+
+                    try:
+                        distance_km = haversine(
+                            (packet_location[0], packet_location[1]),
+                            message["location"],
+                        )
+                    except (ValueError, TypeError):
+                        distance_km = 1000
+                    radius_km = (
+                        self.config["radius_km"] if "radius_km" in self.config else 5
+                    )
+                    if distance_km <= radius_km:
+                        target_node = packet["fromId"]
+                        self.logger.debug(f"Sending dropped message to {target_node}")
+                        meshtastic_client.sendText(
+                            text=message["text"], destinationId=target_node
+                        )
+                    else:
+                        unsent_messages.append(message)
+                self.set_node_data(self.special_node, unsent_messages)
+                total_unsent_messages = len(unsent_messages)
+                if total_unsent_messages > 0:
+                    self.logger.debug(f"{total_unsent_messages} message(s) remaining")
+
+        # Attempt to drop a message
+        if (
+            "decoded" in packet
+            and "portnum" in packet["decoded"]
+            and packet["decoded"]["portnum"] == "TEXT_MESSAGE_APP"
+        ):
+            text = packet["decoded"]["text"] if "text" in packet["decoded"] else None
+            if f"!{self.plugin_name}" not in text:
+                return False
+
+            match = re.search(r"!drop\s+(.+)$", text)
+            if not match:
+                return False
+
+            drop_message = match.group(1)
+
+            position = {}
+            for _node, info in meshtastic_client.nodes.items():
+                if info["user"]["id"] == packet["fromId"]:
+                    if "position" in info:
+                        position = info["position"]
+                    else:
+                        continue
+
+            if "latitude" not in position or "longitude" not in position:
+                self.logger.debug(
+                    "Position of dropping node is not known. Skipping ..."
+                )
+                return True
+
+            self.store_node_data(
+                self.special_node,
+                {
+                    "location": (position["latitude"], position["longitude"]),
+                    "text": drop_message,
+                    "originator": packet["fromId"],
+                },
+            )
+            self.logger.debug(f"Dropped a message: {drop_message}")
+            return True
+
+    async def handle_room_message(self, room, event, full_message):
+        # Pass the event to matches() instead of full_message
+        if self.matches(event):
+            return True