readerboard 0.1.1__py3-none-any.whl

readerboard/api/routes_simple.py

@@ -0,0 +1,143 @@
+"""A smaller surface for clients that would rather not read status codes.
+
+Fixed paths, one message, and **every response is HTTP 200** with the outcome in
+the body. That suits a Home Assistant ``rest_command`` or a shell one-liner in a
+cron job, neither of which branches gracefully on a status code.
+
+There is one exception to always-200, and it is deliberate: a request without a
+valid API key gets a 401 like any other, because a caller the service will not
+talk to is not the same as a request that failed.
+
+``POST /Write/Message`` writes to a reserved slot rather than to the sign's
+priority file. That distinction matters more than it looks. By protocol a
+priority message suppresses every other file on the sign, so writing one here
+would quietly turn a service that shares the sign between several sources into a
+service that can only ever show one thing. Written to an ordinary slot it looks
+identical while it is the only message registered, and it shares the sign the
+moment anything else registers.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter
+
+from readerboard.api.deps import ControllerDep, RegistryDep, RequireApiKey, SettingsDep
+from readerboard.api.models import (
+    SimpleCommandRequest,
+    SimpleControlCommand,
+    SimpleDisplayMode,
+    SimpleMessageRequest,
+    SimpleResult,
+    SimpleToken,
+)
+from readerboard.protocol.tokens import CONTROL_COMMANDS, DISPLAY_MODES, MARKUP_TOKENS
+from readerboard.services import commands
+from readerboard.services.registry import DEFAULT_SLOT_KEY
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+write = APIRouter(prefix="/Write", tags=["Write (simple)"])
+enumerations = APIRouter(prefix="/Enumerations", tags=["Enumerations (simple)"])
+
+
+@write.post("/Message", summary="Write a message to the sign", dependencies=[RequireApiKey])
+async def write_message(
+    body: SimpleMessageRequest, registry: RegistryDep, settings: SettingsDep
+) -> SimpleResult:
+    """Display a message on the sign.
+
+    The message goes into a reserved slot rather than the sign's priority file,
+    so other sources can share the sign with it.
+    """
+    try:
+        await registry.upsert(
+            DEFAULT_SLOT_KEY,
+            body.message,
+            mode=body.display_mode.strip().upper(),
+            position="MIDDLE",
+            source="simple",
+            # Unset by default, which is exactly how this endpoint has always
+            # behaved: the message stays until something replaces it. Set it and
+            # an automation that stops calling leaves an empty sign rather than
+            # a stale temperature that still looks current.
+            ttl_seconds=settings.default_slot_ttl_seconds,
+            # Unknown tokens are passed through as literal text, exactly as the
+            # old parser did, so a payload that worked before cannot start
+            # failing now.
+            strict=False,
+        )
+    except KeyError:
+        return SimpleResult.error(
+            "The display mode '%s' is not valid" % body.display_mode
+        )
+    except Exception as err:
+        logger.warning("simple write failed: %s", err)
+        return SimpleResult.error(str(err))
+
+    return SimpleResult.ok("Message displayed on sign")
+
+
+@write.post(
+    "/ControlCommand",
+    summary="Send a control command to the sign",
+    dependencies=[RequireApiKey],
+)
+async def write_control_command(
+    body: SimpleCommandRequest, controller: ControllerDep
+) -> SimpleResult:
+    """Send one of the sign's control commands."""
+    try:
+        payload = commands.build(body.command, body.parameter)
+    except commands.UnknownCommand:
+        # The old wording, kept because something may be matching on it.
+        return SimpleResult.error("Unrecognized control command '%s'" % body.command)
+    except commands.BadParameter as err:
+        return SimpleResult.error(str(err))
+
+    try:
+        await controller.send_special(payload)
+    except Exception as err:
+        logger.warning("simple control command failed: %s", err)
+        return SimpleResult.error(str(err))
+
+    return SimpleResult.ok("Control command sent to sign")
+
+
+@enumerations.get("/DisplayModes", summary="Available display modes")
+async def display_modes() -> list[SimpleDisplayMode]:
+    """List the display modes, in the old shape."""
+    return [
+        SimpleDisplayMode(display_mode=token.text, description=token.description)
+        for token in DISPLAY_MODES
+    ]
+
+
+@enumerations.get("/ControlCommands", summary="Available control commands")
+async def control_commands() -> list[SimpleControlCommand]:
+    """List the control commands, in the old shape."""
+    return [
+        SimpleControlCommand(control_command=token.text, description=token.description)
+        for token in CONTROL_COMMANDS
+    ]
+
+
+@enumerations.get("/MarkupTokens", summary="Available markup tokens")
+async def markup_tokens() -> list[SimpleToken]:
+    """List the markup tokens, in the old shape.
+
+    ``token_text`` is the token to write in a message, such as ``<red>``, and
+    ``description`` says what it does. Easy to describe the wrong way round,
+    which is why they are spelled out here.
+    """
+    return [
+        SimpleToken(token_text=token.text, description=token.description)
+        for token in MARKUP_TOKENS
+    ]
+
+
+router.include_router(write)
+router.include_router(enumerations)

