mmrelay 1.1.2__py3-none-any.whl → 1.1.3__py3-none-any.whl

mmrelay/plugins/base_plugin.py

@@ -14,10 +14,14 @@ from mmrelay.db_utils import (
     store_plugin_data,
 )
 from mmrelay.log_utils import get_logger
+from mmrelay.message_queue import DEFAULT_MESSAGE_DELAY, queue_message
 
 # Global config variable that will be set from main.py
 config = None
 
+# Track if we've already shown the deprecated warning
+_deprecated_warning_shown = False
+
 
 class BasePlugin(ABC):
     """Abstract base class for all mmrelay plugins.
@@ -59,20 +63,16 @@ class BasePlugin(ABC):
         return ""
 
     def __init__(self, plugin_name=None) -> None:
-        """Initialize the plugin with configuration and logging.
+        """
+        Initialize the plugin instance, setting its name, logger, configuration, mapped channels, and response delay.
 
-        Args:
-            plugin_name (str, optional): Plugin name override. If not provided,
-                                       uses class-level plugin_name attribute.
+        Parameters:
+            plugin_name (str, optional): Overrides the plugin's name. If not provided, uses the class-level `plugin_name` attribute.
 
         Raises:
-            ValueError: If plugin_name is not set via parameter or class attribute
+            ValueError: If the 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
+        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.
         """
         # Allow plugin_name to be passed as a parameter for simpler initialization
         # This maintains backward compatibility while providing a cleaner API
@@ -132,26 +132,43 @@ class BasePlugin(ABC):
                 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
+        # Get the response delay from the meshtastic config
+        self.response_delay = DEFAULT_MESSAGE_DELAY
         if config is not None:
-            self.response_delay = config.get("meshtastic", {}).get(
-                "plugin_response_delay", self.response_delay
-            )
+            meshtastic_config = config.get("meshtastic", {})
+
+            # Check for new message_delay option first, with fallback to deprecated option
+            delay = None
+            delay_key = None
+            if "message_delay" in meshtastic_config:
+                delay = meshtastic_config["message_delay"]
+                delay_key = "message_delay"
+            elif "plugin_response_delay" in meshtastic_config:
+                delay = meshtastic_config["plugin_response_delay"]
+                delay_key = "plugin_response_delay"
+                # Show deprecated warning only once globally
+                global _deprecated_warning_shown
+                if not _deprecated_warning_shown:
+                    self.logger.warning(
+                        "Configuration option 'plugin_response_delay' is deprecated. "
+                        "Please use 'message_delay' instead. Support for 'plugin_response_delay' will be removed in a future version."
+                    )
+                    _deprecated_warning_shown = True
+
+            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:
+                    self.logger.warning(
+                        f"{delay_key} of {self.response_delay}s is below minimum of 2.0s (firmware constraint). Using 2.0s."
+                    )
+                    self.response_delay = 2.0
 
     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
