scietex.vfd-service 0.1.0__tar.gz

scietex_vfd_service-0.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_vfd_service-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: scietex.vfd_service
+Version: 0.1.0
+Summary: Scietex microservice daemon for variable frequency drive monitoring and control
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.vfd_service/issues
+Project-URL: Homepage, https://github.com/bond-anton/scietex.vfd_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.service[valkey]~=6.2.0
+Requires-Dist: scietex.hal.vfd<3.0.0,>=2.0.0
+Requires-Dist: pymodbus~=3.15
+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.vfd_service
+
+Scietex microservice daemon for variable frequency drive (VFD) monitoring and
+control.
+
+The service drives one or more VFDs through the Scietex Modbus gateway. Each
+drive is handled by a driver from
+[`scietex.hal.vfd`](https://github.com/bond-anton/scietex.hal.vfd), selected by
+entry point name in the service configuration. The service polls each drive on
+its own long-lived task, publishes readings to a per-drive Valkey stream, and
+exposes control tasks (`vfd:start`, `vfd:stop`, `vfd:set-frequency`,
+`vfd:clear-error`) on the data lane.
+
+## Supported drives
+
+| Driver entry point | Drive | Temperature reading |
+| --- | --- | --- |
+| `intek_spe_b_modbus` | Intek SPE-B | none (overheat is a fault code) |
+| `vesper_e5_8200_modbus` | Vesper E5-8200 | none (overheat is a fault code) |
+| `vesper_e4_8400_modbus` | Vesper E4-8400 / E4-P8402 | power-module temperature (U1-46) |
+
+The gateway descriptors (`intek_spe_b`, `vesper_e5_8200`, `vesper_e4_8400`)
+live under the `scietex.modbus.drivers` group and are registered with the
+gateway, not with this service. The `_modbus` suffix distinguishes the HAL
+driver entry points from the gateway descriptors.
+
+## Configuration
+
+The service reads `vfd/vfd.yml` under the framework config directory
+(`SCIETEX_CONFIG_DIR`, default `/config` in the container). The file is created
+with defaults on first start.
+
+```yaml
+gateway:
+  host: 127.0.0.1
+  port: 15020
+  timeout: 1.0
+drives:
+  - label: pump
+    driver: intek_spe_b_modbus
+    unit_id: 1
+    poll_interval: 1.0
+    # max_frequency_hz: 50.0
+failure_threshold: 3
+stream_maxlen: 10000
+```
+
+- `gateway` — Modbus/TCP endpoint of the Scietex Modbus gateway.
+- `drives[].label` — unique label; the registry key and the stream key segment.
+- `drives[].driver` — HAL driver entry point name (see the table above).
+- `drives[].unit_id` — Modbus unit id the gateway routes to the drive. This is
+  the drive's own configured address (`Pd.02` on SPE-B, `09-00` on E5-8200,
+  `H5-01` on E4-8400).
+- `drives[].poll_interval` — seconds between reads.
+- `drives[].max_frequency_hz` — optional. Only meaningful for a drive whose
+  protocol does not expose its configured maximum output frequency; the driver
+  uses it to derive `frequency_percent` and to bound `set_frequency`. Omit it to
+  keep the driver's own default (SPE-B reads `P0.10` from the drive, E4-8400
+  reads `E1-04`; E5-8200 falls back to 50 Hz).
+- `failure_threshold` — consecutive failed reads before a drive is reported as
+  disconnected. One dropped frame on an RS485 segment must not flip the status.
+- `stream_maxlen` — entries retained per drive's readings stream.
+
+A configuration change at runtime is **restart-required**: the drive registry is
+not live-rebuilt.
+
+## Tasks
+
+Control lane:
+
+- `monitoring:start` / `monitoring:stop` — payload `{"label": "pump"}` or empty
+  for every drive.
+
+Data lane:
+
+- `vfd:read` — payload `{"label": "pump"}`. Returns every parameter field plus
+  the decoded fault (`error_code`, `error_message`).
+- `vfd:start` — `{"label": "pump", "forward": true, "slow": false}`.
+- `vfd:stop` — `{"label": "pump", "freewheel": false}`.
+- `vfd:set-frequency` — `{"label": "pump", "frequency_hz": 42.5}`.
+- `vfd:clear-error` — `{"label": "pump", "comm": false}`.
+
+Every control task is gated on the drive's declared capabilities, so an
+unsupported command is rejected as `UNSUPPORTED` before the driver is called.
+`vfd:read` is ungated.
+
+## Valkey keys
+
+- Readings stream: `scietex:{service}:{instance_id}:vfd:{label}:readings`
+  with fields `ts`, `frequency_hz`, `frequency_percent`, `output_current`,
+  `output_voltage`, `output_power`, `dc_bus_voltage`, `heatsink_temperature_c`,
+  `motor_temperature_c`, `state`. A field the drive does not report is written
+  as an empty value, which is distinguishable from a reported `0.0`.
+- Telemetry: `scietex:{service}:{instance_id}:telemetry`, pushed every 2 s with
+  a 6 s TTL.
+
+## Running
+
+```bash
+start-vfd-service --conf-dir /etc/scietex
+```
+
+Flags: `--conf-dir` (auto-resolved when omitted), `--service-name` (default
+`$SCIETEX_SERVICE_NAME` or `VFD`), `--logging-level` (default
+`$SCIETEX_LOGGING_LEVEL` or `INFO`). It runs in the foreground until `SIGINT` or
+`SIGTERM`.
+
+## Development
+
+```bash
+uv venv --python 3.14 .venv
+uv pip install -e ".[dev,test,lint]" --python .venv/bin/python
+tox -e format,lint,type,test
+```
+
+## Container
+
+```bash
+./build_image.sh [--latest]
+```
+
+Builds and pushes `registry.buro-nts.ru/scietex-vfd-service:<version>` for
+`linux/amd64` and `linux/arm64`. The image installs the released wheel from
+PyPI, so publish the version first.
+
+## Deployment prerequisites
+
+The gateway speaks 8-N-1 on its serial port. Each drive must be configured to
+match before the gateway can talk to it:
+
+- **Intek SPE-B** — `Pd.01` → `3` (8-N-1), `Pd.05` → `1` (standard Modbus),
+  `Pd.02` → the unit id used in `vfd.yml`.
+- **Vesper E5-8200** — `09-01` → `0` (RTU), `09-03` → `0` (1 stop bit),
+  `09-04` → `0` (no parity), `09-05` → `0` (8 data bits), `09-00` → the unit id.
+- **Vesper E4-8400** — `H5-08` → `0` (RTU), `H5-09` → `0` (1 stop bit),
+  `H5-10` → `0` (8 data bits), `H5-03` → `0` (no parity), `H5-01` → the unit id.
+
+The drive must also accept its setpoint from the communication channel
+(`P0.03` = `9` on SPE-B, `b1-01`/`b1-02` = `2` on E4-8400). See the HAL
+protocol docs for the full register maps.

