mmrelay 1.2.3__py3-none-any.whl → 1.2.4__py3-none-any.whl

mmrelay/__init__.py

@@ -2,4 +2,4 @@
 Meshtastic Matrix Relay - Bridge between Meshtastic mesh networks and Matrix chat rooms.
 """
 
-__version__ = "1.2.3"
+__version__ = "1.2.4"

mmrelay/cli.py

@@ -1524,15 +1524,15 @@ def handle_service_command(args):
 
 def _diagnose_config_paths(args):
     """
-    Print a diagnostic summary of resolved configuration file search paths and their directory accessibility.
-    
-    Computes the ordered list of candidate config file locations via get_config_paths(args) and prints each path with a short directory status icon:
+    Prints a diagnostic summary of resolved configuration file search paths and their directory accessibility.
+
+    Each candidate config path is printed with a status icon:
     - ✅ directory exists and is writable
     - ⚠️ directory exists but is not writable
     - ❌ directory does not exist
-    
+
     Parameters:
-        args (argparse.Namespace): CLI arguments used to determine the config search order (passed to get_config_paths).
+        args (argparse.Namespace): CLI arguments used to determine the ordered list of candidate config paths (passed to get_config_paths).
     """
     print("1. Testing configuration paths...")
     from mmrelay.config import get_config_paths
@@ -1586,19 +1586,15 @@ def _diagnose_sample_config_accessibility():
 
 def _diagnose_platform_specific(args):
     """
-    Run platform-specific diagnostic checks and report results.
-    
-    On Windows, attempts to import and run Windows-specific requirement checks and a
-    configuration-generation test, printing per-component statuses and any warnings.
-    On non-Windows platforms this reports that platform-specific tests are not
-    required.
-    
+    Run platform-specific diagnostic checks and print a concise report.
+
+    On Windows, executes Windows-specific requirement checks and a configuration-generation test using the provided CLI arguments; on non-Windows platforms, reports that platform-specific tests are not required.
+
     Parameters:
-        args (argparse.Namespace): CLI arguments passed through to the Windows
-            configuration-generation test (only used when running on Windows).
-    
+        args (argparse.Namespace): CLI arguments forwarded to the Windows configuration-generation test (used only when running on Windows).
+
     Returns:
-        bool: True if Windows checks were executed (running on Windows), False otherwise.
+        bool: `True` if Windows checks were executed (running on Windows), `False` otherwise.
     """
     print("3. Platform-specific diagnostics...")
     import sys
@@ -1721,15 +1717,15 @@ def _diagnose_minimal_config_template():
 
 def handle_config_diagnose(args):
     """
-    Run non-destructive diagnostics for the MMRelay configuration subsystem and print a human-readable report.
-    
-    Performs four checks without modifying user files: (1) resolves and reports candidate configuration file paths and their directory accessibility, (2) verifies availability of the packaged sample configuration, (3) runs platform-specific diagnostics (Windows checks when applicable), and (4) validates the built-in minimal YAML configuration template. Results and actionable guidance are written to stdout/stderr.
-    
+    Run a set of non-destructive diagnostics for the MMRelay configuration subsystem and print a concise, human-readable report.
+
+    Performs four checks without modifying user files: (1) resolves and reports candidate configuration file paths and their directory accessibility, (2) verifies availability and readability of the packaged sample configuration, (3) executes platform-specific diagnostics (Windows checks when applicable), and (4) validates the built-in minimal YAML configuration template. Results and actionable guidance are written to stdout/stderr; additional Windows-specific guidance may be printed to stderr on unexpected failures.
+
     Parameters:
-        args (argparse.Namespace): Parsed CLI arguments used to resolve configuration search paths and to control platform-specific checks.
-    
+        args (argparse.Namespace): Parsed CLI arguments used to determine configuration search paths and to control platform-specific diagnostic behavior.
+
     Returns:
-        int: Exit code (0 on success, 1 on failure). On failure an error summary is printed to stderr.
+        int: Exit code where `0` indicates diagnostics completed successfully and `1` indicates a failure occurred (an error summary is printed to stderr).
     """
     print("MMRelay Configuration System Diagnostics")
     print("=" * 40)

mmrelay/config.py

@@ -196,14 +196,12 @@ def get_log_dir():
 
 def get_e2ee_store_dir():
     """
-    Return the absolute path to the application's end-to-end-encryption (E2EE) data store directory, creating it if missing.
-    
-    On Linux and macOS this is "<base_dir>/store" where base_dir is returned by get_base_dir().
-    On Windows this is "<custom_data_dir>/store" when module-level custom_data_dir is set; otherwise it is
-    platformdirs.user_data_dir(APP_NAME, APP_AUTHOR)/store.
-    
+    Get the absolute path to the application's end-to-end encryption (E2EE) data store directory, creating it if necessary.
+
+    On Linux and macOS the directory is located under the application base directory; on Windows it uses the configured custom data directory when set, otherwise the platform-specific user data directory. The directory will be created if it does not exist.
+
     Returns:
-        str: Absolute path to the ensured store directory.
+        store_dir (str): Absolute path to the ensured E2EE store directory.
     """
     if sys.platform in ["linux", "darwin"]:
         # Use ~/.mmrelay/store/ for Linux and Mac

mmrelay/constants/queue.py

@@ -6,7 +6,10 @@ delays, size limits, and water marks for queue management.
 """
 
 # Message timing constants
