tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/devices/schema/rfid.py

@@ -0,0 +1,44 @@
+"""Schema of the driver ``rfid``."""
+
+from typing import Any
+
+from tinyjukebox.devices.schema import adriver
+
+__all__ = ["SPI_PINS", "get_schema"]
+
+SPI_PINS = (9, 10, 11)
+"""MISO, MOSI and SCLK of SPI0 - rfid-reader would make them outputs, and SPI would not work until the next boot"""
+
+
+def _pin(description: str) -> dict[str, Any]:
+    return {
+        "description": description,
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 53,
+        "not": {"enum": list(SPI_PINS)},
+    }
+
+
+def get_schema() -> dict[str, Any]:
+    driver_specific_properties = {
+        "pins": {
+            "description": "rfid reader pins (BCM numbers); two different ones, none of 9, 10, 11 (SPI0)",
+            "type": "object",
+            "properties": {
+                "pin_rst": _pin("reset pin"),
+                "pin_cs": _pin("chip select - rfid-reader drives it itself, any free pin; e.g. 8 for SPI0 CE0"),
+            },
+            "required": ["pin_rst", "pin_cs"],
+            "additionalProperties": False,
+        },
+    }
+    schema = adriver.get_schema("rfid", driver_specific_properties)
+    schema["driver"]["properties"]["command"] = {
+        "description": "command that starts rfid-reader (optional, default: sudo -n /usr/local/bin/rfid-reader); "
+        "the pins are appended as arguments",
+        "type": "array",
+        "items": {"type": "string"},
+        "minItems": 1,
+    }
+    return schema

tinyjukebox/devices/schema/rgbled.py

@@ -0,0 +1,26 @@
+"""Schema of the driver ``rgbled``."""
+
+from typing import Any
+
+from tinyjukebox.devices.schema import adriver
+from tinyjukebox.messages import Color
+
+__all__ = ["COLOR_NAMES", "get_schema"]
+
+COLOR_NAMES = [color.name for color in Color]
+
+PHYSICAL_CLOSED = {
+    "description": "low/high - gpio level that switches the color on",
+    "type": "string",
+    "enum": ["low", "high"],
+}
+
+
+def get_schema() -> dict[str, Any]:
+    driver_specific_properties: dict[str, Any] = {
+        "initial-color": {"description": "color at startup", "type": "string", "enum": COLOR_NAMES},
+    }
+    for color in ("red", "green", "blue"):
+        driver_specific_properties[f"pin-{color}"] = {"description": f"gpio pin {color}", "type": "integer"}
+        driver_specific_properties[f"physical-closed-{color}"] = PHYSICAL_CLOSED
+    return adriver.get_schema("rgbled", driver_specific_properties)

tinyjukebox/diagnostics.py

