mmrelay 1.0.11__py3-none-any.whl → 1.1.1__py3-none-any.whl

mmrelay/__init__.py

@@ -14,4 +14,4 @@ else:
         __version__ = version("mmrelay")
     except PackageNotFoundError:
         # If all else fails, use hardcoded version
-        __version__ = "1.0.11"
+        __version__ = "1.1.1"

mmrelay/log_utils.py

@@ -30,6 +30,17 @@ log_file_path = None
 
 
 def get_logger(name):
+    """
+    Create and configure a logger with console and optional file output, supporting colorized output and log rotation.
+
+    The logger's level, color usage, and file logging behavior are determined by global configuration and command line arguments. Console output uses rich formatting if enabled. File logging supports log rotation and stores logs in a configurable or default location. The log file path is stored globally if the logger name is "M<>M Relay".
+
+    Parameters:
+        name (str): The name of the logger to create.
+
+    Returns:
+        logging.Logger: The configured logger instance.
+    """
     logger = logging.getLogger(name=name)
 
     # Default to INFO level if config is not available
@@ -134,3 +145,48 @@ def get_logger(name):
         logger.addHandler(file_handler)
 
     return logger
+
+
+def setup_upstream_logging_capture():
+    """
+    Redirects warning and error log messages from upstream libraries and the root logger into the application's formatted logging system.
+
+    This ensures that log output from external dependencies (such as "meshtastic", "bleak", and "asyncio") appears with consistent formatting alongside the application's own logs. Only messages at WARNING level or higher are captured, and messages originating from the application's own loggers are excluded to prevent recursion.
+    """
+    # Get our main logger
+    main_logger = get_logger("Upstream")
+
+    # Create a custom handler that redirects root logger messages
+    class UpstreamLogHandler(logging.Handler):
+        def emit(self, record):
+            # Skip if this is already from our logger to avoid recursion
+            """
+            Redirects log records from external sources to the main logger, mapping their severity and prefixing with the original logger name.
+
+            Skips records originating from the application's own loggers to prevent recursion.
+            """
+            if record.name.startswith("mmrelay") or record.name == "Upstream":
+                return
+
+            # Map the log level and emit through our logger
+            if record.levelno >= logging.ERROR:
+                main_logger.error(f"[{record.name}] {record.getMessage()}")
+            elif record.levelno >= logging.WARNING:
+                main_logger.warning(f"[{record.name}] {record.getMessage()}")
+            elif record.levelno >= logging.INFO:
+                main_logger.info(f"[{record.name}] {record.getMessage()}")
+            else:
+                main_logger.debug(f"[{record.name}] {record.getMessage()}")
+
+    # Add our handler to the root logger
+    root_logger = logging.getLogger()
+    upstream_handler = UpstreamLogHandler()
+    upstream_handler.setLevel(logging.WARNING)  # Only capture warnings and errors
+    root_logger.addHandler(upstream_handler)
+
+    # Also set up specific loggers for known upstream libraries
+    for logger_name in ["meshtastic", "bleak", "asyncio"]:
+        upstream_logger = logging.getLogger(logger_name)
+        upstream_logger.addHandler(upstream_handler)
+        upstream_logger.setLevel(logging.WARNING)
+        upstream_logger.propagate = False  # Prevent duplicate messages via root logger

mmrelay/main.py

@@ -20,7 +20,7 @@ from mmrelay.db_utils import (
     update_shortnames,
     wipe_message_map,
 )
-from mmrelay.log_utils import get_logger
+from mmrelay.log_utils import get_logger, setup_upstream_logging_capture
 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_member, on_room_message
@@ -50,13 +50,12 @@ def print_banner():
 
 async def main(config):
     """
-    Main asynchronous function to set up and run the relay.
-    Includes logic for wiping the message_map if configured in database.msg_map.wipe_on_restart
-    or db.msg_map.wipe_on_restart (legacy format).
-    Also updates longnames and shortnames periodically as before.
+    Sets up and runs the asynchronous relay between Meshtastic and Matrix, managing connections, event handling, and graceful shutdown.
 
-    Args:
-        config: The loaded configuration
+    This function initializes the database, configures logging, loads plugins, connects to both Meshtastic and Matrix, joins specified Matrix rooms, and registers event callbacks for message and membership events. It periodically updates node names from the Meshtastic network and manages the Matrix sync loop, handling reconnections and shutdown signals. If configured, it wipes the message map on startup and shutdown.
+
+    Parameters:
+        config: The loaded configuration dictionary containing Matrix, Meshtastic, and database settings.
     """
     # Extract Matrix configuration
     from typing import List
