mmrelay 1.0__tar.gz

mmrelay-1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 geoffwhittington
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mmrelay-1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include requirements.txt
+include sample_config.yaml
+recursive-include tools *

mmrelay-1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mmrelay
+Version: 1.0
+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: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Communications
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: meshtastic
+Requires-Dist: Pillow==11.1.0
+Requires-Dist: matrix-nio==0.25.2
+Requires-Dist: matplotlib==3.10.1
+Requires-Dist: requests==2.32.3
+Requires-Dist: markdown==3.7
+Requires-Dist: haversine==2.9.0
+Requires-Dist: schedule==1.2.2
+Requires-Dist: platformdirs==4.2.0
+Requires-Dist: py-staticmaps>=0.4.0
+Dynamic: license-file
+
+# M<>M Relay
+
+## (Meshtastic <=> Matrix Relay)
+
+A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
+
+---
+
+## Getting Started
+
+MMRelay runs on Linux, macOS, and Windows.
+
+### Quick Installation
+
+```bash
+# Install using pip
+pip install mmrelay
+
+# Or use pipx for isolated installation (recommended)
+pipx install mmrelay
+```
+
+### Resources
+
+- **New Users**: See [INSTRUCTIONS.md](INSTRUCTIONS.md) for setup and configuration
+- **Existing Users**: Check [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) for migration guidance
+- **Configuration**: Review [sample_config.yaml](sample_config.yaml) for examples
+
+### Command-Line Options
+
+```bash
+usage: mmrelay [-h] [--config CONFIG] [--data-dir DATA_DIR] [--log-level {error,warning,info,debug}] [--logfile LOGFILE] [--version] [--generate-config] [--install-service] [--check-config]
+
+Options:
+  -h, --help            Show this help message and exit
+  --config CONFIG       Path to config file
+  --data-dir DATA_DIR   Base directory for all data (logs, database, plugins)
+  --log-level {error,warning,info,debug}
+                        Set logging level
+  --logfile LOGFILE     Path to log file (can be overridden by --data-dir)
+  --version             Show version and exit
+  --generate-config     Generate a sample config.yaml file
+  --install-service     Install or update the systemd user service
+  --check-config        Check if the configuration file is valid
+```
+
+---
+
+## 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
+- ✨️ _Cross-platform reactions 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._
+
+---
+
+## Windows Installer
+
+![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).
+
+---
+
+## Plugins
+
+M<>M Relay supports plugins for extending its functionality, enabling customization and enhancement of the relay to suit specific needs.
+
+### Core Plugins
+
+Generate a map of your nodes:
+
+![Map Plugin Screenshot](https://user-images.githubusercontent.com/1770544/235247915-47750b4f-d505-4792-a458-54a5f24c1523.png)
+
+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).
+
+### Community & Custom Plugins
+
+It is possible to create custom plugins and share them with the community. Check [example_plugins/README.md](https://github.com/geoffwhittington/meshtastic-matrix-relay/tree/main/example_plugins) and the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide).
+
+✨️ Visit the [Community Plugins List](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
+
+#### Install a Community Plugin
+
+Add the repository under the `community-plugins` section in `config.yaml`:
+
+```yaml
+community-plugins:
+  example-plugin:
+    active: true
+    repository: https://github.com/jeremiah-k/mmr-plugin-template.git
+    tag: main
+```
+
+### Plugin System
+
+MMRelay features a powerful plugin system with standardized locations:
+
+- **Core Plugins**: Pre-installed with the package
+- **Custom Plugins**: Your own plugins in `~/.mmrelay/plugins/custom/`
+- **Community Plugins**: Third-party plugins in `~/.mmrelay/plugins/community/`
+
+Plugins make it easy to extend functionality without modifying the core code.
+
+---
+
+## Getting Started with Matrix
+
+See our Wiki page [Getting Started With Matrix & MM Relay](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Getting-Started-With-Matrix-&-MM-Relay).
+
+---
+
+## Already on Matrix?
+
+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!

mmrelay-1.0/README.md

@@ -0,0 +1,132 @@
+# M<>M Relay
+
+## (Meshtastic <=> Matrix Relay)
+
+A powerful and easy-to-use relay between Meshtastic devices and Matrix chat rooms, allowing seamless communication across platforms. This opens the door for bridging Meshtastic devices to [many other platforms](https://matrix.org/bridges/).
+
+---
+
+## Getting Started
+
+MMRelay runs on Linux, macOS, and Windows.
+
+### Quick Installation
+
+```bash
+# Install using pip
+pip install mmrelay
+
+# Or use pipx for isolated installation (recommended)
+pipx install mmrelay
+```
+
+### Resources
+
+- **New Users**: See [INSTRUCTIONS.md](INSTRUCTIONS.md) for setup and configuration
+- **Existing Users**: Check [UPGRADE_TO_V1.md](UPGRADE_TO_V1.md) for migration guidance
+- **Configuration**: Review [sample_config.yaml](sample_config.yaml) for examples
+
+### Command-Line Options
+
+```bash
+usage: mmrelay [-h] [--config CONFIG] [--data-dir DATA_DIR] [--log-level {error,warning,info,debug}] [--logfile LOGFILE] [--version] [--generate-config] [--install-service] [--check-config]
+
+Options:
+  -h, --help            Show this help message and exit
+  --config CONFIG       Path to config file
+  --data-dir DATA_DIR   Base directory for all data (logs, database, plugins)
+  --log-level {error,warning,info,debug}
+                        Set logging level
+  --logfile LOGFILE     Path to log file (can be overridden by --data-dir)
+  --version             Show version and exit
+  --generate-config     Generate a sample config.yaml file
+  --install-service     Install or update the systemd user service
+  --check-config        Check if the configuration file is valid
+```
+
+---
+
+## 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
+- ✨️ _Cross-platform reactions 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._
+
+---
+
+## Windows Installer
+
+![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).
+
+---
+
+## Plugins
+
+M<>M Relay supports plugins for extending its functionality, enabling customization and enhancement of the relay to suit specific needs.
+
+### Core Plugins
+
+Generate a map of your nodes:
+
+![Map Plugin Screenshot](https://user-images.githubusercontent.com/1770544/235247915-47750b4f-d505-4792-a458-54a5f24c1523.png)
+
+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).
+
+### Community & Custom Plugins
+
+It is possible to create custom plugins and share them with the community. Check [example_plugins/README.md](https://github.com/geoffwhittington/meshtastic-matrix-relay/tree/main/example_plugins) and the [Community Plugins Development Guide](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-Development-Guide).
+
+✨️ Visit the [Community Plugins List](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Community-Plugin-List)!
+
+#### Install a Community Plugin
+
+Add the repository under the `community-plugins` section in `config.yaml`:
+
+```yaml
+community-plugins:
+  example-plugin:
+    active: true
+    repository: https://github.com/jeremiah-k/mmr-plugin-template.git
+    tag: main
+```
+
+### Plugin System
+
+MMRelay features a powerful plugin system with standardized locations:
+
+- **Core Plugins**: Pre-installed with the package
+- **Custom Plugins**: Your own plugins in `~/.mmrelay/plugins/custom/`
+- **Community Plugins**: Third-party plugins in `~/.mmrelay/plugins/community/`
+
+Plugins make it easy to extend functionality without modifying the core code.
+
+---
+
+## Getting Started with Matrix
+
+See our Wiki page [Getting Started With Matrix & MM Relay](https://github.com/geoffwhittington/meshtastic-matrix-relay/wiki/Getting-Started-With-Matrix-&-MM-Relay).
+
+---
+
+## Already on Matrix?
+
+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!

mmrelay-1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

mmrelay-1.0/requirements.txt

@@ -0,0 +1,10 @@
+meshtastic
+Pillow==11.1.0
+matrix-nio==0.25.2
+matplotlib==3.10.1
+requests==2.32.3
+markdown==3.7
+haversine==2.9.0
+schedule==1.2.2
+platformdirs==4.2.0
+py-staticmaps>=0.4.0

mmrelay-1.0/sample_config.yaml

@@ -0,0 +1,63 @@
+matrix:
+  homeserver: https://example.matrix.org
+  access_token: reaalllllyloooooongsecretttttcodeeeeeeforrrrbot # See: https://t2bot.io/docs/access_tokens/
+  bot_user_id: "@botuser:example.matrix.org"
+
+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
+  - id: "!someroomid:example.matrix.org"
+    meshtastic_channel: 2
+
+meshtastic:
+  connection_type: serial # Choose either "tcp", "serial", or "ble"
+  serial_port: /dev/ttyUSB0 # Only used when connection is "serial"
+  host: meshtastic.local # Only used when connection is "tcp"
+  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;
+  relay_reactions: true # Defaults to false, set to true to enable relay reactions between platforms
+
+logging:
+  level: info
+  #log_to_file: true                          # Default is false
+  #filename: ~/.mmrelay/logs/mmrelay.log      # Default location
+  #max_log_size: 10485760                     # 10 MB default if omitted
+  #backup_count: 1                            # Keeps 1 backup as the default if omitted
+
+#database:
+#  path: ~/.mmrelay/data/meshtastic.sqlite   # Default location
+#  msg_map: # The message map is necessary for the relay_reactions functionality. If `relay_reactions` is set to false, nothing will be saved to the message map.
+#    msgs_to_keep: 500 # If set to 0, it will not delete any messages; Defaults to 500
+#    wipe_on_restart: true # Clears out the message map when the relay is restarted; Defaults to False
+
+# These are core Plugins - Note: Some plugins are experimental and some need maintenance.
+plugins:
+  ping:
+    active: true
+    #channels: [2,3,5] # List of channels the plugin will respond to; DMs are always processed if the plugin is active
+  weather:
+    active: true
+    units: imperial # Options: metric, imperial - Default is metric
+    #channels: [] # Empty list, will only respond to DMs
+  nodes:
+    active: true
+    # Does not need to specify channels, as it's a Matrix-only plugin
+
+#community-plugins:
+#  sample_plugin:
+#    active: true
+#    repository: https://github.com/username/sample_plugin.git
+#    tag: master
+#  advanced_plugin:
+#    active: false
+#    repository: https://github.com/username/advanced_plugin.git
+#    tag: v1.2.0
+
+#custom-plugins:
+#  my_custom_plugin:
+#    active: true
+#  another_custom_plugin:
+#    active: false

mmrelay-1.0/setup.cfg

@@ -0,0 +1,46 @@
+[metadata]
+name = mmrelay
+version = 1.0
+author = Geoff Whittington, Jeremiah K., and contributors
+author_email = jeremiahk@gmx.com
+description = Bridge between Meshtastic mesh networks and Matrix chat rooms
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/geoffwhittington/meshtastic-matrix-relay
+project_urls = 
+	Bug Tracker = https://github.com/geoffwhittington/meshtastic-matrix-relay/issues
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+	Development Status :: 4 - Beta
+	Topic :: Communications
+
+[options]
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.8
+install_requires = 
+	meshtastic
+	Pillow==11.1.0
+	matrix-nio==0.25.2
+	matplotlib==3.10.1
+	requests==2.32.3
+	markdown==3.7
+	haversine==2.9.0
+	schedule==1.2.2
+	platformdirs==4.2.0
+	py-staticmaps>=0.4.0
+
+[options.packages.find]
+where = src
+
+[options.entry_points]
+console_scripts = 
+	mmrelay = mmrelay.cli:main
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

mmrelay-1.0/src/mmrelay/__init__.py

@@ -0,0 +1,9 @@
+"""
+Meshtastic Matrix Relay - Bridge between Meshtastic mesh networks and Matrix chat rooms.
+"""
+
+import os
+
+# Get version from environment variable if available (set by GitHub Actions)
+# Otherwise, use a default version
+__version__ = os.environ.get("GITHUB_REF_NAME", "1.0.0")