@@ -0,0 +1,179 @@
+"""Central diagnostics (docs/developer/library.md, section 4.22): what the box logs that is worth a look from the
+library - warnings and errors, and the structured events that a component marks with :func:`diagnostic`.
+
+The records are collected by a log handler that never waits: it redacts the record, puts it into a bounded buffer and
+returns. The synchronization takes them from there in its own thread and delivers them to the library (``take`` and
+``delivered``); without a connection they wait. Under pressure the buffer drops INFO before WARNING before ERROR and
+counts what it dropped. The log file of the box stays the full record; the library gets what helps to find a fault.
+
+Nothing that identifies a person or opens a door leaves the box: :func:`redact` removes passwords, keys, tokens,
+certificates, the query of addresses, tag UIDs, bluetooth addresses and the ids of Spotify.
+"""
+
+import collections
+import logging
+import re
+import threading
+import time
+import traceback
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from tinyjukebox.sync.util import timestamp
+
+__all__ = ["CAPACITY", "Collector", "diagnostic", "redact"]
+
+CAPACITY = 2000  # records a box keeps for the library at most
+MAX_MESSAGE = 2000  # characters of a message
+MAX_TRACEBACK = 8000
+STARTED = time.monotonic()
+
+_REDACTIONS = [
+    # certificates and keys
+    (re.compile(r"-----BEGIN [A-Z ]+-----.*?-----END [A-Z ]+-----", re.S), "<pem>"),
+    # Authorization: Box id:secret, Bearer ..., token ...
+    (
+        re.compile(r"(?i)\b(authorization|bearer|token|box)\b(\s*[:=]?\s*)(\S+:)?[A-Za-z0-9_\-.~+/]{16,}=*"),
+        r"\1\2<secret>",
+    ),
+    # password=..., "secret": "...", key: ...
+    (
+        re.compile(
+            r"""(?i)(["']?\b(?:password|passwd|secret|key|token|bootstrap|client_secret)["']?\s*[:=]\s*)(["']?)"""
+            r"""[^\s"',;}]+"""
+        ),
+        r"\1\2<secret>",
+    ),
+    # the query of an address may carry a token or who listens
+    (re.compile(r"(https?://[^\s?#'\"]+)\?[^\s'\"]*"), r"\1?<query>"),
+    # user:password@ in an address
+    (re.compile(r"(https?://)[^\s/@'\"]+@"), r"\1<user>@"),
+    # ids of Spotify (the kind stays)
+    (re.compile(r"\bspotify:(album|playlist|track|episode|show|audiobook|artist):[A-Za-z0-9]+"), r"spotify:\1:<id>"),
+    (re.compile(r"(open\.spotify\.com/(?:[a-z]+/)?)[A-Za-z0-9]{10,}"), r"\1<id>"),
+    # hex bytes with colons, never a part of a longer run: six are the address of a bluetooth device, four to ten (four,
+    # seven or ten for a tag) the UID of a tag
+    (re.compile(r"(?<![0-9A-Fa-f:])[0-9A-Fa-f]{2}(?::[0-9A-Fa-f]{2}){5}(?![0-9A-Fa-f:])"), "<mac>"),
+    (re.compile(r"(?<![0-9A-Fa-f:])[0-9A-Fa-f]{2}(?::[0-9A-Fa-f]{2}){3,9}(?![0-9A-Fa-f:])"), "<uid>"),
+]
+
+
+def redact(text: str) -> str:
+    """``text`` without credentials, certificate material, queries of addresses, tag UIDs, bluetooth addresses and ids
+    of Spotify."""
+    for pattern, replacement in _REDACTIONS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+def diagnostic(code: str, text: str | None = None, **params: Any) -> dict[str, Any]:
+    """``extra`` for a log call that is a structured event: a stable code and safe parameters, e.g.
+    ``logger.info("radio started in %d ms", ms, extra=diagnostic("radio.startup", resolve_ms=12))``. The library gets
+    such a record whatever its level - with ``text`` instead of the message of the log file, if that says more than
+    the library should know (e.g. the whole address of a stream)."""
+    return {"diagnostic": {"code": code, "params": params, "text": text}}
+
+
+_PRIORITY = {"DEBUG": 0, "INFO": 0, "WARNING": 1, "ERROR": 2, "CRITICAL": 2}
+
+
+class Collector(logging.Handler):
+    """Collects records for the library. ``level``: from which level an ordinary record is collected; ``urgent()`` is
+    called for an error (it must not block - e.g. it wakes the synchronization)."""
+
+    def __init__(
+        self,
+        level: int = logging.WARNING,
+        capacity: int = CAPACITY,
+        urgent: Callable[[], None] | None = None,
+        root: str = "",
+    ) -> None:
+        super().__init__(logging.DEBUG)
+        self._level = level
+        self._capacity = capacity
+        self.urgent = urgent
+        self._root = root + "." if root else ""
+        self._lock = threading.Lock()
+        self._records: collections.deque[dict[str, Any]] = collections.deque()
+        self._number = 0
+        self._taken = 0  # the highest number handed out by take(): such a record is not changed any more
+        self.dropped: dict[str, int] = collections.defaultdict(int)  # by level, since the last delivery
+
+    def emit(self, record: logging.LogRecord) -> None:
+        marked = getattr(record, "diagnostic", None)
+        if record.levelno < self._level and marked is None:
+            return
+        try:
+            entry = self._entry(record, marked)
+        except Exception:  # a broken log call must not break the logging - nor the box
+            return
+        with self._lock:
+            last = self._records[-1] if self._records else None
+            if (
+                last is not None
+                and last["seq"] > self._taken
+                and (last["code"], last["message"], last["level"]) == (entry["code"], entry["message"], entry["level"])
+            ):
+                last["repeated"] = last.get("repeated", 1) + 1  # a fault that repeats is one record
+                last["last"] = entry["time"]
+            else:
+                self._number += 1
+                self._records.append({"seq": self._number, **entry})
+                if len(self._records) > self._capacity:
+                    self._drop()
+        if record.levelno >= logging.ERROR and self.urgent is not None:
+            self.urgent()
+
+    def _drop(self) -> None:
+        """The oldest record of the lowest priority goes; what is dropped is counted."""
+        lowest = min(_PRIORITY.get(entry["level"], 0) for entry in self._records)
+        for index, entry in enumerate(self._records):
+            if _PRIORITY.get(entry["level"], 0) == lowest:
+                del self._records[index]
+                self.dropped[entry["level"]] += entry.get("repeated", 1)
+                return
+
+    def _entry(self, record: logging.LogRecord, marked: Mapping[str, Any] | None) -> dict[str, Any]:
+        component = record.name[len(self._root) :] if record.name.startswith(self._root) else record.name
+        message = redact(marked["text"] if marked and marked.get("text") else record.getMessage())[:MAX_MESSAGE]
+        entry: dict[str, Any] = {
+            "time": timestamp(), "uptime": round(record.created - time.time() + time.monotonic() - STARTED, 1),
+            "level": record.levelname, "component": component,
+            # a stable code: the one of a structured event, else the text of the call before its values
+            "code": marked["code"] if marked else redact(str(record.msg))[:200],
+            "message": message,
+        }  # fmt: skip
+        if marked and marked.get("params"):
+            entry["params"] = {key: _safe(value) for key, value in marked["params"].items()}
+        if record.exc_info and record.exc_info[1] is not None:
+            entry["exception"] = type(record.exc_info[1]).__name__
+            entry["traceback"] = redact("".join(traceback.format_exception(*record.exc_info)))[-MAX_TRACEBACK:]
+        return entry
+
+    def take(self, limit: int = 200) -> tuple[list[dict[str, Any]], dict[str, int]]:
+        """The oldest records that wait, and what was dropped - they stay until :meth:`delivered`."""
+        with self._lock:
+            taken = [dict(entry) for entry in list(self._records)[:limit]]
+            if taken:
+                self._taken = max(self._taken, taken[-1]["seq"])
+            return taken, dict(self.dropped)
+
+    def delivered(self, last: int, dropped: Mapping[str, int]) -> None:
+        """The library has the records up to number ``last`` and knows of what was dropped until then."""
+        with self._lock:
+            while self._records and self._records[0]["seq"] <= last:
+                self._records.popleft()
+            for level, count in dropped.items():
+                self.dropped[level] -= count
+                if self.dropped[level] <= 0:
+                    del self.dropped[level]
+
+    def waiting(self) -> int:
+        with self._lock:
+            return len(self._records)
+
+
+def _safe(value: Any) -> Any:
+    if isinstance(value, bool | int | float) or value is None:
+        return value
+    return redact(str(value))[:500]