@@ -69,6 +68,9 @@ async def main(config):
     # Initialize the SQLite database
     initialize_database()
 
+    # Set up upstream logging capture to format library messages consistently
+    setup_upstream_logging_capture()
+
     # Check database config for wipe_on_restart (preferred format)
     database_config = config.get("database", {})
     msg_map_config = database_config.get("msg_map", {})
@@ -131,11 +133,8 @@ async def main(config):
         # On Windows, we can't use add_signal_handler, so we'll handle KeyboardInterrupt
         pass
 
-    # -------------------------------------------------------------------
-    # IMPORTANT: We create a task to run the meshtastic_utils.check_connection()
-    # so its while loop runs in parallel with the matrix sync loop
-    # Use "_" to avoid trunk's "assigned but unused variable" warning
-    # -------------------------------------------------------------------
+    # Start connection health monitoring using getMetadata() heartbeat
+    # This provides proactive connection detection for all interface types
     _ = asyncio.create_task(meshtastic_utils.check_connection())
 
     # Start the Matrix client sync loop

mmrelay/matrix_utils.py

@@ -207,9 +207,9 @@ async def join_matrix_room(matrix_client, room_id_or_alias: str) -> None:
         if room_id_or_alias.startswith("#"):
             # If it's a room alias, resolve it to a room ID
             response = await matrix_client.room_resolve_alias(room_id_or_alias)
-            if not response.room_id:
+            if not hasattr(response, "room_id") or not response.room_id:
                 logger.error(
-                    f"Failed to resolve room alias '{room_id_or_alias}': {response.message}"
+                    f"Failed to resolve room alias '{room_id_or_alias}': {getattr(response, 'message', str(response))}"
                 )
                 return
             room_id = response.room_id
