diff --git a/CHANGELOG.md b/CHANGELOG.md index be7d54b6d..258384262 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # 2026-04-24 +## Support for bridging to Meshtastic via meshtastic-matrix-relay + +Thanks to [luschmar](https://github.com/luschmar), the playbook now supports bridging to [Meshtastic](https://meshtastic.org/) mesh networks via [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) (mmrelay). + +To learn more, see our [Setting up a Matrix <-> Meshtastic bridge](./docs/configuring-playbook-bridge-meshtastic-relay.md) documentation page. + ## (BC Break) mautrix-telegram has been rewritten in Go (bridgev2) The [mautrix-telegram](./docs/configuring-playbook-bridge-mautrix-telegram.md) bridge has been [rewritten in Go](https://mau.fi/blog/2026-04-mautrix-release/) on top of the [bridgev2](https://docs.mau.fi/bridges/go/) architecture. See the [upstream v26.04 release notes](https://github.com/mautrix/telegram/releases/tag/v0.2604.0) for what changed in the bridge itself (shared-portal behavior, management-room state, new features, etc.). diff --git a/README.md b/README.md index bc0e581e8..b84158ba3 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,7 @@ Bridges can be used to connect your Matrix installation with third-party communi | [matrix-steam-bridge](https://github.com/jasonlaguidice/matrix-steam-bridge) | ❌ | Bridge to [Steam](https://steampowered.com/) | [Link](docs/configuring-playbook-bridge-steam.md) | | [matrix-wechat](https://github.com/duo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | [Link](docs/configuring-playbook-bridge-wechat.md) | | [Heisenbridge](https://github.com/hifi/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) | +| [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) | ❌ | Bridge to [Meshtastic](https://meshtastic.org/) mesh networks | [Link](docs/configuring-playbook-bridge-meshtastic-relay.md) | | [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | ❌ | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) | | [mx-puppet-steam](https://codeberg.org/icewind/mx-puppet-steam) | ❌ | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) | | [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) | diff --git a/docs/configuring-playbook-bridge-meshtastic-relay.md b/docs/configuring-playbook-bridge-meshtastic-relay.md new file mode 100644 index 000000000..a337d8ad9 --- /dev/null +++ b/docs/configuring-playbook-bridge-meshtastic-relay.md @@ -0,0 +1,95 @@ + + +# Setting up a Matrix <-> Meshtastic bridge (optional) + +The playbook can install and configure [meshtastic-matrix-relay](https://github.com/jeremiah-k/meshtastic-matrix-relay) (sometimes referred to as `mmrelay`) for you — a bridge between [Matrix](https://matrix.org/) and [Meshtastic](https://meshtastic.org/) mesh networks. + +See the [project's documentation](https://github.com/jeremiah-k/meshtastic-matrix-relay) to learn what it does and why it might be useful to you. + +## Prerequisites + +You need a Matrix account for the bot. You can either [register the bot account manually](registering-users.md) or let the playbook create it when running `ansible-playbook … --tags=ensure-matrix-users-created`. Either way, you'll need the account's **password** to configure the bridge — unlike most other bridges in this playbook, `mmrelay` authenticates with a password and creates its own session (optionally with End-to-End Encryption material). + +You also need access to a Meshtastic device, connected to the server via one of: + +- **TCP**: the device is reachable on the network (e.g. a Meshtastic node running the TCP API), +- **Serial**: the device is plugged in via USB and available on the host (e.g. `/dev/ttyUSB0`), +- **BLE**: the device is reachable via Bluetooth Low Energy from the host. + +## Adjusting the playbook configuration + +To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: + +```yaml +matrix_meshtastic_relay_enabled: true + +# Password for the bot's Matrix account. +# On first startup, the bridge uses this to log in and persist credentials +# (including End-to-End Encryption material) under its data directory. +# After that, the password can be removed from this variable. +matrix_meshtastic_relay_matrix_bot_password: "PASSWORD_FOR_THE_BOT" + +# How the bridge connects to your Meshtastic device. +# One of: tcp, serial, ble +matrix_meshtastic_relay_connection_type: tcp + +# For connection_type: tcp +matrix_meshtastic_relay_tcp_host: "meshtastic.local" + +# For connection_type: serial +# matrix_meshtastic_relay_serial_port: "/dev/ttyUSB0" + +# For connection_type: ble +# matrix_meshtastic_relay_ble_address: "AA:BB:CC:DD:EE:FF" + +# Matrix rooms to bridge to Meshtastic channels. +matrix_meshtastic_relay_matrix_rooms_list: + - id: "#meshtastic:{{ matrix_domain }}" + meshtastic_channel: "0" +``` + +By default, the bot's Matrix ID is `@meshtasticbot:{{ matrix_domain }}`. To change it, adjust `matrix_meshtastic_relay_matrix_bot_user_id`. + +### Bluetooth (BLE) connections + +When `matrix_meshtastic_relay_connection_type` is `ble`, the container runs with `--network=host` and bind-mounts the host's DBus socket — both are required for Bluetooth pairing/communication. Only use this connection type if you trust the playbook-managed host and are comfortable with these privileges. + +### Serial connections + +When `matrix_meshtastic_relay_connection_type` is `serial`, the host device referenced by `matrix_meshtastic_relay_serial_port` is passed through to the container. Make sure that `matrix_user_uid` / `matrix_user_gid` have read/write access to that device (e.g. by adding the matrix user to the `dialout` group, or adjusting udev rules). + +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +Take a look at: + +- `roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml` for some variables that you can customize via your `vars.yml` file. You can override individual `matrix_meshtastic_relay_*` variables, or make finer-grained adjustments via `matrix_meshtastic_relay_configuration_extension_yaml`. + +## Installing + +After configuring the playbook, run the playbook with [playbook tags](playbook-tags.md) as below: + + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`. + +`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +## Usage + +Invite the bot to the Matrix rooms listed in `matrix_meshtastic_relay_matrix_rooms_list` and it will relay between Matrix and the corresponding Meshtastic channel. Messages sent on Meshtastic will appear in Matrix and vice versa. + +See the [project's wiki](https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki) for details about commands, plugins and advanced usage. + +## Troubleshooting + +As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-meshtastic-relay`. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 112aacbf9..ee4a13731 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -182,6 +182,8 @@ Bridges can be used to connect your Matrix installation with third-party communi - [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md) +- [Setting up a Matrix <-> Meshtastic bridge](configuring-playbook-bridge-meshtastic-relay.md) + - [Setting up WeChat bridging](configuring-playbook-bridge-wechat.md) ### Bots diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index 7a9cd107e..e35122de6 100755 --- a/group_vars/matrix_servers +++ b/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 diff --git a/roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml b/roles/custom/matrix-bridge-meshtastic-relay/defaults/main.yml new file mode 100644 index 000000000..48e14088f --- /dev/null +++ b/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 diff --git a/roles/custom/matrix-bridge-meshtastic-relay/tasks/main.yml b/roles/custom/matrix-bridge-meshtastic-relay/tasks/main.yml new file mode 100644 index 000000000..ae0d63338 --- /dev/null +++ b/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" diff --git a/roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_install.yml b/roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_install.yml new file mode 100644 index 000000000..d0555d42b --- /dev/null +++ b/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) + }} diff --git a/roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_uninstall.yml b/roles/custom/matrix-bridge-meshtastic-relay/tasks/setup_uninstall.yml new file mode 100644 index 000000000..890de619d --- /dev/null +++ b/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 diff --git a/roles/custom/matrix-bridge-meshtastic-relay/tasks/validate_config.yml b/roles/custom/matrix-bridge-meshtastic-relay/tasks/validate_config.yml new file mode 100644 index 000000000..80f31d47f --- /dev/null +++ b/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']" diff --git a/roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2 b/roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2 new file mode 100644 index 000000000..414ddfd55 --- /dev/null +++ b/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 diff --git a/roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2.license b/roles/custom/matrix-bridge-meshtastic-relay/templates/systemd/matrix-meshtastic-relay.service.j2.license new file mode 100644 index 000000000..59b1edbf7 --- /dev/null +++ b/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 diff --git a/setup.yml b/setup.yml index b319b087e..91dc4ea0b 100644 --- a/setup.yml +++ b/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