tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/data/targets.py

@@ -0,0 +1,256 @@
+"""All targets (``targets.json``): albums, radio stations and entries of Spotify."""
+
+import json
+import logging
+import os
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.data.common import Listener, Mirror, TargetType, UpdateJson, is_unmapped
+from tinyjukebox.data.jsondata import JsonData
+from tinyjukebox.data.target import Target, TargetAlbum, TargetRadio, TargetSpotify
+from tinyjukebox.schema.targets import schema
+
+__all__ = ["LAST_ID_SUFFIX", "Targets", "create_target_factory", "load_target_factory"]
+
+LAST_ID_SUFFIX = "-last-id.json"
+"""``targets.json`` -> ``targets-last-id.json``: the highest album id given so far."""
+
+
+def _is_number(target_id: str | None) -> bool:
+    return target_id is not None and target_id.isascii() and target_id.isdigit()
+
+
+def _check_target_dict(target: dict[str, Any] | None, logger: logging.Logger) -> dict[str, Any]:
+    if target is None:
+        logger.error("target not provided")
+        raise ValueError("target not provided")
+    if "target-id" not in target:
+        logger.error("provided target has no attribute target-id")
+        raise ValueError("provided target has no attribute target-id")
+    if is_unmapped(target["target-id"]):
+        logger.error("target-id must be set.")
+        raise ValueError("target-id must be set.")
+    if "target-type" not in target:
+        raise ValueError("provided target has no attribute target-type")
+    if target["target-type"] not in (TargetType.album.name, TargetType.radio.name, TargetType.spotify.name):
+        logger.error("unknown target type: %s.", target["target-type"])
+        raise ValueError(f"unknown target type: {target['target-type']}.")
+    return target
+
+
+def create_target_factory(
+    target: dict[str, Any] | None, root_folder: str, update_json: UpdateJson | None, logger: logging.Logger
+) -> Target:
+    """A new target - checked for sanity (e.g. files exist, valid url). :raises ValueError: otherwise."""
+    factory_logger = get_child(logger, "create_target_factory")
+    target = _check_target_dict(target, factory_logger)
+    if target["target-type"] == TargetType.radio.name:
+        return TargetRadio.create_target(target, logger, update_json)
+    if target["target-type"] == TargetType.spotify.name:
+        return TargetSpotify.create_target(target, logger, update_json)
+    return TargetAlbum.create_target(target, root_folder, logger, update_json)
+
+
+def load_target_factory(
+    target: dict[str, Any] | None, root_folder: str, update_json: UpdateJson, logger: logging.Logger
+) -> Target:
+    """A target from the json file - not checked for sanity (a missing album must not prevent the start)."""
+    factory_logger = get_child(logger, "load_target_factory")
+    target = _check_target_dict(target, factory_logger)
+    if target["target-type"] == TargetType.radio.name:
+        return TargetRadio(target, logger, update_json)
+    if target["target-type"] == TargetType.spotify.name:
+        return TargetSpotify(target, logger, update_json)
+    return TargetAlbum(target, root_folder, logger, update_json)
+
+
+class Targets:
+    """Targets by id. Changes are written to the json file immediately (see :class:`~tinyjukebox.data.tags.Tags`
+    for the locking rules).
+
+    Albums, radio stations and entries of Spotify share the ids. New ids count up and are never given twice - also
+    not after the target with the highest id has been deleted: the new target would inherit everything that still
+    refers to the old id (e.g. the cover cached by the browser). The highest id given so far is kept in a file of its
+    own (:data:`LAST_ID_SUFFIX`) - older versions would reject an additional entry in the targets json. Without that
+    file, new ids follow the highest existing id.
+
+    With ``id_source`` the ids come from there: the library assigns them for all boxes, and a box that works with a
+    library creates a target under a provisional id (:mod:`tinyjukebox.sync`).
+    """
+
+    def __init__(self, filename: str, root_folder: str, logger: logging.Logger) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._lock = threading.RLock()
+        self._json = JsonData(filename, filename + "_", schema, self._logger, entries=True)
+        self._last_id_file = os.path.splitext(filename)[0] + LAST_ID_SUFFIX
+        self.root_folder = root_folder
+        self.id_source: Callable[[], str] | None = None
+        self._mirror = Mirror()
+        self.targets: dict[str, Target] = {}
+        for key, target in list(self._json.data.items()):
+            try:
+                self.targets[key] = load_target_factory(target, root_folder, self._update_json, self._logger)
+            except ValueError as e:  # a target this version cannot use does not keep the box from starting
+                self._json.set_aside(key, target, str(e))
+
+    def _to_dict(self) -> dict[str, Any]:
+        return {key: target.to_dict() for key, target in self.targets.items()}
+
+    def _update_json(self) -> None:
+        with self._lock:
+            data = self._to_dict()
+            self._json.store(data)
+            self._mirror.changed(data)
+
+    def listen(self, listener: Listener) -> None:
+        """``listener(target_id, entry)`` is called for every target that changes from now on (``None``: deleted)."""
+        with self._lock:
+            self._mirror.listen(listener, self._to_dict())
+
+    def sync(self, get: Callable[[], dict[str, Any]], renamed: dict[str, str] | None = None) -> bool:
+        """Make the targets what ``get()`` returns (the content of ``targets.json``), keeping the targets that stay
+        - also one whose id changed from a key of ``renamed`` to its value. The listener is not called. Returns
+        whether something changed."""
+        with self._lock:
+            data, aside = self._json.split(get())
+            if data == self._to_dict() and aside == self._json.aside:
+                return False
+            for old, new in (renamed or {}).items():
+                if old in self.targets and new in data and new not in self.targets:
+                    self.targets[new] = self.targets.pop(old)
+            for key in [key for key in self.targets if key not in data]:
+                del self.targets[key]
+            for key, entry in data.items():
+                target = self.targets.get(key)
+                try:
+                    if (
+                        target is not None
+                        and target.target_type is not None
+                        and target.target_type.name == entry.get("target-type")
+                    ):
+                        target.load(entry)
+                    else:
+                        self.targets[key] = load_target_factory(
+                            entry, self.root_folder, self._update_json, self._logger
+                        )
+                except ValueError as e:
+                    self._logger.warning("sync - target '%s' set aside: %s", key, e)
+                    self.targets.pop(key, None)
+                    aside[key] = entry
+                self._remember_id(key)
+            data = self._to_dict()
+            self._json.store(data, aside)
+            self._mirror.replaced(data)
+            return True
+
+    def all(self) -> list[Target]:
+        """Snapshot of all targets."""
+        with self._lock:
+            return list(self.targets.values())
+
+    def albums(self) -> list[TargetAlbum]:
+        return [target for target in self.all() if isinstance(target, TargetAlbum)]
+
+    def radios(self) -> list[TargetRadio]:
+        return [target for target in self.all() if isinstance(target, TargetRadio)]
+
+    def spotify_entries(self) -> list[TargetSpotify]:
+        return [target for target in self.all() if isinstance(target, TargetSpotify)]
+
+    def get_target(self, target_id: str) -> Target:
+        """:raises ValueError: for unknown ids."""
+        target = self.targets.get(target_id)
+        if target is None:
+            self._logger.warning("get_target - unknown target_id %s.", target_id)
+            raise ValueError(f"get_target - unknown target_id {target_id}.")
+        return target
+
+    def get_targets_of_type(self, target_type: TargetType) -> list[Target]:
+        return [target for target in self.all() if target.target_type == target_type]
+
+    def add_target(self, target: dict[str, Any] | None, create_id: bool = True) -> Target:
+        """Add a target (``create_id``: with a new id). :raises ValueError: if it is invalid or the id exists."""
+        if target is None:
+            self._logger.warning("add_target - target is None.")
+            raise ValueError("add_target - target is None.")
+        with self._lock:
+            if create_id:
+                target["target-id"] = self.id_source() if self.id_source else str(self._highest_id() + 1)
+            self._logger.info("add_target - target: %s.", target)
+            if str(target.get("target-id")) in self.targets or str(target.get("target-id")) in self._json.aside:
+                self._logger.warning("add_target - target_id %s exists already.", target["target-id"])
+                raise ValueError(f"add_target - target_id {target['target-id']} exists already.")
+            new_target = create_target_factory(target, self.root_folder, self._update_json, self._logger)
+            target_id = new_target.target_id
+            assert target_id is not None  # noqa: S101 - set by the constructor
+            self._remember_id(target_id)
+            self.targets[target_id] = new_target
+            self._update_json()
+        return new_target
+
+    def delete_target(self, target_id: str | None) -> None:
+        if target_id is None:
+            self._logger.warning("delete_target - target_id is None.")
+            raise ValueError("delete_target - target_id is None.")
+        with self._lock:
+            if target_id not in self.targets:
+                self._logger.warning("delete_target - unknown target_id %s.", target_id)
+                raise ValueError(f"delete_target - unknown target_id {target_id}.")
+            self._remember_id(target_id)  # e.g. the file does not exist yet - the id would be given again
+            del self.targets[target_id]
+            self._update_json()
+
+    def sanity_check(self) -> tuple[bool, str]:
+        errors = []
+        for key, target in list(self.targets.items()):
+            if key != target.target_id:
+                message = f"sanity_check - key '{key}' != target.target_id '{target.target_id}'"
+                self._logger.warning(message)
+                errors.append(message)
+            passed, error = target.sanity_check()
+            if not passed:
+                errors.append(error)
+        return not errors, "\n".join(errors)
+
+    def to_text(self) -> str:
+        return "\n".join(f"key: {key}, target: {target.to_text()}" for key, target in list(self.targets.items()))
+
+    def _highest_id(self) -> int:
+        """The highest id given so far (0: none) - stored or, if higher, of the existing targets."""
+        keys = [*self.targets, *self._json.aside]  # a target set aside keeps its id, too
+        return max([self._read_last_id(), *(int(key) for key in keys if _is_number(key))])
+
+    def _remember_id(self, target_id: str) -> None:
+        """Raise the stored last id to ``target_id`` - before the targets json is written: a crash leaves a gap,
+        never an id that is given twice."""
+        if _is_number(target_id) and int(target_id) > self._read_last_id():
+            self._write_last_id(int(target_id))
+
+    def _read_last_id(self) -> int:
+        try:
+            with open(self._last_id_file, encoding="utf-8") as f:
+                last_id = json.load(f)["last-id"]
+        except FileNotFoundError:
+            return 0
+        except (OSError, ValueError, KeyError, TypeError) as e:
+            self._logger.warning(
+                "cannot read '%s' (%s) - new ids follow the highest existing id.", self._last_id_file, e
+            )
+            return 0
+        if not isinstance(last_id, int) or isinstance(last_id, bool):
+            self._logger.warning(
+                "'%s': last-id must be a number - new ids follow the highest existing id.", self._last_id_file
+            )
+            return 0
+        return last_id
+
+    def _write_last_id(self, last_id: int) -> None:
+        temp = self._last_id_file + ".tmp"
+        with open(temp, "w", encoding="utf-8") as f:
+            json.dump({"last-id": last_id}, f)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(temp, self._last_id_file)