@@ -510,23 +510,42 @@ async def send_reply_to_meshtastic(
         try:
             if reply_id is not None:
                 # Send as a structured reply using our custom function
-                sent_packet = sendTextReply(
-                    meshtastic_interface,
-                    text=reply_message,
-                    reply_id=reply_id,
-                    channelIndex=meshtastic_channel,
-                )
-                meshtastic_logger.info(
-                    f"Relaying Matrix reply from {full_display_name} to radio broadcast as structured reply to message {reply_id}"
-                )
+                try:
+                    sent_packet = sendTextReply(
+                        meshtastic_interface,
+                        text=reply_message,
+                        reply_id=reply_id,
+                        channelIndex=meshtastic_channel,
+                    )
+                    meshtastic_logger.info(
+                        f"Relaying Matrix reply from {full_display_name} to radio broadcast as structured reply to message {reply_id}"
+                    )
+                    meshtastic_logger.debug(
+                        f"sendTextReply returned packet: {sent_packet}"
+                    )
+                except Exception as e:
+                    meshtastic_logger.error(
+                        f"Error sending structured reply to Meshtastic: {e}"
+                    )
+                    return
             else:
                 # Send as regular message (fallback for when no reply_id is available)
-                sent_packet = meshtastic_interface.sendText(
-                    text=reply_message, channelIndex=meshtastic_channel
-                )
-                meshtastic_logger.info(
-                    f"Relaying Matrix reply from {full_display_name} to radio broadcast as regular message"
-                )
+                try:
+                    meshtastic_logger.debug(
+                        f"Attempting to send text to Meshtastic: '{reply_message}' on channel {meshtastic_channel}"
+                    )
+                    sent_packet = meshtastic_interface.sendText(
+                        text=reply_message, channelIndex=meshtastic_channel
+                    )
+                    meshtastic_logger.info(
+                        f"Relaying Matrix reply from {full_display_name} to radio broadcast as regular message"
+                    )
+                    meshtastic_logger.debug(f"sendText returned packet: {sent_packet}")
+                except Exception as e:
+                    meshtastic_logger.error(
+                        f"Error sending reply message to Meshtastic: {e}"
+                    )
+                    return
 
             # Store the reply in message map if storage is enabled
             if storage_enabled and sent_packet and hasattr(sent_packet, "id"):
@@ -766,9 +785,16 @@ async def on_room_message(
                 logger.debug(
                     f"Sending reaction to Meshtastic with meshnet={local_meshnet_name}: {reaction_message}"
                 )
-                meshtastic_interface.sendText(
-                    text=reaction_message, channelIndex=meshtastic_channel
-                )
+                try:
+                    sent_packet = meshtastic_interface.sendText(
+                        text=reaction_message, channelIndex=meshtastic_channel
+                    )
+                    logger.debug(
+                        f"Remote reaction sendText returned packet: {sent_packet}"
+                    )
+                except Exception as e:
+                    logger.error(f"Error sending remote reaction to Meshtastic: {e}")
+                    return
             # We've relayed the remote reaction to our local mesh, so we're done.
             return
 
@@ -829,9 +855,16 @@ async def on_room_message(
                 logger.debug(
                     f"Sending reaction to Meshtastic with meshnet={local_meshnet_name}: {reaction_message}"
                 )
-                meshtastic_interface.sendText(
-                    text=reaction_message, channelIndex=meshtastic_channel
-                )
+                try:
+                    sent_packet = meshtastic_interface.sendText(
+                        text=reaction_message, channelIndex=meshtastic_channel
+                    )
+                    logger.debug(
+                        f"Local reaction sendText returned packet: {sent_packet}"
+                    )
+                except Exception as e:
+                    logger.error(f"Error sending local reaction to Meshtastic: {e}")
+                    return
             return
 
     # Handle Matrix replies to Meshtastic messages (only if replies are enabled)
@@ -938,13 +971,25 @@ async def on_room_message(
             if portnum == "DETECTION_SENSOR_APP":
                 # If detection_sensor is enabled, forward this data as detection sensor data
                 if config["meshtastic"].get("detection_sensor", False):
-                    sent_packet = meshtastic_interface.sendData(
-                        data=full_message.encode("utf-8"),
-                        channelIndex=meshtastic_channel,
-                        portNum=meshtastic.protobuf.portnums_pb2.PortNum.DETECTION_SENSOR_APP,
-                    )
-                    # Note: Detection sensor messages are not stored in message_map because they are never replied to
-                    # Only TEXT_MESSAGE_APP messages need to be stored for reaction handling
+                    try:
+                        meshtastic_logger.debug(
+                            f"Attempting to send detection sensor data to Meshtastic: '{full_message}' on channel {meshtastic_channel}"
+                        )
+                        sent_packet = meshtastic_interface.sendData(
+                            data=full_message.encode("utf-8"),
+                            channelIndex=meshtastic_channel,
+                            portNum=meshtastic.protobuf.portnums_pb2.PortNum.DETECTION_SENSOR_APP,
+                        )
+                        meshtastic_logger.debug(
+                            f"sendData returned packet: {sent_packet}"
+                        )
+                        # Note: Detection sensor messages are not stored in message_map because they are never replied to
+                        # Only TEXT_MESSAGE_APP messages need to be stored for reaction handling
+                    except Exception as e:
+                        meshtastic_logger.error(
+                            f"Error sending detection sensor data to Meshtastic: {e}"
+                        )
+                        return
                 else:
                     meshtastic_logger.debug(
                         f"Detection sensor packet received from {full_display_name}, but detection sensor processing is disabled."
@@ -958,8 +1003,15 @@ async def on_room_message(
                     sent_packet = meshtastic_interface.sendText(
                         text=full_message, channelIndex=meshtastic_channel
                     )
+                    if not sent_packet:
+                        meshtastic_logger.warning(
+                            "sendText returned None - message may not have been sent"
+                        )
                 except Exception as e:
                     meshtastic_logger.error(f"Error sending message to Meshtastic: {e}")
+                    import traceback
+
+                    meshtastic_logger.error(f"Full traceback: {traceback.format_exc()}")
                     return
                 # Store message_map only if storage is enabled and only for TEXT_MESSAGE_APP
                 # (these are the only messages that can be replied to and thus need reaction handling)

mmrelay/meshtastic_utils.py

@@ -47,14 +47,18 @@ reconnecting = False
 shutting_down = False
 reconnect_task = None  # To keep track of the reconnect task
 
+# Track pubsub subscription state to prevent duplicate subscriptions during reconnections
+subscribed_to_messages = False
+subscribed_to_connection_lost = False
+subscribed_to_connection_established = False
+
 
 def is_running_as_service():
     """
     Check if the application is running as a systemd service.
-    This is used to determine whether to show Rich progress indicators.
-
+    
     Returns:
-        bool: True if running as a service, False otherwise
+        True if the process is running under systemd, either by detecting the INVOCATION_ID environment variable or by verifying that the parent process is systemd; otherwise, False.
     """
     # Check for INVOCATION_ID environment variable (set by systemd)
     if os.environ.get("INVOCATION_ID"):
@@ -85,14 +89,16 @@ def serial_port_exists(port_name):
 
 def connect_meshtastic(passed_config=None, force_connect=False):
     """
-    Establish a connection to the Meshtastic device.
-    Attempts a connection based on connection_type (serial/ble/network).
-    Retries until successful or shutting_down is set.
-    If already connected and not force_connect, returns the existing client.
-
-    Args:
-        passed_config: The configuration dictionary to use (will update global config)
-        force_connect: Whether to force a new connection even if one exists
+    Establishes and manages a connection to a Meshtastic device using the specified connection type (serial, BLE, or TCP).
+    
+    If a configuration is provided, updates the global configuration and Matrix room mappings. Handles reconnection logic, including closing any existing connection if `force_connect` is True. Retries connection attempts with exponential backoff until successful or shutdown is initiated. Subscribes to message and connection events only once per process to avoid duplicate subscriptions.
+    
+    Parameters:
+        passed_config (dict, optional): Configuration dictionary to use for the connection. If provided, updates the global configuration.
+        force_connect (bool, optional): If True, forces a new connection even if one already exists.
+    
+    Returns:
+        Meshtastic interface client if the connection is successful, or None if the connection fails or shutdown is in progress.
     """
     global meshtastic_client, shutting_down, config, matrix_rooms
     if shutting_down:
@@ -197,11 +203,26 @@ def connect_meshtastic(passed_config=None, force_connect=False):
                     f"Connected to {nodeInfo['user']['shortName']} / {nodeInfo['user']['hwModel']}"
                 )
 
-                # Subscribe to message and connection lost events
-                pub.subscribe(on_meshtastic_message, "meshtastic.receive")
-                pub.subscribe(
-                    on_lost_meshtastic_connection, "meshtastic.connection.lost"
-                )
+                # Subscribe to message and connection events (only if not already subscribed)
+                global subscribed_to_messages, subscribed_to_connection_lost, subscribed_to_connection_established
+                if not subscribed_to_messages:
+                    pub.subscribe(on_meshtastic_message, "meshtastic.receive")
+                    subscribed_to_messages = True
+                    logger.debug("Subscribed to meshtastic.receive")
+
+                if not subscribed_to_connection_lost:
+                    pub.subscribe(
+                        on_lost_meshtastic_connection, "meshtastic.connection.lost"
+                    )
+                    subscribed_to_connection_lost = True
+                    logger.debug("Subscribed to meshtastic.connection.lost")
+
+                if not subscribed_to_connection_established:
+                    pub.subscribe(
+                        on_established_meshtastic_connection, "meshtastic.connection.established"
+                    )
+                    subscribed_to_connection_established = True
+                    logger.debug("Subscribed to meshtastic.connection.established")
 
             except (
                 serial.SerialException,
@@ -228,10 +249,13 @@ def connect_meshtastic(passed_config=None, force_connect=False):
     return meshtastic_client
 
 
-def on_lost_meshtastic_connection(interface=None):
+def on_lost_meshtastic_connection(interface=None, detection_source="detected by library"):
     """
-    Callback invoked when the Meshtastic connection is lost.
-    Initiates a reconnect sequence unless shutting_down is True.
+    Handles Meshtastic connection loss by initiating a reconnection sequence unless a shutdown is in progress or a reconnection is already underway.
+    
+    Parameters:
+        interface: The interface that lost connection (unused; present for compatibility).
+        detection_source (str): Description of how the disconnection was detected.
     """
     global meshtastic_client, reconnecting, shutting_down, event_loop, reconnect_task
     with meshtastic_lock:
@@ -244,7 +268,7 @@ def on_lost_meshtastic_connection(interface=None):
             )
             return
         reconnecting = True
-        logger.error("Lost connection. Reconnecting...")
+        logger.error(f"Lost connection ({detection_source}). Reconnecting...")
 
         if meshtastic_client:
             try:
@@ -265,8 +289,9 @@ def on_lost_meshtastic_connection(interface=None):
 
 async def reconnect():
     """
-    Asynchronously attempts to reconnect with exponential backoff.
-    Stops if shutting_down is set.
+    Asynchronously attempts to reconnect to the Meshtastic device using exponential backoff, stopping if a shutdown is initiated.
+    
+    The function increases the wait time between attempts up to a maximum of 5 minutes and provides a progress bar if not running as a service. The reconnection process halts immediately if the shutdown flag is set or if reconnection succeeds.
     """
     global meshtastic_client, reconnecting, shutting_down
     backoff_time = 10
@@ -321,11 +346,23 @@ async def reconnect():
         reconnecting = False
 
 
-def on_meshtastic_message(packet, interface):
+def on_established_meshtastic_connection(interface=None):
     """
-    Processes incoming Meshtastic messages and relays them to Matrix rooms or plugins based on message type and interaction settings.
+    Callback triggered when a Meshtastic connection is successfully established.
+    
+    Clears the reconnecting flag and logs the connection event.
+    """
+    global reconnecting
+    with meshtastic_lock:
+        logger.info("Connection established (detected by library)")
+        reconnecting = False  # Clear reconnecting flag when connection is confirmed
 
-    Handles reactions and replies by relaying them to Matrix if enabled in the interaction settings. Normal text messages are relayed to all mapped Matrix rooms unless handled by a plugin or directed to the relay node. Non-text messages are passed to plugins for processing. Filters out messages from unmapped channels or disabled detection sensors, and ensures sender information is retrieved or stored as needed.
+
+def on_meshtastic_message(packet, interface):
+    """
+    Process incoming Meshtastic messages and relay them to Matrix rooms or plugins according to message type and interaction settings.
+    
+    Handles reactions and replies by relaying them to Matrix if enabled. Normal text messages are relayed to all mapped Matrix rooms unless handled by a plugin or directed to the relay node. Non-text messages are passed to plugins for processing. Messages from unmapped channels or disabled detection sensors are filtered out, and sender information is retrieved or stored as needed.
     """
     global config, matrix_rooms
 
@@ -630,35 +667,71 @@ def on_meshtastic_message(packet, interface):
 
 async def check_connection():
     """
-    Periodically checks the Meshtastic connection by calling localNode.getMetadata().
-    If it fails or doesn't return the firmware version, we assume the connection is lost
-    and attempt to reconnect.
+    Periodically verifies the health of the Meshtastic connection and triggers reconnection if needed.
+    
+    For non-BLE connections, this coroutine calls `localNode.getMetadata()` at a configurable interval to confirm the connection is alive. If the health check fails or does not return expected metadata, it invokes the connection lost handler to initiate reconnection. BLE connections are excluded from periodic checks, as their library provides real-time disconnection detection.
+    
+    This coroutine runs continuously until shutdown is requested.
     """
-    global meshtastic_client, shutting_down, config
+    global meshtastic_client, shutting_down, config, reconnecting
 
     # Check if config is available
     if config is None:
         logger.error("No configuration available. Cannot check connection.")
         return
 
+    # Get heartbeat interval from config, default to 180 seconds
+    heartbeat_interval = config["meshtastic"].get("heartbeat_interval", 180)
     connection_type = config["meshtastic"]["connection_type"]
+
+    logger.info(
+        f"Starting connection heartbeat monitor (interval: {heartbeat_interval}s)"
+    )
+
+    # Track if we've logged the BLE skip message to avoid spam
+    ble_skip_logged = False
+
     while not shutting_down:
-        if meshtastic_client:
-            try:
-                output_capture = io.StringIO()
-                with contextlib.redirect_stdout(
-                    output_capture
-                ), contextlib.redirect_stderr(output_capture):
-                    meshtastic_client.localNode.getMetadata()
+        if meshtastic_client and not reconnecting:
+            # BLE has real-time disconnection detection in the library
+            # Skip periodic health checks to avoid duplicate reconnection attempts
+            if connection_type == "ble":
+                if not ble_skip_logged:
+                    logger.info("BLE connection uses real-time disconnection detection - health checks disabled")
+                    ble_skip_logged = True
+            else:
+                try:
+                    logger.debug(
+                        f"Checking {connection_type} connection health using getMetadata()"
+                    )
+                    output_capture = io.StringIO()
+                    with contextlib.redirect_stdout(
+                        output_capture
+                    ), contextlib.redirect_stderr(output_capture):
+                        meshtastic_client.localNode.getMetadata()
 
-                console_output = output_capture.getvalue()
-                if "firmware_version" not in console_output:
-                    raise Exception("No firmware_version in getMetadata output.")
+                    console_output = output_capture.getvalue()
+                    if "firmware_version" not in console_output:
+                        raise Exception("No firmware_version in getMetadata output.")
 
-            except Exception as e:
-                logger.error(f"{connection_type.capitalize()} connection lost: {e}")
-                on_lost_meshtastic_connection(meshtastic_client)
-        await asyncio.sleep(30)  # Check connection every 30 seconds
+                    logger.debug(f"{connection_type.capitalize()} connection healthy")
+
+                except Exception as e:
+                    # Only trigger reconnection if we're not already reconnecting
+                    if not reconnecting:
+                        logger.warning(
+                            f"{connection_type.capitalize()} connection health check failed: {e}"
+                        )
+                        # Use existing handler with health check reason
+                        on_lost_meshtastic_connection(detection_source=f"health check failed: {str(e)}")
+                    else:
+                        logger.debug("Skipping reconnection trigger - already reconnecting")
+        elif reconnecting:
+            logger.debug("Skipping connection check - reconnection in progress")
+        elif not meshtastic_client:
+            logger.debug("Skipping connection check - no client available")
+
+        await asyncio.sleep(heartbeat_interval)
 
 
 def sendTextReply(

mmrelay/tools/sample-docker-compose.yaml

@@ -0,0 +1,39 @@
+services:
+  mmrelay:
+    build: .
+    container_name: meshtastic-matrix-relay
+    restart: unless-stopped
+    user: "${UID:-1000}:${GID:-1000}"
+
+    environment:
+      - TZ=UTC
+      - PYTHONUNBUFFERED=1
+      - MPLCONFIGDIR=/tmp/matplotlib
+
+    volumes:
+      # Configuration - uses standard ~/.mmrelay/config.yaml location
+      # Create this first with: make config
+      - ${MMRELAY_HOME}/.mmrelay/config.yaml:/app/config.yaml:ro
+
+      # Data and logs - same locations as standalone installation
+      # These directories will be created automatically
+      - ${MMRELAY_HOME}/.mmrelay/data:/app/data
+      - ${MMRELAY_HOME}/.mmrelay/logs:/app/logs
+
+    # For TCP connections (most common) - Meshtastic typically uses port 4403
+    ports:
+      - 4403:4403
+
+    # For serial connections, uncomment the device you need:
+    # devices:
+    #   - /dev/ttyUSB0:/dev/ttyUSB0
+    #   - /dev/ttyACM0:/dev/ttyACM0
+
+    # For BLE connections, uncomment these:
+    # privileged: true
+    # network_mode: host
+    # Additional volumes for BLE (add to existing volumes section above):
+    #   - /var/run/dbus:/var/run/dbus:ro
+    #   - /sys/bus/usb:/sys/bus/usb:ro
+    #   - /sys/class/bluetooth:/sys/class/bluetooth:ro
+    #   - /sys/devices:/sys/devices:ro

mmrelay/tools/sample.env

@@ -0,0 +1,10 @@
+# Docker Compose environment variables
+# Customize these paths if needed
+
+# Base directory for mmrelay data
+# This will be expanded by your shell when docker compose runs
+MMRELAY_HOME=$HOME
+
+# Preferred editor for config editing
+# Will be set automatically when you select an editor via 'make edit'
+EDITOR=nano

mmrelay/tools/sample_config.yaml

@@ -10,18 +10,18 @@ matrix_rooms: # Needs at least 1 room & channel, but supports all Meshtastic cha
     meshtastic_channel: 2
 
 meshtastic:
-  connection_type: serial # Choose either "tcp", "serial", or "ble"
-  serial_port: /dev/ttyUSB0 # Only used when connection is "serial"
+  connection_type: tcp # Choose either "tcp", "serial", or "ble"
   host: meshtastic.local # Only used when connection is "tcp"
+  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;
+  # heartbeat_interval: 180 # Interval in seconds to check connection health using getMetadata() (default: 180)
   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
-  # Note: Legacy 'relay_reactions' setting is deprecated but still supported
 
 logging:
   level: info

{mmrelay-1.0.11.dist-info → mmrelay-1.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mmrelay
-Version: 1.0.11
+Version: 1.1.1
 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
@@ -14,8 +14,8 @@ Classifier: Topic :: Communications
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: meshtastic
-Requires-Dist: Pillow==11.2.1
+Requires-Dist: meshtastic>=2.6.4
+Requires-Dist: Pillow==11.3.0
 Requires-Dist: matrix-nio==0.25.2
 Requires-Dist: matplotlib==3.10.1
 Requires-Dist: requests==2.32.4
@@ -26,7 +26,17 @@ Requires-Dist: platformdirs==4.3.8
 Requires-Dist: py-staticmaps>=0.4.0
 Requires-Dist: rich==14.0.0
 Requires-Dist: setuptools==80.9.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
 Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # M<>M Relay
 
@@ -34,13 +44,27 @@ Dynamic: license-file
 
 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/).
 
+## Features
+
+- Bidirectional message relay between Meshtastic devices and Matrix chat rooms, capable of supporting multiple meshnets
+- Supports serial, network, and **_BLE (now too!)_** connections for Meshtastic devices
+- Custom fields are embedded in Matrix messages for relaying messages between multiple meshnets
+- Truncates long messages to fit within Meshtastic's payload size
+- SQLite database to store node information for improved functionality
+- Customizable logging level for easy debugging
+- Configurable through a simple YAML file
+- Supports mapping multiple rooms and channels 1:1
+- Relays messages to/from an MQTT broker, if configured in the Meshtastic firmware
+- ✨️ _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._
+
 ## Documentation
 
 Visit our [Wiki](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki) for comprehensive guides and information.
 
 - [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
 
 ---
 
@@ -61,22 +85,23 @@ mmrelay --install-service
 
 For detailed installation and configuration instructions, see the [Installation Guide](docs/INSTRUCTIONS.md).
 
----
+## Docker
 
-## Features
+MMRelay includes official Docker support for easy deployment and management:
 
-- Bidirectional message relay between Meshtastic devices and Matrix chat rooms, capable of supporting multiple meshnets
-- Supports serial, network, and **_BLE (now too!)_** connections for Meshtastic devices
-- Custom fields are embedded in Matrix messages for relaying messages between multiple meshnets
-- Truncates long messages to fit within Meshtastic's payload size
-- SQLite database to store node information for improved functionality
-- Customizable logging level for easy debugging
-- Configurable through a simple YAML file
-- Supports mapping multiple rooms and channels 1:1
-- Relays messages to/from an MQTT broker, if configured in the Meshtastic firmware
-- ✨️ _Cross-platform reactions support_ ✨️ **NEW!!**
+```bash
+# Quick setup with Docker
+make setup   # Copy config and open editor (first time)
+make build   # Build the Docker image
+make run     # Start the container
+make logs    # View logs
+```
 
-_We would love to support [Matrix E2EE rooms](https://github.com/geoffwhittington/meshtastic-matrix-relay/issues/33), but this is currently not implemented._
+Docker provides isolated environment, easy deployment, automatic restarts, and volume persistence.
+
+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.
 
 ---
 
@@ -84,7 +109,7 @@ _We would love to support [Matrix E2EE rooms](https://github.com/geoffwhittingto
 
 ![Windows Installer Screenshot](https://user-images.githubusercontent.com/1770544/235249050-8c79107a-50cc-4803-b989-39e58100342d.png)
 
-The latest installer is available [here](https://github.com/geoffwhittington/meshtastic-matrix-relay/releases).
+The latest installer is available in the [releases section](https://github.com/geoffwhittington/meshtastic-matrix-relay/releases).
 
 ---
 
@@ -102,7 +127,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 [here](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Core-Plugins).
+See the full list of [core plugins](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Core-Plugins).
 
 ### Community & Custom Plugins
 
@@ -147,6 +172,6 @@ See our Wiki page [Getting Started With Matrix & MM Relay](https://github.com/ge
 
 Join us!
 
-- Our project's room: [#mmrelay:meshnet.club](https://matrix.to/#/#mmrelay:meshnet.club)
-- Part of the Meshtastic Community Matrix space: [#meshtastic-community:meshnet.club](https://matrix.to/#/#meshtastic-community:meshnet.club)
-- Public Relay Room: [#relay-room:meshnet.club](https://matrix.to/#/#relay-room:meshnet.club) - Where we bridge multiple meshnets. Feel free to join us, with or without a relay!
+- Our project's room: [#mmrelay:matrix.org](https://matrix.to/#/#mmrelay:matrix.org)
+- Part of the Meshtastic Community Matrix space: [#meshnetclub:matrix.org](https://matrix.to/#/#meshnetclub:matrix.org)
+- Public Relay Room: [#mmrelay-relay-room:matrix.org](https://matrix.to/#/#mmrelay-relay-room:matrix.org) - Where we bridge multiple meshnets. Feel free to join us, with or without a relay!

{mmrelay-1.0.11.dist-info → mmrelay-1.1.1.dist-info}/RECORD

@@ -1,12 +1,12 @@
-mmrelay/__init__.py,sha256=XeHKtvrDgq8NM54pZypZ-29wpSYfW2ZBq4vBqTw3FQM,595
+mmrelay/__init__.py,sha256=v-xcK3JoA0m2eBmIudme82RPgp5PQInzRSs5mitHB28,594
 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=FXhaq4WSDHwlqiG3k1BbSxiOl5be4P4Kyr1gsIThOBw,4572
-mmrelay/main.py,sha256=88hmJzv-Fw3CSjcMSlQWKjlZlIlZBjOujMfi85r5uCk,11301
-mmrelay/matrix_utils.py,sha256=dtmj6yFUax6xR5NTpbgK_6WYHIcg8saFhU05_tviN7A,43172
-mmrelay/meshtastic_utils.py,sha256=7r8FnZiwlmLZbj3PtVuMO2Plt1reYeGnclxFyMq7hBU,26953
+mmrelay/log_utils.py,sha256=ot0GpYppyNuPOWY8d3EXdLPojoJYEqfmUjVlcYm8neY,7532
+mmrelay/main.py,sha256=TL5xWFXIGwAQKau-hN4sRB0wxtNWzc629ry_qPbovv0,11585
+mmrelay/matrix_utils.py,sha256=XSOHztRrdIjFGyYt8QhGBL6nMv_6iodeYL288pG9voA,45813
+mmrelay/meshtastic_utils.py,sha256=MgCNGSufQDddncVKJVgmp_6DDZbcHSvOvW72vuNDLeg,31596
 mmrelay/plugin_loader.py,sha256=NRiXF6Ty1WD9jNXXKvzJh7kE0ba5oICXNVAfMaTPqH4,39247
 mmrelay/setup_utils.py,sha256=N6qdScHKHEMFKDmT1l7dcLDPNTusZXPkyxrLXjFLhRI,19910
 mmrelay/plugins/__init__.py,sha256=KVMQIXRhe0wlGj4O3IZ0vOIQRKFkfPYejHXhJL17qrc,51
@@ -23,10 +23,12 @@ mmrelay/plugins/telemetry_plugin.py,sha256=8SxWv4BLXMUTbiVaD3MjlMMdQyS7S_1OfLlVN
 mmrelay/plugins/weather_plugin.py,sha256=1bQhmiX-enNphzGoFVprU0LcZQX9BvGxWAJAG8Wekg0,8596
 mmrelay/tools/__init__.py,sha256=WFjDQjdevgg19_zT6iEoL29rvb1JPqYSd8708Jn5D7A,838
 mmrelay/tools/mmrelay.service,sha256=3vqK1VbfXvVftkTrTEOan77aTHeOT36hIAL7HqJsmTg,567
-mmrelay/tools/sample_config.yaml,sha256=HVEUYawNILwMukAnQL4Eh_2PlSvt2581eyfkxl8OxsA,3258
-mmrelay-1.0.11.dist-info/licenses/LICENSE,sha256=yceWauM1c0-FHxVplsD7W1-AbSeRaUNlmqT4UO1msBU,1073
-mmrelay-1.0.11.dist-info/METADATA,sha256=qWciy6Gpa4aa0pToMg4wDSgQUqM0HMZhhUaIA2fr8jM,5919
-mmrelay-1.0.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mmrelay-1.0.11.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
-mmrelay-1.0.11.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
-mmrelay-1.0.11.dist-info/RECORD,,
+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=0BKND0qbke8z9X9J9iHleu567dZt3RmHUxhZlQEEdFk,3290
+mmrelay-1.1.1.dist-info/licenses/LICENSE,sha256=yceWauM1c0-FHxVplsD7W1-AbSeRaUNlmqT4UO1msBU,1073
+mmrelay-1.1.1.dist-info/METADATA,sha256=ltSYRsnKQvdwsKd0CqAqMoSMWLsqZq8Pcpmfy_OjqI8,6713
+mmrelay-1.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mmrelay-1.1.1.dist-info/entry_points.txt,sha256=SJZwGUOEpQ-qx4H8UL4xKFnKeInGUaZNW1I0ddjK7Ws,45
+mmrelay-1.1.1.dist-info/top_level.txt,sha256=B_ZLCRm7NYAmI3PipRUyHGymP-C-q16LSeMGzmqJfo4,8
+mmrelay-1.1.1.dist-info/RECORD,,