scietex_vfd_service-0.1.0/README.md

@@ -0,0 +1,140 @@
+# scietex.vfd_service
+
+Scietex microservice daemon for variable frequency drive (VFD) monitoring and
+control.
+
+The service drives one or more VFDs through the Scietex Modbus gateway. Each
+drive is handled by a driver from
+[`scietex.hal.vfd`](https://github.com/bond-anton/scietex.hal.vfd), selected by
+entry point name in the service configuration. The service polls each drive on
+its own long-lived task, publishes readings to a per-drive Valkey stream, and
+exposes control tasks (`vfd:start`, `vfd:stop`, `vfd:set-frequency`,
+`vfd:clear-error`) on the data lane.
+
+## Supported drives
+
+| Driver entry point | Drive | Temperature reading |
+| --- | --- | --- |
+| `intek_spe_b_modbus` | Intek SPE-B | none (overheat is a fault code) |
+| `vesper_e5_8200_modbus` | Vesper E5-8200 | none (overheat is a fault code) |
+| `vesper_e4_8400_modbus` | Vesper E4-8400 / E4-P8402 | power-module temperature (U1-46) |
+
+The gateway descriptors (`intek_spe_b`, `vesper_e5_8200`, `vesper_e4_8400`)
+live under the `scietex.modbus.drivers` group and are registered with the
+gateway, not with this service. The `_modbus` suffix distinguishes the HAL
+driver entry points from the gateway descriptors.
+
+## Configuration
+
+The service reads `vfd/vfd.yml` under the framework config directory
+(`SCIETEX_CONFIG_DIR`, default `/config` in the container). The file is created
+with defaults on first start.
+
+```yaml
+gateway:
+  host: 127.0.0.1
+  port: 15020
+  timeout: 1.0
+drives:
+  - label: pump
+    driver: intek_spe_b_modbus
+    unit_id: 1
+    poll_interval: 1.0
+    # max_frequency_hz: 50.0
+failure_threshold: 3
+stream_maxlen: 10000
+```
+
+- `gateway` — Modbus/TCP endpoint of the Scietex Modbus gateway.
+- `drives[].label` — unique label; the registry key and the stream key segment.
+- `drives[].driver` — HAL driver entry point name (see the table above).
+- `drives[].unit_id` — Modbus unit id the gateway routes to the drive. This is
+  the drive's own configured address (`Pd.02` on SPE-B, `09-00` on E5-8200,
+  `H5-01` on E4-8400).
+- `drives[].poll_interval` — seconds between reads.
+- `drives[].max_frequency_hz` — optional. Only meaningful for a drive whose
+  protocol does not expose its configured maximum output frequency; the driver
+  uses it to derive `frequency_percent` and to bound `set_frequency`. Omit it to
+  keep the driver's own default (SPE-B reads `P0.10` from the drive, E4-8400
+  reads `E1-04`; E5-8200 falls back to 50 Hz).
+- `failure_threshold` — consecutive failed reads before a drive is reported as
+  disconnected. One dropped frame on an RS485 segment must not flip the status.
+- `stream_maxlen` — entries retained per drive's readings stream.
+
+A configuration change at runtime is **restart-required**: the drive registry is
+not live-rebuilt.
+
+## Tasks
+
+Control lane:
+
+- `monitoring:start` / `monitoring:stop` — payload `{"label": "pump"}` or empty
+  for every drive.
+
+Data lane:
+
+- `vfd:read` — payload `{"label": "pump"}`. Returns every parameter field plus
+  the decoded fault (`error_code`, `error_message`).
+- `vfd:start` — `{"label": "pump", "forward": true, "slow": false}`.
+- `vfd:stop` — `{"label": "pump", "freewheel": false}`.
+- `vfd:set-frequency` — `{"label": "pump", "frequency_hz": 42.5}`.
+- `vfd:clear-error` — `{"label": "pump", "comm": false}`.
+
+Every control task is gated on the drive's declared capabilities, so an
+unsupported command is rejected as `UNSUPPORTED` before the driver is called.
+`vfd:read` is ungated.
+
+## Valkey keys
+
+- Readings stream: `scietex:{service}:{instance_id}:vfd:{label}:readings`
+  with fields `ts`, `frequency_hz`, `frequency_percent`, `output_current`,
+  `output_voltage`, `output_power`, `dc_bus_voltage`, `heatsink_temperature_c`,
+  `motor_temperature_c`, `state`. A field the drive does not report is written
+  as an empty value, which is distinguishable from a reported `0.0`.
+- Telemetry: `scietex:{service}:{instance_id}:telemetry`, pushed every 2 s with
+  a 6 s TTL.
+
+## Running
+
+```bash
+start-vfd-service --conf-dir /etc/scietex
+```
+
+Flags: `--conf-dir` (auto-resolved when omitted), `--service-name` (default
+`$SCIETEX_SERVICE_NAME` or `VFD`), `--logging-level` (default
+`$SCIETEX_LOGGING_LEVEL` or `INFO`). It runs in the foreground until `SIGINT` or
+`SIGTERM`.
+
+## Development
+
+```bash
+uv venv --python 3.14 .venv
+uv pip install -e ".[dev,test,lint]" --python .venv/bin/python
+tox -e format,lint,type,test
+```
+
+## Container
+
+```bash
+./build_image.sh [--latest]
+```
+
+Builds and pushes `registry.buro-nts.ru/scietex-vfd-service:<version>` for
+`linux/amd64` and `linux/arm64`. The image installs the released wheel from
+PyPI, so publish the version first.
+
+## Deployment prerequisites
+
+The gateway speaks 8-N-1 on its serial port. Each drive must be configured to
+match before the gateway can talk to it:
+
+- **Intek SPE-B** — `Pd.01` → `3` (8-N-1), `Pd.05` → `1` (standard Modbus),
+  `Pd.02` → the unit id used in `vfd.yml`.
+- **Vesper E5-8200** — `09-01` → `0` (RTU), `09-03` → `0` (1 stop bit),
+  `09-04` → `0` (no parity), `09-05` → `0` (8 data bits), `09-00` → the unit id.
+- **Vesper E4-8400** — `H5-08` → `0` (RTU), `H5-09` → `0` (1 stop bit),
+  `H5-10` → `0` (8 data bits), `H5-03` → `0` (no parity), `H5-01` → the unit id.
+
+The drive must also accept its setpoint from the communication channel
+(`P0.03` = `9` on SPE-B, `b1-01`/`b1-02` = `2` on E4-8400). See the HAL
+protocol docs for the full register maps.

