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

# 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_bridge_meshtastic_relay_enabled: true

# renovate: datasource=docker depName=jeremiah-k/mmrelay packageName=ghcr.io/jeremiah-k/mmrelay
matrix_bridge_meshtastic_relay_version: 1.4.1
matrix_bridge_meshtastic_relay_container_image: "{{ matrix_bridge_meshtastic_relay_container_image_registry_prefix }}jeremiah-k/mmrelay:{{ matrix_bridge_meshtastic_relay_version }}"
matrix_bridge_meshtastic_relay_container_image_registry_prefix: "{{ matrix_bridge_meshtastic_relay_container_image_registry_prefix_upstream }}"
matrix_bridge_meshtastic_relay_container_image_registry_prefix_upstream: "{{ matrix_bridge_meshtastic_relay_container_image_registry_prefix_upstream_default }}"
matrix_bridge_meshtastic_relay_container_image_registry_prefix_upstream_default: "ghcr.io/"

matrix_bridge_meshtastic_relay_base_path: "{{ matrix_base_data_path }}/meshtastic-relay"

# Holds the Ansible-managed `config.yaml`. Mounted read-only at `/config` in the
# container; mmrelay is pointed at `/config/config.yaml` via the `--config` CLI flag.
matrix_bridge_meshtastic_relay_config_path: "{{ matrix_bridge_meshtastic_relay_base_path }}/config"

# Runtime data directory. Mounted read-write at `/data` (MMRELAY_HOME) in the container.
# mmrelay auto-creates `database/`, `logs/`, `matrix/` (credentials + E2EE store)
# and `plugins/` subdirectories underneath as needed.
matrix_bridge_meshtastic_relay_data_path: "{{ matrix_bridge_meshtastic_relay_base_path }}/data"

matrix_bridge_meshtastic_relay_container_network: ""

matrix_bridge_meshtastic_relay_container_additional_networks: "{{ matrix_bridge_meshtastic_relay_container_additional_networks_auto + matrix_bridge_meshtastic_relay_container_additional_networks_custom }}"
matrix_bridge_meshtastic_relay_container_additional_networks_auto: []
matrix_bridge_meshtastic_relay_container_additional_networks_custom: []

# A list of extra arguments to pass to the container
matrix_bridge_meshtastic_relay_container_extra_arguments: []

# Controls how long the pre-start cleanup should wait for stale container-name release
# before failing startup explicitly.
matrix_bridge_meshtastic_relay_container_cleanup_timeout_seconds: "{{ devture_systemd_docker_base_container_cleanup_timeout_seconds }}"

# Controls the delay between pre-start cleanup retries.
matrix_bridge_meshtastic_relay_container_cleanup_retry_delay_seconds: "{{ devture_systemd_docker_base_container_cleanup_retry_delay_seconds }}"

# Shell command used in the systemd pre-start phase to deterministically remove a stale
# container and wait until Docker releases its name.
matrix_bridge_meshtastic_relay_container_cleanup_command: |
  i=0;
  while [ "$i" -lt {{ matrix_bridge_meshtastic_relay_container_cleanup_timeout_seconds }} ]; do
  {{ devture_systemd_docker_base_host_command_docker }} stop -t {{ devture_systemd_docker_base_container_stop_grace_time_seconds }} matrix-meshtastic-relay >/dev/null 2>&1 || true;
  {{ devture_systemd_docker_base_host_command_docker }} rm -f matrix-meshtastic-relay >/dev/null 2>&1 || true;
  if {{ devture_systemd_docker_base_host_command_docker }} container inspect matrix-meshtastic-relay >/dev/null 2>&1; then
  i=$((i + 1));
  sleep {{ matrix_bridge_meshtastic_relay_container_cleanup_retry_delay_seconds }};
  continue;
  fi;
  if {{ devture_systemd_docker_base_host_command_docker }} info >/dev/null 2>&1; then
  exit 0;
  fi;
  echo "Failed to query Docker daemon while cleaning up matrix-meshtastic-relay" >&2;
  exit 1;
  done;
  echo "Failed to remove stale container matrix-meshtastic-relay after {{ matrix_bridge_meshtastic_relay_container_cleanup_timeout_seconds }} attempts" >&2;
  exit 1

# List of systemd services that matrix-meshtastic-relay.service depends on.
matrix_bridge_meshtastic_relay_systemd_required_services_list: "{{ matrix_bridge_meshtastic_relay_systemd_required_services_list_default + matrix_bridge_meshtastic_relay_systemd_required_services_list_auto + matrix_bridge_meshtastic_relay_systemd_required_services_list_custom }}"
matrix_bridge_meshtastic_relay_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
matrix_bridge_meshtastic_relay_systemd_required_services_list_auto: []
matrix_bridge_meshtastic_relay_systemd_required_services_list_custom: []

# List of systemd services that matrix-meshtastic-relay.service wants
matrix_bridge_meshtastic_relay_systemd_wanted_services_list: []

# Hostname of the Matrix homeserver the bot connects to.
matrix_bridge_meshtastic_relay_matrix_host: ""

# URL of the Matrix homeserver the bot connects to.
matrix_bridge_meshtastic_relay_matrix_homeserver_url: "https://{{ matrix_bridge_meshtastic_relay_matrix_host }}"

