mmrelay 1.0.7__tar.gz → 1.0.9__tar.gz

{mmrelay-1.0.7 → mmrelay-1.0.9}/MANIFEST.in

@@ -1,6 +1,4 @@
 include LICENSE
 include README.md
 include requirements.txt
-include sample_config.yaml
-recursive-include tools *
 recursive-include src/mmrelay/tools *

{mmrelay-1.0.7/src/mmrelay.egg-info → mmrelay-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.0.7
+Version: 1.0.9
 Summary: Bridge between Meshtastic mesh networks and Matrix chat rooms
 Home-page: https://github.com/geoffwhittington/meshtastic-matrix-relay
 Author: Geoff Whittington, Jeremiah K., and contributors
@@ -22,72 +22,45 @@ Requires-Dist: requests==2.32.3
 Requires-Dist: markdown==3.8
 Requires-Dist: haversine==2.9.0
 Requires-Dist: schedule==1.2.2
-Requires-Dist: platformdirs==4.3.7
+Requires-Dist: platformdirs==4.3.8
 Requires-Dist: py-staticmaps>=0.4.0
 Requires-Dist: rich==14.0.0
-Requires-Dist: setuptools==80.3.1
+Requires-Dist: setuptools==80.9.0
 Dynamic: license-file
 
 # M<>M Relay
 
-## ✨ Version 1.0 Released! ✨
+## (Meshtastic <=> Matrix Relay)
 
-**We're excited to announce MMRelay v1.0 with improved packaging, standardized directories, and enhanced CLI!**
+A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
 
-**Existing users:** Version 1.0 requires a few quick migration steps:
+## Documentation
 
-1. Follow the [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) guide for a smooth transition
-2. Move your configuration to the new standard location (`~/.mmrelay/config.yaml`)
-3. See [ANNOUNCEMENT.md](ANNOUNCEMENT.md) for all the exciting new features
+Visit our [Wiki](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
 
-Not ready to upgrade yet? No problem! Run `git checkout 0.10.1` to continue using the previous version.
-
-## (Meshtastic <=> Matrix Relay)
-
-A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
+- [Installation Instructions](docs/INSTRUCTIONS.md) - Setup and configuration guide
+- [v1.0 Release Announcement](docs/ANNOUNCEMENT.md) - New changes in v1.0
+- [Upgrade Guide](docs/UPGRADE_TO_V1.md) - Migration guidance for existing users
 
 ---
 
-## Getting Started
+## Quick Start
 
 MMRelay runs on Linux, macOS, and Windows.
 
-### Quick Installation
-
 ```bash
 # Install using pipx for isolated installation (recommended)
 pipx install mmrelay
 
-# Pip will also work if you prefer
-pip install mmrelay
-```
-
-For pipx installation instructions, see: [pipx installation guide](https://pipx.pypa.io/stable/installation/#on-linux)
+# Generate a sample configuration file & then edit it
+mmrelay --generate-config
 
-### Resources
-
-- **New Users**: See [INSTRUCTIONS.md](INSTRUCTIONS.md) for setup and configuration
-- **Existing Users**: See [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) for migration guidance
-- **Configuration**: Review [sample_config.yaml](src/mmrelay/tools/sample_config.yaml) for examples
-
-### Command-Line Options
-
-```bash
-usage: mmrelay [-h] [--config CONFIG] [--data-dir DATA_DIR] [--log-level {error,warning,info,debug}] [--logfile LOGFILE] [--version] [--generate-config] [--install-service] [--check-config]
-
-Options:
-  -h, --help            Show this help message and exit
-  --config CONFIG       Path to config file
-  --data-dir DATA_DIR   Base directory for all data (logs, database, plugins)
-  --log-level {error,warning,info,debug}
-                        Set logging level
-  --logfile LOGFILE     Path to log file (can be overridden by --data-dir)
-  --version             Show version and exit
-  --generate-config     Generate a sample config.yaml file
-  --install-service     Install or update the systemd user service
-  --check-config        Check if the configuration file is valid
+# Start the relay (without --install-service to run manually)
+mmrelay --install-service
 ```
 
+For detailed installation and configuration instructions, see the [Installation Guide](docs/INSTRUCTIONS.md).
+
 ---
 
 ## Features
@@ -133,7 +106,12 @@ See the full list of core plugins [here](https://github.com/geoffwhittington/mes
 
 ### Community & Custom Plugins
 
-It is possible to create custom plugins and share them with the community. Check [example_plugins/README.md](https://github.com/geoffwhittington/meshtastic-matrix-relay/tree/main/example_plugins) and the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide).
+MMRelay's plugin system allows you to extend functionality in two ways:
+
+- **Custom Plugins**: Create personal plugins for your own use, stored in `~/.mmrelay/plugins/custom/`
+- **Community Plugins**: Share your creations with others or use plugins developed by the community
+
+Check the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide) in our wiki to get started.
 
 ✨️ Visit the [Community Plugins List](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
 
@@ -151,14 +129,12 @@ community-plugins:
 
 ### Plugin System
 
-MMRelay features a powerful plugin system with standardized locations:
+Plugins make it easy to extend functionality without modifying the core program. MMRelay features a powerful plugin system with standardized locations:
 
 - **Core Plugins**: Pre-installed with the package
 - **Custom Plugins**: Your own plugins in `~/.mmrelay/plugins/custom/`
 - **Community Plugins**: Third-party plugins in `~/.mmrelay/plugins/community/`
 
-Plugins make it easy to extend functionality without modifying the core code.
-
 ---
 
 ## Getting Started with Matrix

{mmrelay-1.0.7 → mmrelay-1.0.9}/README.md

@@ -1,63 +1,36 @@
 # M<>M Relay
 
-## ✨ Version 1.0 Released! ✨
+## (Meshtastic <=> Matrix Relay)
 
-**We're excited to announce MMRelay v1.0 with improved packaging, standardized directories, and enhanced CLI!**
+A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
 
-**Existing users:** Version 1.0 requires a few quick migration steps:
+## Documentation
 
-1. Follow the [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) guide for a smooth transition
-2. Move your configuration to the new standard location (`~/.mmrelay/config.yaml`)
-3. See [ANNOUNCEMENT.md](ANNOUNCEMENT.md) for all the exciting new features
+Visit our [Wiki](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
 
-Not ready to upgrade yet? No problem! Run `git checkout 0.10.1` to continue using the previous version.
-
-## (Meshtastic <=> Matrix Relay)
-
-A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
+- [Installation Instructions](docs/INSTRUCTIONS.md) - Setup and configuration guide
+- [v1.0 Release Announcement](docs/ANNOUNCEMENT.md) - New changes in v1.0
+- [Upgrade Guide](docs/UPGRADE_TO_V1.md) - Migration guidance for existing users
 
 ---
 
-## Getting Started
+## Quick Start
 
 MMRelay runs on Linux, macOS, and Windows.
 
-### Quick Installation
-
 ```bash
 # Install using pipx for isolated installation (recommended)
 pipx install mmrelay
 
-# Pip will also work if you prefer
-pip install mmrelay
-```
-
-For pipx installation instructions, see: [pipx installation guide](https://pipx.pypa.io/stable/installation/#on-linux)
+# Generate a sample configuration file & then edit it
+mmrelay --generate-config
 
-### Resources
-
-- **New Users**: See [INSTRUCTIONS.md](INSTRUCTIONS.md) for setup and configuration
-- **Existing Users**: See [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) for migration guidance
-- **Configuration**: Review [sample_config.yaml](src/mmrelay/tools/sample_config.yaml) for examples
-
-### Command-Line Options
-
-```bash
-usage: mmrelay [-h] [--config CONFIG] [--data-dir DATA_DIR] [--log-level {error,warning,info,debug}] [--logfile LOGFILE] [--version] [--generate-config] [--install-service] [--check-config]
-
-Options:
-  -h, --help            Show this help message and exit
-  --config CONFIG       Path to config file
-  --data-dir DATA_DIR   Base directory for all data (logs, database, plugins)
-  --log-level {error,warning,info,debug}
-                        Set logging level
-  --logfile LOGFILE     Path to log file (can be overridden by --data-dir)
-  --version             Show version and exit
-  --generate-config     Generate a sample config.yaml file
-  --install-service     Install or update the systemd user service
-  --check-config        Check if the configuration file is valid
+# Start the relay (without --install-service to run manually)
+mmrelay --install-service
 ```
 
+For detailed installation and configuration instructions, see the [Installation Guide](docs/INSTRUCTIONS.md).
+
 ---
 
 ## Features
@@ -103,7 +76,12 @@ See the full list of core plugins [here](https://github.com/geoffwhittington/mes
 
 ### Community & Custom Plugins
 
-It is possible to create custom plugins and share them with the community. Check [example_plugins/README.md](https://github.com/geoffwhittington/meshtastic-matrix-relay/tree/main/example_plugins) and the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide).
+MMRelay's plugin system allows you to extend functionality in two ways:
+
+- **Custom Plugins**: Create personal plugins for your own use, stored in `~/.mmrelay/plugins/custom/`
+- **Community Plugins**: Share your creations with others or use plugins developed by the community
+
+Check the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide) in our wiki to get started.
 
 ✨️ Visit the [Community Plugins List](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
 
@@ -121,14 +99,12 @@ community-plugins:
 
 ### Plugin System
 
-MMRelay features a powerful plugin system with standardized locations:
+Plugins make it easy to extend functionality without modifying the core program. MMRelay features a powerful plugin system with standardized locations:
 
 - **Core Plugins**: Pre-installed with the package
 - **Custom Plugins**: Your own plugins in `~/.mmrelay/plugins/custom/`
 - **Community Plugins**: Third-party plugins in `~/.mmrelay/plugins/community/`
 
-Plugins make it easy to extend functionality without modifying the core code.
-
 ---
 
 ## Getting Started with Matrix

{mmrelay-1.0.7 → mmrelay-1.0.9}/requirements.txt

@@ -6,7 +6,7 @@ requests==2.32.3
 markdown==3.8
 haversine==2.9.0
 schedule==1.2.2
-platformdirs==4.3.7
+platformdirs==4.3.8
 py-staticmaps>=0.4.0
 rich==14.0.0
-setuptools==80.3.1
+setuptools==80.9.0

{mmrelay-1.0.7 → mmrelay-1.0.9}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = mmrelay
-version = 1.0.7
+version = 1.0.9
 author = Geoff Whittington, Jeremiah K., and contributors
 author_email = jeremiahk@gmx.com
 description = Bridge between Meshtastic mesh networks and Matrix chat rooms
@@ -30,10 +30,10 @@ install_requires =
 	markdown==3.8
 	haversine==2.9.0
 	schedule==1.2.2
-	platformdirs==4.3.7
+	platformdirs==4.3.8
 	py-staticmaps>=0.4.0
 	rich==14.0.0
-	setuptools==80.3.1
+	setuptools==80.9.0
 include_package_data = True
 
 [options.packages.find]

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/__init__.py

@@ -15,4 +15,4 @@ else:
         __version__ = pkg_resources.get_distribution("mmrelay").version
     except pkg_resources.DistributionNotFound:
         # If all else fails, use hardcoded version
-        __version__ = "1.0.1"
+        __version__ = "1.0.8"

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/main.py

@@ -9,6 +9,7 @@ import signal
 import sys
 
 from nio import ReactionEvent, RoomMessageEmote, RoomMessageNotice, RoomMessageText
+from nio.events.room_events import RoomMemberEvent
 
 # Import version from package
 # Import meshtastic_utils as a module to set event_loop
@@ -22,7 +23,7 @@ from mmrelay.db_utils import (
 from mmrelay.log_utils import get_logger
 from mmrelay.matrix_utils import connect_matrix, join_matrix_room
 from mmrelay.matrix_utils import logger as matrix_logger
-from mmrelay.matrix_utils import on_room_message
+from mmrelay.matrix_utils import on_room_member, on_room_message
 from mmrelay.meshtastic_utils import connect_meshtastic
 from mmrelay.meshtastic_utils import logger as meshtastic_logger
 from mmrelay.plugin_loader import load_plugins
@@ -109,6 +110,8 @@ async def main(config):
     )
     # Add ReactionEvent callback so we can handle matrix reactions
     matrix_client.add_event_callback(on_room_message, ReactionEvent)
+    # Add RoomMemberEvent callback to track room-specific display name changes
+    matrix_client.add_event_callback(on_room_member, RoomMemberEvent)
 
     # Set up shutdown event
     shutdown_event = asyncio.Event()

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/matrix_utils.py

@@ -18,6 +18,7 @@ from nio import (
     UploadResponse,
     WhoamiError,
 )
+from nio.events.room_events import RoomMemberEvent
 from PIL import Image
 
 from mmrelay.db_utils import (
@@ -517,8 +518,16 @@ async def on_room_message(
             meshtastic_id, matrix_room_id, meshtastic_text_db, meshtastic_meshnet_db = (
                 orig
             )
-            display_name_response = await matrix_client.get_displayname(event.sender)
-            full_display_name = display_name_response.displayname or event.sender
+            # Get room-specific display name if available, fallback to global display name
+            room_display_name = room.user_name(event.sender)
+            if room_display_name:
+                full_display_name = room_display_name
+            else:
+                # Fallback to global display name if room-specific name is not available
+                display_name_response = await matrix_client.get_displayname(
+                    event.sender
+                )
+                full_display_name = display_name_response.displayname or event.sender
 
             # If not from a remote meshnet, proceed as normal to relay back to the originating meshnet
             short_display_name = full_display_name[:5]
@@ -578,8 +587,14 @@ async def on_room_message(
             return
     else:
         # Normal Matrix message from a Matrix user
-        display_name_response = await matrix_client.get_displayname(event.sender)
-        full_display_name = display_name_response.displayname or event.sender
+        # Get room-specific display name if available, fallback to global display name
+        room_display_name = room.user_name(event.sender)
+        if room_display_name:
+            full_display_name = room_display_name
+        else:
+            # Fallback to global display name if room-specific name is not available
+            display_name_response = await matrix_client.get_displayname(event.sender)
+            full_display_name = display_name_response.displayname or event.sender
         short_display_name = full_display_name[:5]
         prefix = f"{short_display_name}[M]: "
         logger.debug(f"Processing matrix message from [{full_display_name}]: {text}")
@@ -752,3 +767,18 @@ async def send_room_image(
         message_type="m.room.message",
         content={"msgtype": "m.image", "url": upload_response.content_uri, "body": ""},
     )
+
+
+async def on_room_member(room: MatrixRoom, event: RoomMemberEvent) -> None:
+    """
+    Callback to handle room member events, specifically tracking room-specific display name changes.
+    This ensures we detect when users update their display names in specific rooms.
+
+    Note: This callback doesn't need to do any explicit processing since matrix-nio
+    automatically updates the room state and room.user_name() will return the
+    updated room-specific display name immediately after this event.
+    """
+    # The callback is registered to ensure matrix-nio processes the event,
+    # but no explicit action is needed since room.user_name() automatically
+    # handles room-specific display names after the room state is updated.
+    pass

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugin_loader.py

@@ -57,6 +57,28 @@ def get_community_plugin_dirs():
 
 
 def clone_or_update_repo(repo_url, ref, plugins_dir):
+    """Clone or update a Git repository for community plugins.
+
+    Args:
+        repo_url (str): Git repository URL to clone/update
+        ref (dict): Reference specification with keys:
+                   - type: "tag" or "branch"
+                   - value: tag name or branch name
+        plugins_dir (str): Directory where the repository should be cloned
+
+    Returns:
+        bool: True if successful, False if clone/update failed
+
+    Handles complex Git operations including:
+    - Cloning new repositories with specific tags/branches
+    - Updating existing repositories and switching refs
+    - Installing requirements.txt dependencies via pip or pipx
+    - Fallback to default branches (main/master) when specified ref fails
+    - Robust error handling and logging
+
+    The function automatically installs Python dependencies if a requirements.txt
+    file is found in the repository root.
+    """
     # 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)
@@ -497,6 +519,27 @@ def clone_or_update_repo(repo_url, ref, plugins_dir):
 
 
 def load_plugins_from_directory(directory, recursive=False):
+    """Load plugin classes from Python files in a directory.
+
+    Args:
+        directory (str): Directory path to search for plugin files
+        recursive (bool): Whether to search subdirectories recursively
+
+    Returns:
+        list: List of instantiated plugin objects found in the directory
+
+    Scans for .py files and attempts to import each as a module. Looks for
+    a 'Plugin' class in each module and instantiates it if found.
+
+    Features:
+    - Automatic dependency installation for missing imports (via pip/pipx)
+    - Compatibility layer for import paths (plugins vs mmrelay.plugins)
+    - Proper sys.path management for plugin directory imports
+    - Comprehensive error handling and logging
+
+    Skips files that don't define a Plugin class or have import errors
+    that can't be automatically resolved.
+    """
     plugins = []
     if os.path.isdir(directory):
         for root, _dirs, files in os.walk(directory):
@@ -617,6 +660,26 @@ def load_plugins_from_directory(directory, recursive=False):
 
 
 def load_plugins(passed_config=None):
+    """Load and initialize all active plugins based on configuration.
+
+    Args:
+        passed_config (dict, optional): Configuration dictionary to use.
+                                       If None, uses global config variable.
+
+    Returns:
+        list: List of active plugin instances sorted by priority
+
+    This is the main plugin loading function that:
+    - Loads core plugins from mmrelay.plugins package
+    - Processes custom plugins from ~/.mmrelay/plugins/custom and plugins/custom
+    - Downloads and loads community plugins from configured Git repositories
+    - Filters plugins based on active status in configuration
+    - Sorts active plugins by priority and calls their start() method
+    - Sets up proper plugin configuration and channel mapping
+
+    Only plugins explicitly marked as active=true in config are loaded.
+    Custom and community plugins are cloned/updated automatically.
+    """
     global sorted_active_plugins
     global plugins_loaded
     global config

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/base_plugin.py

@@ -20,6 +20,27 @@ config = None
 
 
 class BasePlugin(ABC):
+    """Abstract base class for all mmrelay plugins.
+
+    Provides common functionality for plugin development including:
+    - Configuration management and validation
+    - Database storage for plugin-specific data
+    - Channel and direct message handling
+    - Matrix message sending capabilities
+    - Scheduling support for background tasks
+    - Command matching and routing
+
+    Attributes:
+        plugin_name (str): Unique identifier for the plugin
+        max_data_rows_per_node (int): Maximum data rows stored per node (default: 100)
+        priority (int): Plugin execution priority (lower = higher priority, default: 10)
+
+    Subclasses must:
+    - Set plugin_name as a class attribute
+    - Implement handle_meshtastic_message() and handle_room_message()
+    - Optionally override other methods for custom behavior
+    """
+
     # Class-level default attributes
     plugin_name = None  # Must be overridden in subclasses
     max_data_rows_per_node = 100
@@ -27,27 +48,53 @@ class BasePlugin(ABC):
 
     @property
     def description(self):
+        """Get the plugin description for help text.
+
+        Returns:
+            str: Human-readable description of plugin functionality
+
+        Override this property in subclasses to provide meaningful help text
+        that will be displayed by the help plugin.
+        """
         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.
+    def __init__(self, plugin_name=None) -> None:
+        """Initialize the plugin with configuration and logging.
 
+        Args:
+            plugin_name (str, optional): Plugin name override. If not provided,
+                                       uses class-level plugin_name attribute.
+
+        Raises:
+            ValueError: If plugin_name is not set via parameter or class attribute
+
+        Sets up:
+        - Plugin-specific logger
+        - Configuration from global config
+        - Channel mapping and validation
+        - Response delay settings
+        """
+        # Allow plugin_name to be passed as a parameter for simpler initialization
+        # This maintains backward compatibility while providing a cleaner API
         super().__init__()
 
-        # Verify plugin_name is properly defined
+        # If plugin_name is provided as a parameter, use it
+        if plugin_name is not None:
+            self.plugin_name = plugin_name
+
+        # For backward compatibility: if plugin_name is not provided as a parameter,
+        # check if it's set as an instance attribute (old way) or use the class attribute
         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__()"
-            )
+            # Try to get the class-level plugin_name
+            class_plugin_name = getattr(self.__class__, "plugin_name", None)
+            if class_plugin_name is not None:
+                self.plugin_name = class_plugin_name
+            else:
+                raise ValueError(
+                    f"{self.__class__.__name__} is missing plugin_name definition. "
+                    f"Either set class.plugin_name, pass plugin_name to __init__, "
+                    f"or set self.plugin_name before calling super().__init__()"
+                )
 
         self.logger = get_logger(f"Plugin:{self.plugin_name}")
         self.config = {"active": False}
@@ -66,6 +113,8 @@ class BasePlugin(ABC):
                 room.get("meshtastic_channel")
                 for room in config.get("matrix_rooms", [])
             ]
+        else:
+            self.mapped_channels = []
 
         # Get the channels specified for this plugin, or default to all mapped channels
         self.channels = self.config.get("channels", self.mapped_channels)
@@ -91,6 +140,19 @@ class BasePlugin(ABC):
             )
 
     def start(self):
+        """Start the plugin and set up scheduled tasks if configured.
+
+        Called automatically when the plugin is loaded. Checks plugin configuration
+        for scheduling settings and sets up background jobs accordingly.
+
+        Supported schedule formats in config:
+        - schedule.hours + schedule.at: Run every N hours at specific time
+        - schedule.minutes + schedule.at: Run every N minutes at specific time
+        - schedule.hours: Run every N hours
+        - schedule.minutes: Run every N minutes
+
+        Creates a daemon thread to run the scheduler if any schedule is configured.
+        """
         if "schedule" not in self.config or (
             "at" not in self.config["schedule"]
             and "hours" not in self.config["schedule"]
@@ -132,9 +194,27 @@ class BasePlugin(ABC):
 
     # trunk-ignore(ruff/B027)
     def background_job(self):
+        """Background task executed on schedule.
+
+        Override this method in subclasses to implement scheduled functionality.
+        Called automatically based on schedule configuration in start().
+
+        Default implementation does nothing.
+        """
         pass  # Implement in subclass if needed
 
     def strip_raw(self, data):
+        """Recursively remove 'raw' keys from data structures.
+
+        Args:
+            data: Data structure (dict, list, or other) to clean
+
+        Returns:
+            Cleaned data structure with 'raw' keys removed
+
+        Useful for cleaning packet data before logging or storage to remove
+        binary protobuf data that's not human-readable.
+        """
         if isinstance(data, dict):
             data.pop("raw", None)
             for k, v in data.items():
@@ -144,19 +224,59 @@ class BasePlugin(ABC):
         return data
 
     def get_response_delay(self):
+        """Get the configured response delay for meshtastic messages.
+
+        Returns:
+            int: Delay in seconds before sending responses (default: 3)
+
+        Used to prevent message flooding and ensure proper radio etiquette.
+        Delay is configured via meshtastic.plugin_response_delay in config.
+        """
         return self.response_delay
 
-    # Modified method to accept is_direct_message parameter
     def is_channel_enabled(self, channel, is_direct_message=False):
+        """Check if the plugin should respond on a specific channel.
+
+        Args:
+            channel: Channel identifier to check
+            is_direct_message (bool): Whether this is a direct message
+
+        Returns:
+            bool: True if plugin should respond, False otherwise
+
+        Direct messages always return True if the plugin is active.
+        For channel messages, checks if channel is in plugin's configured channels list.
+        """
         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):
+        """Get list of Matrix commands this plugin responds to.
+
+        Returns:
+            list: List of command strings (without ! prefix)
+
+        Default implementation returns [plugin_name]. Override to provide
+        custom commands or multiple command aliases.
+        """
         return [self.plugin_name]
 
     async def send_matrix_message(self, room_id, message, formatted=True):
+        """Send a message to a Matrix room.
+
+        Args:
+            room_id (str): Matrix room identifier
+            message (str): Message content to send
+            formatted (bool): Whether to send as formatted HTML (default: True)
+
+        Returns:
+            dict: Response from Matrix API room_send
+
+        Connects to Matrix using matrix_utils and sends a room message
+        with optional HTML formatting via markdown.
+        """
         from mmrelay.matrix_utils import connect_matrix
 
         matrix_client = await connect_matrix()
@@ -173,9 +293,26 @@ class BasePlugin(ABC):
         )
 
     def get_mesh_commands(self):
+        """Get list of mesh/radio commands this plugin responds to.
+
+        Returns:
+            list: List of command strings (without ! prefix)
+
+        Default implementation returns empty list. Override to handle
+        commands sent over the mesh radio network.
+        """
         return []
 
     def store_node_data(self, meshtastic_id, node_data):
+        """Store data for a specific node, appending to existing data.
+
+        Args:
+            meshtastic_id (str): Node identifier
+            node_data: Data to store (single item or list)
+
+        Retrieves existing data, appends new data, trims to max_data_rows_per_node,
+        and stores back to database. Use for accumulating time-series data.
+        """
         data = self.get_node_data(meshtastic_id=meshtastic_id)
         data = data[-self.max_data_rows_per_node :]
         if isinstance(node_data, list):
@@ -185,21 +322,56 @@ class BasePlugin(ABC):
         store_plugin_data(self.plugin_name, meshtastic_id, data)
 
     def set_node_data(self, meshtastic_id, node_data):
+        """Replace all data for a specific node.
+
+        Args:
+            meshtastic_id (str): Node identifier
+            node_data: Data to store (replaces existing data)
+
+        Completely replaces existing data for the node, trimming to
+        max_data_rows_per_node if needed. Use when you want to reset
+        or completely replace a node's 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):
+        """Delete all stored data for a specific node.
+
+        Args:
+            meshtastic_id (str): Node identifier
+
+        Returns:
+            bool: True if deletion succeeded, False otherwise
+        """
         return delete_plugin_data(self.plugin_name, meshtastic_id)
 
     def get_node_data(self, meshtastic_id):
+        """Retrieve stored data for a specific node.
+
+        Args:
+            meshtastic_id (str): Node identifier
+
+        Returns:
+            list: Stored data for the node (JSON deserialized)
+        """
         return get_plugin_data_for_node(self.plugin_name, meshtastic_id)
 
     def get_data(self):
+        """Retrieve all stored data for this plugin across all nodes.
+
+        Returns:
+            list: List of tuples containing raw data entries
+
+        Returns raw data without JSON deserialization. Use get_node_data()
+        for individual node data that's automatically deserialized.
+        """
         return get_plugin_data(self.plugin_name)
 
     def get_plugin_data_dir(self, subdir=None):
         """
         Returns the directory for storing plugin-specific data files.
+
         Creates the directory if it doesn't exist.
 
         Args:
@@ -225,6 +397,17 @@ class BasePlugin(ABC):
         return plugin_dir
 
     def matches(self, event):
+        """Check if a Matrix event matches this plugin's commands.
+
+        Args:
+            event: Matrix room event to check
+
+        Returns:
+            bool: True if event matches plugin commands, False otherwise
+
+        Uses bot_command() utility to check if the event contains any of
+        the plugin's matrix commands with proper bot command syntax.
+        """
         from mmrelay.matrix_utils import bot_command
 
         # Pass the entire event to bot_command

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/debug_plugin.py

@@ -2,6 +2,19 @@ from mmrelay.plugins.base_plugin import BasePlugin
 
 
 class Plugin(BasePlugin):
+    """Debug plugin for logging packet information.
+
+    A low-priority plugin that logs all received meshtastic packets
+    for debugging and development purposes. Strips raw binary data
+    before logging to keep output readable.
+
+    Configuration:
+        priority: 1 (runs first, before other plugins)
+
+    Never intercepts messages (always returns False) so other plugins
+    can still process the same packets.
+    """
+
     plugin_name = "debug"
     priority = 1
 

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/drop_plugin.py

@@ -10,9 +10,8 @@ class Plugin(BasePlugin):
     plugin_name = "drop"
     special_node = "!NODE_MSGS!"
 
-    def __init__(self):
-        self.plugin_name = "drop"
-        super().__init__()
+    # No __init__ method needed with the simplified plugin system
+    # The BasePlugin will automatically use the class-level plugin_name
 
     def get_position(self, meshtastic_client, node_id):
         for _node, info in meshtastic_client.nodes.items():

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/help_plugin.py

@@ -5,14 +5,28 @@ from mmrelay.plugins.base_plugin import BasePlugin
 
 
 class Plugin(BasePlugin):
-    plugin_name = "help"
+    """Help command plugin for listing available commands.
+
+    Provides users with information about available relay commands
+    and plugin functionality.
+
+    Commands:
+        !help: List all available commands
+        !help <command>: Show detailed help for a specific command
+
+    Dynamically discovers available commands from all loaded plugins
+    and their descriptions.
+    """
 
-    def __init__(self):
-        self.plugin_name = "help"
-        super().__init__()
+    plugin_name = "help"
 
     @property
     def description(self):
+        """Get plugin description.
+
+        Returns:
+            str: Description of help functionality
+        """
         return "List supported relay commands"
 
     async def handle_meshtastic_message(
@@ -21,9 +35,19 @@ class Plugin(BasePlugin):
         return False
 
     def get_matrix_commands(self):
+        """Get Matrix commands handled by this plugin.
+
+        Returns:
+            list: List containing the help command
+        """
         return [self.plugin_name]
 
     def get_mesh_commands(self):
+        """Get mesh commands handled by this plugin.
+
+        Returns:
+            list: Empty list (help only works via Matrix)
+        """
         return []
 
     async def handle_room_message(self, room, event, full_message):

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/map_plugin.py

@@ -156,6 +156,19 @@ class TextLabel(staticmaps.Object):
 
 
 def anonymize_location(lat, lon, radius=1000):
+    """Add random offset to GPS coordinates for privacy protection.
+
+    Args:
+        lat (float): Original latitude
+        lon (float): Original longitude
+        radius (int): Maximum offset distance in meters (default: 1000)
+
+    Returns:
+        tuple: (new_lat, new_lon) with random offset applied
+
+    Adds random offset within specified radius to obscure exact locations
+    while maintaining general geographic area for mapping purposes.
+    """
     # Generate random offsets for latitude and longitude
     lat_offset = random.uniform(-radius / 111320, radius / 111320)
     lon_offset = random.uniform(
@@ -233,11 +246,28 @@ async def send_image(client: AsyncClient, room_id: str, image: Image.Image):
 
 
 class Plugin(BasePlugin):
+    """Static map generation plugin for mesh node locations.
+
+    Generates static maps showing positions of mesh nodes with labeled markers.
+    Supports customizable zoom levels, image sizes, and privacy features.
+
+    Commands:
+        !map: Generate map with default settings
+        !map zoom=N: Set zoom level (0-30)
+        !map size=W,H: Set image dimensions (max 1000x1000)
+
+    Configuration:
+        zoom (int): Default zoom level (default: 8)
+        image_width/image_height (int): Default image size (default: 1000x1000)
+        anonymize (bool): Whether to offset coordinates for privacy (default: true)
+        radius (int): Anonymization offset radius in meters (default: 1000)
+
+    Uploads generated maps as images to Matrix rooms.
+    """
     plugin_name = "map"
 
-    def __init__(self):
-        self.plugin_name = "map"
-        super().__init__()
+    # No __init__ method needed with the simplified plugin system
+    # The BasePlugin will automatically use the class-level plugin_name
 
     @property
     def description(self):

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/mesh_relay_plugin.py

@@ -1,3 +1,5 @@
+# Note: This plugin was experimental and is not functional.
+
 import base64
 import json
 import re
@@ -8,12 +10,36 @@ from mmrelay.plugins.base_plugin import BasePlugin, config
 
 
 class Plugin(BasePlugin):
+    """Core mesh-to-Matrix relay plugin.
+
+    Handles bidirectional message relay between Meshtastic mesh network
+    and Matrix chat rooms. Processes radio packets and forwards them
+    to configured Matrix rooms, and vice versa.
+
+    This plugin is fundamental to the relay's core functionality and
+    typically runs with high priority to ensure messages are properly
+    bridged between the two networks.
+
+    Configuration:
+        max_data_rows_per_node: 50 (reduced storage for performance)
+    """
+
     plugin_name = "mesh_relay"
     max_data_rows_per_node = 50
 
     def normalize(self, dict_obj):
-        """
-        Packets are either a dict, string dict or string
+        """Normalize packet data to consistent dictionary format.
+
+        Args:
+            dict_obj: Packet data (dict, JSON string, or plain string)
+
+        Returns:
+            dict: Normalized packet dictionary with raw data stripped
+
+        Handles various packet formats:
+        - Dict objects (passed through)
+        - JSON strings (parsed)
+        - Plain strings (wrapped in TEXT_MESSAGE_APP format)
         """
         if not isinstance(dict_obj, dict):
             try:
@@ -24,6 +50,17 @@ class Plugin(BasePlugin):
         return self.strip_raw(dict_obj)
 
     def process(self, packet):
+        """Process and prepare packet data for relay.
+
+        Args:
+            packet: Raw packet data to process
+
+        Returns:
+            dict: Processed packet with base64-encoded binary payloads
+
+        Normalizes packet format and encodes binary payloads as base64
+        for JSON serialization and Matrix transmission.
+        """
         packet = self.normalize(packet)
 
         if "decoded" in packet and "payload" in packet["decoded"]:
@@ -35,14 +72,39 @@ class Plugin(BasePlugin):
         return packet
 
     def get_matrix_commands(self):
+        """Get Matrix commands handled by this plugin.
+
+        Returns:
+            list: Empty list (this plugin handles all traffic, not specific commands)
+        """
         return []
 
     def get_mesh_commands(self):
+        """Get mesh commands handled by this plugin.
+
+        Returns:
+            list: Empty list (this plugin handles all traffic, not specific commands)
+        """
         return []
 
     async def handle_meshtastic_message(
         self, packet, formatted_message, longname, meshnet_name
     ):
+        """Handle incoming meshtastic message and relay to Matrix.
+
+        Args:
+            packet: Raw packet data (dict or JSON) to relay
+            formatted_message (str): Human-readable message extracted from packet
+            longname (str): Long name of the sender node
+            meshnet_name (str): Name of the mesh network
+
+        Returns:
+            bool: Always returns False to allow other plugins to process the same packet
+
+        Processes the packet by normalizing and preparing it, connects to the Matrix client,
+        checks if the meshtastic channel is mapped to a Matrix room based on config,
+        and sends the packet to the appropriate Matrix room.
+        """
         from mmrelay.matrix_utils import connect_matrix
 
         packet = self.process(packet)
@@ -80,6 +142,17 @@ class Plugin(BasePlugin):
         return False
 
     def matches(self, event):
+        """Check if Matrix event is a relayed radio packet.
+
+        Args:
+            event: Matrix room event object
+
+        Returns:
+            bool: True if event contains embedded meshtastic packet JSON
+
+        Identifies Matrix messages that contain embedded meshtastic packet
+        data by matching the default relay message format "Processed <portnum> radio packet".
+        """
         # Check for the presence of necessary keys in the event
         content = event.source.get("content", {})
         body = content.get("body", "")
@@ -90,6 +163,20 @@ class Plugin(BasePlugin):
         return False
 
     async def handle_room_message(self, room, event, full_message):
+        """Handle incoming Matrix room message and relay to meshtastic mesh.
+
+        Args:
+            room: Matrix Room object where message was received
+            event: Matrix room event containing the message
+            full_message (str): Raw message body text
+
+        Returns:
+            bool: True if packet relaying succeeded, False otherwise
+
+        Checks if the Matrix event matches the expected embedded packet format,
+        retrieves the packet JSON, decodes it, reconstructs a MeshPacket,
+        connects to the meshtastic client, and sends the packet via the radio.
+        """
         # Use the event for matching instead of full_message
         if not self.matches(event):
             return False

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/ping_plugin.py

@@ -17,9 +17,8 @@ class Plugin(BasePlugin):
     plugin_name = "ping"
     punctuation = string.punctuation
 
-    def __init__(self):
-        self.plugin_name = "ping"
-        super().__init__()
+    # No __init__ method needed with the simplified plugin system
+    # The BasePlugin will automatically use the class-level plugin_name
 
     @property
     def description(self):

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay/plugins/weather_plugin.py

@@ -9,9 +9,8 @@ from mmrelay.plugins.base_plugin import BasePlugin
 class Plugin(BasePlugin):
     plugin_name = "weather"
 
-    def __init__(self):
-        self.plugin_name = "weather"
-        super().__init__()
+    # No __init__ method needed with the simplified plugin system
+    # The BasePlugin will automatically use the class-level plugin_name
 
     @property
     def description(self):

{mmrelay-1.0.7 → mmrelay-1.0.9/src/mmrelay.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.0.7
+Version: 1.0.9
 Summary: Bridge between Meshtastic mesh networks and Matrix chat rooms
 Home-page: https://github.com/geoffwhittington/meshtastic-matrix-relay
 Author: Geoff Whittington, Jeremiah K., and contributors
@@ -22,72 +22,45 @@ Requires-Dist: requests==2.32.3
 Requires-Dist: markdown==3.8
 Requires-Dist: haversine==2.9.0
 Requires-Dist: schedule==1.2.2
-Requires-Dist: platformdirs==4.3.7
+Requires-Dist: platformdirs==4.3.8
 Requires-Dist: py-staticmaps>=0.4.0
 Requires-Dist: rich==14.0.0
-Requires-Dist: setuptools==80.3.1
+Requires-Dist: setuptools==80.9.0
 Dynamic: license-file
 
 # M<>M Relay
 
-## ✨ Version 1.0 Released! ✨
+## (Meshtastic <=> Matrix Relay)
 
-**We're excited to announce MMRelay v1.0 with improved packaging, standardized directories, and enhanced CLI!**
+A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
 
-**Existing users:** Version 1.0 requires a few quick migration steps:
+## Documentation
 
-1. Follow the [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) guide for a smooth transition
-2. Move your configuration to the new standard location (`~/.mmrelay/config.yaml`)
-3. See [ANNOUNCEMENT.md](ANNOUNCEMENT.md) for all the exciting new features
+Visit our [Wiki](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
 
-Not ready to upgrade yet? No problem! Run `git checkout 0.10.1` to continue using the previous version.
-
-## (Meshtastic <=> Matrix Relay)
-
-A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
+- [Installation Instructions](docs/INSTRUCTIONS.md) - Setup and configuration guide
+- [v1.0 Release Announcement](docs/ANNOUNCEMENT.md) - New changes in v1.0
+- [Upgrade Guide](docs/UPGRADE_TO_V1.md) - Migration guidance for existing users
 
 ---
 
-## Getting Started
+## Quick Start
 
 MMRelay runs on Linux, macOS, and Windows.
 
-### Quick Installation
-
 ```bash
 # Install using pipx for isolated installation (recommended)
 pipx install mmrelay
 
-# Pip will also work if you prefer
-pip install mmrelay
-```
-
-For pipx installation instructions, see: [pipx installation guide](https://pipx.pypa.io/stable/installation/#on-linux)
+# Generate a sample configuration file & then edit it
+mmrelay --generate-config
 
-### Resources
-
-- **New Users**: See [INSTRUCTIONS.md](INSTRUCTIONS.md) for setup and configuration
-- **Existing Users**: See [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) for migration guidance
-- **Configuration**: Review [sample_config.yaml](src/mmrelay/tools/sample_config.yaml) for examples
-
-### Command-Line Options
-
-```bash
-usage: mmrelay [-h] [--config CONFIG] [--data-dir DATA_DIR] [--log-level {error,warning,info,debug}] [--logfile LOGFILE] [--version] [--generate-config] [--install-service] [--check-config]
-
-Options:
-  -h, --help            Show this help message and exit
-  --config CONFIG       Path to config file
-  --data-dir DATA_DIR   Base directory for all data (logs, database, plugins)
-  --log-level {error,warning,info,debug}
-                        Set logging level
-  --logfile LOGFILE     Path to log file (can be overridden by --data-dir)
-  --version             Show version and exit
-  --generate-config     Generate a sample config.yaml file
-  --install-service     Install or update the systemd user service
-  --check-config        Check if the configuration file is valid
+# Start the relay (without --install-service to run manually)
+mmrelay --install-service
 ```
 
+For detailed installation and configuration instructions, see the [Installation Guide](docs/INSTRUCTIONS.md).
+
 ---
 
 ## Features
@@ -133,7 +106,12 @@ See the full list of core plugins [here](https://github.com/geoffwhittington/mes
 
 ### Community & Custom Plugins
 
-It is possible to create custom plugins and share them with the community. Check [example_plugins/README.md](https://github.com/geoffwhittington/meshtastic-matrix-relay/tree/main/example_plugins) and the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide).
+MMRelay's plugin system allows you to extend functionality in two ways:
+
+- **Custom Plugins**: Create personal plugins for your own use, stored in `~/.mmrelay/plugins/custom/`
+- **Community Plugins**: Share your creations with others or use plugins developed by the community
+
+Check the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide) in our wiki to get started.
 
 ✨️ Visit the [Community Plugins List](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
 
@@ -151,14 +129,12 @@ community-plugins:
 
 ### Plugin System
 
-MMRelay features a powerful plugin system with standardized locations:
+Plugins make it easy to extend functionality without modifying the core program. MMRelay features a powerful plugin system with standardized locations:
 
 - **Core Plugins**: Pre-installed with the package
 - **Custom Plugins**: Your own plugins in `~/.mmrelay/plugins/custom/`
 - **Community Plugins**: Third-party plugins in `~/.mmrelay/plugins/community/`
 
-Plugins make it easy to extend functionality without modifying the core code.
-
 ---
 
 ## Getting Started with Matrix

{mmrelay-1.0.7 → mmrelay-1.0.9}/src/mmrelay.egg-info/requires.txt

@@ -6,7 +6,7 @@ requests==2.32.3
 markdown==3.8
 haversine==2.9.0
 schedule==1.2.2
-platformdirs==4.3.7
+platformdirs==4.3.8
 py-staticmaps>=0.4.0
 rich==14.0.0
-setuptools==80.3.1
+setuptools==80.9.0