scietex.adc-service 0.1.0__tar.gz

scietex_adc_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_adc_service-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: scietex.adc_service
+Version: 0.1.0
+Summary: Scietex microservice daemon for SPI ADC devices
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License-Expression: MIT
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.adc_service/issues
+Project-URL: Homepage, https://github.com/bond-anton/scietex.adc_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.adc<1.0.0,>=0.1.0
+Requires-Dist: msgspec>=0.18.6
+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"
+Provides-Extra: spi
+Requires-Dist: scietex.hal.adc[spi]<1.0.0,>=0.1.0; extra == "spi"
+Provides-Extra: gpiozero
+Requires-Dist: scietex.hal.adc[gpiozero]<1.0.0,>=0.1.0; extra == "gpiozero"
+Dynamic: license-file
+
+# scietex.adc_service
+
+**scietex.adc_service** is a [`scietex.service`](https://github.com/bond-anton/scietex.service)
+worker connected to Valkey that owns one or more SPI ADC devices (MCP3204,
+MCP3208) through [`scietex.hal.adc`](https://github.com/bond-anton/scietex.hal.adc).
+It opens the configured converters at startup, exposes single-ended and
+differential reads as `adc:*` tasks, and publishes a telemetry snapshot of the
+live devices. A device that fails to open does not stop the worker: it is
+recorded, reported as unavailable, and the remaining devices keep working.
+Configuration can also be pushed at runtime through the framework's
+remote-config channel.
+
+**Python ≥ 3.10** · **License: MIT**
+
+## Documentation
+
+- [Overview](docs/index.md) — what the service does and how it fits together
+- [Configuration](docs/configuration.md) — the `adc.yml` schema and precedence
+- [Deployment](docs/deployment.md) — container, SPI device access, Quadlet
+- [Remote configuration](docs/remote-config.md) — the declarative `adc` section
+
+## Installation
+
+```bash
+pip install "scietex.adc_service[spi]"      # spidev backend for /dev/spidev*
+pip install "scietex.adc_service[gpiozero]" # plain-GPIO backend
+```
+
+The core package pulls in `scietex.hal.adc`, `scietex.service[valkey]`, and
+`msgspec`. The backend extras are optional: a core install can still build a
+device from a caller-supplied transport, but an operator normally installs the
+extra that matches the board's wiring.
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `adc/adc.yml` under its config directory. Create it by hand,
+or let the service generate a default on first run. The file is the bootstrap
+layer of a four-layer merge: constructor defaults < `adc.yml` < the framework's
+`config.yml` snapshot < the remote `adc` section.
+
+### 2. Run the service
+
+```bash
+start-adc-service --conf-dir /etc/scietex
+```
+
+The config directory resolves automatically when `--conf-dir` is omitted. The
+service runs in the foreground until `SIGINT` or `SIGTERM`.
+
+### 3. Read a channel
+
+Submit an `adc:read` task to the worker with payload
+`{"device_id": "adc0", "channel": 0}`. The result carries the raw 12-bit `code`
+and the scaled `voltage`.
+
+## Configuration at a glance
+
+Devices are keyed by a **string** id, which names the device in task payloads
+and telemetry:
+
+```yaml
+devices:
+  adc0:
+    type: MCP3208
+    port: 0
+    device: 0
+    v_ref: 3.3
+  adc1:
+    type: MCP3204
+    device: 1
+    v_ref: 5.0
+    poll: false
+poll_enabled: true
+```
+
+Per-device fields: `type` (required, `MCP3204` or `MCP3208`), `port` and `device`
+for the SPI wiring, `clock_pin`/`mosi_pin`/`miso_pin`/`select_pin` for the
+gpiozero backend, `v_ref`, `label`, `log_level`, and `poll` (default `true`).
+`port` is the SPI bus number and `device` is the chip-select; both are integers.
+Top-level fields: `devices` and `poll_enabled` (default `true`). Unknown fields
+are rejected.
+
+## Tasks
+
+| Task | Lane | Request | Result |
+|---|---|---|---|
+| `adc:list` | control | optional `device_id` | per-device `device_id`, `available`, `error`, `v_ref`, `channels`, `differential`, `poll`; plus `poll_enabled` |
+| `adc:read` | data | `device_id`, `channel`, `differential` | `device_id`, `channel`, `differential`, `code`, `voltage` |
+| `adc:read_all` | data | `device_id` | `device_id`, `codes`, `voltages` |
+
+Differential reads use `adc:read` with `differential: true`; `channel` then
+names a differential pair instead of a single-ended input. An id that is
+configured but failed to open is a successful `adc:list` entry with
+`available: false`, not a task error.
+
+## Telemetry
+
+The worker publishes to `scietex:{service}:{instance_id}:telemetry` every 2 s
+with a 6 s TTL. The snapshot lists every configured device with its open state,
+`v_ref`, channel counts, and `poll` flag, plus the service-wide `poll_enabled`
+switch. Polling is opt-out both per device (`poll: false`) and globally
+(`poll_enabled: false`).
+
+## Container and quadlet
+
+```bash
+podman build --build-arg VERSION=0.1.0 -t scietex-adc-service .
+podman run --rm --device /dev/spidev0.0 -v ./config:/config scietex-adc-service
+```
+
+The container only dials Valkey, so it publishes no port and needs no
+capabilities. `/dev/spidevX.Y` must be passed with `--device`; without it the
+worker still starts and reports the device unavailable.
+
+For a persistent deployment, install `deploy/adc-service.container` as
+`~/.config/containers/systemd/adc-service.container` and the SPI drop-in as
+`~/.config/containers/systemd/adc-service.container.d/50-spi-devices.conf`,
+then `systemctl --user daemon-reload && systemctl --user start adc-service`.
+The Quadlet bind-mounts `~/.config/scietex`, so `adc/adc.yml` stays
+hand-editable on the host.
+
+## 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
+```

scietex_adc_service-0.1.0/README.md

@@ -0,0 +1,132 @@
+# scietex.adc_service
+
+**scietex.adc_service** is a [`scietex.service`](https://github.com/bond-anton/scietex.service)
+worker connected to Valkey that owns one or more SPI ADC devices (MCP3204,
+MCP3208) through [`scietex.hal.adc`](https://github.com/bond-anton/scietex.hal.adc).
+It opens the configured converters at startup, exposes single-ended and
+differential reads as `adc:*` tasks, and publishes a telemetry snapshot of the
+live devices. A device that fails to open does not stop the worker: it is
+recorded, reported as unavailable, and the remaining devices keep working.
+Configuration can also be pushed at runtime through the framework's
+remote-config channel.
+
+**Python ≥ 3.10** · **License: MIT**
+
+## Documentation
+
+- [Overview](docs/index.md) — what the service does and how it fits together
+- [Configuration](docs/configuration.md) — the `adc.yml` schema and precedence
+- [Deployment](docs/deployment.md) — container, SPI device access, Quadlet
+- [Remote configuration](docs/remote-config.md) — the declarative `adc` section
+
+## Installation
+
+```bash
+pip install "scietex.adc_service[spi]"      # spidev backend for /dev/spidev*
+pip install "scietex.adc_service[gpiozero]" # plain-GPIO backend
+```
+
+The core package pulls in `scietex.hal.adc`, `scietex.service[valkey]`, and
+`msgspec`. The backend extras are optional: a core install can still build a
+device from a caller-supplied transport, but an operator normally installs the
+extra that matches the board's wiring.
+
+## Quick start
+
+### 1. Write a configuration file
+
+The service reads `adc/adc.yml` under its config directory. Create it by hand,
+or let the service generate a default on first run. The file is the bootstrap
+layer of a four-layer merge: constructor defaults < `adc.yml` < the framework's
+`config.yml` snapshot < the remote `adc` section.
+
+### 2. Run the service
+
+```bash
+start-adc-service --conf-dir /etc/scietex
+```
+
+The config directory resolves automatically when `--conf-dir` is omitted. The
+service runs in the foreground until `SIGINT` or `SIGTERM`.
+
+### 3. Read a channel
+
+Submit an `adc:read` task to the worker with payload
+`{"device_id": "adc0", "channel": 0}`. The result carries the raw 12-bit `code`
+and the scaled `voltage`.
+
+## Configuration at a glance
+
+Devices are keyed by a **string** id, which names the device in task payloads
+and telemetry:
+
+```yaml
+devices:
+  adc0:
+    type: MCP3208
+    port: 0
+    device: 0
+    v_ref: 3.3
+  adc1:
+    type: MCP3204
+    device: 1
+    v_ref: 5.0
+    poll: false
+poll_enabled: true
+```
+
+Per-device fields: `type` (required, `MCP3204` or `MCP3208`), `port` and `device`
+for the SPI wiring, `clock_pin`/`mosi_pin`/`miso_pin`/`select_pin` for the
+gpiozero backend, `v_ref`, `label`, `log_level`, and `poll` (default `true`).
+`port` is the SPI bus number and `device` is the chip-select; both are integers.
+Top-level fields: `devices` and `poll_enabled` (default `true`). Unknown fields
+are rejected.
+
+## Tasks
+
+| Task | Lane | Request | Result |
+|---|---|---|---|
+| `adc:list` | control | optional `device_id` | per-device `device_id`, `available`, `error`, `v_ref`, `channels`, `differential`, `poll`; plus `poll_enabled` |
+| `adc:read` | data | `device_id`, `channel`, `differential` | `device_id`, `channel`, `differential`, `code`, `voltage` |
+| `adc:read_all` | data | `device_id` | `device_id`, `codes`, `voltages` |
+
+Differential reads use `adc:read` with `differential: true`; `channel` then
+names a differential pair instead of a single-ended input. An id that is
+configured but failed to open is a successful `adc:list` entry with
+`available: false`, not a task error.
+
+## Telemetry
+
+The worker publishes to `scietex:{service}:{instance_id}:telemetry` every 2 s
+with a 6 s TTL. The snapshot lists every configured device with its open state,
+`v_ref`, channel counts, and `poll` flag, plus the service-wide `poll_enabled`
+switch. Polling is opt-out both per device (`poll: false`) and globally
+(`poll_enabled: false`).
+
+## Container and quadlet
+
+```bash
+podman build --build-arg VERSION=0.1.0 -t scietex-adc-service .
+podman run --rm --device /dev/spidev0.0 -v ./config:/config scietex-adc-service
+```
+
+The container only dials Valkey, so it publishes no port and needs no
+capabilities. `/dev/spidevX.Y` must be passed with `--device`; without it the
+worker still starts and reports the device unavailable.
+
+For a persistent deployment, install `deploy/adc-service.container` as
+`~/.config/containers/systemd/adc-service.container` and the SPI drop-in as
+`~/.config/containers/systemd/adc-service.container.d/50-spi-devices.conf`,
+then `systemctl --user daemon-reload && systemctl --user start adc-service`.
+The Quadlet bind-mounts `~/.config/scietex`, so `adc/adc.yml` stays
+hand-editable on the host.
+
+## 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
+```

scietex_adc_service-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "scietex.adc_service"
+description = "Scietex microservice daemon for SPI ADC devices"
+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.adc>=0.1.0,<1.0.0",
+  "msgspec>=0.18.6",
+]
+dynamic = ["version"]
+
+[project.urls]
+"Bug Tracker" = "https://github.com/bond-anton/scietex.adc_service/issues"
+"Homepage" = "https://github.com/bond-anton/scietex.adc_service"
+
+[project.scripts]
+start-adc-service = "scietex.adc_service.run_worker:main"
+
+[project.optional-dependencies]
+dev = ["tox>=4.45.0"]
+lint = ["ruff", "ty"]
+test = ["pytest", "pytest-asyncio"]
+# SPI backends are optional: a core install can still build ADC objects from a
+# caller-supplied transport. An operator installs the extra for the board's
+# wiring — spidev for /dev/spidev*, gpiozero for plain GPIO pins.
+spi = ["scietex.hal.adc[spi]>=0.1.0,<1.0.0"]
+gpiozero = ["scietex.hal.adc[gpiozero]>=0.1.0,<1.0.0"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.setuptools.dynamic]
+version = { attr = "scietex.adc_service.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.adc_service" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true

scietex_adc_service-0.1.0/setup.cfg

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

scietex_adc_service-0.1.0/src/scietex/adc_service/__init__.py

@@ -0,0 +1,25 @@
+"""ADC Service."""
+
+from .adc_worker import AdcWorker
+from .config import (
+    ADC_SECTION,
+    ADC_SETTINGS_DEFAULTS,
+    AdcDeviceSettings,
+    AdcServiceSettings,
+    read_adc_config,
+)
+from .devices import ChannelNotFound, DeviceNotFound, DeviceUnavailable
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "AdcWorker",
+    "ADC_SECTION",
+    "ADC_SETTINGS_DEFAULTS",
+    "AdcDeviceSettings",
+    "AdcServiceSettings",
+    "ChannelNotFound",
+    "DeviceNotFound",
+    "DeviceUnavailable",
+    "read_adc_config",
+]

scietex_adc_service-0.1.0/src/scietex/adc_service/adc_worker.py

@@ -0,0 +1,159 @@
+"""ADC worker: a Valkey-backed service that owns a set of SPI converters.
+
+`AdcWorker` extends `ValkeyWorker` with a live `AdcDeviceRegistry`. Settings
+resolve through the framework's four-layer merge: constructor default (L0) <
+``adc.yml`` bootstrap patch (L1) < framework ``config.yml`` snapshot (L2) <
+remote ``adc`` section (L3). Every apply rebuilds the registry from the merged
+struct; a device that cannot be opened is recorded and the rest keep working.
+A ``Telemetry`` manager publishes the open-device snapshot every 2 s.
+"""
+
+import asyncio
+import logging
+from typing import cast
+
+import msgspec
+from glide import (
+    ConnectionError as GlideConnectionError,
+)
+from glide import (
+    ExpirySet,
+    ExpiryType,
+    RequestError,
+)
+from glide import (
+    TimeoutError as GlideTimeoutError,
+)
+
+from scietex.service import Manager, ValkeyWorker, ValkeyWorkerConfig
+
+from .config import (
+    ADC_SECTION,
+    ADC_SETTINGS_DEFAULTS,
+    AdcServiceSettings,
+    read_adc_config,
+)
+from .devices import AdcDeviceRegistry
+from .task_handlers import AdcListHandler, AdcReadAllHandler, AdcReadHandler
+from .telemetry import TELEMETRY_INTERVAL, TELEMETRY_TTL, build_telemetry
+
+
+class AdcWorker(ValkeyWorker):
+    """A `ValkeyWorker` that reads configured SPI ADC devices on demand."""
+
+    def __init__(self, config: ValkeyWorkerConfig | None = None, *, client_factory=None, theme=None) -> None:
+        super().__init__(config, client_factory=client_factory, theme=theme)
+        self._settings: AdcServiceSettings | None = None
+        self._devices = AdcDeviceRegistry(self.logger)
+        # The apply hook runs during ``initialize`` (L2/L3 delivery) and at
+        # runtime. False until ``initialize`` finishes so the hook does not
+        # rebuild the registry twice on startup; ``initialize`` rebuilds once
+        # from the final merged settings.
+        self._startup_complete: bool = False
+        # Telemetry encoding is owned here because the framework's encoder is
+        # private; the key is resolved once at construction.
+        self._telemetry_encoder = msgspec.msgpack.Encoder()
+        self._telemetry_key = f"scietex:{self.service_name}:{self.instance_id}:telemetry"
+        self.register_config_settings(
+            ADC_SECTION,
+            AdcServiceSettings,
+            apply=self._apply_adc_settings,
+            defaults=ADC_SETTINGS_DEFAULTS,
+            bootstrap=lambda: read_adc_config(self.conf_dir),
+        )
+        # All three handlers share the registry, so a config apply is visible
+        # to an in-flight handler without re-registration.
+        self.add_task_handler(AdcListHandler, devices=self._devices)
+        self.add_task_handler(AdcReadHandler, devices=self._devices)
+        self.add_task_handler(AdcReadAllHandler, devices=self._devices)
+
+    @property
+    def adc_settings(self) -> AdcServiceSettings | None:
+        """The effective ADC settings, or `None` before startup."""
+        return self._settings
+
+    @property
+    def devices(self) -> AdcDeviceRegistry:
+        """The live device registry shared with the task handlers."""
+        return self._devices
+
+    async def initialize(self) -> bool:
+        """Initialize the framework, then open every configured device.
+
+        `super().initialize()` seeds the L0+L1 layers (running the ``adc.yml``
+        bootstrap provider) and applies the L2/L3 layers, so the merged settings
+        are read back via `current_config_settings` afterwards. A bootstrap
+        failure is swallowed by the framework's seeder and surfaces as an
+        unresolved section, which is the ``None`` guard below. Per-device open
+        failures do not fail startup: the registry records them and the worker
+        serves the hardware that is present.
+
+        Returns:
+            `True` if the settings resolved and the registry rebuilt, `False`
+            on a framework, resolution, or registry-wide failure.
+        """
+        self._startup_complete = False
+        if not await super().initialize():
+            return False
+
+        resolved = self.current_config_settings(ADC_SECTION)
+        if resolved is None:
+            self.logger.error("ADC settings were not resolved before device startup")
+            return False
+        settings = cast(AdcServiceSettings, resolved)
+        try:
+            self._devices.rebuild(settings)
+        except Exception as exc:
+            self.logger.error("Failed to build the ADC device registry: %s", exc)
+            return False
+        self._settings = settings
+        self._startup_complete = True
+        return True
+
+    async def cleanup(self) -> None:
+        """Close every open device, then the framework resources."""
+        self._startup_complete = False
+        self._devices.close()
+        await super().cleanup()
+
+    def _apply_adc_settings(self, settings: AdcServiceSettings) -> None:
+        """Store merged settings and rebuild the live devices.
+
+        The hook is synchronous (the framework invokes it inline, before the
+        core swap), and `AdcDeviceRegistry.rebuild` is synchronous by design.
+        During startup the hook only stores: `initialize` rebuilds once from
+        the final merged settings to avoid opening every device twice.
+
+        A registry-wide failure propagates, which the framework reports as a
+        failed apply; per-device failures are recorded in the registry and
+        leave the apply successful.
+        """
+        if not self._startup_complete:
+            self._settings = settings
+            return
+        self._devices.rebuild(settings)
+        self._settings = settings
+
+    @Manager(name="Telemetry")
+    async def telemetry_loop(self) -> None:
+        """Publish device telemetry to Valkey once per iteration.
+
+        The manager runtime repeats this body forever with auto-restart on
+        error. The write is guarded on `self.client` and runs even before the
+        first configuration, so the UI observes ``configured=false``. Glide
+        errors are logged at WARNING and reported to the transport health,
+        which drives the reconnect — matching the heartbeat's error handling.
+        """
+        client = self.client
+        if client is not None:
+            payload = build_telemetry(self)
+            try:
+                await client.set(
+                    self._telemetry_key,
+                    value=self._telemetry_encoder.encode(payload),
+                    expiry=ExpirySet(ExpiryType.SEC, TELEMETRY_TTL),
+                )
+            except (GlideConnectionError, RequestError, GlideTimeoutError) as exc:
+                self.logger.log(logging.WARNING, "Failed to publish ADC telemetry: %s", exc)
+                self._health.report_failure(exc)
+        await asyncio.sleep(TELEMETRY_INTERVAL)