scietex_vfd_service-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "scietex.vfd_service"
+description = "Scietex microservice daemon for variable frequency drive monitoring and control"
+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.service[valkey]~=6.2.0",
+  "scietex.hal.vfd>=2.0.0,<3.0.0",
+  "pymodbus~=3.15",
+]
+dynamic = ["version"]
+
+[project.urls]
+"Bug Tracker" = "https://github.com/bond-anton/scietex.vfd_service/issues"
+"Homepage" = "https://github.com/bond-anton/scietex.vfd_service"
+
+[project.scripts]
+start-vfd-service = "scietex.vfd_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.vfd_service.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.vfd_service" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

scietex_vfd_service-0.1.0/setup.cfg

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

scietex_vfd_service-0.1.0/src/scietex/vfd_service/__init__.py

@@ -0,0 +1,27 @@
+"""VFD Service."""
+
+from .config import (
+    VFD_CONFIG_FILE,
+    VFD_CONFIG_SUBDIR,
+    VFD_SECTION,
+    VFD_SETTINGS_DEFAULTS,
+    ModbusGatewaySettings,
+    VFDServiceSettings,
+    VFDSettings,
+    read_vfd_config,
+)
+from .version import __version__
+from .vfd_worker import VFDWorker
+
+__all__ = [
+    "__version__",
+    "VFDWorker",
+    "VFD_SECTION",
+    "VFD_CONFIG_SUBDIR",
+    "VFD_CONFIG_FILE",
+    "VFD_SETTINGS_DEFAULTS",
+    "ModbusGatewaySettings",
+    "VFDServiceSettings",
+    "VFDSettings",
+    "read_vfd_config",
+]