readerboard/api/routes_v2.py

@@ -0,0 +1,207 @@
+"""The current API.
+
+Status codes mean what they say here: 400 for a message the sign cannot render,
+401 for a missing key, 404 for a slot that does not exist, 409 when the pool is
+full, and 503 when the sign is unreachable. The routes in ``routes_simple``
+deliberately do none of that, and answer 200 to everything instead.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Response, status
+
+from readerboard.api.deps import AlertsDep, ClockDep, ControllerDep, RegistryDep, RequireApiKey
+from readerboard.api.models import (
+    AlertRequest,
+    AlertResponse,
+    ClockResponse,
+    ControlCommandRequest,
+    MessageRequest,
+    SlotKey,
+    SlotResponse,
+    TokenInfo,
+)
+from readerboard.protocol.tokens import (
+    CONTROL_COMMANDS,
+    DISPLAY_MODES,
+    MARKUP_TOKENS,
+    TEXT_POSITIONS,
+    Token,
+)
+from readerboard.services import commands
+
+router = APIRouter(prefix="/v2")
+
+messages = APIRouter(prefix="/messages", tags=["Messages"])
+alerts_routes = APIRouter(prefix="/alerts", tags=["Alerts"])
+sign_routes = APIRouter(prefix="/sign", tags=["Sign"])
+enumerations = APIRouter(prefix="/enumerations", tags=["Enumerations"])
+
+
+# ===========================================================================
+# Messages
+# ===========================================================================
+
+
+@messages.get("", summary="List the messages sharing the sign")
+async def list_messages(registry: RegistryDep) -> list[SlotResponse]:
+    """Return every registered slot, in the order the sign plays them."""
+    return [SlotResponse.of(slot) for slot in registry.list_slots()]
+
+
+@messages.get("/{key}", summary="Read one message")
+async def get_message(key: SlotKey, registry: RegistryDep) -> SlotResponse:
+    """Return one slot by name."""
+    return SlotResponse.of(registry.get(key))
+
+
+@messages.put("/{key}", summary="Register or replace a message", dependencies=[RequireApiKey])
+async def put_message(
+    key: SlotKey, body: MessageRequest, registry: RegistryDep
+) -> SlotResponse:
+    """Put a message in a slot, replacing whatever was there.
+
+    The sign rotates through every registered slot on its own, so registering a
+    second message does not displace the first.
+    """
+    slot = await registry.upsert(
+        key,
+        body.message,
+        mode=body.display_mode,
+        position=body.position,
+        order=body.order,
+        ttl_seconds=body.ttl_seconds,
+        source=body.source,
+    )
+    return SlotResponse.of(slot)
+
+
+@messages.delete(
+    "/{key}",
+    summary="Take a message off the sign",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[RequireApiKey],
+)
+async def delete_message(key: SlotKey, registry: RegistryDep) -> Response:
+    """Remove one slot and free the sign file it held."""
+    await registry.remove(key)
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@messages.delete(
+    "",
+    summary="Take every message off the sign",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[RequireApiKey],
+)
+async def clear_messages(registry: RegistryDep) -> Response:
+    """Remove every slot, leaving the sign showing nothing."""
+    await registry.clear()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ===========================================================================
+# Alerts
+# ===========================================================================
+
+
+@alerts_routes.get("", summary="Read the alert holding the sign")
+async def get_alert(alerts: AlertsDep) -> AlertResponse | None:
+    """Return the active alert, or null if the sign is rotating normally."""
+    alert = alerts.active
+    return AlertResponse.of(alert) if alert else None
+
+
+@alerts_routes.post("", summary="Take the sign over with an alert", dependencies=[RequireApiKey])
+async def post_alert(body: AlertRequest, alerts: AlertsDep) -> AlertResponse:
+    """Take the whole sign over until the alert is released.
+
+    This uses the sign's priority file, which suppresses every other message. If
+    a ttl is given, the sign is released automatically and the rotation resumes
+    by itself.
+    """
+    alert = await alerts.raise_alert(
+        body.message,
+        mode=body.display_mode,
+        position=body.position,
+        ttl_seconds=body.ttl_seconds,
+    )
+    return AlertResponse.of(alert)
+
+
+@alerts_routes.delete(
+    "",
+    summary="Give the sign back",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[RequireApiKey],
+)
+async def delete_alert(alerts: AlertsDep) -> Response:
+    """Release an alert so the rotation resumes."""
+    await alerts.release()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ===========================================================================
+# The sign itself
+# ===========================================================================
+
+
+@sign_routes.post("/sync-clock", summary="Set the sign's clock now", dependencies=[RequireApiKey])
+async def sync_clock(clock: ClockDep) -> ClockResponse:
+    """Set the sign's clock and day of week immediately.
+
+    The service already does this at startup, hourly, and whenever the link to
+    the sign comes back. This is for when you would rather not wait.
+    """
+    return ClockResponse(synced_at=await clock.sync())
+
+
+@sign_routes.post(
+    "/command",
+    summary="Send a control command to the sign",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[RequireApiKey],
+)
+async def send_command(body: ControlCommandRequest, controller: ControllerDep) -> Response:
+    """Send one of the sign's own control commands."""
+    await controller.send_special(commands.build(body.command, body.parameter))
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+# ===========================================================================
+# Enumerations
+# ===========================================================================
+
+
+def _as_info(tokens: tuple[Token, ...]) -> list[TokenInfo]:
+    return [TokenInfo(name=token.text, description=token.description) for token in tokens]
+
+
+@enumerations.get("/markup-tokens", summary="Markup tokens a message may contain")
+async def markup_tokens() -> list[TokenInfo]:
+    """List every token that can be written inline in a message."""
+    return _as_info(MARKUP_TOKENS)
+
+
+@enumerations.get("/display-modes", summary="Ways the sign can present a message")
+async def display_modes() -> list[TokenInfo]:
+    """List every display mode."""
+    return _as_info(DISPLAY_MODES)
+
+
+@enumerations.get("/text-positions", summary="Where text sits vertically")
+async def text_positions() -> list[TokenInfo]:
+    """List every vertical text position."""
+    return _as_info(TEXT_POSITIONS)
+
+
+@enumerations.get("/control-commands", summary="Commands aimed at the sign itself")
+async def control_commands() -> list[TokenInfo]:
+    """List every control command."""
+    return _as_info(CONTROL_COMMANDS)
+
+
+router.include_router(messages)
+router.include_router(alerts_routes)
+router.include_router(sign_routes)
+router.include_router(enumerations)