# Fully-qualified Matrix ID of the bot user.
matrix_bridge_meshtastic_relay_matrix_bot_user_id: "@meshtasticbot:{{ matrix_bridge_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_bridge_meshtastic_relay_data_path }}/matrix/` on the host. After
# that, the password can (and should) be cleared from configuration.
matrix_bridge_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_bridge_meshtastic_relay_e2ee_enabled: true

# Connection type to the Meshtastic device. One of: "tcp", "serial", "ble".
matrix_bridge_meshtastic_relay_connection_type: ""

# For `tcp` connection type: hostname/IP of the Meshtastic device to connect to.
matrix_bridge_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_bridge_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_bridge_meshtastic_relay_ble_address: "AA:BB:CC:DD:EE:FF"

# Display name of the Meshtastic network.
matrix_bridge_meshtastic_relay_meshnet_name: "MediumFast"

# Whether relaying from Matrix to Meshtastic is enabled.
matrix_bridge_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_bridge_meshtastic_relay_matrix_rooms_list:
  - id: "#meshtastic:{{ matrix_bridge_meshtastic_relay_matrix_host }}"
    meshtastic_channel: "0"

# Whether plugins should only respond when the bot is explicitly mentioned.
matrix_bridge_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_bridge_meshtastic_relay_plugins_ping_enabled: true
matrix_bridge_meshtastic_relay_plugins_health_enabled: true
matrix_bridge_meshtastic_relay_plugins_weather_enabled: true
matrix_bridge_meshtastic_relay_plugins_weather_units: metric
matrix_bridge_meshtastic_relay_plugins_telemetry_enabled: true
matrix_bridge_meshtastic_relay_plugins_map_enabled: true
matrix_bridge_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_bridge_meshtastic_relay_configuration_extension_yaml` to override
# specific values or add/remove keys without having to maintain a full copy here.
matrix_bridge_meshtastic_relay_configuration_default:
  matrix:
    homeserver: "{{ matrix_bridge_meshtastic_relay_matrix_homeserver_url }}"
    password: "{{ matrix_bridge_meshtastic_relay_matrix_bot_password }}"
    bot_user_id: "{{ matrix_bridge_meshtastic_relay_matrix_bot_user_id }}"
    e2ee:
      enabled: "{{ matrix_bridge_meshtastic_relay_e2ee_enabled }}"
  matrix_rooms: "{{ matrix_bridge_meshtastic_relay_matrix_rooms_list }}"
  meshtastic: "{{ matrix_bridge_meshtastic_relay_meshtastic_configuration }}"
  logging:
    level: info
    log_to_file: false
  database:
    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_bridge_meshtastic_relay_plugin_global_require_bot_mention }}"
    ping:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_ping_enabled }}"
    health:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_health_enabled }}"
    weather:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_weather_enabled }}"
      units: "{{ matrix_bridge_meshtastic_relay_plugins_weather_units }}"
    telemetry:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_telemetry_enabled }}"
    map:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_map_enabled }}"
    nodes:
      active: "{{ matrix_bridge_meshtastic_relay_plugins_nodes_enabled }}"

# Connection-type-specific `meshtastic` configuration block used by
# `matrix_bridge_meshtastic_relay_configuration_default`.
matrix_bridge_meshtastic_relay_meshtastic_configuration: |
  {{
    (
      {'connection_type': 'tcp', 'host': matrix_bridge_meshtastic_relay_tcp_host}
      if matrix_bridge_meshtastic_relay_connection_type == 'tcp' else
      (
        {'connection_type': 'serial', 'serial_port': matrix_bridge_meshtastic_relay_serial_port}
        if matrix_bridge_meshtastic_relay_connection_type == 'serial' else
        (
          {'connection_type': 'ble', 'ble_address': matrix_bridge_meshtastic_relay_ble_address}
          if matrix_bridge_meshtastic_relay_connection_type == 'ble' else {}
        )
      )
    ) | combine({
      'meshnet_name': matrix_bridge_meshtastic_relay_meshnet_name,
      'broadcast_enabled': matrix_bridge_meshtastic_relay_meshtastic_broadcast_enabled,
      'message_interactions': {
        'reactions': false,
        'replies': false,
      },
    })
  }}

# Holds additional configuration values that get merged into the default
# configuration (see `matrix_bridge_meshtastic_relay_configuration_default`).
#
# If you need something more special, you can take full control by changing
# `matrix_bridge_meshtastic_relay_configuration` directly.
matrix_bridge_meshtastic_relay_configuration_extension_yaml: |
  # Your custom YAML configuration goes here.
  # This configuration extends the default starting configuration (`matrix_bridge_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_bridge_meshtastic_relay_configuration` directly.

matrix_bridge_meshtastic_relay_configuration_extension: "{{ matrix_bridge_meshtastic_relay_configuration_extension_yaml | from_yaml if matrix_bridge_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_bridge_meshtastic_relay_configuration_extension_yaml` instead.
matrix_bridge_meshtastic_relay_configuration: "{{ matrix_bridge_meshtastic_relay_configuration_default | combine(matrix_bridge_meshtastic_relay_configuration_extension, recursive=True) }}"

# matrix_bridge_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_bridge_meshtastic_relay_restart_necessary: false