scietex_vfd_service-0.1.0/src/scietex/vfd_service/config.py

@@ -0,0 +1,152 @@
+"""Configuration models and YAML loader for the VFD service.
+
+`VFDServiceSettings` is the concrete constructor (L0) base and the validation
+target for the service's remote configuration. The drive list is a field-level
+map merged onto L0 and overlaid by the remote `vfd` section (L3).
+
+This module is deliberately **not** registered as an L1 bootstrap provider. The
+worker reads `vfd.yml` directly at startup (before `super().initialize()`) and
+uses it only to seed the initial in-memory drive list; the config section is
+registered with `bootstrap=None`, so L1 never enters the layer stack and the
+remote L3 config cleanly replaces it. Trade-off: `config:show` will not display
+it as a layer.
+
+The structs are kept deliberately thin: the drive ``driver`` is an entry point
+name resolved at runtime (e.g. ``intek_spe_b``), so the YAML schema only
+constrains types and unknown fields.
+"""
+
+from pathlib import Path
+
+import msgspec
+
+#: Remote-config section name the settings are registered under.
+VFD_SECTION: str = "vfd"
+
+#: Subdirectory under the shared config dir that namespaces this service's
+#: files. The service-owned ``vfd.yml`` lives here, so services sharing one
+#: config dir cannot collide.
+VFD_CONFIG_SUBDIR: str = "vfd"
+
+#: Filename of the service-owned YAML config file in the config subdirectory.
+VFD_CONFIG_FILE: str = "vfd.yml"
+
+
+class ModbusGatewaySettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Modbus/TCP gateway connection settings.
+
+    The service drives VFDs through the Scietex Modbus gateway, so only the TCP
+    endpoint and the transaction timeout are configurable here.
+    """
+
+    host: str = "127.0.0.1"
+    port: int = 502
+    timeout: float = 1.0
+
+
+class VFDSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Settings for a single variable frequency drive driven by the service.
+
+    ``label`` and ``driver`` are required. ``driver`` is the entry point name of
+    a `scietex.hal.vfd` driver, resolved at runtime, e.g. ``intek_spe_b``.
+
+    ``max_frequency_hz`` is optional and only meaningful for drives whose
+    protocol does not expose their configured maximum output frequency: the
+    driver uses it to derive ``frequency_percent`` and to bound
+    ``set_frequency``. ``None`` leaves the driver's own default in place.
+    """
+
+    label: str
+    driver: str
+    unit_id: int = 1
+    poll_interval: float = 1.0
+    max_frequency_hz: float | None = None
+
+
+class VFDServiceSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Top-level VFD service settings.
+
+    ``failure_threshold`` and ``stream_maxlen`` are service-wide rather than
+    per-drive: every drive on the bus shares the same RS485 segment, so the
+    noise tolerance is a property of the segment, and the readings stream is a
+    retention concern that does not vary by drive.
+    """
+
+    gateway: ModbusGatewaySettings = ModbusGatewaySettings()
+    drives: list[VFDSettings] = msgspec.field(default_factory=list)
+    #: Consecutive failed reads before a drive is reported as disconnected.
+    #: One failed read is common on an RS485 segment, so a single glitch must
+    #: not flip the status icon.
+    failure_threshold: int = 3
+    #: Entries retained per drive's readings stream.
+    stream_maxlen: int = 10000
+
+
+#: Concrete L0 base for the service's configuration merge. A field absent from
+#: every layer, or explicitly cleared with ``null``, resolves to the value here.
+VFD_SETTINGS_DEFAULTS: VFDServiceSettings = VFDServiceSettings()
+
+
+def read_vfd_config(conf_dir: Path | None, *, create_default: bool = True) -> dict[str, object]:
+    """Read the service config from ``vfd/vfd.yml`` under the config directory.
+
+    The service's files are namespaced in a ``vfd/`` subdirectory so they do not
+    collide with other services sharing the framework's single config dir. 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``.
+
+    The return value is the raw ``vfd.yml`` mapping (an L1-style patch). When
+    the file is just created, the builtins of the default struct are returned so
+    the patch is equivalent to an empty override.
+
+    Args:
+        conf_dir: Path to the configuration directory.
+        create_default: Whether to create the directory and write a default
+            ``vfd.yml`` when missing. Default ``True``.
+
+    Returns:
+        The parsed ``vfd.yml`` mapping as a dict, or the builtins of the default
+        `VFDServiceSettings` when the file was just created.
+
+    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 / VFD_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!")
+    vfd_yml = service_dir.joinpath(VFD_CONFIG_FILE)
+    if not vfd_yml.exists():
+        if create_default:
+            settings = VFDServiceSettings()
+            with open(vfd_yml, "wb") as f:
+                f.write(msgspec.yaml.encode(settings))
+            return msgspec.to_builtins(settings)
+        raise RuntimeError(
+            f"VFD configuration file {vfd_yml} does not exist and create_default=False "
+            "(pass create_default=True to generate defaults)."
+        )
+    try:
+        with open(vfd_yml, "rb") as f:
+            patch = msgspec.yaml.decode(f.read(), type=dict)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to parse VFD configuration file {vfd_yml}. Fix the file or remove it to regenerate defaults."
+        ) from exc
+    return patch

