scietex.modbus-service 1.1.0__tar.gz

scietex_modbus_service-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Bondarenko
+
+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.

scietex_modbus_service-1.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: scietex.modbus_service
+Version: 1.1.0
+Summary: Scietex microservice daemon for MODBUS communication
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.modbus_service/issues
+Project-URL: Homepage, https://github.com/bond-anton/scietex.modbus_service
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scietex.hal.serial>=2.0.2
+Requires-Dist: scietex.service[valkey]~=5.2.0
+Provides-Extra: dev
+Requires-Dist: tox>=4.45.0; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: ty; extra == "lint"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Dynamic: license-file
+
+# scietex.modbus_service
+
+**scietex.modbus_service** is a `scietex.service` worker that runs the
+serial-to-TCP Modbus gateway from
+[`scietex.hal.serial`](https://github.com/bond-anton/scietex.hal.serial). It
+bridges a serial RS485 bus to TCP/IP: TCP clients speak plain Modbus/TCP, and
+the gateway routes each request to the right device on the bus **by device id**.
+
+The worker is a long-running daemon. It owns one serial port and one TCP
+listener, both built once at startup from `modbus.yml` and torn down on
+shutdown. Configuration can also be pushed at runtime through the framework's
+remote-config channel, but the gateway itself is **restart-required** — see
+[Remote configuration](docs/remote-config.md).
+
+**Python ≥ 3.10** · **License: MIT**
+
+## Documentation
+
+- [Overview](docs/index.md) — what the service does and how it fits together
+- [Configuration](docs/configuration.md) — the `modbus.yml` schema and precedence
+- [Deployment](docs/deployment.md) — container, serial device access, port 502
+- [Remote configuration](docs/remote-config.md) — the declarative `modbus` section
+
+## Installation
+
+```bash
+pip install scietex.modbus_service
+```
+
+This pulls in `scietex.hal.serial` (the gateway core) and
+`scietex.service[valkey]` (the worker framework and its Valkey transport).
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `modbus.yml` from a `modbus/` subdirectory of its config
+directory. Create it by hand, or let the service generate defaults on first run:
+
+```yaml
+serial:
+  port: /dev/ttyUSB0
+  baudrate: 9600
+  bytesize: 8
+  parity: N
+  stopbits: 1
+  timeout: null
+host: 0.0.0.0
+port: 502
+default_framer: RTU
+devices:
+  1:
+    framer: RTU
+  2:
+    framer: ASCII
+allow_unknown_devices: false
+bus_retries: 0
+```
+
+`port` at the top level is the **TCP listen port**; `serial.port` is the
+**serial device path**. They are unrelated — do not conflate them.
+
+### 2. Run the service
+
+```bash
+start-modbus-service --conf-dir /etc/scietex
+```
+
+The service resolves its config directory automatically when `--conf-dir` is
+omitted (see [Configuration](docs/configuration.md#config-directory-resolution)).
+It runs in the foreground until it receives `SIGINT` or `SIGTERM`.
+
+### 3. Point a Modbus/TCP client at it
+
+Connect to `host:port` and issue normal Modbus/TCP requests, using the target
+device id as the unit id. No special protocol is required.
+
+## Configuration at a glance
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `serial.port` | `/dev/ttyUSB0` | Serial device path |
+| `serial.baudrate` | `9600` | Bus baud rate |
+| `host` / `port` | `0.0.0.0` / `502` | TCP bind address and port |
+| `default_framer` | `RTU` | Framer for devices without an explicit entry |
+| `devices` | `{}` | Per-device routing table, keyed by device id |
+| `allow_unknown_devices` | `false` | Route unknown ids with the default framer |
+| `bus_retries` | `0` | Retry count for bus transactions |
+
+Full field reference: [Configuration](docs/configuration.md).
+
+## Container
+
+A `Containerfile` is included. It installs the released package from PyPI
+(selected by the `VERSION` build arg), runs as a non-root `appuser` in the
+`dialout` group, mounts `/config`, and sets `SCIETEX_CONFIG_DIR=/config`:
+
+```bash
+podman build --build-arg VERSION=1.1.0 -t scietex-modbus-service .
+podman run --rm \
+  --device /dev/ttyUSB0 \
+  --cap-add NET_BIND_SERVICE \
+  -v ./config:/config \
+  scietex-modbus-service
+```
+
+Port 502 is privileged — binding it needs `--cap-add NET_BIND_SERVICE`, or
+override the port in `modbus.yml`. See [Deployment](docs/deployment.md) for
+details.
+
+## Development
+
+Dependencies are managed with **uv**; checks and tests run through **tox**:
+
+```bash
+uv sync --all-extras
+uv run tox                    # format, lint, type, py314
+uv run tox -e py314           # tests only
+```
+
+See [AGENTS.md](AGENTS.md) for the full toolchain and repo conventions.

scietex_modbus_service-1.1.0/README.md

@@ -0,0 +1,121 @@
+# scietex.modbus_service
+
+**scietex.modbus_service** is a `scietex.service` worker that runs the
+serial-to-TCP Modbus gateway from
+[`scietex.hal.serial`](https://github.com/bond-anton/scietex.hal.serial). It
+bridges a serial RS485 bus to TCP/IP: TCP clients speak plain Modbus/TCP, and
+the gateway routes each request to the right device on the bus **by device id**.
+
+The worker is a long-running daemon. It owns one serial port and one TCP
+listener, both built once at startup from `modbus.yml` and torn down on
+shutdown. Configuration can also be pushed at runtime through the framework's
+remote-config channel, but the gateway itself is **restart-required** — see
+[Remote configuration](docs/remote-config.md).
+
+**Python ≥ 3.10** · **License: MIT**
+
+## Documentation
+
+- [Overview](docs/index.md) — what the service does and how it fits together
+- [Configuration](docs/configuration.md) — the `modbus.yml` schema and precedence
+- [Deployment](docs/deployment.md) — container, serial device access, port 502
+- [Remote configuration](docs/remote-config.md) — the declarative `modbus` section
+
+## Installation
+
+```bash
+pip install scietex.modbus_service
+```
+
+This pulls in `scietex.hal.serial` (the gateway core) and
+`scietex.service[valkey]` (the worker framework and its Valkey transport).
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `modbus.yml` from a `modbus/` subdirectory of its config
+directory. Create it by hand, or let the service generate defaults on first run:
+
+```yaml
+serial:
+  port: /dev/ttyUSB0
+  baudrate: 9600
+  bytesize: 8
+  parity: N
+  stopbits: 1
+  timeout: null
+host: 0.0.0.0
+port: 502
+default_framer: RTU
+devices:
+  1:
+    framer: RTU
+  2:
+    framer: ASCII
+allow_unknown_devices: false
+bus_retries: 0
+```
+
+`port` at the top level is the **TCP listen port**; `serial.port` is the
+**serial device path**. They are unrelated — do not conflate them.
+
+### 2. Run the service
+
+```bash
+start-modbus-service --conf-dir /etc/scietex
+```
+
+The service resolves its config directory automatically when `--conf-dir` is
+omitted (see [Configuration](docs/configuration.md#config-directory-resolution)).
+It runs in the foreground until it receives `SIGINT` or `SIGTERM`.
+
+### 3. Point a Modbus/TCP client at it
+
+Connect to `host:port` and issue normal Modbus/TCP requests, using the target
+device id as the unit id. No special protocol is required.
+
+## Configuration at a glance
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `serial.port` | `/dev/ttyUSB0` | Serial device path |
+| `serial.baudrate` | `9600` | Bus baud rate |
+| `host` / `port` | `0.0.0.0` / `502` | TCP bind address and port |
+| `default_framer` | `RTU` | Framer for devices without an explicit entry |
+| `devices` | `{}` | Per-device routing table, keyed by device id |
+| `allow_unknown_devices` | `false` | Route unknown ids with the default framer |
+| `bus_retries` | `0` | Retry count for bus transactions |
+
+Full field reference: [Configuration](docs/configuration.md).
+
+## Container
+
+A `Containerfile` is included. It installs the released package from PyPI
+(selected by the `VERSION` build arg), runs as a non-root `appuser` in the
+`dialout` group, mounts `/config`, and sets `SCIETEX_CONFIG_DIR=/config`:
+
+```bash
+podman build --build-arg VERSION=1.1.0 -t scietex-modbus-service .
+podman run --rm \
+  --device /dev/ttyUSB0 \
+  --cap-add NET_BIND_SERVICE \
+  -v ./config:/config \
+  scietex-modbus-service
+```
+
+Port 502 is privileged — binding it needs `--cap-add NET_BIND_SERVICE`, or
+override the port in `modbus.yml`. See [Deployment](docs/deployment.md) for
+details.
+
+## Development
+
+Dependencies are managed with **uv**; checks and tests run through **tox**:
+
+```bash
+uv sync --all-extras
+uv run tox                    # format, lint, type, py314
+uv run tox -e py314           # tests only
+```
+
+See [AGENTS.md](AGENTS.md) for the full toolchain and repo conventions.

scietex_modbus_service-1.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "scietex.modbus_service"
+description = "Scietex microservice daemon for MODBUS communication"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+authors = [{ name = "Anton Bondarenko", email = "bond.anton@gmail.com" }]
+classifiers = [
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+]
+dependencies = [
+  "scietex.hal.serial>=2.0.2",
+  "scietex.service[valkey]~=5.2.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+"Bug Tracker" = "https://github.com/bond-anton/scietex.modbus_service/issues"
+"Homepage" = "https://github.com/bond-anton/scietex.modbus_service"
+
+[project.scripts]
+start-modbus-service = "scietex.modbus_service.run_worker:main"
+
+[project.optional-dependencies]
+dev = ["tox>=4.45.0"]
+lint = ["ruff", "ty"]
+test = ["pytest", "pytest-asyncio"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "scietex.modbus_service.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.modbus_service" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

scietex_modbus_service-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scietex_modbus_service-1.1.0/src/scietex/modbus_service/__init__.py

@@ -0,0 +1,23 @@
+"""Modbus Gateway Service."""
+
+from .config import (
+    MODBUS_SECTION,
+    ModbusDeviceSettings,
+    ModbusSerialSettings,
+    ModbusServiceSettings,
+    read_modbus_config,
+    to_gateway_config,
+)
+from .modbus_worker import ModbusWorker
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "ModbusWorker",
+    "MODBUS_SECTION",
+    "ModbusDeviceSettings",
+    "ModbusSerialSettings",
+    "ModbusServiceSettings",
+    "read_modbus_config",
+    "to_gateway_config",
+]

scietex_modbus_service-1.1.0/src/scietex/modbus_service/config.py

@@ -0,0 +1,188 @@
+"""Configuration models and YAML loader for the Modbus gateway service.
+
+`ModbusServiceSettings` is the service-owned bootstrap snapshot stored in
+`modbus.yml` under the config directory. It is kept deliberately thin: device-id
+range, framer resolvability, and plugin dotted-path resolution are delegated to
+`GatewayConfig.__post_init__` via `to_gateway_config`, so the YAML schema only
+constrains types and unknown fields.
+
+The serial settings intentionally omit a ``framer`` field: the gateway selects
+framing per device via `GatewayConfig.default_framer` (and each device's own
+`framer`), so a framer on the serial connection is dead configuration. The
+top-level ``port`` is the TCP listen port, while ``serial.port`` is the device
+path — the two are unrelated and must not be conflated.
+"""
+
+from pathlib import Path
+
+import msgspec
+from scietex.hal.serial import GatewayConfig, GatewayDeviceConfig, ModbusSerialConnectionConfig
+from scietex.hal.serial.config.defaults import (
+    DEFAULT_BAUDRATE,
+    DEFAULT_BYTESIZE,
+    DEFAULT_PARITY,
+    DEFAULT_STOPBITS,
+    DEFAULT_TIMEOUT,
+)
+
+#: Remote-config section name the settings are registered under.
+MODBUS_SECTION: str = "modbus"
+
+#: Subdirectory under the shared config dir that namespaces this service's
+#: files. The framework's ``config.yml`` snapshot and the service-owned
+#: ``modbus.yml`` both live here, so services sharing one config dir (the
+#: framework resolves a single dir for all scietex services) cannot collide.
+MODBUS_CONFIG_SUBDIR: str = "modbus"
+
+#: Filename of the service-owned bootstrap snapshot in the config subdirectory.
+MODBUS_CONFIG_FILE: str = "modbus.yml"
+
+
+class ModbusDeviceSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Per-device routing settings for a single Modbus device id.
+
+    The device id itself is the dict key in `ModbusServiceSettings.devices`, not
+    a field here, so the conversion seam can derive `GatewayDeviceConfig.device_id`
+    from it and satisfy the gateway's ``key == device.device_id`` invariant.
+    """
+
+    framer: str = "RTU"
+    decoder: str | None = None
+    pdus: list[str] = msgspec.field(default_factory=list)
+    translator: str | None = None
+
+
+class ModbusSerialSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Serial bus connection settings.
+
+    ``port`` is the device path (e.g. ``/dev/ttyUSB0``). There is no ``framer``
+    field: the gateway ignores the serial-level framer and selects framing per
+    device from `GatewayConfig.default_framer` / `ModbusDeviceSettings.framer`.
+    """
+
+    port: str = "/dev/ttyUSB0"
+    baudrate: int = DEFAULT_BAUDRATE
+    bytesize: int = DEFAULT_BYTESIZE
+    parity: str = DEFAULT_PARITY
+    stopbits: int | float = DEFAULT_STOPBITS
+    timeout: float | None = DEFAULT_TIMEOUT
+
+
+class ModbusServiceSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Top-level Modbus gateway settings.
+
+    ``port`` is the TCP listen port; ``serial.port`` is the device path. Device
+    entries are keyed by device id so the key becomes the `device_id` when
+    converted to `GatewayDeviceConfig` objects.
+    """
+
+    serial: ModbusSerialSettings = ModbusSerialSettings()
+    host: str = "0.0.0.0"
+    port: int = 502
+    default_framer: str = "RTU"
+    devices: dict[int, ModbusDeviceSettings] = msgspec.field(default_factory=dict)
+    allow_unknown_devices: bool = False
+    bus_retries: int = 0
+
+
+def read_modbus_config(conf_dir: Path | None, *, create_default: bool = True) -> ModbusServiceSettings:
+    """Read Modbus settings from ``modbus/modbus.yml`` under the config directory.
+
+    The service's files are namespaced in a ``modbus/`` subdirectory so they do
+    not collide with other services sharing the framework's single config dir.
+    Mirrors `read_valkey_config` otherwise: the file (and, when missing, its
+    directory) is only created when ``create_default=True`` (the bootstrap path).
+    A ``None`` or non-directory ``conf_dir``, a missing file/directory with
+    ``create_default=False``, or an unparseable file each raise `RuntimeError`.
+    An existing-but-invalid file is left untouched regardless of ``create_default``.
+
+    Args:
+        conf_dir: Path to the configuration directory.
+        create_default: Whether to create the directory and write a default
+            ``modbus.yml`` when missing. Default ``True``.
+
+    Returns:
+        A `ModbusServiceSettings` loaded from ``modbus.yml`` or default values.
+
+    Raises:
+        RuntimeError: If ``conf_dir`` is ``None`` or not a directory, the file
+            is missing with ``create_default=False``, or the file cannot be parsed.
+    """
+    if not isinstance(conf_dir, Path):
+        raise RuntimeError("Configuration dir was not set!")
+    service_dir = conf_dir / MODBUS_CONFIG_SUBDIR
+    if not service_dir.exists():
+        if create_default:
+            try:
+                service_dir.mkdir(parents=True, exist_ok=True)
+            except Exception as exc:
+                raise RuntimeError(f"Failed to create configuration directory {service_dir}!") from exc
+        else:
+            raise RuntimeError(
+                f"Configuration directory {service_dir} does not exist and create_default=False (no default generated)."
+            )
+    elif not service_dir.is_dir():
+        raise RuntimeError(f"Provided configuration directory path {service_dir} is not a directory!")
+    modbus_yml = service_dir.joinpath(MODBUS_CONFIG_FILE)
+    if not modbus_yml.exists():
+        if create_default:
+            settings = ModbusServiceSettings()
+            with open(modbus_yml, "wb") as f:
+                f.write(msgspec.yaml.encode(settings))
+            return settings
+        raise RuntimeError(
+            f"Modbus configuration file {modbus_yml} does not exist and create_default=False "
+            "(pass create_default=True to generate defaults)."
+        )
+    try:
+        with open(modbus_yml, "rb") as f:
+            return msgspec.yaml.decode(f.read(), type=ModbusServiceSettings, strict=True)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to parse Modbus configuration file {modbus_yml}. Fix the file or remove it to regenerate defaults."
+        ) from exc
+
+
+def to_gateway_config(settings: ModbusServiceSettings) -> GatewayConfig:
+    """Convert service settings into a `GatewayConfig` for the gateway core.
+
+    The device id is taken from each dict key so the gateway's invariant
+    (``key == device.device_id``) holds. ``framer`` is intentionally not passed
+    to `ModbusSerialConnectionConfig` — the gateway ignores it. Validation
+    (device-id range, framer/decoder/pdu/translator resolution) is delegated to
+    `GatewayConfig.__post_init__`, so `GatewayConfigError` and
+    `SerialConnectionConfigError` propagate unchanged to the caller.
+
+    Args:
+        settings: The service settings to convert.
+
+    Returns:
+        A `GatewayConfig` ready for `ModbusGateway`.
+    """
+    serial = ModbusSerialConnectionConfig(
+        port=settings.serial.port,
+        baudrate=settings.serial.baudrate,
+        bytesize=settings.serial.bytesize,
+        parity=settings.serial.parity,
+        stopbits=settings.serial.stopbits,
+        timeout=settings.serial.timeout,
+    )
+    devices = {
+        device_id: GatewayDeviceConfig(
+            device_id=device_id,
+            framer=device.framer,
+            decoder=device.decoder,
+            pdus=device.pdus,
+            translator=device.translator,
+        )
+        for device_id, device in settings.devices.items()
+    }
+    return GatewayConfig(
+        serial=serial,
+        host=settings.host,
+        port=settings.port,
+        default_framer=settings.default_framer,
+        devices=devices,
+        allow_unknown_devices=settings.allow_unknown_devices,
+        bus_retries=settings.bus_retries,
+    )

scietex_modbus_service-1.1.0/src/scietex/modbus_service/modbus_worker.py

@@ -0,0 +1,135 @@
+"""Modbus gateway worker: a Valkey-backed service that owns a Modbus gateway.
+
+`ModbusWorker` extends `ValkeyWorker` and fronts a serial Modbus bus with a TCP
+listener. The gateway (serial bus + TCP listener) is built once at startup from
+``modbus.yml`` and torn down at cleanup. The remote-config ``modbus`` section is
+declarative / restart-required: applying it validates and stores the desired
+settings but never live-rebuilds the gateway, because reopening the serial bus
+and rebinding the TCP listener on a running worker is unsafe.
+"""
+
+from scietex.hal.serial import GatewayConfigError, GatewayTcpServer, ModbusGateway
+from scietex.hal.serial.config import SerialConnectionConfigError
+from scietex.service import ValkeyWorker, ValkeyWorkerConfig
+
+from .config import MODBUS_SECTION, ModbusServiceSettings, read_modbus_config, to_gateway_config
+
+
+class ModbusWorker(ValkeyWorker):
+    """A `ValkeyWorker` that runs a serial<->TCP Modbus gateway.
+
+    Settings precedence: constructor default < ``modbus.yml`` < framework
+    ``config.yml`` / remote ``modbus`` section. The gateway is built from the
+    effective settings after the framework applies its local and remote config,
+    so the remote section's apply hook runs before gateway construction.
+    """
+
+    def __init__(self, config: ValkeyWorkerConfig | None = None, *, client_factory=None, theme=None) -> None:
+        super().__init__(config, client_factory=client_factory, theme=theme)
+        self._settings: ModbusServiceSettings | None = None
+        self._gateway: ModbusGateway | None = None
+        self._tcp_server: GatewayTcpServer | None = None
+        self.register_config_settings(MODBUS_SECTION, ModbusServiceSettings, apply=self._apply_modbus_settings)
+
+    @property
+    def gateway(self) -> ModbusGateway | None:
+        """The running `ModbusGateway`, or `None` before startup."""
+        return self._gateway
+
+    @property
+    def tcp_server(self) -> GatewayTcpServer | None:
+        """The running `GatewayTcpServer`, or `None` before startup."""
+        return self._tcp_server
+
+    @property
+    def modbus_settings(self) -> ModbusServiceSettings | None:
+        """The effective Modbus settings, or `None` before startup."""
+        return self._settings
+
+    async def initialize(self) -> bool:
+        """Load settings, initialize the framework, then build and start the gateway.
+
+        The gateway is built after `super().initialize()` so the remote config
+        apply (which runs the ``modbus`` section hook) has already updated
+        ``self._settings`` before the conversion seam reads it. Both the gateway
+        and TCP server references are assigned before either is started, so a
+        mid-start failure still leaves them reachable by `_stop_gateway`.
+
+        Returns:
+            `True` if the framework initialized and the gateway started;
+            `False` on any configuration or startup failure.
+        """
+        try:
+            self._settings = read_modbus_config(self.conf_dir)
+        except RuntimeError as exc:
+            self.logger.error("Failed to load Modbus configuration: %s", exc)
+            return False
+
+        if not await super().initialize():
+            return False
+
+        settings = self._settings
+        if settings is None:
+            self.logger.error("Modbus settings were not resolved before gateway startup")
+            return False
+
+        try:
+            gw_config = to_gateway_config(settings)
+        except (GatewayConfigError, SerialConnectionConfigError) as exc:
+            self.logger.error("Invalid Modbus gateway configuration: %s", exc)
+            return False
+
+        self._gateway = ModbusGateway(gw_config, logger=self.logger)
+        self._tcp_server = GatewayTcpServer(gw_config, self._gateway, logger=self.logger)
+        try:
+            await self._gateway.start()
+            await self._tcp_server.start()
+        except Exception as exc:
+            self.logger.error("Failed to start the Modbus gateway: %s", exc)
+            await self._stop_gateway()
+            return False
+        return True
+
+    async def cleanup(self) -> None:
+        """Tear down the gateway, then the framework resources."""
+        await self._stop_gateway()
+        await super().cleanup()
+
+    async def _stop_gateway(self) -> None:
+        """Stop the TCP server and gateway, nulling refs before awaiting.
+
+        Nulling each reference before awaiting its ``stop()`` makes this
+        idempotent even when ``start()`` failed midway, and guards against a
+        concurrent second cleanup. ``stop()`` errors are logged and swallowed so
+        a teardown failure never aborts shutdown.
+        """
+        tcp_server, self._tcp_server = self._tcp_server, None
+        gateway, self._gateway = self._gateway, None
+        if tcp_server is not None:
+            try:
+                await tcp_server.stop()
+            except Exception as exc:
+                self.logger.warning("Failed to stop the Modbus TCP server: %s", exc)
+        if gateway is not None:
+            try:
+                await gateway.stop()
+            except Exception as exc:
+                self.logger.warning("Failed to stop the Modbus gateway: %s", exc)
+
+    def _apply_modbus_settings(self, settings: ModbusServiceSettings) -> None:
+        """Validate and store remote Modbus settings without rebuilding the gateway.
+
+        The conversion seam validates declaratively: a bad device id, framer, or
+        plugin path raises, which the framework reports as a failed apply. The
+        gateway is not rebuilt here — the serial bus and TCP listener are
+        restart-required — so a running worker only logs that a restart is needed.
+        """
+        to_gateway_config(settings)
+        self._settings = settings
+        if self._gateway is not None:
+            self.logger.warning(
+                "Modbus settings applied; restart required to rebuild the gateway "
+                "(serial port and TCP listener are not live-reloaded)"
+            )
+        else:
+            self.logger.info("Stored Modbus settings for gateway startup")