tinyjukebox/errors.py

@@ -0,0 +1,91 @@
+"""Errors of the box control (see :mod:`tinyjukebox.control`); the rest api maps them to http status codes."""
+
+from typing import Any
+
+__all__ = [
+    "ApiError",
+    "BadRequest",
+    "Conflict",
+    "Forbidden",
+    "Gone",
+    "InsufficientStorage",
+    "LengthRequired",
+    "MethodNotAllowed",
+    "NotFound",
+    "PayloadTooLarge",
+    "ServiceUnavailable",
+    "TooManyRequests",
+    "Unauthorized",
+    "Unprocessable",
+]
+
+
+class ApiError(Exception):
+    """Base class - ``message`` is the English text of the error, ``details`` are added to the json error response.
+
+    An error that a user of the web page runs into has a ``code`` among its details, and the values its text needs
+    (``Conflict("tag ... exists already.", code="tag.exists", uid=uid)``): the page shows its own text for the code,
+    in its language (``error.<code>`` in ``web/web/texts``), and the message for an error without one."""
+
+    status = 500
+
+    def __init__(self, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details
+
+
+# the names follow the http status texts - an 'Error' suffix would only add noise
+class BadRequest(ApiError):  # noqa: N818
+    status = 400
+
+
+class Unauthorized(ApiError):  # noqa: N818
+    status = 401
+
+
+class Forbidden(ApiError):  # noqa: N818
+    status = 403
+
+
+class NotFound(ApiError):  # noqa: N818
+    status = 404
+
+
+class MethodNotAllowed(ApiError):  # noqa: N818
+    status = 405
+
+    def __init__(self, allowed: list[str]) -> None:
+        super().__init__("method not allowed.", allowed=sorted(set(allowed)))
+
+
+class Conflict(ApiError):  # noqa: N818
+    status = 409
+
+
+class Gone(ApiError):  # noqa: N818
+    status = 410
+
+
+class LengthRequired(ApiError):  # noqa: N818
+    status = 411
+
+
+class PayloadTooLarge(ApiError):  # noqa: N818
+    status = 413
+
+
+class Unprocessable(ApiError):  # noqa: N818
+    status = 422
+
+
+class TooManyRequests(ApiError):  # noqa: N818
+    status = 429
+
+
+class ServiceUnavailable(ApiError):  # noqa: N818
+    status = 503
+
+
+class InsufficientStorage(ApiError):  # noqa: N818
+    status = 507

tinyjukebox/headset.py

@@ -0,0 +1,296 @@
+"""The bluetooth headset as seen by the box: output and volume follow the connection, a lost headset pauses the
+playback, next + prev held start the pairing. Bluetooth itself is the business of the bluetooth driver (or of the
+virtual headset) - they talk via :data:`~tinyjukebox.messages.BLUETOOTH_STATE` and
+:data:`~tinyjukebox.messages.BLUETOOTH_COMMAND`."""
+
+import logging
+import threading
+import time
+from typing import Any, Protocol
+
+from tinyjukebox.albumplayer.simpleplayer import AudioOutput, bluealsa_device
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.core.pubsub import PubSubClient
+from tinyjukebox.messages import (
+    BLUETOOTH_COMMAND,
+    BLUETOOTH_STATE,
+    BUTTON_HELD,
+    BUTTON_PRESSED,
+    BUTTON_RELEASED,
+    BluetoothAction,
+    BluetoothCommand,
+    BluetoothState,
+    Button,
+    PairingResult,
+)
+from tinyjukebox.rgbled import Color, RGBLed
+from tinyjukebox.stm.stmoperation import AlbumControl
+from tinyjukebox.volumemanager import VolumeProfile, Volumes
+
+__all__ = ["PAIRING_BUTTONS", "BluetoothVolumeControl", "Headset"]
+
+PAIRING_BUTTONS = frozenset({Button.NEXT, Button.PREV})
+"""Held together (``hold_timeout`` of their input drivers): search a headset and pair it."""
+SEARCH_LED_TIMEOUT = 120.0  # the search led ends by itself at the latest - the driver ends a search after 60 s
+SEARCH_BLINK = 0.2
+PAIRED_LED = 2.0  # seconds white after a successful pairing
+FAILED_LED = 3.0  # seconds red blinking after a failed search
+CONNECT_SETTLE = 3.0
+"""Seconds after a connect in which a louder volume that the headset reports is the one of the last time, which
+arrives late: the volume of the box is set again (never as loud as the last time) - unless the volume has been changed
+on the box meanwhile."""
+SPEAKER_AFTER_LOSS = 3.0
+"""Seconds after the loss of the headset after which the speaker is the output at the latest - normally it is as soon
+as the playback has paused."""
+
+
+def _address(state: BluetoothState) -> str | None:
+    return state.device.address if state.device is not None else None
+
+
+class BluetoothVolumeControl:
+    """Volume of the headset: set by the bluetooth driver (:data:`~tinyjukebox.messages.BLUETOOTH_COMMAND`) - only while
+    the headset is connected."""
+
+    def __init__(self, pubsub_client: PubSubClient, logger: logging.Logger) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._pubsub_client = pubsub_client
+        self.connected = False
+
+    def set_volume(self, volume: float) -> None:
+        if self.connected:
+            self._pubsub_client.publish(BLUETOOTH_COMMAND, BluetoothCommand(BluetoothAction.VOLUME, volume))
+
+
+class Albums(Protocol):
+    def get_album(self) -> AlbumControl | None: ...
+
+
+class Headset:
+    """Reacts on the :class:`~tinyjukebox.messages.BluetoothState` of the driver:
+
+    * connected: the players play on the headset (a playing track continues there), the buttons change its volume,
+      which starts at its start value,
+    * disconnected: a playing album or radio station pauses (it continues if the headset comes back within 10 min),
+      the speaker is the output again once the playback has paused - and plays only after a button press,
+    * volume changed on the headset: taken over, limited to its maximum,
+    * search: led overlay (blue blinking fast, then 2 s white or 3 s red blinking).
+
+    The handlers run in the pubsub dispatch thread - they only queue events and publish messages.
+    """
+
+    def __init__(
+        self,
+        pubsub_client: PubSubClient,
+        logger: logging.Logger,
+        rgbled: RGBLed,
+        output: AudioOutput,
+        volumes: Volumes,
+        volume_control: BluetoothVolumeControl,
+        albums: Albums,
+    ) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._pubsub_client = pubsub_client
+        self._rgbled = rgbled
+        self._output = output
+        self._volumes = volumes
+        self._volume_control = volume_control
+        self._albums = albums
+        self._lock = threading.RLock()  # the handlers publish - a synchronous pubsub client calls them again
+        self._state: BluetoothState | None = None
+        self._held: set[Button] = set()
+        # counts the losses of the headset: a switch to the speaker asked for before a reconnect is void
+        self._losses = 0
+        self._speaker_timer: threading.Timer | None = None
+        self._connected_at = 0.0  # monotonic time of the last connect
+        # the volume the box set at the connect, or a quieter one the headset reported since - None once settled
+        self._start_volume: float | None = None
+
+    @property
+    def state(self) -> BluetoothState | None:
+        """The last state of the driver - ``None``: there is no bluetooth driver (or it has not reported yet)."""
+        return self._state
+
+    def info(self) -> dict[str, Any]:
+        state = self._state
+        if state is None:
+            return {"available": False, "virtual": False, "device": None, "connected": False, "battery": None,
+                    "volume": None, "pairing": False, "pairing_result": None}  # fmt: skip
+        device = state.device
+        return {
+            "available": True,
+            "virtual": state.virtual,
+            "device": {"address": device.address, "name": device.name} if device is not None else None,
+            "connected": state.connected,
+            "battery": state.battery,
+            "volume": state.volume,
+            "pairing": state.pairing,
+            "pairing_result": state.pairing_result.value if state.pairing_result is not None else None,
+        }
+
+    # --- commands -------------------------------------------------------------------------------------------------
+
+    def pair(self) -> None:
+        """Search a headset in pairing mode and pair it (the driver ignores it while a search runs). Without
+        bluetooth the led shows the failure at once."""
+        if self._state is None:
+            self._logger.warning("pair - bluetooth is not available")
+            self._rgbled.show_overlay(Color.RED, Color.BLACK, SEARCH_BLINK, FAILED_LED)
+            return
+        self._logger.info("pair - starting the search")
+        self._pubsub_client.publish(BLUETOOTH_COMMAND, BluetoothCommand(BluetoothAction.PAIR))
+
+    def unpair(self) -> None:
+        self._logger.info("unpair")
+        self._pubsub_client.publish(BLUETOOTH_COMMAND, BluetoothCommand(BluetoothAction.UNPAIR))
+
+    # --- handlers -------------------------------------------------------------------------------------------------
+
+    def _state_handler(self, message: object) -> None:
+        if not isinstance(message, BluetoothState):
+            self._logger.error("_state_handler - expected a BluetoothState, received %r", message)
+            return
+        with self._lock:
+            previous = self._state or BluetoothState()
+            self._state = message
+            self._logger.info("_state_handler - %s", message)
+            # the address counts: BlueZ may learn the name of the headset only after it has connected
+            same_device = _address(previous) == _address(message)
+            if message.connected and (not previous.connected or not same_device):
+                self._connected(message)
+            elif previous.connected and not message.connected:
+                self._disconnected()
+            elif message.connected and message.volume is not None and message.volume != previous.volume:
+                self._volume_reported(message.volume)
+            self._show_search(previous, message)
+
+    def _volume_reported(self, volume: float) -> None:
+        """Changed on the headset (absolute volume) - or the report of an own change, which is ignored.
+
+        Just after a connect a louder volume is the one of the last time, which BlueALSA may report only after the box
+        has set its start value: the volume of the box is set again, once (:data:`CONNECT_SETTLE`)."""
+        manager = self._volumes.manager(VolumeProfile.HEADPHONES)
+        start = self._start_volume
+        if start is not None and (
+            time.monotonic() - self._connected_at >= CONNECT_SETTLE or round(manager.get_volume()) != round(start)
+        ):
+            start = self._start_volume = None  # settled - or changed on the box (buttons, web page)
+        if start is not None and round(volume) > round(start):
+            self._start_volume = None
+            self._logger.info("the headset reports %s%% just after it connected - the volume of the box counts",
+                              round(volume))  # fmt: skip
+            manager.update_volume()
+            return
+        manager.mixer_changed(volume)
+        if start is not None:
+            self._start_volume = manager.get_volume()  # a quieter one is taken over
+
+    def _connected(self, state: BluetoothState) -> None:
+        assert state.device is not None  # noqa: S101 - connected implies a paired headset
+        address = state.device.address
+        self._logger.info("headset %s connected - playing on it", address)
+        self._losses += 1  # a switch to the speaker that waits for a paused playback is void now
+        self._cancel_speaker_timer()
+        self._connected_at = time.monotonic()
+        volume = self._volumes.manager(VolumeProfile.HEADPHONES)
+        self._volume_control.connected = True
+        self._volumes.use(VolumeProfile.HEADPHONES)
+        volume.reset()  # never as loud as the last time
+        self._start_volume = volume.get_volume()
+        # the players open the headset with the current volume - the volume set above may arrive after the first sound
+        self._output.use_headset(None if state.virtual else lambda: bluealsa_device(address, volume.get_volume()))
+        album = self._albums.get_album()
+        if album is not None:
+            album.cmd_output_changed()
+
+    def _disconnected(self) -> None:
+        self._volume_control.connected = False
+        self._volumes.use(VolumeProfile.SPEAKER)
+        album = self._albums.get_album()
+        if album is None:
+            self._logger.info("headset disconnected - the speaker is the output again")
+            self._output.use_speaker()
+            return
+        self._logger.info("headset disconnected - pausing, the speaker is the output again once the playback paused")
+        # until the playback has paused the output stays on the headset that has gone: what starts meanwhile - a
+        # track that was due, a button pressed just before - fails there and pauses instead of playing on the speaker
+        self._losses += 1
+        loss = self._losses
+
+        def speaker() -> None:
+            self._speaker_after(loss)
+
+        self._cancel_speaker_timer()
+        timer = threading.Timer(SPEAKER_AFTER_LOSS, speaker)  # if the playback ends without handling it
+        timer.name, timer.daemon = "Headset.speaker", True
+        self._speaker_timer = timer
+        timer.start()
+        album.cmd_output_lost(then=speaker)
+
+    def _speaker_after(self, loss: int) -> None:
+        """The playback has handled the loss of the headset (or the time is up): the speaker is the output - unless
+        the headset has come back meanwhile."""
+        with self._lock:
+            if loss != self._losses:
+                return
+            self._losses += 1  # done: the other one of the two calls does nothing
+            self._cancel_speaker_timer()
+            self._output.use_speaker()
+            self._logger.info("the speaker is the output again")
+
+    def _cancel_speaker_timer(self) -> None:
+        timer, self._speaker_timer = self._speaker_timer, None
+        if timer is not None:
+            timer.cancel()
+
+    def _show_search(self, previous: BluetoothState, state: BluetoothState) -> None:
+        if state.pairing and not previous.pairing:
+            self._rgbled.show_overlay(Color.BLUE, Color.BLACK, SEARCH_BLINK, SEARCH_LED_TIMEOUT)
+        elif previous.pairing and not state.pairing:
+            if state.pairing_result is PairingResult.PAIRED:
+                self._rgbled.show_overlay(Color.WHITE, duration=PAIRED_LED)
+            else:
+                self._rgbled.show_overlay(Color.RED, Color.BLACK, SEARCH_BLINK, FAILED_LED)
+
+    def _button_handler(self, topic: str, message: object) -> None:
+        """Next + prev held together start the search. A press or release ends the hold of a button."""
+        if not isinstance(message, Button):
+            return
+        with self._lock:
+            if topic != BUTTON_HELD:
+                self._held.discard(message)
+                return
+            self._held.add(message)
+            if not self._held >= PAIRING_BUTTONS:
+                return
+            self._held -= PAIRING_BUTTONS
+        self._logger.info("next and prev held - pairing")
+        self.pair()
+
+    def _pressed(self, message: object) -> None:
+        self._button_handler(BUTTON_PRESSED, message)
+
+    def _held_handler(self, message: object) -> None:
+        self._button_handler(BUTTON_HELD, message)
+
+    def _released(self, message: object) -> None:
+        self._button_handler(BUTTON_RELEASED, message)
+
+    # --- start / stop ---------------------------------------------------------------------------------------------
+
+    def start(self) -> None:
+        self._pubsub_client.subscribe(BLUETOOTH_STATE, self._state_handler)
+        self._pubsub_client.subscribe(BUTTON_PRESSED, self._pressed)
+        self._pubsub_client.subscribe(BUTTON_HELD, self._held_handler)
+        self._pubsub_client.subscribe(BUTTON_RELEASED, self._released)
+
+    def stop(self) -> None:
+        self._pubsub_client.unsubscribe(BLUETOOTH_STATE, self._state_handler, ignore_not_found=True)
+        self._pubsub_client.unsubscribe(BUTTON_PRESSED, self._pressed, ignore_not_found=True)
+        self._pubsub_client.unsubscribe(BUTTON_HELD, self._held_handler, ignore_not_found=True)
+        self._pubsub_client.unsubscribe(BUTTON_RELEASED, self._released, ignore_not_found=True)
+        with self._lock:
+            self._losses += 1  # a switch to the speaker that runs right now is void
+            self._cancel_speaker_timer()
+        self._volume_control.connected = False  # nothing is published after the pubsub client has been disconnected
+        self._rgbled.clear_overlay()