Add Matrix <-> Meshtastic bridge (meshtastic-matrix-relay)

Vendors the meshtastic-matrix-relay (mmrelay) role into roles/custom/
following the conventions used by other bridge roles.

Co-authored-by: luschmar <90399580+luschmar@users.noreply.github.com>

group_vars/matrix_servers

@@ -429,6 +429,13 @@ devture_systemd_service_manager_services_list_auto: |
       'groups': ['matrix', 'bridges', 'hookshot', 'bridge-hookshot'],
     }] if matrix_hookshot_enabled else [])
     +
+    ([{
+      'name': 'matrix-meshtastic-relay.service',
+      'priority': 2000,
+      'restart_necessary': (matrix_meshtastic_relay_restart_necessary | bool),
+      'groups': ['matrix', 'bridges', 'meshtastic-relay'],
+    }] if matrix_meshtastic_relay_enabled else [])
+    +
     ([{
       'name': 'matrix-mautrix-bluesky.service',
       'priority': 2000,
@@ -2489,6 +2496,39 @@ matrix_hookshot_public_hostname: "{{ matrix_server_fqn_matrix }}"
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-bridge-meshtastic-relay
+#
+######################################################################
+
+# We don't enable bridges by default.
+matrix_meshtastic_relay_enabled: false
+
+matrix_meshtastic_relay_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_meshtastic_relay_container_image_registry_prefix_upstream_default }}"
+
+matrix_meshtastic_relay_matrix_host: "{{ matrix_domain }}"
+
+matrix_meshtastic_relay_matrix_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+
+matrix_meshtastic_relay_container_network: "{{ matrix_addons_container_network }}"
+
+matrix_meshtastic_relay_systemd_required_services_list_auto: |
+  {{
+    matrix_addons_homeserver_systemd_services_list
+  }}
+
+matrix_meshtastic_relay_container_additional_networks_auto: |
+  {{
+    ([] if matrix_addons_homeserver_container_network == '' or matrix_addons_homeserver_container_network == matrix_meshtastic_relay_container_network else [matrix_addons_homeserver_container_network])
+  }}
+
+######################################################################
+#
+# /matrix-bridge-meshtastic-relay
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-bridge-mx-puppet-steam

roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml

@@ -0,0 +1,198 @@
+# SPDX-FileCopyrightText: 2025 - 2026 luschmar
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+# matrix-meshtastic-relay is a Matrix <-> Meshtastic bridge.
+# Project source code URL: https://github.com/jeremiah-k/meshtastic-matrix-relay
+
+matrix_meshtastic_relay_enabled: true
+
+# renovate: datasource=docker depName=jeremiah-k/mmrelay packageName=ghcr.io/jeremiah-k/mmrelay
+matrix_meshtastic_relay_version: 1.2.8
+matrix_meshtastic_relay_container_image: "{{ matrix_meshtastic_relay_container_image_registry_prefix }}jeremiah-k/mmrelay:{{ matrix_meshtastic_relay_version }}"
+matrix_meshtastic_relay_container_image_registry_prefix: "{{ matrix_meshtastic_relay_container_image_registry_prefix_upstream }}"
+matrix_meshtastic_relay_container_image_registry_prefix_upstream: "{{ matrix_meshtastic_relay_container_image_registry_prefix_upstream_default }}"
+matrix_meshtastic_relay_container_image_registry_prefix_upstream_default: "ghcr.io/"
+matrix_meshtastic_relay_container_image_force_pull: "{{ matrix_meshtastic_relay_container_image.endswith(':latest') }}"
+
+matrix_meshtastic_relay_base_path: "{{ matrix_base_data_path }}/meshtastic-relay"
+matrix_meshtastic_relay_config_path: "{{ matrix_meshtastic_relay_base_path }}/config"
+matrix_meshtastic_relay_data_path: "{{ matrix_meshtastic_relay_base_path }}/data"
+matrix_meshtastic_relay_logs_path: "{{ matrix_meshtastic_relay_base_path }}/logs"
+
+matrix_meshtastic_relay_container_network: ""
+
+matrix_meshtastic_relay_container_additional_networks: "{{ matrix_meshtastic_relay_container_additional_networks_auto + matrix_meshtastic_relay_container_additional_networks_custom }}"
+matrix_meshtastic_relay_container_additional_networks_auto: []
+matrix_meshtastic_relay_container_additional_networks_custom: []
+
+# A list of extra arguments to pass to the container
+matrix_meshtastic_relay_container_extra_arguments: []
+
+# List of systemd services that matrix-meshtastic-relay.service depends on.
+matrix_meshtastic_relay_systemd_required_services_list: "{{ matrix_meshtastic_relay_systemd_required_services_list_default + matrix_meshtastic_relay_systemd_required_services_list_auto + matrix_meshtastic_relay_systemd_required_services_list_custom }}"
+matrix_meshtastic_relay_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+matrix_meshtastic_relay_systemd_required_services_list_auto: []
+matrix_meshtastic_relay_systemd_required_services_list_custom: []
+
+# List of systemd services that matrix-meshtastic-relay.service wants
+matrix_meshtastic_relay_systemd_wanted_services_list: []
+
+# Hostname of the Matrix homeserver the bot connects to.
+matrix_meshtastic_relay_matrix_host: ""
+
+# URL of the Matrix homeserver the bot connects to.
+matrix_meshtastic_relay_matrix_homeserver_url: "https://{{ matrix_meshtastic_relay_matrix_host }}"
+
+# Fully-qualified Matrix ID of the bot user.
+matrix_meshtastic_relay_matrix_bot_user_id: "@meshtasticbot:{{ matrix_meshtastic_relay_matrix_host }}"
+
+# Password for the bot's Matrix account.
+# On first startup, mmrelay uses this to log in and persist credentials (including E2EE
+# material) under `{{ matrix_meshtastic_relay_data_path }}`. After that, the password
+# can (and should) be cleared from configuration.
+matrix_meshtastic_relay_matrix_bot_password: ""
+
+# Controls whether End-to-End Encryption is enabled.
+# Requires password-based login on first start so that mmrelay can create `credentials.json`.
+matrix_meshtastic_relay_e2ee_enabled: true
+
+# Connection type to the Meshtastic device. One of: "tcp", "serial", "ble".
+matrix_meshtastic_relay_connection_type: ""
+
+# For `tcp` connection type: hostname/IP of the Meshtastic device to connect to.
+matrix_meshtastic_relay_tcp_host: "meshtastic.local"
+
+# For `serial` connection type: path of the serial device to connect to.
+# This device is passed through to the container. The host must have it available.
+matrix_meshtastic_relay_serial_port: "/dev/ttyUSB0"
+
+# For `ble` connection type: BLE MAC address of the Meshtastic device to connect to.
+# BLE requires `--network=host` and a DBus bind-mount (see the systemd service template).
+matrix_meshtastic_relay_ble_address: "AA:BB:CC:DD:EE:FF"
+
+# Display name of the Meshtastic network.
+matrix_meshtastic_relay_meshnet_name: "MediumFast"
+
+# Whether relaying from Matrix to Meshtastic is enabled.
+matrix_meshtastic_relay_meshtastic_broadcast_enabled: true
+
+# Matrix rooms to bridge to Meshtastic channels.
+# Each entry should have an `id` (Matrix room alias or room ID) and a `meshtastic_channel`.
+matrix_meshtastic_relay_matrix_rooms_list:
+  - id: "#meshtastic:{{ matrix_meshtastic_relay_matrix_host }}"
+    meshtastic_channel: "0"
+
+# Whether plugins should only respond when the bot is explicitly mentioned.
+matrix_meshtastic_relay_plugin_global_require_bot_mention: true
+
+# Enabled built-in ("core") plugins.
+# See: https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki/Core-Plugins
+matrix_meshtastic_relay_plugins_ping_enabled: true
+matrix_meshtastic_relay_plugins_health_enabled: true
+matrix_meshtastic_relay_plugins_weather_enabled: true
+matrix_meshtastic_relay_plugins_weather_units: metric
+matrix_meshtastic_relay_plugins_telemetry_enabled: true
+matrix_meshtastic_relay_plugins_map_enabled: true
+matrix_meshtastic_relay_plugins_nodes_enabled: true
+
+# Default configuration passed to the bridge via config.yaml.
+# See `../templates/config.yaml.j2` for what's rendered.
+# Use `matrix_meshtastic_relay_configuration_extension_yaml` to override
+# specific values or add/remove keys without having to maintain a full copy here.
+matrix_meshtastic_relay_configuration_default:
+  matrix:
+    homeserver: "{{ matrix_meshtastic_relay_matrix_homeserver_url }}"
+    password: "{{ matrix_meshtastic_relay_matrix_bot_password }}"
+    bot_user_id: "{{ matrix_meshtastic_relay_matrix_bot_user_id }}"
+    e2ee:
+      enabled: "{{ matrix_meshtastic_relay_e2ee_enabled }}"
+      store_path: /app/data/store
+  matrix_rooms: "{{ matrix_meshtastic_relay_matrix_rooms_list }}"
+  meshtastic: "{{ matrix_meshtastic_relay_meshtastic_configuration }}"
+  logging:
+    level: info
+    log_to_file: false
+  database:
+    path: /app/data/meshtastic.sqlite
+    enable_wal: true
+    busy_timeout_ms: 5000
+    pragmas:
+      synchronous: NORMAL
+      temp_store: MEMORY
+    msg_map:
+      msgs_to_keep: 500
+      wipe_on_restart: true
+  plugins:
+    require_bot_mention: "{{ matrix_meshtastic_relay_plugin_global_require_bot_mention }}"
+    ping:
+      active: "{{ matrix_meshtastic_relay_plugins_ping_enabled }}"
+    health:
+      active: "{{ matrix_meshtastic_relay_plugins_health_enabled }}"
+    weather:
+      active: "{{ matrix_meshtastic_relay_plugins_weather_enabled }}"
+      units: "{{ matrix_meshtastic_relay_plugins_weather_units }}"
+    telemetry:
+      active: "{{ matrix_meshtastic_relay_plugins_telemetry_enabled }}"
+    map:
+      active: "{{ matrix_meshtastic_relay_plugins_map_enabled }}"
+    nodes:
+      active: "{{ matrix_meshtastic_relay_plugins_nodes_enabled }}"
+
+# Connection-type-specific `meshtastic` configuration block used by
+# `matrix_meshtastic_relay_configuration_default`.
+matrix_meshtastic_relay_meshtastic_configuration: |
+  {{
+    (
+      {'connection_type': 'tcp', 'host': matrix_meshtastic_relay_tcp_host}
+      if matrix_meshtastic_relay_connection_type == 'tcp' else
+      (
+        {'connection_type': 'serial', 'serial_port': matrix_meshtastic_relay_serial_port}
+        if matrix_meshtastic_relay_connection_type == 'serial' else
+        (
+          {'connection_type': 'ble', 'ble_address': matrix_meshtastic_relay_ble_address}
+          if matrix_meshtastic_relay_connection_type == 'ble' else {}
+        )
+      )
+    ) | combine({
+      'meshnet_name': matrix_meshtastic_relay_meshnet_name,
+      'broadcast_enabled': matrix_meshtastic_relay_meshtastic_broadcast_enabled,
+      'message_interactions': {
+        'reactions': false,
+        'replies': false,
+      },
+    })
+  }}
+
+# Holds additional configuration values that get merged into the default
+# configuration (see `matrix_meshtastic_relay_configuration_default`).
+#
+# If you need something more special, you can take full control by changing
+# `matrix_meshtastic_relay_configuration` directly.
+matrix_meshtastic_relay_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_meshtastic_relay_configuration_default`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # redefining `matrix_meshtastic_relay_configuration` directly.
+
+matrix_meshtastic_relay_configuration_extension: "{{ matrix_meshtastic_relay_configuration_extension_yaml | from_yaml if matrix_meshtastic_relay_configuration_extension_yaml | from_yaml is mapping else {} }}"
+
+# Holds the final configuration rendered to `config.yaml`.
+# Normally, you don't need to change this variable — use
+# `matrix_meshtastic_relay_configuration_extension_yaml` instead.
+matrix_meshtastic_relay_configuration: "{{ matrix_meshtastic_relay_configuration_default | combine(matrix_meshtastic_relay_configuration_extension, recursive=True) }}"
+
+# matrix_meshtastic_relay_restart_necessary controls whether the service
+# will be restarted (when true) or merely started (when false) by the
+# systemd service manager role (when conditional restart is enabled).
+#
+# This value is automatically computed during installation based on whether
+# any configuration files, the systemd service file, or the container image changed.
+# The default of `false` means "no restart needed" — appropriate when the role's
+# installation tasks haven't run (e.g., due to --tags skipping them).
+matrix_meshtastic_relay_restart_necessary: false

roles/custom/matrix-bridge-meshtastic-relay/tasks/main.yml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2025 - 2026 luschmar
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- tags:
+    - setup-all
+    - setup-meshtastic-relay
+    - install-all
+    - install-meshtastic-relay
+  block:
+    - when: matrix_meshtastic_relay_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/validate_config.yml"
+
+    - when: matrix_meshtastic_relay_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_install.yml"
+
+- tags:
+    - setup-all
+    - setup-meshtastic-relay
+  block:
+    - when: not matrix_meshtastic_relay_enabled | bool
+      ansible.builtin.include_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"

roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_install.yml

@@ -0,0 +1,63 @@
+# SPDX-FileCopyrightText: 2025 - 2026 luschmar
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Ensure matrix-meshtastic-relay image is pulled
+  community.docker.docker_image:
+    name: "{{ matrix_meshtastic_relay_container_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_meshtastic_relay_container_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_meshtastic_relay_container_image_force_pull }}"
+  register: matrix_meshtastic_relay_container_image_pull_result
+  retries: "{{ devture_playbook_help_container_retries_count }}"
+  delay: "{{ devture_playbook_help_container_retries_delay }}"
+  until: matrix_meshtastic_relay_container_image_pull_result is not failed
+
+- name: Ensure matrix-meshtastic-relay paths exist
+  ansible.builtin.file:
+    path: "{{ item }}"
+    state: directory
+    mode: '0750'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  with_items:
+    - "{{ matrix_meshtastic_relay_base_path }}"
+    - "{{ matrix_meshtastic_relay_config_path }}"
+    - "{{ matrix_meshtastic_relay_data_path }}"
+    - "{{ matrix_meshtastic_relay_logs_path }}"
+
+- name: Ensure matrix-meshtastic-relay config.yaml is installed
+  ansible.builtin.copy:
+    content: "{{ matrix_meshtastic_relay_configuration | to_nice_yaml(indent=2, width=999999) }}"
+    dest: "{{ matrix_meshtastic_relay_config_path }}/config.yaml"
+    mode: '0600'
+    owner: "{{ matrix_user_name }}"
+    group: "{{ matrix_group_name }}"
+  register: matrix_meshtastic_relay_config_result
+
+- name: Ensure matrix-meshtastic-relay container network is created
+  community.general.docker_network:
+    enable_ipv6: "{{ devture_systemd_docker_base_ipv6_enabled }}"
+    name: "{{ matrix_meshtastic_relay_container_network }}"
+    driver: bridge
+    driver_options: "{{ devture_systemd_docker_base_container_networks_driver_options }}"
+  when: "matrix_meshtastic_relay_connection_type != 'ble'"
+
+- name: Ensure matrix-meshtastic-relay.service installed
+  ansible.builtin.template:
+    src: "{{ role_path }}/templates/systemd/matrix-meshtastic-relay.service.j2"
+    dest: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
+    mode: '0644'
+  register: matrix_meshtastic_relay_systemd_service_result
+
+- name: Determine whether matrix-meshtastic-relay needs a restart
+  ansible.builtin.set_fact:
+    matrix_meshtastic_relay_restart_necessary: >-
+      {{
+        matrix_meshtastic_relay_config_result.changed | default(false)
+        or matrix_meshtastic_relay_systemd_service_result.changed | default(false)
+        or matrix_meshtastic_relay_container_image_pull_result.changed | default(false)
+      }}

roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_uninstall.yml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2025 - 2026 luschmar
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Check existence of matrix-meshtastic-relay service
+  ansible.builtin.stat:
+    path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
+  register: matrix_meshtastic_relay_service_stat
+
+- when: matrix_meshtastic_relay_service_stat.stat.exists | bool
+  block:
+    - name: Ensure matrix-meshtastic-relay is stopped
+      ansible.builtin.service:
+        name: matrix-meshtastic-relay
+        state: stopped
+        enabled: false
+        daemon_reload: true
+
+    - name: Ensure matrix-meshtastic-relay.service doesn't exist
+      ansible.builtin.file:
+        path: "{{ devture_systemd_docker_base_systemd_path }}/matrix-meshtastic-relay.service"
+        state: absent

roles/custom/matrix-bridge-meshtastic-relay/tasks/validate_config.yml

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2025 - 2026 luschmar
+# SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+
+- name: Fail if required matrix-meshtastic-relay settings not defined
+  ansible.builtin.fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item.name }}`).
+  when: "item.when | bool and lookup('vars', item.name, default='') | string | length == 0"
+  with_items:
+    - {'name': 'matrix_meshtastic_relay_matrix_host', when: true}
+    - {'name': 'matrix_meshtastic_relay_matrix_bot_password', when: true}
+    - {'name': 'matrix_meshtastic_relay_connection_type', when: true}
+
+- name: Fail if matrix_meshtastic_relay_connection_type is invalid
+  ansible.builtin.fail:
+    msg: >-
+      `matrix_meshtastic_relay_connection_type` must be one of: `tcp`, `serial`, `ble`.
+      Got: `{{ matrix_meshtastic_relay_connection_type }}`.
+  when: "matrix_meshtastic_relay_connection_type not in ['tcp', 'serial', 'ble']"

roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2

@@ -0,0 +1,59 @@
+#jinja2: lstrip_blocks: True
+[Unit]
+Description=Matrix <-> Meshtastic bridge
+{% for service in matrix_meshtastic_relay_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_meshtastic_relay_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ devture_systemd_docker_base_systemd_unit_home_path }}"
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-meshtastic-relay
+ExecStartPre=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-meshtastic-relay
+
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} create \
+			--rm \
+			--name=matrix-meshtastic-relay \
+			--log-driver=none \
+			--user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+			--cap-drop=ALL \
+			--read-only \
+			--tmpfs=/tmp:rw,noexec,nosuid,size=50m \
+			--tmpfs=/.cache:rw,noexec,nosuid,size=50m \
+			--mount type=bind,src={{ matrix_meshtastic_relay_config_path }}/config.yaml,dst=/app/config.yaml,ro \
+			--mount type=bind,src={{ matrix_meshtastic_relay_data_path }},dst=/app/data \
+			--mount type=bind,src={{ matrix_meshtastic_relay_logs_path }},dst=/app/logs \
+			{% if matrix_meshtastic_relay_connection_type == 'ble' %}
+			--network=host \
+			--security-opt apparmor=unconfined \
+			--mount type=bind,src=/var/run/dbus,dst=/var/run/dbus,ro \
+			{% else %}
+			--network={{ matrix_meshtastic_relay_container_network }} \
+			{% endif %}
+			{% if matrix_meshtastic_relay_connection_type == 'serial' %}
+			--device={{ matrix_meshtastic_relay_serial_port }} \
+			{% endif %}
+			{% for arg in matrix_meshtastic_relay_container_extra_arguments %}
+			{{ arg }} \
+			{% endfor %}
+			{{ matrix_meshtastic_relay_container_image }}
+
+{% for network in matrix_meshtastic_relay_container_additional_networks %}
+ExecStartPre={{ devture_systemd_docker_base_host_command_docker }} network connect {{ network }} matrix-meshtastic-relay
+{% endfor %}
+
+ExecStart={{ devture_systemd_docker_base_host_command_docker }} start --attach matrix-meshtastic-relay
+
+ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-meshtastic-relay
+ExecStop=-{{ devture_systemd_docker_base_host_command_docker }} rm matrix-meshtastic-relay
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-meshtastic-relay
+
+[Install]
+WantedBy=multi-user.target

roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2.license

@@ -0,0 +1,4 @@
+SPDX-FileCopyrightText: 2025 - 2026 luschmar
+SPDX-FileCopyrightText: 2026 Slavi Pantaleev
+
+SPDX-License-Identifier: AGPL-3.0-or-later

setup.yml

@@ -78,6 +78,7 @@
     - custom/matrix-bridge-steam
     - custom/matrix-bridge-heisenbridge
     - custom/matrix-bridge-hookshot
+    - custom/matrix-bridge-meshtastic-relay
     - custom/matrix-bot-matrix-reminder-bot
     - custom/matrix-bot-matrix-registration-bot
     - custom/matrix-bot-maubot