mmrelay 1.2.6__py3-none-any.whl

mmrelay/plugins/mesh_relay_plugin.py

@@ -0,0 +1,222 @@
+# Note: This plugin was experimental and is not functional.
+
+import base64
+import json
+import re
+
+from meshtastic import mesh_pb2
+
+from mmrelay.constants.database import DEFAULT_MAX_DATA_ROWS_PER_NODE_MESH_RELAY
+from mmrelay.plugins.base_plugin import BasePlugin, config
+
+
+class Plugin(BasePlugin):
+    """Core mesh-to-Matrix relay plugin.
+
+    Handles bidirectional message relay between Meshtastic mesh network
+    and Matrix chat rooms. Processes radio packets and forwards them
+    to configured Matrix rooms, and vice versa.
+
+    This plugin is fundamental to the relay's core functionality and
+    typically runs with high priority to ensure messages are properly
+    bridged between the two networks.
+
+    Configuration:
+        max_data_rows_per_node: 50 (reduced storage for performance)
+    """
+
+    plugin_name = "mesh_relay"
+    max_data_rows_per_node = DEFAULT_MAX_DATA_ROWS_PER_NODE_MESH_RELAY
+
+    def normalize(self, dict_obj):
+        """
+        Converts packet data in various formats (dict, JSON string, or plain string) into a normalized dictionary with raw data fields removed.
+
+        Parameters:
+            dict_obj: Packet data as a dictionary, JSON string, or plain string.
+
+        Returns:
+            A dictionary representing the normalized packet with raw fields stripped.
+        """
+        if not isinstance(dict_obj, dict):
+            try:
+                dict_obj = json.loads(dict_obj)
+            except (json.JSONDecodeError, TypeError):
+                dict_obj = {"decoded": {"text": dict_obj}}
+
+        return self.strip_raw(dict_obj)
+
+    def process(self, packet):
+        """Process and prepare packet data for relay.
+
+        Args:
+            packet: Raw packet data to process
+
+        Returns:
+            dict: Processed packet with base64-encoded binary payloads
+
+        Normalizes packet format and encodes binary payloads as base64
+        for JSON serialization and Matrix transmission.
+        """
+        packet = self.normalize(packet)
+
+        if "decoded" in packet and "payload" in packet["decoded"]:
+            if isinstance(packet["decoded"]["payload"], bytes):
+                packet["decoded"]["payload"] = base64.b64encode(
+                    packet["decoded"]["payload"]
+                ).decode("utf-8")
+
+        return packet
+
+    def get_matrix_commands(self):
+        """Get Matrix commands handled by this plugin.
+
+        Returns:
+            list: Empty list (this plugin handles all traffic, not specific commands)
+        """
+        return []
+
+    def get_mesh_commands(self):
+        """Get mesh commands handled by this plugin.
+
+        Returns:
+            list: Empty list (this plugin handles all traffic, not specific commands)
+        """
+        return []
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        """
+        Relay a Meshtastic packet to a configured Matrix room.
+
+        Normalizes and prepares the incoming Meshtastic packet, determines its channel (defaults to 0 if absent), and, if that channel is mapped in plugin configuration, sends the processed packet to the mapped Matrix room. The sent Matrix event includes a JSON-serialized `meshtastic_packet` in the content and sets `mmrelay_suppress` to True to mark it as a bridged packet. If the packet's channel is not mapped, the function returns without sending anything.
+
+        Parameters:
+            packet: Raw Meshtastic packet (dict, JSON string, or other) to be normalized and relayed.
+            formatted_message (str): Human-readable message extracted from the packet (not used for routing).
+            longname (str): Long name of the sending node (informational).
+            meshnet_name (str): Name of the mesh network (informational).
+
+        Returns:
+            None
+        """
+        from mmrelay.matrix_utils import connect_matrix
+
+        packet = self.process(packet)
+        matrix_client = await connect_matrix()
+
+        packet_type = packet["decoded"]["portnum"]
+        if "channel" in packet:
+            channel = packet["channel"]
+        else:
+            channel = 0
+
+        channel_mapped = False
+        if config is not None:
+            matrix_rooms = config.get("matrix_rooms", [])
+            for room in matrix_rooms:
+                if room["meshtastic_channel"] == channel:
+                    channel_mapped = True
+                    break
+
+        if not channel_mapped:
+            self.logger.debug(f"Skipping message from unmapped channel {channel}")
+            return False
+
+        await matrix_client.room_send(
+            room_id=room["id"],
+            message_type="m.room.message",
+            content={
+                "msgtype": "m.text",
+                "mmrelay_suppress": True,
+                "meshtastic_packet": json.dumps(packet),
+                "body": f"Processed {packet_type} radio packet",
+            },
+        )
+
+        return True
+
+    def matches(self, event):
+        """
+        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 with a `"body"` string.
+
+        Returns:
+            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", {})
+        body = content.get("body", "")
+
+        if isinstance(body, str):
+            match = re.match(r"^Processed (.+) radio packet$", body)
+            return bool(match)
+        return False
+
+    async def handle_room_message(self, room, event, full_message):
+        """
+        Relay an embedded Meshtastic packet from a Matrix room message to the Meshtastic mesh.
+
+        If the Matrix event contains an embedded meshtastic packet (detected via self.matches),
+        this function looks up the Meshtastic channel mapped to the Matrix room, parses the
+        embedded JSON packet from the event content, reconstructs a MeshPacket (decoding the
+        base64-encoded payload), and sends it on the radio via the Meshtastic client.
+
+        Parameters:
+            room: Matrix room object where the message was received (used to find room→channel mapping).
+            event: Matrix event containing the message; the embedded packet is read from event.source["content"].
+            full_message: Unused — matching and extraction are performed against `event`.
+
+        Returns:
+            None
+
+        Side effects:
+            Sends a packet onto the Meshtastic radio network when a valid embedded packet and room→channel mapping exist.
+        """
+        # Use the event for matching instead of full_message
+        if not self.matches(event):
+            return False
+
+        channel = None
+        if config is not None:
+            matrix_rooms = config.get("matrix_rooms", [])
+            for room_config in matrix_rooms:
+                if room_config["id"] == room.room_id:
+                    channel = room_config["meshtastic_channel"]
+
+        if channel is None:
+            self.logger.debug(f"Skipping message from unmapped channel {channel}")
+            return False
+
+        packet_json = event.source["content"].get("meshtastic_packet")
+        if not packet_json:
+            self.logger.debug("Missing embedded packet")
+            return False
+
+        try:
+            packet = json.loads(packet_json)
+        except (json.JSONDecodeError, TypeError):
+            self.logger.exception("Error processing embedded packet")
+            return False
+
+        from mmrelay.meshtastic_utils import connect_meshtastic
+
+        meshtastic_client = connect_meshtastic()
+        meshPacket = mesh_pb2.MeshPacket()
+        meshPacket.channel = channel
+        meshPacket.decoded.payload = base64.b64decode(packet["decoded"]["payload"])
+        meshPacket.decoded.portnum = packet["decoded"]["portnum"]
+        meshPacket.decoded.want_response = False
+        meshPacket.id = meshtastic_client._generatePacketId()
+
+        self.logger.debug("Relaying packet to Radio")
+
+        meshtastic_client._sendPacket(
+            meshPacket=meshPacket, destinationId=packet["toId"]
+        )
+        return True

mmrelay/plugins/nodes_plugin.py

@@ -0,0 +1,92 @@
+from datetime import datetime
+
+from mmrelay.plugins.base_plugin import BasePlugin
+
+
+def get_relative_time(timestamp):
+    now = datetime.now()
+    dt = datetime.fromtimestamp(timestamp)
+
+    # Calculate the time difference between the current time and the given timestamp
+    delta = now - dt
+
+    # Extract the relevant components from the time difference
+    days = delta.days
+    seconds = delta.seconds
+
+    # Convert the time difference into a relative timeframe
+    if days > 7:
+        return dt.strftime(
+            "%b %d, %Y"
+        )  # Return the timestamp in a specific format if it's older than 7 days
+    elif days >= 1:
+        return f"{days} days ago"
+    elif seconds >= 3600:
+        hours = seconds // 3600
+        return f"{hours} hours ago"
+    elif seconds >= 60:
+        minutes = seconds // 60
+        return f"{minutes} minutes ago"
+    else:
+        return "Just now"
+
+
+class Plugin(BasePlugin):
+    plugin_name = "nodes"
+
+    @property
+    def description(self):
+        return """Show mesh radios and node data
+
+$shortname $longname / $devicemodel / $battery $voltage / $snr / $lastseen
+"""
+
+    def generate_response(self):
+        from mmrelay.meshtastic_utils import connect_meshtastic
+
+        meshtastic_client = connect_meshtastic()
+
+        response = f"Nodes: {len(meshtastic_client.nodes)}\n"
+
+        for _node, info in meshtastic_client.nodes.items():
+            snr = ""
+            if "snr" in info and info["snr"] is not None:
+                snr = f"{info['snr']} dB "
+
+            last_heard = None
+            if "lastHeard" in info and info["lastHeard"] is not None:
+                last_heard = get_relative_time(info["lastHeard"])
+
+            voltage = "?V"
+            battery = "?%"
+            if "deviceMetrics" in info:
+                if (
+                    "voltage" in info["deviceMetrics"]
+                    and info["deviceMetrics"]["voltage"] is not None
+                ):
+                    voltage = f"{info['deviceMetrics']['voltage']}V "
+                if (
+                    "batteryLevel" in info["deviceMetrics"]
+                    and info["deviceMetrics"]["batteryLevel"] is not None
+                ):
+                    battery = f"{info['deviceMetrics']['batteryLevel']}% "
+
+            response += f"{info['user']['shortName']} {info['user']['longName']} / {info['user']['hwModel']} / {battery} {voltage} / {snr} / {last_heard}\n"
+
+        return response
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        return False
+
+    async def handle_room_message(self, room, event, full_message):
+        # Pass the event to matches()
+        if not self.matches(event):
+            return False
+
+        await self.send_matrix_message(
+            room_id=room.room_id, message=self.generate_response(), formatted=False
+        )
+
+        return True

mmrelay/plugins/ping_plugin.py

@@ -0,0 +1,128 @@
+import asyncio
+import re
+import string
+
+from meshtastic.mesh_interface import BROADCAST_NUM
+
+from mmrelay.plugins.base_plugin import BasePlugin
+
+
+def match_case(source, target):
+    """
+    Apply the letter-case pattern of `source` onto `target`.
+
+    Parameters:
+        source (str): String whose uppercase/lowercase pattern will be used.
+        target (str): String whose characters will be converted to match `source`'s case.
+
+    Returns:
+        str: A new string where each character from `target` is uppercased if the corresponding character in `source` is uppercase, otherwise lowercased. The result length is the minimum of the two input lengths.
+    """
+    return "".join(
+        c.upper() if s.isupper() else c.lower()
+        for s, c in zip(source, target, strict=False)
+    )
+
+
+class Plugin(BasePlugin):
+    plugin_name = "ping"
+    punctuation = string.punctuation
+
+    # No __init__ method needed with the simplified plugin system
+    # The BasePlugin will automatically use the class-level plugin_name
+
+    @property
+    def description(self):
+        return "Check connectivity with the relay or respond to pings over the mesh"
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        if "decoded" in packet and "text" in packet["decoded"]:
+            message = packet["decoded"]["text"].strip()
+            channel = packet.get("channel", 0)  # Default to channel 0 if not provided
+
+            from mmrelay.meshtastic_utils import connect_meshtastic
+
+            meshtastic_client = connect_meshtastic()
+
+            # Determine if the message is a direct message
+            toId = packet.get("to")
+            myId = meshtastic_client.myInfo.my_node_num  # Get relay's own node number
+
+            if toId == myId:
+                # Direct message to us
+                is_direct_message = True
+            elif toId == BROADCAST_NUM:
+                is_direct_message = False
+            else:
+                # Message to someone else; we may ignore it
+                is_direct_message = False
+
+            # Pass is_direct_message to is_channel_enabled
+            if not self.is_channel_enabled(
+                channel, is_direct_message=is_direct_message
+            ):
+                # Removed unnecessary logging
+                return False
+
+            # Updated regex to match optional punctuation before and after "ping"
+            match = re.search(
+                r"(?<!\w)([!?]*)(ping)([!?]*)(?!\w)", message, re.IGNORECASE
+            )
+            if match:
+                # Log that the plugin is processing the message
+                self.logger.info(
+                    f"Processing message from {longname} on channel {channel} with plugin '{self.plugin_name}'"
+                )
+
+                # Extract matched text and punctuation
+                pre_punc = match.group(1)
+                matched_text = match.group(2)
+                post_punc = match.group(3)
+
+                total_punc_length = len(pre_punc) + len(post_punc)
+
+                # Define the base response
+                base_response = "pong"
+
+                # Adjust base_response to match the case pattern of matched_text
+                base_response = match_case(matched_text, base_response)
+
+                # Construct the reply message
+                if total_punc_length > 5:
+                    reply_message = "Pong..."
+                else:
+                    reply_message = pre_punc + base_response + post_punc
+
+                # Wait for the response delay
+                await asyncio.sleep(self.get_response_delay())
+
+                fromId = packet.get("fromId")
+
+                if is_direct_message:
+                    # Send reply as DM
+                    meshtastic_client.sendText(
+                        text=reply_message,
+                        destinationId=fromId,
+                    )
+                else:
+                    # Send the reply back to the same channel
+                    meshtastic_client.sendText(text=reply_message, channelIndex=channel)
+                return True
+            else:
+                return False  # No match, do not process
+
+    def get_matrix_commands(self):
+        return [self.plugin_name]
+
+    def get_mesh_commands(self):
+        return [self.plugin_name]
+
+    async def handle_room_message(self, room, event, full_message):
+        # Pass the event to matches()
+        if not self.matches(event):
+            return False
+
+        await self.send_matrix_message(room.room_id, "pong!")
+        return True

mmrelay/plugins/telemetry_plugin.py

@@ -0,0 +1,179 @@
+import io
+import json
+import re
+from datetime import datetime, timedelta
+
+import matplotlib.pyplot as plt
+from PIL import Image
+
+from mmrelay.plugins.base_plugin import BasePlugin
+
+
+class Plugin(BasePlugin):
+    plugin_name = "telemetry"
+    max_data_rows_per_node = 50
+
+    def commands(self):
+        return ["batteryLevel", "voltage", "airUtilTx"]
+
+    def description(self):
+        return "Graph of avg Mesh telemetry value for last 12 hours"
+
+    def _generate_timeperiods(self, hours=12):
+        # Calculate the start and end times
+        end_time = datetime.now()
+        start_time = end_time - timedelta(hours=hours)
+
+        # Create a list of hourly intervals for the last 12 hours
+        hourly_intervals = []
+        current_time = start_time
+        while current_time <= end_time:
+            hourly_intervals.append(current_time)
+            current_time += timedelta(hours=1)
+        return hourly_intervals
+
+    async def handle_meshtastic_message(
+        self, packet, formatted_message, longname, meshnet_name
+    ):
+        # Support deviceMetrics only for now
+        if (
+            "decoded" in packet
+            and "portnum" in packet["decoded"]
+            and packet["decoded"]["portnum"] == "TELEMETRY_APP"
+            and "telemetry" in packet["decoded"]
+            and "deviceMetrics" in packet["decoded"]["telemetry"]
+        ):
+            telemetry_data = []
+            data = self.get_node_data(meshtastic_id=packet["fromId"])
+            if data:
+                telemetry_data = data
+            packet_data = packet["decoded"]["telemetry"]
+
+            telemetry_data.append(
+                {
+                    "time": packet_data["time"],
+                    "batteryLevel": (
+                        packet_data["deviceMetrics"]["batteryLevel"]
+                        if "batteryLevel" in packet_data["deviceMetrics"]
+                        else 0
+                    ),
+                    "voltage": (
+                        packet_data["deviceMetrics"]["voltage"]
+                        if "voltage" in packet_data["deviceMetrics"]
+                        else 0
+                    ),
+                    "airUtilTx": (
+                        packet_data["deviceMetrics"]["airUtilTx"]
+                        if "airUtilTx" in packet_data["deviceMetrics"]
+                        else 0
+                    ),
+                }
+            )
+            self.set_node_data(meshtastic_id=packet["fromId"], node_data=telemetry_data)
+            return False
+
+    def get_matrix_commands(self):
+        return ["batteryLevel", "voltage", "airUtilTx"]
+
+    def get_mesh_commands(self):
+        return []
+
+    def matches(self, event):
+        from mmrelay.matrix_utils import bot_command
+
+        # Use bot_command() to check if any of the commands match
+        for command in self.get_matrix_commands():
+            if bot_command(command, event):
+                return True
+        return False
+
+    async def handle_room_message(self, room, event, full_message):
+        # Pass the event to matches()
+        if not self.matches(event):
+            return False
+
+        match = re.search(
+            r":\s+!(batteryLevel|voltage|airUtilTx)(?:\s+(.+))?$", full_message
+        )
+        if not match:
+            return False
+
+        telemetry_option = match.group(1)
+        node = match.group(2)
+
+        hourly_intervals = self._generate_timeperiods()
+        from mmrelay.matrix_utils import connect_matrix
+
+        matrix_client = await connect_matrix()
+
+        # Compute the hourly averages for each node
+        hourly_averages = {}
+
+        def calculate_averages(node_data_rows):
+            for record in node_data_rows:
+                record_time = datetime.fromtimestamp(
+                    record["time"]
+                )  # Replace with your timestamp field name
+                telemetry_value = record[
+                    telemetry_option
+                ]  # Replace with your battery level field name
+                for i in range(len(hourly_intervals) - 1):
+                    if hourly_intervals[i] <= record_time < hourly_intervals[i + 1]:
+                        if i not in hourly_averages:
+                            hourly_averages[i] = []
+                        hourly_averages[i].append(telemetry_value)
+                        break
+
+        if node:
+            node_data_rows = self.get_node_data(node)
+            calculate_averages(node_data_rows)
+        else:
+            for node_data_json in self.get_data():
+                node_data_rows = json.loads(node_data_json[0])
+                calculate_averages(node_data_rows)
+
+        # Compute the final hourly averages
+        final_averages = {}
+        for i, interval in enumerate(hourly_intervals[:-1]):
+            if i in hourly_averages:
+                final_averages[interval] = sum(hourly_averages[i]) / len(
+                    hourly_averages[i]
+                )
+            else:
+                final_averages[interval] = 0.0
+
+        # Extract the hourly intervals and average values into separate lists
+        hourly_intervals = list(final_averages.keys())
+        average_values = list(final_averages.values())
+
+        # Convert the hourly intervals to strings
+        hourly_strings = [hour.strftime("%H") for hour in hourly_intervals]
+
+        # Create the plot
+        fig, ax = plt.subplots()
+        ax.plot(hourly_strings, average_values)
+
+        # Set the plot title and axis labels
+        if node:
+            title = f"{node} Hourly {telemetry_option} Averages"
+        else:
+            title = f"Network Hourly {telemetry_option} Averages"
+        ax.set_title(title)
+        ax.set_xlabel("Hour")
+        ax.set_ylabel(f"{telemetry_option}")
+
+        # Rotate the x-axis labels for readability
+        plt.xticks(rotation=45)
+
+        # Save the plot as a PIL image
+        buf = io.BytesIO()
+        fig.canvas.print_png(buf)
+        buf.seek(0)
+        img = Image.open(buf)
+        pil_image = Image.frombytes(mode="RGBA", size=img.size, data=img.tobytes())
+
+        from mmrelay.matrix_utils import send_room_image, upload_image
+
+        upload_response = await upload_image(matrix_client, pil_image, "graph.png")
+        await send_room_image(matrix_client, room.room_id, upload_response)
+        return True