readerboard/config.py

@@ -0,0 +1,222 @@
+"""Everything the service reads from its environment, in one place.
+
+Settings come from three places, later ones winning: the defaults below, a TOML
+file (``/etc/readerboard/config.toml`` unless ``READERBOARD_CONFIG_FILE`` says
+otherwise), and environment variables prefixed ``READERBOARD_``.
+
+One change here is worth calling out because it will bite on upgrade. The old
+``config.json`` held ``com_port``, a bare device name that the server prefixed
+with ``/dev/`` before opening. This service takes a full pyserial URL in
+``serial_url`` instead, so a sign on an Ethernet adapter is
+``socket://192.168.2.51:4001`` and a sign on a cable is ``/dev/ttyUSB0``. There
+is no prefixing, and no way to express a network sign in the old key.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic import Field, SecretStr, field_validator, model_validator
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+DEFAULT_CONFIG_FILE = Path("/etc/readerboard/config.toml")
+
+# A BetaBrite Classic holds roughly 30000 bytes of messages and graphics all
+# told. Allocating the whole of it leaves the sign no room for anything else, so
+# the service refuses a pool that claims more than this much of it. The protocol
+# charges eleven bytes of directory overhead per configured file on top of each
+# file's own size, and that is counted too.
+SIGN_MEMORY_BUDGET = 26000
+
+
+def _config_file() -> Path:
+    override = os.environ.get("READERBOARD_CONFIG_FILE")
+    return Path(override) if override else DEFAULT_CONFIG_FILE
+
+
+class Settings(BaseSettings):
+    """The service's configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="READERBOARD_",
+        toml_file=_config_file(),
+        extra="forbid",
+    )
+
+    # == the link to the sign ==============================================
+
+    serial_url: str = Field(
+        default="loop://",
+        description=(
+            "pyserial URL for the sign: socket://host:port for an Ethernet to RS-232 "
+            "adapter, /dev/ttyUSB0 for a direct cable, or loop:// to run without one"
+        ),
+    )
+    baud_rate: int = Field(default=9600, ge=110, le=921600)
+    serial_timeout: float = Field(default=10.0, gt=0)
+    inter_packet_delay: float = Field(
+        default=0.5,
+        ge=0,
+        le=10,
+        description=(
+            "seconds to wait after each transmission before sending another. The old "
+            "server always slept 2 seconds; run scripts/protocol_spike.py to find what "
+            "this sign actually needs"
+        ),
+    )
+    backoff_initial: float = Field(default=1.0, gt=0)
+    backoff_max: float = Field(default=60.0, gt=0)
+
+    # == the pool of sign files the rotation uses ==========================
+
+    slot_count: int = Field(
+        default=8,
+        ge=1,
+        le=26,
+        description="how many messages can share the sign at once, one sign file each",
+    )
+    slot_capacity: int = Field(
+        default=256,
+        ge=16,
+        le=4096,
+        description="bytes allocated to each message, after markup has been rendered",
+    )
+
+    # == behaviour =========================================================
+
+    default_display_mode: str = "HOLD"
+    default_text_position: str = "MIDDLE"
+    registry_sweep_seconds: float = Field(default=15.0, gt=0)
+    refresh_interval_seconds: float = Field(
+        default=900.0,
+        gt=0,
+        description=(
+            "how often to push every message to the sign again whether or not it looks "
+            "necessary. This is what repairs a sign that was power cycled behind a "
+            "still-connected Ethernet adapter, which nothing else can detect"
+        ),
+    )
+    default_slot_ttl_seconds: float | None = Field(
+        default=None,
+        gt=0,
+        description=(
+            "expire the slot POST /Write/Message writes to, after this long. Unset, "
+            "which is the default, reproduces the old behaviour exactly: the message "
+            "stays until something replaces it. Setting it means a Home Assistant "
+            "automation that dies leaves a visibly empty sign rather than a quietly "
+            "wrong temperature"
+        ),
+    )
+    clock_sync_enabled: bool = True
+    clock_sync_interval_seconds: float = Field(default=3600.0, gt=0)
+    timezone: str | None = Field(
+        default=None,
+        description=(
+            "IANA name such as America/New_York, used when setting the sign's clock. "
+            "Unset means the machine's own local time"
+        ),
+    )
+
+    # == the HTTP surface ==================================================
+
+    host: str = "0.0.0.0"
+    port: int = Field(default=5001, ge=1, le=65535)
+    api_key: SecretStr = Field(
+        default=SecretStr(""),
+        description="required on every write. Generated by scripts/install.sh if absent",
+    )
+
+    # == where state and logs go ===========================================
+
+    state_path: Path = Path("/var/lib/readerboard/state.json")
+    log_level: str = "INFO"
+    log_file: Path | None = None
+
+    @field_validator("log_level")
+    @classmethod
+    def _check_log_level(cls, value: str) -> str:
+        allowed = {"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"}
+        upper = value.upper()
+        if upper not in allowed:
+            raise ValueError("log_level must be one of %s" % ", ".join(sorted(allowed)))
+        return upper
+
+    @field_validator("default_display_mode")
+    @classmethod
+    def _check_mode(cls, value: str) -> str:
+        from readerboard.protocol.tokens import MODE_BY_NAME
+
+        upper = value.upper()
+        if upper not in MODE_BY_NAME:
+            raise ValueError("unknown display mode %r" % value)
+        return upper
+
+    @field_validator("default_text_position")
+    @classmethod
+    def _check_position(cls, value: str) -> str:
+        from readerboard.protocol.tokens import POSITION_BY_NAME
+
+        upper = value.upper()
+        if upper not in POSITION_BY_NAME:
+            raise ValueError("unknown text position %r" % value)
+        return upper
+
+    @field_validator("timezone")
+    @classmethod
+    def _check_timezone(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+        try:
+            ZoneInfo(value)
+        except (ZoneInfoNotFoundError, ValueError) as err:
+            raise ValueError("unknown timezone %r: %s" % (value, err)) from err
+        return value
+
+    @model_validator(mode="after")
+    def _check_pool_fits(self) -> Settings:
+        from readerboard.protocol.constants import FILE_OVERHEAD_BYTES
+
+        claimed = self.slot_count * (self.slot_capacity + FILE_OVERHEAD_BYTES)
+        if claimed > SIGN_MEMORY_BUDGET:
+            raise ValueError(
+                "slot_count %d at slot_capacity %d claims %d bytes of the sign's "
+                "memory pool, more than the %d this service is willing to take. "
+                "Lower one of them."
+                % (self.slot_count, self.slot_capacity, claimed, SIGN_MEMORY_BUDGET)
+            )
+        if self.backoff_max < self.backoff_initial:
+            raise ValueError("backoff_max must not be smaller than backoff_initial")
+        return self
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Put the TOML file below the environment but above the defaults."""
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            TomlConfigSettingsSource(settings_cls),
+            file_secret_settings,
+        )
+
+    def redacted(self) -> dict[str, Any]:
+        """Return the settings as a dict with the API key removed, safe to log."""
+        data = self.model_dump(mode="json")
+        data["api_key"] = "set" if self.api_key.get_secret_value() else "unset"
+        return data

readerboard/logging_setup.py

@@ -0,0 +1,53 @@
+"""Logging configuration.
+
+Output goes to stderr, which is what journald reads when the service runs under
+systemd, with an optional rotating file as well for anyone not running it that
+way.
+
+Log messages are documentation. They are the only account of what the service
+did that anyone will read at three in the morning, so they say what happened and
+what it means rather than dumping state. The one thing they never contain is the
+API key.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import sys
+from pathlib import Path
+
+FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+MAX_FILE_BYTES = 1_000_000
+BACKUP_COUNT = 3
+
+
+def configure(level: str = "INFO", log_file: Path | None = None) -> None:
+    """Set up logging for the service. Safe to call more than once."""
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    for handler in list(root.handlers):
+        root.removeHandler(handler)
+        handler.close()
+
+    formatter = logging.Formatter(FORMAT, datefmt=DATE_FORMAT)
+
+    stream = logging.StreamHandler(sys.stderr)
+    stream.setFormatter(formatter)
+    root.addHandler(stream)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        rotating = logging.handlers.RotatingFileHandler(
+            log_file, maxBytes=MAX_FILE_BYTES, backupCount=BACKUP_COUNT, encoding="utf-8"
+        )
+        rotating.setFormatter(formatter)
+        root.addHandler(rotating)
+
+    # uvicorn installs its own handlers; letting them propagate to ours would
+    # print every access line twice.
+    for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
+        logging.getLogger(name).propagate = False

readerboard/protocol/__init__.py

@@ -0,0 +1 @@
+"""The Alpha sign protocol: constants, markup, and frame builders."""