tinyjukebox/data/volumelimits.py

@@ -0,0 +1,68 @@
+"""Start value and maximum of the volumes, changed at runtime (``volume.json`` next to ``tags.json``)."""
+
+import logging
+import os
+import threading
+from collections.abc import Mapping
+from typing import Any
+
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.data.common import Listener
+from tinyjukebox.data.jsondata import JsonData
+from tinyjukebox.schema.volume import schema
+
+__all__ = ["VolumeLimits"]
+
+
+class VolumeLimits:
+    """``{"speaker": {"default-volume": 50, "max-volume": 80}, "headphones": {...}}`` - a profile that has never been
+    changed is missing: the config applies to it. A missing or broken file is not fatal (the config applies)."""
+
+    def __init__(self, filename: str, logger: logging.Logger) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._lock = threading.Lock()
+        self._listener: Listener | None = None
+        backup = filename + "_"
+        if not os.path.exists(filename) and not os.path.exists(backup):
+            self._logger.info("__init__ - no volume file yet - the config applies until a limit is changed.")
+            self._create(filename)
+        try:
+            self._json = JsonData(filename, backup, schema, self._logger)
+        except FileNotFoundError:
+            self._logger.warning("__init__ - no usable volume file - the config applies.")
+            self._create(filename)
+            self._json = JsonData(filename, backup, schema, self._logger)
+
+    @staticmethod
+    def _create(filename: str) -> None:
+        with open(filename, "w", encoding="utf-8") as outfile:
+            outfile.write("{}")
+
+    def apply(self, profile: str, config: Mapping[str, Any]) -> dict[str, Any]:
+        """``config`` (keys ``default-volume``, ``max-volume``, ...) with the stored limits of ``profile``."""
+        with self._lock:
+            return {**config, **self._json.data.get(profile, {})}
+
+    def store(self, profile: str, default_volume: float, max_volume: float) -> None:
+        with self._lock:
+            data = dict(self._json.data)
+            data[profile] = {"default-volume": default_volume, "max-volume": max_volume}
+            self._json.store(data)
+            if self._listener is not None:
+                self._listener(profile, data[profile])
+
+    def listen(self, listener: Listener) -> None:
+        """``listener(profile, limits)`` is called whenever the limits of a profile are changed."""
+        self._listener = listener
+
+    def all(self) -> dict[str, Any]:
+        with self._lock:
+            return dict(self._json.data)
+
+    def sync(self, data: dict[str, Any]) -> bool:
+        """Make the stored limits ``data``; they apply from the next start. The listener is not called."""
+        with self._lock:
+            if data == self._json.data:
+                return False
+            self._json.store(dict(data))
+            return True

