scietex.gpiod-service 1.2.0__tar.gz

scietex_gpiod_service-1.2.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_gpiod_service-1.2.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: scietex.gpiod_service
+Version: 1.2.0
+Summary: Scietex microservice daemon for GPIO control
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bond-anton/scietex.gpiod_service
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.gpiod_service/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gpiod~=2.5.0; sys_platform == "linux"
+Requires-Dist: msgspec>=0.21.1
+Requires-Dist: scietex.service[valkey]~=6.2.0
+Provides-Extra: dev
+Requires-Dist: tox>=4.54.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: ty; extra == "lint"
+Dynamic: license-file
+
+# scietex.gpiod_service
+
+`scietex.gpiod_service` is a [`scietex.service`](https://github.com/bond-anton/scietex.service)
+worker that owns the host's GPIO lines through
+[libgpiod](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/) v2.
+
+It requests the lines the API tells it to, keeps them requested, and exposes
+their values over Valkey. Configuration is delivered by the API and applied
+**live** — changing a line's direction or bias does not restart the worker.
+
+## Install
+
+```bash
+pip install scietex.gpiod_service
+```
+
+Requires Python 3.13+, Linux, and libgpiod v2 (`gpiod~=2.5.0`).
+
+## Run
+
+```bash
+start-gpiod-service --conf-dir /etc/scietex
+```
+
+| Flag | Environment | Default |
+| --- | --- | --- |
+| `--conf-dir` | `SCIETEX_CONFIG_DIR` | auto-resolved (see below) |
+| `--service-name` | `SCIETEX_SERVICE_NAME` | `GPIODService` |
+| `--logging-level` | `SCIETEX_LOGGING_LEVEL` | `INFO` |
+
+On first run the service creates `<conf-dir>/gpiod/gpiod.yml` with defaults.
+With no chips configured it logs `waiting for remote configuration` and keeps
+running; the API then delivers the real configuration.
+
+`--service-name` must match the managed service name registered in the API — it
+is what discriminates the Valkey config key. Run exactly one worker per
+installation.
+
+## Documentation
+
+| Page | Contents |
+| --- | --- |
+| [Overview](docs/index.md) | What the service does and how it fits together |
+| [Configuration](docs/configuration.md) | The `gpio` section schema, `gpiod.yml`, and the 0.1.x incompatibility |
+| [Operations](docs/operations.md) | Service name, live re-apply vs restart, telemetry, container access |
+
+## Development
+
+```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 repo conventions.
+
+## License
+
+MIT

scietex_gpiod_service-1.2.0/README.md

@@ -0,0 +1,59 @@
+# scietex.gpiod_service
+
+`scietex.gpiod_service` is a [`scietex.service`](https://github.com/bond-anton/scietex.service)
+worker that owns the host's GPIO lines through
+[libgpiod](https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/) v2.
+
+It requests the lines the API tells it to, keeps them requested, and exposes
+their values over Valkey. Configuration is delivered by the API and applied
+**live** — changing a line's direction or bias does not restart the worker.
+
+## Install
+
+```bash
+pip install scietex.gpiod_service
+```
+
+Requires Python 3.13+, Linux, and libgpiod v2 (`gpiod~=2.5.0`).
+
+## Run
+
+```bash
+start-gpiod-service --conf-dir /etc/scietex
+```
+
+| Flag | Environment | Default |
+| --- | --- | --- |
+| `--conf-dir` | `SCIETEX_CONFIG_DIR` | auto-resolved (see below) |
+| `--service-name` | `SCIETEX_SERVICE_NAME` | `GPIODService` |
+| `--logging-level` | `SCIETEX_LOGGING_LEVEL` | `INFO` |
+
+On first run the service creates `<conf-dir>/gpiod/gpiod.yml` with defaults.
+With no chips configured it logs `waiting for remote configuration` and keeps
+running; the API then delivers the real configuration.
+
+`--service-name` must match the managed service name registered in the API — it
+is what discriminates the Valkey config key. Run exactly one worker per
+installation.
+
+## Documentation
+
+| Page | Contents |
+| --- | --- |
+| [Overview](docs/index.md) | What the service does and how it fits together |
+| [Configuration](docs/configuration.md) | The `gpio` section schema, `gpiod.yml`, and the 0.1.x incompatibility |
+| [Operations](docs/operations.md) | Service name, live re-apply vs restart, telemetry, container access |
+
+## Development
+
+```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 repo conventions.
+
+## License
+
+MIT

scietex_gpiod_service-1.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scietex.gpiod_service"
+dynamic = ["version"]
+description = "Scietex microservice daemon for GPIO control"
+authors = [{ name = "Anton Bondarenko", email = "bond.anton@gmail.com" }]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+readme = "README.md"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+requires-python = ">=3.13"
+dependencies = [
+  "gpiod~=2.5.0; sys_platform == 'linux'",
+  "msgspec>=0.21.1",
+  "scietex.service[valkey]~=6.2.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/bond-anton/scietex.gpiod_service"
+"Bug Tracker" = "https://github.com/bond-anton/scietex.gpiod_service/issues"
+
+[project.optional-dependencies]
+dev = ["tox>=4.54.0"]
+test = ["pytest", "pytest-asyncio"]
+lint = ["ruff", "ty"]
+
+[project.scripts]
+start-gpiod-service = "scietex.gpiod_service.run_worker:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "scietex.gpiod_service.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.gpiod_service" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

scietex_gpiod_service-1.2.0/setup.cfg

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

scietex_gpiod_service-1.2.0/src/scietex/gpiod_service/__init__.py

@@ -0,0 +1,23 @@
+"""Microservice for GPIO control."""
+
+from .config import (
+    GPIO_SECTION,
+    GPIO_SETTINGS_DEFAULTS,
+    GpioChipSettings,
+    GpioLineSettings,
+    GpioServiceSettings,
+    read_gpio_config,
+)
+from .gpiod_worker import GpiodWorker
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "GpiodWorker",
+    "GPIO_SECTION",
+    "GPIO_SETTINGS_DEFAULTS",
+    "GpioChipSettings",
+    "GpioLineSettings",
+    "GpioServiceSettings",
+    "read_gpio_config",
+]

scietex_gpiod_service-1.2.0/src/scietex/gpiod_service/config.py

@@ -0,0 +1,150 @@
+"""Configuration models and YAML loader for the GPIO service.
+
+`GpioServiceSettings` is the concrete constructor (L0) base and the validation
+target of the framework's four-layer config merge. ``gpiod/gpiod.yml`` is the L1
+bootstrap patch: a field-level map merged onto L0, then overlaid by the
+framework's ``config.yml`` snapshot (L2) and the remote ``gpio`` section (L3).
+
+The section mirrors the API's `GPIOWorkerConfiguration` field-for-field (§3.1 of
+the GPIO plugin spec): ``chips`` keyed by chip path, each chip's ``lines`` keyed
+by line name. ``name`` is deliberately absent — the framework strips it from the
+delivered patch. The wire literals are stored verbatim (uppercase), so the worker
+maps them to gpiod enums without a translation layer on either side.
+
+``gpiod.yml`` files written for the 0.1.x worker are not compatible: the old file
+described ``inputs``/``outputs``/``buttons`` dicts; the new one is a thin L1
+bootstrap of the section struct above.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+import msgspec
+
+#: Remote-config section name the settings are registered under. Must be
+#: byte-identical to the API-side ``GPIOWorkerConfiguration.section``, or the
+#: framework rejects a delivery with ``UNKNOWN_CONFIG_SECTION``.
+GPIO_SECTION: str = "gpio"
+
+#: Subdirectory under the shared config dir that namespaces this service's files.
+GPIO_CONFIG_SUBDIR: str = "gpiod"
+
+#: Filename of the service-owned L1 bootstrap patch in the config subdirectory.
+GPIO_CONFIG_FILE: str = "gpiod.yml"
+
+
+class GpioLineSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Electrical settings for a single requested line.
+
+    ``offset`` is the physical line offset on the chip and the key used by
+    ``request_lines`` / ``get_value`` / ``set_value``. The remaining fields are
+    the wire literals from the assigning line configuration (§3.2); ``device``
+    and ``item`` are informational only and never used for addressing.
+    """
+
+    offset: int
+    direction: Literal["INPUT", "OUTPUT", "AS_IS"] = "AS_IS"
+    drive: Literal["PUSH_PULL", "OPEN_DRAIN", "OPEN_SOURCE"] = "PUSH_PULL"
+    bias: Literal["PULL_UP", "PULL_DOWN", "DISABLED", "AS_IS"] = "AS_IS"
+    edge_detection: Literal["NONE", "RISING", "FALLING", "BOTH"] = "NONE"
+    output_value: Literal["ACTIVE", "INACTIVE"] | None = None
+    active_level: Literal["HIGH", "LOW"] = "HIGH"
+    debounce_period_ms: int | None = None
+    device: str | None = None
+    item: str | None = None
+
+
+class GpioChipSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """One chip and the lines to request on it.
+
+    The chip's own path is the dict key in `GpioServiceSettings.chips`, not a
+    field here, because that is what ``gpiod.Chip(path)`` opens. ``lines`` is
+    keyed by line name — the label the worker's ``read``/``write`` commands and
+    telemetry streams use.
+    """
+
+    name: str
+    lines: dict[str, GpioLineSettings] = msgspec.field(default_factory=dict)
+
+
+class GpioServiceSettings(msgspec.Struct, frozen=True, forbid_unknown_fields=True):
+    """Top-level GPIO service settings.
+
+    ``chips`` is keyed by chip path (the device node). ``consumer`` is the kernel
+    consumer label passed to every ``request_lines`` call, ``poll_interval`` is
+    the monitor-loop cadence, and ``monitor_autostart`` starts the monitor task
+    after the first successful apply.
+
+    ``edge_stream_maxlen`` and ``line_stream_maxlen`` bound the Valkey streams
+    the worker appends to. Both are approximate trims (``MAXLEN ~ N``): an exact
+    trim on every ``xadd`` costs a full stream scan, and a stream that is a few
+    entries over its bound is harmless. ``pulse_max_ms`` caps a ``pulse`` task's
+    duration so a caller cannot hold a relay energized indefinitely.
+    """
+
+    chips: dict[str, GpioChipSettings] = msgspec.field(default_factory=dict)
+    poll_interval: float = 1.0
+    consumer: str = "gpiod"
+    monitor_autostart: bool = False
+    edge_stream_maxlen: int = 10000
+    line_stream_maxlen: int = 1000
+    pulse_max_ms: int = 60000
+
+
+#: Concrete L0 base for the framework's layered merge. A field absent from every
+#: layer, or explicitly cleared with ``null``, resolves to the value here.
+GPIO_SETTINGS_DEFAULTS: GpioServiceSettings = GpioServiceSettings()
+
+
+def read_gpio_config(conf_dir: Path | None, *, create_default: bool = True) -> dict[str, object]:
+    """Read the L1 bootstrap patch from ``gpiod/gpiod.yml`` under the config directory.
+
+    The file (and, when missing, its directory) is only created when
+    ``create_default=True`` (the bootstrap path). Unlike the Modbus loader, a
+    missing file or directory with ``create_default=False`` returns ``{}`` rather
+    than raising — the bootstrap provider must never fail startup, and an empty
+    patch simply inherits the L0 defaults. An existing-but-invalid file raises
+    `RuntimeError` and is left untouched.
+
+    Args:
+        conf_dir: Path to the configuration directory.
+        create_default: Whether to create the directory and write a default
+            ``gpiod.yml`` when missing. Default ``True``.
+
+    Returns:
+        The parsed ``gpiod.yml`` mapping as the L1 patch, the builtins of the
+        default `GpioServiceSettings` when the file was just created, or ``{}``
+        when the file/directory is missing with ``create_default=False``.
+
+    Raises:
+        RuntimeError: If ``conf_dir`` is ``None``, the resolved service directory
+            exists but is not a directory, or the file cannot be parsed.
+    """
+    if not isinstance(conf_dir, Path):
+        raise RuntimeError("Configuration dir was not set!")
+    service_dir = conf_dir / GPIO_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:
+            return {}
+    elif not service_dir.is_dir():
+        raise RuntimeError(f"Provided configuration directory path {service_dir} is not a directory!")
+    gpiod_yml = service_dir.joinpath(GPIO_CONFIG_FILE)
+    if not gpiod_yml.exists():
+        if create_default:
+            settings = GpioServiceSettings()
+            with open(gpiod_yml, "wb") as f:
+                f.write(msgspec.yaml.encode(settings))
+            return msgspec.to_builtins(settings)
+        return {}
+    try:
+        with open(gpiod_yml, "rb") as f:
+            return msgspec.yaml.decode(f.read(), type=dict)
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to parse GPIO configuration file {gpiod_yml}. Fix the file or remove it to regenerate defaults."
+        ) from exc