scietex_vfd_service-0.1.0/src/scietex/vfd_service/run_worker.py

@@ -0,0 +1,73 @@
+"""Entry point to run the VFD worker as a foreground daemon."""
+
+import argparse
+import asyncio
+import os
+
+from scietex.service import ValkeyWorkerConfig
+
+from .config import VFD_CONFIG_SUBDIR
+from .version import __version__
+from .vfd_worker import VFDWorker
+
+#: Environment fallbacks for the CLI options, so a container can be configured
+#: with ``-e`` without overriding its command. An explicit CLI flag still wins.
+ENV_SERVICE_NAME: str = "SCIETEX_SERVICE_NAME"
+ENV_LOGGING_LEVEL: str = "SCIETEX_LOGGING_LEVEL"
+
+DEFAULT_SERVICE_NAME: str = "VFD"
+DEFAULT_LOGGING_LEVEL: str = "INFO"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the CLI parser with environment-variable fallbacks.
+
+    ``--conf-dir`` defaults to ``None`` so the framework's ``prepare_conf_dir``
+    resolves it (it already honors ``SCIETEX_CONFIG_DIR``); the other options
+    fall back to their environment variables when no flag is given.
+    """
+    parser = argparse.ArgumentParser(description="Run the VFD worker.")
+    parser.add_argument("--conf-dir", default=None, help="Configuration directory (default: auto-resolved)")
+    parser.add_argument(
+        "--service-name",
+        default=os.environ.get(ENV_SERVICE_NAME, DEFAULT_SERVICE_NAME),
+        help=f"Service name (default: ${ENV_SERVICE_NAME} or {DEFAULT_SERVICE_NAME})",
+    )
+    parser.add_argument(
+        "--logging-level",
+        default=os.environ.get(ENV_LOGGING_LEVEL, DEFAULT_LOGGING_LEVEL),
+        help=f"Logging level (default: ${ENV_LOGGING_LEVEL} or {DEFAULT_LOGGING_LEVEL})",
+    )
+    return parser
+
+
+def _build_config(args: argparse.Namespace) -> ValkeyWorkerConfig:
+    """Build the worker config from parsed CLI arguments."""
+    return ValkeyWorkerConfig(
+        service_name=args.service_name,
+        version=__version__,
+        conf_dir=args.conf_dir,
+        logging_level=args.logging_level,
+        remote_config_enabled=True,
+        valkey_config=None,
+        # Namespace the framework snapshot under the same subdir as vfd.yml, so
+        # services sharing one config dir cannot clobber each other's config.
+        config_file=f"{VFD_CONFIG_SUBDIR}/config.yml",
+    )
+
+
+def main() -> None:
+    """Parse CLI arguments and run the VFD worker until exit is requested."""
+    args = _build_parser().parse_args()
+    config = _build_config(args)
+
+    async def run() -> None:
+        worker = VFDWorker(config)
+        await worker.start()
+        await worker.events["exit"].wait()
+
+    asyncio.run(run())
+
+
+if __name__ == "__main__":
+    main()

scietex_vfd_service-0.1.0/src/scietex/vfd_service/task_handlers/__init__.py

@@ -0,0 +1,35 @@
+"""Task handlers served by the VFD worker."""
+
+from .monitoring import (
+    MONITORING_START_TASK_NAME,
+    MONITORING_STOP_TASK_NAME,
+    MonitoringHandler,
+    MonitoringRequest,
+    MonitoringResponse,
+)
+from .vfd_control import (
+    VFD_CLEAR_ERROR_TASK_NAME,
+    VFD_READ_TASK_NAME,
+    VFD_SET_FREQUENCY_TASK_NAME,
+    VFD_START_TASK_NAME,
+    VFD_STOP_TASK_NAME,
+    VFDCommandRequest,
+    VFDCommandResponse,
+    VFDControlHandler,
+)
+
+__all__ = [
+    "MONITORING_START_TASK_NAME",
+    "MONITORING_STOP_TASK_NAME",
+    "VFD_READ_TASK_NAME",
+    "VFD_START_TASK_NAME",
+    "VFD_STOP_TASK_NAME",
+    "VFD_SET_FREQUENCY_TASK_NAME",
+    "VFD_CLEAR_ERROR_TASK_NAME",
+    "MonitoringHandler",
+    "MonitoringRequest",
+    "MonitoringResponse",
+    "VFDControlHandler",
+    "VFDCommandRequest",
+    "VFDCommandResponse",
+]