tinyjukebox/data_folder.py

@@ -0,0 +1,180 @@
+"""Starting with one folder (``--data DIR``, docs/developer/configuration.md, section 1): library and box without a
+config file of their own and without a users file made by hand - for the Docker image and the package from PyPI.
+
+Everything lies below the folder, in the folders library and box use anyway. A file ``DIR/config.yaml``, if there is
+one, changes single values. What the first start needs comes from environment variables, and counts at the first
+start only; afterwards the folder is the truth, and passwords are changed on the page. A password can also come from
+a file: ``TINYJUKEBOX_ADMIN_PASSWORD_FILE`` names it (a secret of Docker), and the variable itself stays empty.
+"""
+
+import copy
+import getpass
+import logging
+import os
+import secrets
+import sys
+from typing import Any
+
+from tinyjukebox.core.config import read_config
+from tinyjukebox.web.auth import MIN_PASSWORD_LENGTH, UsersFile, hash_password
+
+__all__ = [
+    "ADMIN_VARIABLE",
+    "BOOTSTRAP_VARIABLE",
+    "LIBRARY_VARIABLE",
+    "SLOTS_VARIABLE",
+    "box_config",
+    "first_admin",
+    "library_config",
+    "link_library",
+]
+
+ADMIN_VARIABLE = "TINYJUKEBOX_ADMIN_PASSWORD"  # the password of the user admin of the page, at the first start
+BOOTSTRAP_VARIABLE = "TINYJUKEBOX_BOOTSTRAP_PASSWORD"  # a library: the one new boxes prove; a box: the one it proves
+LIBRARY_VARIABLE = "TINYJUKEBOX_LIBRARY"  # a box: the address of its library, at the first start
+SLOTS_VARIABLE = "TINYJUKEBOX_SLOTS"  # a library: the folder with the slot it brings along (the Docker image)
+REPOSITORY = "tgd1975/tinyjukebox"  # where a library finds new versions for its boxes
+PLATFORM = "aarch64-debian-trixie"  # the platform of the boxes
+
+
+def _secret(variable: str) -> str:
+    """The value of ``variable`` - or the content of the file that ``<variable>_FILE`` names, without the line end."""
+    filename = os.environ.get(variable + "_FILE", "")
+    if filename:
+        try:
+            with open(filename, encoding="utf-8") as infile:
+                return infile.read().rstrip("\r\n")
+        except OSError as error:
+            raise SystemExit(f"{variable}_FILE: {filename} cannot be read ({error.strerror or error})") from None
+    return os.environ.get(variable, "")
+
+
+def _merged(base: dict[str, Any], change: dict[str, Any]) -> dict[str, Any]:
+    result = copy.deepcopy(base)
+    for key, value in change.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = _merged(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _with_changes(folder: str, config: dict[str, Any]) -> dict[str, Any]:
+    changes = os.path.join(folder, "config.yaml")
+    return _merged(config, read_config(changes)) if os.path.isfile(changes) else config
+
+
+def _logger(folder: str, name: str) -> dict[str, Any]:
+    return {
+        "log-level": "INFO",
+        "log-file": os.path.join(folder, "log", f"{name}.log"),
+        "log-rotation": {"maxbytes": 1048576, "backupcount": 4},
+    }
+
+
+def _rest_api(folder: str, port: int, name: str) -> dict[str, Any]:
+    return {
+        "port": port,
+        "certificate": os.path.join(folder, "ssl", f"{name}.crt"),
+        "private-key": os.path.join(folder, "ssl", f"{name}.key"),
+        "users-file": os.path.join(folder, "ssl", "users.yaml"),
+    }
+
+
+def _folders(folder: str, *names: str) -> None:
+    for name in names:
+        os.makedirs(os.path.join(folder, name), exist_ok=True)
+    os.chmod(os.path.join(folder, "ssl"), 0o700)  # private key, password hashes
+
+
+def library_config(folder: str) -> dict[str, Any]:
+    """The config of a library below ``folder``."""
+    folder = os.path.abspath(os.path.expanduser(folder))
+    _folders(folder, "data", "albums", "images", "ssl", "log")
+    library: dict[str, Any] = {
+        "data-folder": os.path.join(folder, "data"),
+        "albums-folder": os.path.join(folder, "albums"),
+        "images-folder": os.path.join(folder, "images"),
+        "backups-folder": os.path.join(folder, "backups"),
+        "playlist-filename": "playlist.m3u",
+        "platform": PLATFORM,
+        "releases": {"repository": REPOSITORY},
+        "rest-api": _rest_api(folder, 8866, "library"),
+    }
+    if _secret(BOOTSTRAP_VARIABLE):
+        # taken over at the first start and whenever it names another one (library.md, section 4.14)
+        library["bootstrap-password"] = _secret(BOOTSTRAP_VARIABLE)
+    if os.environ.get(SLOTS_VARIABLE):
+        library["slots-folder"] = os.environ[SLOTS_VARIABLE]
+    return _with_changes(folder, {"logger": _logger(folder, "library"), "library": library})
+
+
+def box_config(folder: str) -> dict[str, Any]:
+    """The config of a box without hardware below ``folder``, as ``deploy/config/tinyjukebox-sim.yaml`` has it."""
+    folder = os.path.abspath(os.path.expanduser(folder))
+    _folders(folder, "albums", "json", "ssl", "log")
+    json_files = {}
+    for key, name in (("tags", "tags"), ("targets", "targets"), ("activities", "activity")):
+        json_files[key] = os.path.join(folder, "json", f"{name}.json")
+        if not os.path.exists(json_files[key]):
+            with open(json_files[key], "w", encoding="utf-8") as outfile:
+                outfile.write("{}\n")
+    box = {
+        "albums-folder": os.path.join(folder, "albums"),
+        "playlist-filename": "playlist.m3u",
+        "volume": {"max-volume": 100, "default-volume": 40, "volume-step": 5},
+        "albumplayer": {"rewind-max-time": 10, "update-schedule": 5, "pause-between-tracks": 0},
+        "json": json_files,
+        "rest-api": _rest_api(folder, 8443, "tinyjukebox"),
+    }
+    return _with_changes(folder, {"logger": _logger(folder, "tinyjukebox"), "tinyjukebox": box})
+
+
+def link_library(folder: str, logger: logging.Logger) -> None:
+    """A box at its first start: the library of ``TINYJUKEBOX_LIBRARY`` with its bootstrap password - as if they had
+    been entered on the page (library.md, section 4.2). Later the page changes them."""
+    address = os.environ.get(LIBRARY_VARIABLE, "").strip().rstrip("/")
+    identity = os.path.join(os.path.abspath(os.path.expanduser(folder)), "identity")
+    if not address or os.path.exists(os.path.join(identity, "library")):
+        return
+    os.makedirs(identity, mode=0o700, exist_ok=True)
+    with open(os.path.join(identity, "library"), "w", encoding="utf-8") as outfile:
+        outfile.write(address + "\n")
+    password = _secret(BOOTSTRAP_VARIABLE)
+    if password:
+        descriptor = os.open(os.path.join(identity, "bootstrap"), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as outfile:
+            outfile.write(password + "\n")
+    logger.info("linked to the library %s at the first start", address)
+
+
+def first_admin(users_file: str, logger: logging.Logger) -> None:
+    """The user ``admin`` of the page, if the page has no user yet: its password from ``TINYJUKEBOX_ADMIN_PASSWORD``
+    (or the file of ``TINYJUKEBOX_ADMIN_PASSWORD_FILE``), asked on the terminal, or - without a terminal - generated
+    and printed once on the error output (``docker logs``), never into the log file."""
+    users = UsersFile.read(users_file)
+    if users:
+        return
+    password = _secret(ADMIN_VARIABLE)
+    generated = False
+    if not password and sys.stdin.isatty():
+        while True:
+            password = getpass.getpass(f"password of the user admin of the page (at least {MIN_PASSWORD_LENGTH}): ")
+            if len(password) >= MIN_PASSWORD_LENGTH and getpass.getpass("again: ") == password:
+                break
+            print("too short, or the two do not match", file=sys.stderr)
+    if not password:
+        password = secrets.token_urlsafe(12)
+        generated = True
+    if len(password) < MIN_PASSWORD_LENGTH:
+        raise SystemExit(f"{ADMIN_VARIABLE}: the password needs at least {MIN_PASSWORD_LENGTH} characters")
+    UsersFile.write(users_file, {"admin": {"password-hash": hash_password(password), "role": "admin"}})
+    if generated:
+        print(f"the page has the user admin with the password {password} - change it on the page (tab System)",
+              file=sys.stderr)  # fmt: skip
+        logger.warning(
+            "the page has the user admin with a generated password: it was printed once on the error output "
+            "(docker logs) - change it on the page (tab System)"
+        )
+    else:
+        logger.info("the page has the user admin")

tinyjukebox/devices/__init__.py

@@ -0,0 +1 @@
+"""Device drivers of the box (RFID reader, buttons, RGB LED) and the DriverManager."""

tinyjukebox/devices/baseclasses/__init__.py

@@ -0,0 +1 @@
+"""Base classes and helpers for drivers."""

tinyjukebox/devices/baseclasses/adriver.py

@@ -0,0 +1,115 @@
+"""Base class of all drivers."""
+
+import logging
+from abc import ABCMeta, abstractmethod
+from collections.abc import Mapping
+from typing import Any, ClassVar
+
+import tinyjukebox
+from tinyjukebox.core.microservice import AbstractMicroservice
+from tinyjukebox.core.pubsub import PubSubClient
+from tinyjukebox.core.ui import Command
+
+__all__ = ["ADriver"]
+
+
+class ADriver(AbstractMicroservice, metaclass=ABCMeta):
+    """Base class of all drivers: a component with the config section ``driver``.
+
+    * applies the common driver config entries ``type`` and ``name``; topics and payloads are defined in
+      :mod:`tinyjukebox.messages`,
+    * start/stop via :meth:`_driver_start` / :meth:`_driver_stop`,
+    * drivers are created and started by the :class:`~tinyjukebox.devices.drivermanager.drivermanager.DriverManager`
+      (config section ``drivers``); they use its pubsub client and logger and have no command line of their own.
+
+    Driver specific console commands are added to ``self._ui_commands`` (or via :meth:`_add_ui_command`) within
+    ``__init__``; :attr:`driver_ui_commands` provides them to the DriverManager.
+    """
+
+    _version: ClassVar[str] = tinyjukebox.__version__
+
+    def __init__(
+        self,
+        config: Mapping[str, Any],
+        pubsub_client: PubSubClient,
+        logger: logging.Logger,
+        logger_name: str | None = None,
+    ) -> None:
+        super().__init__(config, "driver", pubsub_client, logger, logger_name or type(self).__name__, no_gui=True)
+
+        self._type = type(self).__name__
+        if self._type.upper() != self._config["type"].upper():
+            message = f"Type of class ({self._type.upper()}) is different than type of config "
+            message += f"({self._config['type'].upper()})."
+            self._logger.error("ADriver.__init__ - %s", message)
+            raise TypeError(message)
+
+        self._name: str = self._config.get("name", self._type)
+        self._logger = self._logger.getChild(self._name)
+
+        self._base_ui_commands = frozenset(self._ui_commands)
+
+    # --- public -------------------------------------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def driver_type(self) -> str:
+        return self._type
+
+    @property
+    def driver_ui_commands(self) -> dict[str, Command]:
+        """The driver specific console commands (without the generic commands of the microservice)."""
+        return {name: command for name, command in self._ui_commands.items() if name not in self._base_ui_commands}
+
+    def get_name(self) -> str:
+        return self._name
+
+    def get_short_info(self) -> str:
+        return f"[{self._name}] type:{self._type} is_stopped:{self.is_stopped}"
+
+    def state(self) -> dict[str, Any]:
+        """What the driver knows about its hardware right now - the technical view of the web page shows it.
+        ``type`` is the one of the config (``input``, ``rgbled``, ...); drivers add theirs with
+        :meth:`_driver_state`."""
+        return {
+            "name": self._name,
+            "type": str(self._config["type"]).lower(),
+            "running": bool(self.is_started),
+            **self._driver_state(),
+        }
+
+    # --- helpers for drivers ------------------------------------------------------------------------------------
+
+    def _publish_value(self, topic: str, value: Any) -> None:
+        """Publish ``value`` to ``topic`` (see :mod:`tinyjukebox.messages`)."""
+        self._pubsub_client.publish(topic, value)
+        self._logger.info("ADriver._publish_value - %s: %s", topic, value)
+
+    # --- life cycle ---------------------------------------------------------------------------------------------
+
+    def _start(self) -> None:
+        self._driver_start()
+        self._logger.warning("Driver '%s.%s' started", self._type, self._name)
+
+    def _stop(self) -> None:
+        self._driver_stop()
+        self._logger.warning("Driver '%s.%s' stopped", self._type, self._name)
+
+    @abstractmethod
+    def _driver_start(self) -> None:
+        """Set up the hardware, subscribe to topics, start threads."""
+
+    @abstractmethod
+    def _driver_stop(self) -> None:
+        """Reverse of :meth:`_driver_start`."""
+
+    def _driver_state(self) -> dict[str, Any]:
+        """The driver specific part of :meth:`state` - called by any thread, also while the driver is stopped."""
+        return {}
+
+    @classmethod
+    def _get_description(cls) -> str:
+        return f"Device driver '{cls.__name__}'."

tinyjukebox/devices/baseclasses/aevents.py

@@ -0,0 +1,47 @@
+"""Mixin for drivers that react to edges on GPIO pins."""
+
+import logging
+from collections.abc import Callable, Mapping
+from typing import Any, NamedTuple
+
+from RPi import GPIO
+
+__all__ = ["AEvents", "EdgeCallback"]
+
+EdgeCallback = Callable[[int], None]
+
+
+class _Event(NamedTuple):
+    callback: EdgeCallback
+    bounce_time: int
+
+
+class AEvents:
+    """Mixin for drivers that must react to changing pin states (``GPIO.setmode(GPIO.BCM)``).
+
+    Events are registered for both edges. The callback receives the channel and has to read the pin state itself to
+    distinguish rising and falling edges. Callbacks run in the callback thread of the GPIO library.
+    """
+
+    def __init__(self, config: Mapping[str, Any], logger: logging.Logger) -> None:
+        self._events: dict[int, _Event] = {}
+        self._logger_aevents = logger
+        GPIO.setmode(GPIO.BCM)
+
+    def _add_event(self, pin: int, func: EdgeCallback, bounce_time: int = 50) -> None:
+        """Remember an edge callback for ``pin``; it becomes active with :meth:`_register_events`."""
+        self._logger_aevents.info("AEvents._add_event - pin:%s, func:%s, bounce:%s.", pin, func, bounce_time)
+        self._events[int(pin)] = _Event(func, bounce_time)
+
+    def _register_events(self) -> None:
+        """Activate all edge callbacks - usually in ``_driver_start``."""
+        GPIO.setmode(GPIO.BCM)
+        for pin, event in self._events.items():
+            self._logger_aevents.debug("AEvents._register_events - pin:%s, bounce_time:%s", pin, event.bounce_time)
+            GPIO.add_event_detect(pin, GPIO.BOTH, callback=event.callback, bouncetime=event.bounce_time)
+
+    def _unregister_events(self) -> None:
+        """Deactivate all edge callbacks - usually in ``_driver_stop``."""
+        for pin in self._events:
+            self._logger_aevents.debug("AEvents._unregister_events - pin:%s", pin)
+            GPIO.remove_event_detect(pin)