+        """
+        Starts the plugin and configures scheduled background tasks based on plugin settings.
 
-        Creates a daemon thread to run the scheduler if any schedule is configured.
+        If scheduling options are present in the plugin configuration, sets up periodic execution of the `background_job` method using the specified schedule. Runs scheduled jobs in a separate daemon thread. If no scheduling is configured, the plugin starts without background tasks.
         """
         if "schedule" not in self.config or (
             "at" not in self.config["schedule"]
@@ -224,28 +241,64 @@ class BasePlugin(ABC):
         return data
 
     def get_response_delay(self):
-        """Get the configured response delay for meshtastic messages.
+        """
+        Return the configured delay in seconds before sending a Meshtastic response.
 
-        Returns:
-            int: Delay in seconds before sending responses (default: 3)
+        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.
 
-        Used to prevent message flooding and ensure proper radio etiquette.
-        Delay is configured via meshtastic.plugin_response_delay in config.
+        Returns:
+            float: The response delay in seconds.
         """
         return self.response_delay
 
-    def is_channel_enabled(self, channel, is_direct_message=False):
-        """Check if the plugin should respond on a specific channel.
+    def send_message(self, text: str, channel: int = 0, destination_id=None) -> bool:
+        """
+        Send a message to the Meshtastic network via the message queue.
 
-        Args:
-            channel: Channel identifier to check
-            is_direct_message (bool): Whether this is a direct message
+        Automatically queues the message for broadcast or direct delivery, applying rate limiting as configured. Returns True if the message was successfully queued, or False if the Meshtastic client is unavailable.
+
+        Parameters:
+            text (str): The message text to send.
+            channel (int, optional): Channel index to send the message on. Defaults to 0.
+            destination_id (optional): Destination node ID for direct messages; if None, the message is broadcast.
 
         Returns:
-            bool: True if plugin should respond, False otherwise
+            bool: True if the message was queued successfully, False otherwise.
+        """
+        from mmrelay.meshtastic_utils import connect_meshtastic
+
+        meshtastic_client = connect_meshtastic()
+        if not meshtastic_client:
+            self.logger.error("No Meshtastic client available")
+            return False
+
+        description = (
+            f"Plugin {self.plugin_name}: {text[:50]}{'...' if len(text) > 50 else ''}"
+        )
+
+        send_kwargs = {
+            "text": text,
+            "channelIndex": channel,
+        }
+        if destination_id:
+            send_kwargs["destinationId"] = destination_id
+
+        return queue_message(
+            meshtastic_client.sendText,
+            description=description,
+            **send_kwargs,
+        )
+
+    def is_channel_enabled(self, channel, is_direct_message=False):
+        """
+        Determine whether the plugin should respond to a message on the specified channel or direct message.
+
+        Parameters:
+            channel: The channel identifier to check.
+            is_direct_message (bool): Set to True if the message is a direct message.
 
-        Direct messages always return True if the plugin is active.
-        For channel messages, checks if channel is in plugin's configured channels list.
+        Returns:
+            bool: True if the plugin should respond on the given channel or to a direct message; False otherwise.
         """
         if is_direct_message:
             return True  # Always respond to DMs if the plugin is active

mmrelay/tools/sample_config.yaml

@@ -3,6 +3,10 @@ matrix:
   access_token: reaalllllyloooooongsecretttttcodeeeeeeforrrrbot # See: https://t2bot.io/docs/access_tokens/
   bot_user_id: "@botuser:example.matrix.org"
 
+  # Message prefix customization (Meshtastic → Matrix direction)
+  #prefix_enabled: true # Enable prefixes on messages from mesh (e.g., "[Alice/MyMesh]: message")
+  #prefix_format: "[{long}/{mesh}]: " # Default format. Variables: {long1-20}, {long}, {short}, {mesh1-20}, {mesh}
+
 matrix_rooms: # Needs at least 1 room & channel, but supports all Meshtastic channels
   - id: "#someroomalias:example.matrix.org" # Matrix room aliases & IDs supported
     meshtastic_channel: 0
@@ -15,9 +19,6 @@ meshtastic:
   serial_port: /dev/ttyUSB0 # Only used when connection is "serial"
   ble_address: AA:BB:CC:DD:EE:FF # Only used when connection is "ble" - Uses either an address or name from a `meshtastic --ble-scan`
   meshnet_name: Your Meshnet Name # This is displayed in full on Matrix, but is truncated when sent to a Meshnet
-  broadcast_enabled: true # Must be set to true to enable Matrix to Meshtastic messages
-  detection_sensor: true # Must be set to true to forward messages of Meshtastic's detection sensor module
-  plugin_response_delay: 3 # Default response delay in seconds for plugins that respond on the mesh;
   message_interactions: # Configure reactions and replies (both require message storage in database)
     reactions: false # Enable reaction relaying between platforms
     replies: false   # Enable reply relaying between platforms
@@ -29,6 +30,15 @@ meshtastic:
   #                                   # Note: BLE connections use real-time disconnection detection and skip periodic checks
   #                                   # Legacy: heartbeat_interval at meshtastic level still supported but deprecated
 
+  # Additional configuration options (commented out with defaults)
+  #broadcast_enabled: true # Must be set to true to enable Matrix to Meshtastic messages
+  #detection_sensor: true # Must be set to true to forward messages of Meshtastic's detection sensor module
+  #message_delay: 2.2 # Delay in seconds between messages sent to mesh (minimum: 2.0 due to firmware)
+
+  # Message prefix customization (Matrix → Meshtastic direction)
+  #prefix_enabled: true # Enable username prefixes on messages sent to mesh (e.g., "Alice[M]: message")
+  #prefix_format: "{display5}[M]: " # Default format. See EXTRA_CONFIGURATION.md for all variables.
+
 logging:
   level: info
   #log_to_file: true                          # Set to true to enable file logging

{mmrelay-1.1.2.dist-info → mmrelay-1.1.3.dist-info}/METADATA

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.1.2
+Version: 1.1.3
 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
 Author-email: jeremiahk@gmx.com
 Project-URL: Bug Tracker, https://github.com/geoffwhittington/meshtastic-matrix-relay/issues
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
 Classifier: Operating System :: OS Independent
 Classifier: Development Status :: 4 - Beta
 Classifier: Topic :: Communications
@@ -24,7 +24,7 @@ Requires-Dist: haversine==2.9.0
 Requires-Dist: schedule==1.2.2
 Requires-Dist: platformdirs==4.3.8
 Requires-Dist: py-staticmaps>=0.4.0
-Requires-Dist: rich==14.0.0
+Requires-Dist: rich==14.1.0
 Requires-Dist: setuptools==80.9.0
 Dynamic: author
 Dynamic: author-email
@@ -58,11 +58,11 @@ A powerful and easy-to-use relay between Meshtastic devices and Matrix chat room
 - ✨️ _Bidirectional replies and reactions support_ ✨️ **NEW!!**
 - ✨️ _Native Docker support_ ✨️ **NEW!!**
 
-_We would love to support [Matrix E2EE rooms](https://github.com/geoffwhittington/meshtastic-matrix-relay/issues/33), but this is currently not implemented._
+_We would love to support [Matrix E2EE rooms](https://github.com/jeremiah-k/meshtastic-matrix-relay/issues/33), but this is currently not implemented._
 
 ## Documentation
 
-Visit our [Wiki](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
+Visit our [Wiki](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
 
 - [Installation Instructions](docs/INSTRUCTIONS.md) - Setup and configuration guide
 
@@ -101,15 +101,13 @@ Docker provides isolated environment, easy deployment, automatic restarts, and v
 
 For detailed Docker setup instructions, see the [Docker Guide](docs/DOCKER.md).
 
-> **Note**: Docker builds currently use a temporary fork of the meshtastic library with BLE hanging fixes. PyPI releases use the upstream library. This will be resolved when the fixes are merged upstream.
-
 ---
 
 ## Windows Installer
 
 ![Windows Installer Screenshot](https://user-images.githubusercontent.com/1770544/235249050-8c79107a-50cc-4803-b989-39e58100342d.png)
 
-The latest installer is available in the [releases section](https://github.com/geoffwhittington/meshtastic-matrix-relay/releases).
+The latest installer is available in the [releases section](https://github.com/jeremiah-k/meshtastic-matrix-relay/releases).
 
 ---
 
@@ -127,7 +125,7 @@ Produce high-level details about your mesh:
 
 ![Mesh Details Screenshot](https://user-images.githubusercontent.com/1770544/235245873-1ddc773b-a4cd-4c67-b0a5-b55a29504b73.png)
 
-See the full list of [core plugins](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Core-Plugins).
+See the full list of [core plugins](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki/Core-Plugins).
 
 ### Community & Custom Plugins
 
@@ -136,9 +134,9 @@ 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.
+Check the [Community Plugins Development Guide](https://github.com/jeremiah-k/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)!
+✨️ Visit the [Community Plugins List](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
 
 #### Install a Community Plugin
 
@@ -164,7 +162,7 @@ Plugins make it easy to extend functionality without modifying the core program.
 
 ## Getting Started with Matrix
 
-See our Wiki page [Getting Started With Matrix & MM Relay](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Getting-Started-With-Matrix-&-MM-Relay).
+See our Wiki page [Getting Started With Matrix & MM Relay](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki/Getting-Started-With-Matrix-&-MM-Relay).
 
 ---
 

{mmrelay-1.1.2.dist-info → mmrelay-1.1.3.dist-info}/RECORD

@@ -1,16 +1,17 @@
-mmrelay/__init__.py,sha256=ofK1VtDZwWBsSvfj0gcmsvkTTVHq_Go5MpGdU5NxdHM,594
+mmrelay/__init__.py,sha256=4ciaRmcwzGfuaU_HuNDXVr4Qk0WVkPydhrdXIVo9VOs,120
 mmrelay/cli.py,sha256=hdPTlcGsXTJC9GEUiScG7b3IFp02B3lwhqgwFpU3NsM,13835
 mmrelay/config.py,sha256=5VZag8iSc5yLQgvwI76bbpizbtqag74cHnfXCrWHNyA,7910
 mmrelay/config_checker.py,sha256=UnoHVTXzfdTfFkbmXv9r_Si76v-sxXLb5FOaQSOM45E,4909
 mmrelay/db_utils.py,sha256=eTMMkYVWsmO_DkrBfnZMw4ohg_xa0S9TXJoBjRFTwzo,13590
 mmrelay/log_utils.py,sha256=1zVHBJ5qSOG1O4cq4Ebngq9dp81vaZOEq5khulAFuuM,6611
-mmrelay/main.py,sha256=-usvB02bl4ubwQ4obUzncV-5pKTRaplfOvvKcVNWBK8,12493
-mmrelay/matrix_utils.py,sha256=XSOHztRrdIjFGyYt8QhGBL6nMv_6iodeYL288pG9voA,45813
-mmrelay/meshtastic_utils.py,sha256=9H5kt7X5KXx8FvnWm4fU-CVoFq35JjE-YQC2j98Miq0,31012
-mmrelay/plugin_loader.py,sha256=NRiXF6Ty1WD9jNXXKvzJh7kE0ba5oICXNVAfMaTPqH4,39247
+mmrelay/main.py,sha256=46J-B6wDRawB392u71kP6pxNoayBdmwOiKcqsleikhU,13182
+mmrelay/matrix_utils.py,sha256=Ans7Wroh693un0LOp4x2p8NPfGFJ9z6TnG6ApXRXg7Q,55686
+mmrelay/meshtastic_utils.py,sha256=iy7BwMlqOwpkqSB0pTx2n8oqaKs2kWQ4PXFk4y16ys8,31440
+mmrelay/message_queue.py,sha256=spLK7pVugnl9djVLIh5-P7iHZ7kRtZEZIWTcQ4X1TfI,18529
+mmrelay/plugin_loader.py,sha256=UJ-i6cL2q_hwMTqjRkaOAQDTj6uUrmyj56-XbUVGcng,39231
 mmrelay/setup_utils.py,sha256=N6qdScHKHEMFKDmT1l7dcLDPNTusZXPkyxrLXjFLhRI,19910
 mmrelay/plugins/__init__.py,sha256=KVMQIXRhe0wlGj4O3IZ0vOIQRKFkfPYejHXhJL17qrc,51
-mmrelay/plugins/base_plugin.py,sha256=Gf3xrWdYnXu2dnY4TcOhCGy9fZDISna8OI_Pgt_QX8Q,15415
+mmrelay/plugins/base_plugin.py,sha256=DJdM-l-69sMnx6Fgn0rweWF5CuWilnQQAT3nm6eq8f4,18359
 mmrelay/plugins/debug_plugin.py,sha256=adX0cRJHUEDLldajybPfiRDDlvytkZe5aN_dSgNKP2Y,870
 mmrelay/plugins/drop_plugin.py,sha256=0GOz0dgLnFST1HTgqrMayrjwmYlnu02QxfnTZtdPZ3U,4671
 mmrelay/plugins/health_plugin.py,sha256=svV_GfpAVL0QhiVzi3PVZ1mNpsOL1NHSmkRF-Mn_ExE,2250
@@ -25,10 +26,10 @@ mmrelay/tools/__init__.py,sha256=WFjDQjdevgg19_zT6iEoL29rvb1JPqYSd8708Jn5D7A,838
 mmrelay/tools/mmrelay.service,sha256=3vqK1VbfXvVftkTrTEOan77aTHeOT36hIAL7HqJsmTg,567
 mmrelay/tools/sample-docker-compose.yaml,sha256=vVgJrh-6l48hkj5F-52JA5tpDWPBjiPQ36CE9Pkqn44,1251
 mmrelay/tools/sample.env,sha256=RP-o3rX3jnEIrVG2rqCZq31O1yRXou4HcGrXWLVbKKw,311
-mmrelay/tools/sample_config.yaml,sha256=57LkzZUuCFNmfLzeBn9Vs1rtZ_DLdwjWLjiH3-bN6GY,4094
-mmrelay-1.1.2.dist-info/licenses/LICENSE,sha256=yceWauM1c0-FHxVplsD7W1-AbSeRaUNlmqT4UO1msBU,1073
-mmrelay-1.1.2.dist-info/METADATA,sha256=OeWp6ooATRMHmJuFjpdYHtKLZioC03-GYU2ci5WnFOg,6705
-mmrelay-1.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mmrelay-1.1.2.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
-mmrelay-1.1.2.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
-mmrelay-1.1.2.dist-info/RECORD,,
+mmrelay/tools/sample_config.yaml,sha256=grS70MKHFd9e_lZ3GkmzPi4RRW-PdahMOMPCAg07MWs,4718
+mmrelay-1.1.3.dist-info/licenses/LICENSE,sha256=aB_07MhnK-bL5WLI1ucXLUSdW_yBVoepPRYB0kaAOl8,35204
+mmrelay-1.1.3.dist-info/METADATA,sha256=gNG_TVwJfpvt0s7sd3WDEceXl8Li2WCLGHTkYkXOWVQ,6493
+mmrelay-1.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mmrelay-1.1.3.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
+mmrelay-1.1.3.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
+mmrelay-1.1.3.dist-info/RECORD,,