-DEFAULT_MESSAGE_DELAY = 2.0  # Firmware-enforced minimum delay in seconds
+DEFAULT_MESSAGE_DELAY = (
+    2.5  # Set above the 2.0s firmware limit to prevent message dropping
+)
+MINIMUM_MESSAGE_DELAY = 2.1  # Minimum delay enforced to stay above firmware limit
 
 # Queue size management
 MAX_QUEUE_SIZE = 500

mmrelay/log_utils.py

@@ -69,14 +69,13 @@ _COMPONENT_LOGGERS = {
 
 def configure_component_debug_logging():
     """
-    Configure log levels for external component loggers based on config["logging"]["debug"].
+    Configure log levels and handlers for external component loggers based on config.
 
-    Reads per-component entries under `config["logging"]["debug"]` and applies one of:
-    - falsy or missing: silence the component by setting its loggers to CRITICAL+1
-    - boolean True: enable DEBUG for the component's loggers
-    - string: interpret as a logging level name (case-insensitive); invalid names fall back to DEBUG
+    Reads `config["logging"]["debug"]` and for each component:
+    - If enabled (True or a valid log level string), sets the component's loggers to the specified level and attaches the main application's handlers to them. This makes component logs appear in the console and log file.
+    - If disabled (falsy or missing), silences the component by setting its loggers to a level higher than CRITICAL.
 
-    This function mutates the levels of loggers listed in _COMPONENT_LOGGERS and runs only once per process; no-op if called again or if global `config` is None.
+    This function runs only once. It is not thread-safe and should be called early in the application startup, after the main logger is configured but before other modules are imported.
     """
     global _component_debug_configured, config
 
@@ -84,7 +83,22 @@ def configure_component_debug_logging():
     if _component_debug_configured or config is None:
         return
 
-    debug_config = config.get("logging", {}).get("debug", {})
+    # Get the main application logger and its handlers to attach to component loggers
+    main_logger = logging.getLogger(APP_DISPLAY_NAME)
+    main_handlers = main_logger.handlers
+    debug_settings = config.get("logging", {}).get("debug")
+
+    # Ensure debug_config is a dictionary, handling malformed configs gracefully
+    if isinstance(debug_settings, dict):
+        debug_config = debug_settings
+    else:
+        if debug_settings is not None:
+            main_logger.warning(
+                "Debug logging section is not a dictionary. "
+                "All component debug logging will be disabled. "
+                "Check your config.yaml debug section formatting."
+            )
+        debug_config = {}
 
     for component, loggers in _COMPONENT_LOGGERS.items():
         component_config = debug_config.get(component)
@@ -105,8 +119,15 @@ def configure_component_debug_logging():
                 # Invalid config, fall back to DEBUG
                 log_level = logging.DEBUG
 
+            # Configure all loggers for this component
             for logger_name in loggers:
-                logging.getLogger(logger_name).setLevel(log_level)
+                component_logger = logging.getLogger(logger_name)
+                component_logger.setLevel(log_level)
+                component_logger.propagate = False  # Prevent duplicate logging
+                # Attach main handlers to the component logger
+                for handler in main_handlers:
+                    if handler not in component_logger.handlers:
+                        component_logger.addHandler(handler)
         else:
             # Component debug is disabled - completely suppress external library logging
             # Use a level higher than CRITICAL to effectively disable all messages

mmrelay/main.py

@@ -73,9 +73,18 @@ def print_banner():
 
 async def main(config):
     """
-    Coordinates the main asynchronous relay loop between Meshtastic and Matrix clients.
+    Coordinate the asynchronous relay loop between Meshtastic and Matrix clients.
 
-    Initializes the database, loads plugins, starts the message queue, and establishes connections to both Meshtastic and Matrix. Joins configured Matrix rooms, registers event callbacks for message and membership events, and periodically updates node names from the Meshtastic network. Monitors connection health, manages the Matrix sync loop with reconnection and shutdown handling, and ensures graceful shutdown of all components. Optionally wipes the message map on startup and shutdown if configured.
+    Initializes the database and plugins, starts the message queue, connects to Meshtastic and Matrix, joins configured Matrix rooms, registers event callbacks, monitors connection health, runs the Matrix sync loop with automatic retries, and ensures an orderly shutdown of all components (including optional message map wiping on startup and shutdown).
+
+    Parameters:
+        config (dict): Application configuration mapping. Expected keys used by this function include:
+            - "matrix_rooms": list of room dicts with at least an "id" entry,
+            - "meshtastic": optional dict with "message_delay",
+            - "database" (preferred) or legacy "db": optional dict containing "msg_map" with "wipe_on_restart" boolean.
+
+    Raises:
+        ConnectionError: If connecting to Matrix fails and no Matrix client can be obtained.
     """
     # Extract Matrix configuration
     from typing import List
@@ -155,8 +164,8 @@ async def main(config):
     async def shutdown():
         """
         Signal the application to begin shutdown.
-        
-        Sets the Meshtastic shutdown flag and triggers the local shutdown event so any coroutines waiting on that event can start their cleanup. This coroutine only signals shutdown; it does not perform client shutdown or resource cleanup itself.
+
+        Set the Meshtastic shutdown flag and set the local shutdown event so any coroutines waiting on that event can start cleanup.
         """
         matrix_logger.info("Shutdown signal received. Closing down...")
         meshtastic_utils.shutting_down = True  # Set the shutting_down flag

mmrelay/matrix_utils.py

@@ -13,7 +13,6 @@ import time
 from typing import Any, Dict, Optional, Union
 from urllib.parse import urlparse
 
-import meshtastic.protobuf.portnums_pb2
 from nio import (
     AsyncClient,
     AsyncClientConfig,
@@ -789,16 +788,16 @@ def bot_command(command, event):
 
 async def connect_matrix(passed_config=None):
     """
-    Create and initialize a matrix-nio AsyncClient connected to the configured Matrix homeserver.
-    
-    Attempts credential selection in this order: credentials.json (preferred), automatic login using username/password from config (saved to credentials.json), then direct token values from config. Optionally enables End-to-End Encryption (E2EE) when configured and dependencies are available. Performs an initial full-state sync, resolves configured room aliases to room IDs, sets module-level connection state (matrix_client, bot_user_name, matrix_homeserver, matrix_rooms, matrix_access_token, bot_user_id) and returns the ready AsyncClient.
-    
+    Initialize and return a configured matrix-nio AsyncClient connected to the configured Matrix homeserver.
+
+    Creates or restores client credentials (prefers credentials.json, falls back to automatic login using username/password from config, then to direct tokens in config), optionally enables End-to-End Encryption when configured and dependencies are available, performs an initial full-state sync to populate rooms, resolves room aliases found in configuration, and sets module-level connection state used by other functions.
+
     Parameters:
-        passed_config (dict | None): Optional configuration to use for this connection attempt; if provided, it overrides the module-level config for this call.
-    
+        passed_config (dict | None): Optional configuration to use for this connection attempt; when provided it overrides the module-level config for this call.
+
     Returns:
-        AsyncClient | None: An initialized matrix-nio AsyncClient on success, or None if connection/credentials are unavailable.
-    
+        AsyncClient | None: A ready-to-use matrix-nio AsyncClient on success, or `None` if connection or credentials are unavailable.
+
     Raises:
         ValueError: If the required top-level "matrix_rooms" configuration is missing.
         ConnectionError: If the initial Matrix sync fails or times out.
@@ -2318,17 +2317,20 @@ async def send_reply_to_meshtastic(
     reply_id=None,
 ):
     """
-    Enqueue a Matrix reply to be sent over Meshtastic, either as a structured reply targeting an existing Meshtastic message or as a regular broadcast.
-    
-    If Meshtastic broadcasting is disabled this is a no-op. When storage_enabled is True the function will create a mapping entry (using event.event_id and room.room_id) and attach it to the queued message for later reply/reaction correlation. Failures are logged; the function does not raise exceptions.
-    
+    Enqueue a Matrix reply to be delivered over Meshtastic as either a structured reply or a regular broadcast.
+
+    If broadcasting is disabled this function does nothing. When storage_enabled is True, it constructs a mapping record that links the originating Matrix event to the Meshtastic message and attaches it to the queued message so replies and reactions can be correlated later. Errors are logged; the function does not raise.
+
     Parameters:
-        room_config (dict): Room-specific configuration — must include "meshtastic_channel" (integer channel index).
-        room: Matrix room object; room.room_id is used to build mapping metadata.
-        event: Matrix event object; event.event_id is used to build mapping metadata.
+        reply_message (str): Text payload already formatted for Meshtastic.
+        full_display_name (str): Sender display name used in queue descriptions and logs.
+        room_config (dict): Room-specific configuration; must contain "meshtastic_channel" (integer channel index).
+        room: Matrix room object; its room_id is used for mapping metadata.
+        event: Matrix event object; its event_id is used for mapping metadata.
+        text (str): Original Matrix message text used when building mapping metadata.
         storage_enabled (bool): If True, create and attach a message-mapping record to the queued Meshtastic message.
-        reply_id (int | None): If provided, send as a structured Meshtastic reply targeting this message ID; otherwise send a regular text broadcast.
-        local_meshnet_name (str | None): Name of the local meshnet used in mapping metadata.
+        local_meshnet_name (str | None): Local meshnet name included in mapping metadata when present.
+        reply_id (int | None): If provided, send as a structured Meshtastic reply targeting this Meshtastic message ID; otherwise send a regular broadcast.
     """
     loop = asyncio.get_running_loop()
     meshtastic_interface = await loop.run_in_executor(None, connect_meshtastic)
@@ -2433,22 +2435,26 @@ async def handle_matrix_reply(
     meshnet_name=None,
 ):
     """
-    Handle a Matrix reply by forwarding it to Meshtastic when the replied-to Matrix event maps to a Meshtastic message.
-    
-    If the Matrix event identified by reply_to_event_id has an associated Meshtastic mapping, this function formats a Meshtastic reply that preserves sender attribution and enqueues it referencing the original Meshtastic message ID. If no mapping exists, it returns False so normal Matrix processing can continue.
-    
+    Forward a Matrix reply to Meshtastic when the replied-to Matrix event maps to a Meshtastic message.
+
+    If the Matrix event identified by reply_to_event_id has an associated Meshtastic mapping, format a Meshtastic reply that preserves sender attribution and enqueue it referencing the original Meshtastic message ID. If no mapping exists, do nothing.
+
     Parameters:
+        room: Matrix room object where the reply originated.
+        event: Matrix event object representing the reply.
         reply_to_event_id (str): Matrix event ID being replied to; used to locate the Meshtastic mapping.
-        storage_enabled (bool): Whether message mappings/storage are enabled (affects created mapping behavior when sending).
-        local_meshnet_name (str): Local meshnet name used to determine formatting when replying across meshnets.
-        config (dict): Relay configuration passed to formatting routines.
-        mesh_text_override (str | None): Optional text to send instead of derived text.
+        text (str): The reply text from Matrix.
+        room_config (dict): Per-room relay configuration used when sending to Meshtastic.
+        storage_enabled (bool): Whether message mapping/storage is enabled.
+        local_meshnet_name (str): Local meshnet name used to determine cross-meshnet formatting.
+        config (dict): Global relay configuration passed to formatting routines.
+        mesh_text_override (str | None): Optional override text to send instead of the derived text.
         longname (str | None): Sender long display name used for prefixing.
         shortname (str | None): Sender short display name used for prefixing.
         meshnet_name (str | None): Remote meshnet name associated with the original mapping, if any.
-    
+
     Returns:
-        bool: True if a mapping was found and the reply was queued to Meshtastic; False if no mapping existed and nothing was sent.
+        bool: `True` if a mapping was found and the reply was queued to Meshtastic, `False` otherwise.
     """
     # Look up the original message in the message map
     loop = asyncio.get_running_loop()
@@ -2545,23 +2551,14 @@ async def on_room_message(
     ],
 ) -> None:
     """
-    Handle an incoming Matrix room event and, when applicable, relay it to Meshtastic.
+    Handle an incoming Matrix room event and relay it to Meshtastic when applicable.
 
-    Processes text, notice, emote, and reaction events (including replies and messages relayed from other meshnets) for configured rooms. Behavior highlights:
-    - Ignores events from before the bot started and events sent by the bot itself.
-    - Uses per-room configuration and global interaction settings to decide whether to process or ignore the event.
-    - Routes reactions back to the originating Meshtastic message when a mapping exists (supports local and remote-meshnet reaction handling).
-    - Bridges Matrix replies to Meshtastic replies when a corresponding Meshtastic mapping is found and replies are enabled.
-    - Relays regular Matrix messages to Meshtastic using configured prefix/truncation rules; handles special detection-sensor port forwarding.
-    - Integrates with the plugin system; plugins may consume or modify messages. Messages identified as bot commands are not relayed to Meshtastic.
+    Processes text, notice, emote, and reaction events for configured rooms: ignores events from before the bot started and events sent by the bot itself; respects per-room configuration and global interaction settings; routes reactions back to the originating Meshtastic message when a mapping exists (including forwarding remote-meshnet emote reactions as radio text); bridges Matrix replies to Meshtastic replies when a corresponding mapping is found and replies are enabled; relays regular Matrix messages to Meshtastic using configured prefix and truncation rules; and honours detection-sensor forwarding when enabled. Integrates with the plugin system and treats recognized bot commands as non-relayed.
 
     Side effects:
     - May enqueue Meshtastic send operations (text or data) via the internal queue.
-    - May read/write persistent message mappings to support reaction/reply bridging.
-    - May call Matrix APIs (e.g., to fetch display names).
-
-    Returns:
-    - None
+    - May read and write persistent message mappings to support reply/reaction bridging.
+    - May call Matrix APIs (e.g., to fetch display names) and connect to Meshtastic.
     """
     # DEBUG: Log all Matrix message events to trace reception
     logger.debug(
@@ -2971,6 +2968,9 @@ async def on_room_message(
                 if get_meshtastic_config_value(
                     config, "detection_sensor", DEFAULT_DETECTION_SENSOR
                 ):
+                    # Import meshtastic protobuf only when needed to delay logger creation
+                    import meshtastic.protobuf.portnums_pb2
+
                     success = queue_message(
                         meshtastic_interface.sendData,
                         data=full_message.encode("utf-8"),

mmrelay/message_queue.py

@@ -473,11 +473,12 @@ class MessageQueue:
 
     def _should_send_message(self) -> bool:
         """
-        Return True when it is safe to send a Meshtastic message; otherwise False.
-        
-        Performs runtime checks: verifies the module-level `reconnecting` flag is False, a Meshtastic client object exists, and — if the client exposes `is_connected` (callable or boolean) — that it reports connected. If any check fails the method returns False.
-        
-        If importing the Meshtastic utilities raises ImportError, the queue will be stopped asynchronously and the method returns False.
+        Check whether the queue may send a Meshtastic message.
+
+        Performs runtime checks: returns True only if the reconnection flag is not set, a Meshtastic client object exists, and—if the client exposes `is_connected`—that check indicates the client is connected. If importing Meshtastic utilities raises ImportError, a critical log is emitted and the queue is stopped asynchronously.
+
+        Returns:
+            `True` if not reconnecting, a Meshtastic client exists, and the client is connected when checkable; `False` otherwise.
         """
         # Import here to avoid circular imports
         try:
@@ -517,17 +518,17 @@ class MessageQueue:
 
     def _handle_message_mapping(self, result, mapping_info):
         """
-        Persist a sent mesh-to-Matrix message mapping and optionally prune old mappings.
-        
-        If mapping_info contains 'matrix_event_id', 'room_id', and 'text', this stores a mapping using result.id as the mesh message id. If 'msgs_to_keep' is present and > 0 it prunes older mappings to retain that many entries; otherwise DEFAULT_MSGS_TO_KEEP is used.
-        
+        Persist a mapping from a sent Meshtastic message to a Matrix event and optionally prune old mappings.
+
+        Stores a mapping when `mapping_info` contains `matrix_event_id`, `room_id`, and `text`, using `result.id` as the Meshtastic message id. If `mapping_info["msgs_to_keep"]` is present and greater than 0, prunes older mappings to retain that many entries; otherwise uses DEFAULT_MSGS_TO_KEEP.
+
         Parameters:
-            result: An object returned by the send function with an `id` attribute (the mesh message id).
+            result: An object returned by the send function with an `id` attribute representing the Meshtastic message id.
             mapping_info (dict): Mapping details. Relevant keys:
                 - matrix_event_id (str): Matrix event ID to map to.
                 - room_id (str): Matrix room ID where the event was sent.
                 - text (str): Message text to associate with the mapping.
-                - meshnet (optional): Mesh network identifier passed through to storage.
+                - meshnet (optional): Mesh network identifier to pass to storage.
                 - msgs_to_keep (optional, int): Number of mappings to retain when pruning.
         """
         try:

mmrelay/plugins/base_plugin.py

@@ -11,7 +11,7 @@ from mmrelay.constants.database import (
     DEFAULT_MAX_DATA_ROWS_PER_NODE_BASE,
     DEFAULT_TEXT_TRUNCATION_LENGTH,
 )
-from mmrelay.constants.queue import DEFAULT_MESSAGE_DELAY
+from mmrelay.constants.queue import DEFAULT_MESSAGE_DELAY, MINIMUM_MESSAGE_DELAY
 from mmrelay.db_utils import (
     delete_plugin_data,
     get_plugin_data,
@@ -77,7 +77,7 @@ class BasePlugin(ABC):
         Raises:
             ValueError: If the plugin name is not set via parameter or class attribute.
 
-        Loads plugin-specific configuration from the global config, validates assigned channels, and determines the response delay, enforcing a minimum of 2.0 seconds. Logs a warning if deprecated configuration options are used or if channels are not mapped.
+        Loads plugin-specific configuration from the global config, validates assigned channels, and determines the response delay, enforcing a minimum of 2.1 seconds. Logs a warning if deprecated configuration options are used or if channels are not mapped.
         """
         # Allow plugin_name to be passed as a parameter for simpler initialization
         # This maintains backward compatibility while providing a cleaner API
@@ -174,12 +174,12 @@ class BasePlugin(ABC):
 
             if delay is not None:
                 self.response_delay = delay
-                # Enforce minimum delay of 2 seconds due to firmware constraints
-                if self.response_delay < 2.0:
+                # Enforce minimum delay above firmware limit to prevent message dropping
+                if self.response_delay < MINIMUM_MESSAGE_DELAY:
                     self.logger.warning(
-                        f"{delay_key} of {self.response_delay}s is below minimum of 2.0s (firmware constraint). Using 2.0s."
+                        f"{delay_key} of {self.response_delay}s is below minimum of {MINIMUM_MESSAGE_DELAY}s (above firmware limit). Using {MINIMUM_MESSAGE_DELAY}s."
                     )
-                    self.response_delay = 2.0
+                    self.response_delay = MINIMUM_MESSAGE_DELAY
 
     def start(self):
         """
@@ -261,7 +261,7 @@ class BasePlugin(ABC):
         """
         Return the configured delay in seconds before sending a Meshtastic response.
 
-        The delay is determined by the `meshtastic.message_delay` configuration option, defaulting to 2.2 seconds with a minimum of 2.0 seconds. The deprecated `plugin_response_delay` option is also supported for backward compatibility.
+        The delay is determined by the `meshtastic.message_delay` configuration option, defaulting to 2.5 seconds with a minimum of 2.1 seconds. The deprecated `plugin_response_delay` option is also supported for backward compatibility.
 
         Returns:
             float: The response delay in seconds.

mmrelay/plugins/mesh_relay_plugin.py

@@ -122,7 +122,7 @@ class Plugin(BasePlugin):
 
         if not channel_mapped:
             self.logger.debug(f"Skipping message from unmapped channel {channel}")
-            return None
+            return False
 
         await matrix_client.room_send(
             room_id=room["id"],
@@ -135,21 +135,19 @@ class Plugin(BasePlugin):
             },
         )
 
-        return None
+        return True
 
     def matches(self, event):
         """
-        Return True if the Matrix event's content body matches the bridged-packet marker.
-        
-        Checks event.source["content"]["body"] (when it is a string) against the anchored
-        pattern "^Processed (.+) radio packet$". Returns True when the body matches this
-        pattern, otherwise False.
-        
+        Determine whether a Matrix event's message body contains the bridged-packet marker.
+
+        Checks event.source["content"]["body"] (when it is a string) against the anchored pattern `^Processed (.+) radio packet$`.
+
         Parameters:
-            event: Matrix event object whose .source mapping is expected to contain a "content" dict.
-        
+            event: Matrix event object whose `.source` mapping is expected to contain a `"content"` dict with a `"body"` string.
+
         Returns:
-            bool: True if the content body matches the relayed-packet pattern, False otherwise.
+            True if the content body matches `^Processed (.+) radio packet$`, False otherwise.
         """
         # Check for the presence of necessary keys in the event
         content = event.source.get("content", {})
@@ -182,7 +180,7 @@ class Plugin(BasePlugin):
         """
         # Use the event for matching instead of full_message
         if not self.matches(event):
-            return None
+            return False
 
         channel = None
         if config is not None:
@@ -193,18 +191,18 @@ class Plugin(BasePlugin):
 
         if channel is None:
             self.logger.debug(f"Skipping message from unmapped channel {channel}")
-            return None
+            return False
 
         packet_json = event.source["content"].get("meshtastic_packet")
         if not packet_json:
             self.logger.debug("Missing embedded packet")
-            return None
+            return False
 
         try:
             packet = json.loads(packet_json)
-        except (json.JSONDecodeError, TypeError) as e:
-            self.logger.exception(f"Error processing embedded packet: {e}")
-            return None
+        except (json.JSONDecodeError, TypeError):
+            self.logger.exception("Error processing embedded packet")
+            return False
 
         from mmrelay.meshtastic_utils import connect_meshtastic
 
@@ -221,4 +219,4 @@ class Plugin(BasePlugin):
         meshtastic_client._sendPacket(
             meshPacket=meshPacket, destinationId=packet["toId"]
         )
-        return None
+        return True

mmrelay/setup_utils.py

@@ -359,9 +359,9 @@ def is_service_active():
 def create_service_file():
     """
     Create or update the per-user systemd unit file for MMRelay.
-    
+
     Ensures the user systemd directory (~/.config/systemd/user) and the MMRelay logs directory (~/.mmrelay/logs) exist, obtains a service unit template using the module's template-loading fallbacks, substitutes known placeholders (working directory, packaged launcher, and config path), normalizes the Unit's ExecStart to the resolved MMRelay invocation (an mmrelay executable on PATH or a Python `-m mmrelay` fallback) while preserving any trailing arguments, and writes the resulting unit to ~/.config/systemd/user/mmrelay.service.
-    
+
     Returns:
         bool: True if the service file was written successfully; False if a template could not be obtained or writing the file failed.
     """

mmrelay/tools/sample-docker-compose-prebuilt.yaml

@@ -7,13 +7,24 @@ services:
     user: "${UID:-1000}:${GID:-1000}"
     environment:
       - TZ=UTC # Set timezone (PYTHONUNBUFFERED and MPLCONFIGDIR are set in Dockerfile)
+
     volumes:
       # Mount your config directory - create ~/.mmrelay/config.yaml first
       # See docs/DOCKER.md for setup instructions
-      # For SELinux systems (RHEL/CentOS/Fedora), add :Z flag to prevent permission denied errors
-      - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro,Z
-      - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data:Z
-      # For non-SELinux systems, you can use:
-      # - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro
-      # - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data
-      # Tip: For correct permissions and paths, ensure UID, GID, and MMRELAY_HOME are set in a .env file or exported
+      # For non-SELinux systems (most common):
+      - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro
+      - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data
+      # For SELinux systems (RHEL/CentOS/Fedora), add :Z flag to prevent permission denied errors:
+      # - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro,Z
+      # - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data:Z
+
+      # For BLE connections, uncomment these lines (Linux only):
+      # - /var/run/dbus:/var/run/dbus:ro
+
+    # For BLE connections, uncomment these options (Linux only). See DOCKER.md for alternatives.
+    # network_mode: host
+    # security_opt:
+    #   - apparmor=unconfined # Recommended for BLE to allow DBus communication
+    # privileged: true # Alternative if apparmor=unconfined is not acceptable
+
+    # Tip: For correct permissions and paths, ensure UID, GID, and MMRELAY_HOME are set in a .env file or exported

mmrelay/tools/sample-docker-compose.yaml

@@ -7,13 +7,24 @@ services:
     user: "${UID:-1000}:${GID:-1000}"
     environment:
       - TZ=UTC # Set timezone (PYTHONUNBUFFERED and MPLCONFIGDIR are set in Dockerfile)
+
     volumes:
       # Mount your config directory - create ~/.mmrelay/config.yaml first
       # Run 'make config' to set up the files
-      # For SELinux systems (RHEL/CentOS/Fedora), add :Z flag to prevent permission denied errors
-      - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro,Z
-      - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data:Z
-      # For non-SELinux systems, you can use:
-      # - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro
-      # - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data
-      # Tip: For correct permissions and paths, ensure UID, GID, and MMRELAY_HOME are set in a .env file or exported
+      # For non-SELinux systems (most common):
+      - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro
+      - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data
+      # For SELinux systems (RHEL/CentOS/Fedora), add :Z flag to prevent permission denied errors:
+      # - ${MMRELAY_HOME:-$HOME}/.mmrelay/config.yaml:/app/config.yaml:ro,Z
+      # - ${MMRELAY_HOME:-$HOME}/.mmrelay:/app/data:Z
+
+      # For BLE connections, uncomment these lines (Linux only):
+      # - /var/run/dbus:/var/run/dbus:ro
+
+    # For BLE connections, uncomment these options (Linux only). See DOCKER.md for alternatives.
+    # network_mode: host
+    # security_opt:
+    #   - apparmor=unconfined # Recommended for BLE to allow DBus communication
+    # privileged: true # Alternative if apparmor=unconfined is not acceptable
+
+    # Tip: For correct permissions and paths, ensure UID, GID, and MMRELAY_HOME are set in a .env file or exported

{mmrelay-1.2.3.dist-info → mmrelay-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.2.3
+Version: 1.2.4
 Summary: Bridge between Meshtastic mesh networks and Matrix chat rooms
 Home-page: https://github.com/jeremiah-k/meshtastic-matrix-relay
 Author: Geoff Whittington, Jeremiah K., and contributors
@@ -18,7 +18,7 @@ Classifier: Topic :: Communications
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: meshtastic>=2.6.4
+Requires-Dist: meshtastic>=2.7.3
 Requires-Dist: Pillow==11.3.0
 Requires-Dist: matrix-nio==0.25.2
 Requires-Dist: matplotlib==3.10.1

{mmrelay-1.2.3.dist-info → mmrelay-1.2.4.dist-info}/RECORD

@@ -1,18 +1,18 @@
-mmrelay/__init__.py,sha256=SQOj1vq5IynIEPwAMNWFQIlhKBzos14QQ5WYg2Fx87g,120
+mmrelay/__init__.py,sha256=DMVdCPD3oN7x0SkEuR6Pq5etPc622-e-kkxsSN2rl2A,120
 mmrelay/__main__.py,sha256=Z839i5jxZmhdoPvR1-reWoQL4Xpmty81p8TsTKsJLC8,814
-mmrelay/cli.py,sha256=GVQKaJRIJN2wOSWvSRSb3d04RFHm4ZTaXdSLqpFAupE,79506
+mmrelay/cli.py,sha256=T4apzc8aS7smXh0bpqoMSDHpHOOxcjls9-vSB-ue5Nk,79543
 mmrelay/cli_utils.py,sha256=h0JKhU_sToO2_Orf9ddO8x07_L1k201V61yXydfU2es,28887
-mmrelay/config.py,sha256=QF95n5i_XzRkBOPAVLfCD709Mcc17hsXJhJFY1tUv1A,38283
+mmrelay/config.py,sha256=H93dRHAsZOtPQmeO5RZd-S7qx5zsoAn7bt1GgXdOPqw,38285
 mmrelay/db_utils.py,sha256=utt254MipaIRTaGqSAe7N9L_S7eIPSnQsOQj6Gk2E3U,22502
 mmrelay/e2ee_utils.py,sha256=7cSb3F-FYqFcibSmb7eJzQJoRdq4Xk0_L5oppza3PHE,16914
-mmrelay/log_utils.py,sha256=psTzfRUTp1aVIE8U-7bzS7qc1ulU9EavqAEbDt8hUQA,9126
-mmrelay/main.py,sha256=2Zu1cGopppJ3qKQZ8KgvuOYqQJyjU_-LBP3EF6_w_og,16807
-mmrelay/matrix_utils.py,sha256=iz5aKB3ZCd1vrdRjpTosMemyrxoM249AaQ9kVtDhLCI,134485
+mmrelay/log_utils.py,sha256=CGTsHkeviCUKbe_SArYqOjPE5xRTslikMwzrag9LSFE,10290
+mmrelay/main.py,sha256=TlINxwGgk5pVe8gUuxzv29tYlZPuHYdqLcYsmrkUurI,17015
+mmrelay/matrix_utils.py,sha256=QPjwgkEKPgGLNFzeTXgfVusyfran7U_2NDs9UayTLWg,134586
 mmrelay/meshtastic_utils.py,sha256=wbVa8HDjbYNOTDLttVMGeRwTsYt8zJilUv_63FnmHoo,48783
-mmrelay/message_queue.py,sha256=esoXr6AyaWnFnJsWTx-QsqVtkXI17Xn1wU8gy0hXuDo,28156
+mmrelay/message_queue.py,sha256=aSitms4pr34VZ7nycpXuPw5ioA6x5xEdnwZ7_nh1Npw,28243
 mmrelay/plugin_loader.py,sha256=iXUpLGyjir7sfxtnL1REHdg5i5ZGWaHO_6sRQqf_JCE,59052
 mmrelay/runtime_utils.py,sha256=u8DtpfI-U7Ip3SAwjn214WfMTzc-xr5wffjN0i7WBZc,1261
-mmrelay/setup_utils.py,sha256=yh8UTgnm7Bb_oxfFFYrLICRItBx4wRgj0sUOoo3F6ac,32735
+mmrelay/setup_utils.py,sha256=SCFGx9e1wHZt87u2JMAhPUYOy-Ui4eV3irmzy0Zh9lE,32727
 mmrelay/windows_utils.py,sha256=FqjjsrCWhYxvEH5TcfVBuONCpA19VX9kcx7jHKsRWbM,13060
 mmrelay/constants/__init__.py,sha256=M8AXeIcS1JuS8OwmfTmhcCOkAz5XmWlNQ53GBxYOx94,1494
 mmrelay/constants/app.py,sha256=iNKqQMp5WZSfzsuRXYZ00znVm_ZyfwqiWMQgAblG6rY,725
@@ -21,28 +21,28 @@ mmrelay/constants/database.py,sha256=4cHfYfBePDUUtVSflrWyStcxKSQv7VE-jSrb1IzAjls
 mmrelay/constants/formats.py,sha256=cjbrfNNFCKoGSFsFHR1QQDEQudiGquA9MUapfm0_ZNI,494
 mmrelay/constants/messages.py,sha256=Reu_-6gZGGZQVP6BuqBm01QBhVTFjHVRQSPTUcQJG2Q,1531
 mmrelay/constants/network.py,sha256=QjROOAMxcP1pA1F_gUtuXzm2tORCqo5koqZbwrZRSns,1186
-mmrelay/constants/queue.py,sha256=yyWSrtq06b5GWzZwdl6IFtrMvxEuF9PdKSNPh8DdL2M,565
+mmrelay/constants/queue.py,sha256=cNK0cLsgBfQ6nVJm9_Scxj-ICv4RU6DU_PYsUwNyU_E,675
 mmrelay/plugins/__init__.py,sha256=KVMQIXRhe0wlGj4O3IZ0vOIQRKFkfPYejHXhJL17qrc,51
-mmrelay/plugins/base_plugin.py,sha256=Nh_zz-Z49qYatS4i38C2bLOl1sNDUgWsqpD8NLJdnl0,20807
+mmrelay/plugins/base_plugin.py,sha256=lcgKwrAMAIT9RjiC1Nyfs3fgdzUu3OQhCTZEjqh1_wg,20915
 mmrelay/plugins/debug_plugin.py,sha256=adX0cRJHUEDLldajybPfiRDDlvytkZe5aN_dSgNKP2Y,870
 mmrelay/plugins/drop_plugin.py,sha256=x4S-e0Muun2Dy1H2qwRMTBB1ptLmy7ZZJhgPu-KefGs,5394
 mmrelay/plugins/health_plugin.py,sha256=svV_GfpAVL0QhiVzi3PVZ1mNpsOL1NHSmkRF-Mn_ExE,2250
 mmrelay/plugins/help_plugin.py,sha256=S7nBhsANK46Zv9wPHOVegPGcuYGMErBsxAnrRlSSCwg,2149
 mmrelay/plugins/map_plugin.py,sha256=eHV_t3TFcypBD4xT_OQx0hD6_iGkLJOADjwYVny0PvE,11292
-mmrelay/plugins/mesh_relay_plugin.py,sha256=2dcLjHdVXS42BglgUhXHKFqN-Hiy1GxZXZdu3Ae-wBU,8512
+mmrelay/plugins/mesh_relay_plugin.py,sha256=OE07Kz5NvmyjXH3hneK5_eTPQ41mriJGZgsPcg-gpOQ,8428
 mmrelay/plugins/nodes_plugin.py,sha256=RDabzyG5hKG5aYWecsRUcLSjMCCv6Pngmq2Qpld1A1U,2903
 mmrelay/plugins/ping_plugin.py,sha256=8uFnT3qfO3RBaTUOx348voIfKpzXB3zTfcT6Gtfc8kM,4070
 mmrelay/plugins/telemetry_plugin.py,sha256=8SxWv4BLXMUTbiVaD3MjlMMdQyS7S_1OfLlVNAUMSO0,6306
 mmrelay/plugins/weather_plugin.py,sha256=ZmTNlkEjeCvZWHlO7VMend3vnj4h2qWeeU4RUQJY2vM,14183
 mmrelay/tools/__init__.py,sha256=WFjDQjdevgg19_zT6iEoL29rvb1JPqYSd8708Jn5D7A,838
 mmrelay/tools/mmrelay.service,sha256=6_TAskmTh9pXQSDRDeh0EXl2BfsUgm9Q3W9ob5tWCS8,600
-mmrelay/tools/sample-docker-compose-prebuilt.yaml,sha256=RT3IWA4DuLfIB5C7fUT1cDaYhOAxXiUjBan1M6PlvKc,958
-mmrelay/tools/sample-docker-compose.yaml,sha256=pbE9nXSA9DcEbdwhCQ0mZzzmhYRi3L9y8crx3a_YrTE,940
+mmrelay/tools/sample-docker-compose-prebuilt.yaml,sha256=ytQRW882VAecbWO1LsRsU6UbudybNhC-iv2w0Fta1Ls,1368
+mmrelay/tools/sample-docker-compose.yaml,sha256=1UqZFvnJuhVwfNJ92C0qQ5KSdNRVjk8YbRNZgD8yF_M,1350
 mmrelay/tools/sample.env,sha256=RP-o3rX3jnEIrVG2rqCZq31O1yRXou4HcGrXWLVbKKw,311
 mmrelay/tools/sample_config.yaml,sha256=odAeiU-wesWuwnZGyXzVjxaXVYc26p8QI1HOEA-Tvco,6396
-mmrelay-1.2.3.dist-info/licenses/LICENSE,sha256=aB_07MhnK-bL5WLI1ucXLUSdW_yBVoepPRYB0kaAOl8,35204
-mmrelay-1.2.3.dist-info/METADATA,sha256=kmjNvTq2IaKoT7lQ0kfYK7AfD2x4ox__8haxHPHtLWg,6167
-mmrelay-1.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mmrelay-1.2.3.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
-mmrelay-1.2.3.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
-mmrelay-1.2.3.dist-info/RECORD,,
+mmrelay-1.2.4.dist-info/licenses/LICENSE,sha256=aB_07MhnK-bL5WLI1ucXLUSdW_yBVoepPRYB0kaAOl8,35204
+mmrelay-1.2.4.dist-info/METADATA,sha256=SOYGlz1SUe7pRR-VESGmmpy_jO49fwctDcQFvvkjBHo,6167
+mmrelay-1.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mmrelay-1.2.4.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
+mmrelay-1.2.4.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
+mmrelay-1.2.4.dist-info/RECORD,,