readerboard 0.1.4__tar.gz → 0.3.0__tar.gz

{readerboard-0.1.4/readerboard.egg-info → readerboard-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.1.4
-Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
+Version: 0.3.0
+Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, expiring messages and clock sync
 Author: mjaksn
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/mjaksn/readerboard
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Hardware
 Classifier: Typing :: Typed
@@ -72,8 +73,9 @@ until it is released, after which the rotation resumes.
 - **It survives restarts and outages.** The registered messages are persisted, and a
   write that arrives while the sign is unreachable is accepted and delivered when the
   link returns.
-- **Errors are errors.** A dead serial link is a 503, not an HTTP 200 with the word
-  ERROR in the body.
+- **Errors are errors.** A dead serial link is a 503 and a message the sign cannot
+  render is a 400, each with the reason in the body. Nothing here reports a failure
+  under a 200.
 
 ## Requirements
 
@@ -106,6 +108,20 @@ docker run --rm -p 5001:5001 \
 
 Then open <http://127.0.0.1:5001/docs>.
 
+`loop://` swallows everything written to it, so the service runs but there is
+nothing to see. To watch what it would have sent, run it against the sign
+simulator in `tools/signsim/` instead:
+
+```
+pip install --require-hashes -r tools/signsim/requirements.lock
+python scripts/run_with_simulator.py
+```
+
+That starts the simulator and the service together, already pointed at each
+other, and stops both on Ctrl+C. The simulator decodes each transmission, says
+what every byte of it means, and shows what the sign would be holding as a
+result. `tools/signsim/README.md` has the details.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -161,12 +177,13 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
+Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
 
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/temperature \
+curl -X PUT http://localhost:5001/messages/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -174,7 +191,7 @@ curl -X PUT http://localhost:5001/v2/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/doorbell \
+curl -X PUT http://localhost:5001/messages/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
@@ -182,44 +199,25 @@ curl -X PUT http://localhost:5001/v2/messages/doorbell \
 Take the sign over for thirty seconds:
 
 ```
-curl -X POST http://localhost:5001/v2/alerts \
+curl -X POST http://localhost:5001/alerts \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API, including every markup token and display mode, is at `/docs`.
+The full API is at `/docs`. Every markup token, display mode, text position and
+control command is listed by the `/enumerations` reads there, which answer at
+request time rather than being frozen into the description.
 
 ### Writing messages
 
 A message is plain text plus tokens written as `<name>`: `<green>18.4<degree>` is a
-colour change, a number, and a degree symbol. `GET /v2/enumerations/markup-tokens` lists
+colour change, a number, and a degree symbol. `GET /enumerations/markup-tokens` lists
 them all.
 
 Text is encoded against the sign's own character table rather than as UTF-8, so `café`
-displays correctly. A character the sign cannot render is rejected with a 400 on `/v2`,
-and replaced with `?` on the simpler endpoints described below.
-
-## A simpler set of endpoints
-
-Alongside `/v2` there is a smaller surface: `POST /Write/Message`,
-`POST /Write/ControlCommand`, and the `/Enumerations` reads.
-
-These follow one convention that `/v2` does not. **Every response is HTTP 200**, with the
-outcome in the body:
-
-```json
-{"result": "OK", "result_message": "Message displayed on sign"}
-```
-
-That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The single exception is a
-missing or wrong API key, which is a 401: a caller the service will not talk to is not the
-same as a request that failed.
-
-`POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
-not touch the sign's **priority** file, which by protocol suppresses every other message on
-the sign. 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.
+displays correctly. A character the sign cannot render is rejected with a 400, as is an
+unknown token: a write is told what the sign would have made of it rather than being
+shown something it did not ask for.
 
 ## Configuration
 
@@ -242,6 +240,19 @@ the log, but they are not settings to fiddle with.
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
+Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
+that could write to it.
+
+The key is declared to the API description as a security scheme, so the Swagger UI at
+`/docs` has an **Authorize** button: enter the key once and every write on the page
+carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+or a Home Assistant `rest_command` changes.
+
+That page is configured to remember the key, so it survives a reload or a browser
+restart rather than needing to be pasted in again. Convenient on your own machine, and
+worth knowing before you use **Authorize** on a shared or kiosk browser, where the next
+person to open `/docs` inherits it. Use the browser's Logout in the Authorize dialog, or
+just do not authorize there.
 
 **Message content reaches the sign as protocol bytes**, so it is worth knowing what a
 client holding the key can do. The markup renderer emits bytes only for tokens it
@@ -291,26 +302,31 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
-## Licence
+`tools/signsim/` is the sign simulator, a PySide6 stand-in for the sign, described
+above. `tools/apiclient/` is the client, a PySide6 application for calling the API by
+hand: every endpoint, responses shown as text rather than JSON, and a vocabulary it
+loads from the service rather than one compiled into it. The tests of both are
+collected by the `pytest` run here and need no Qt installed; the applications do, and
+each is pinned separately so that nothing the service installs ever pulls Qt in.
 
-MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
+`scripts/run_with_simulator.py` starts the service and the simulator together, and
+with `--with-client` the client as well, so the whole loop comes up from one command.
+Both editors carry it as a launch configuration under the same name, "readerboard and
+the sign simulator", in `.vscode/launch.json` and in `.idea/runConfigurations/`, beside
+configurations for running the pieces separately. Both carry the three way one as
+"readerboard, the sign simulator and the client" as well.
 
-One caveat, recorded because it is easy to miss.
-`readerboard/protocol/constants.py` is vendored from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), and that
-repository carries no license file. No license is not the same as a permissive one: it
-means no copying permission has been granted at all. That module is therefore the one
-part of this project whose provenance is not cleanly MIT.
+## Licence
 
-In practice it is a table of byte values dictated by the protocol rather than authored
-expression, and `docs/protocol-notes.md` now cites the protocol document directly, so the
-table can be regenerated from the primary source if that ever needs settling properly.
+MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
 
 ## Credits
 
-`readerboard/protocol/constants.py` came, with thanks, from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), with some
-corrections noted in the file.
+The protocol is documented in the Alpha Sign Communications Protocol, form 9708-8061,
+published by Adaptive Micro Systems. Every byte value in
+`readerboard/protocol/constants.py` is transcribed from that document, and
+`tests/test_constant_values.py` pins each one against it with a citation per assertion.
 
-The protocol itself is documented in the Alpha Sign Communications Protocol, form
-9708-8061, published by Adaptive Micro Systems.
+An earlier version of this project took that table from
+[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), which is
+recorded here with thanks even though no code from it remains.

{readerboard-0.1.4 → readerboard-0.3.0}/README.md

@@ -30,8 +30,9 @@ until it is released, after which the rotation resumes.
 - **It survives restarts and outages.** The registered messages are persisted, and a
   write that arrives while the sign is unreachable is accepted and delivered when the
   link returns.
-- **Errors are errors.** A dead serial link is a 503, not an HTTP 200 with the word
-  ERROR in the body.
+- **Errors are errors.** A dead serial link is a 503 and a message the sign cannot
+  render is a 400, each with the reason in the body. Nothing here reports a failure
+  under a 200.
 
 ## Requirements
 
@@ -64,6 +65,20 @@ docker run --rm -p 5001:5001 \
 
 Then open <http://127.0.0.1:5001/docs>.
 
+`loop://` swallows everything written to it, so the service runs but there is
+nothing to see. To watch what it would have sent, run it against the sign
+simulator in `tools/signsim/` instead:
+
+```
+pip install --require-hashes -r tools/signsim/requirements.lock
+python scripts/run_with_simulator.py
+```
+
+That starts the simulator and the service together, already pointed at each
+other, and stops both on Ctrl+C. The simulator decodes each transmission, says
+what every byte of it means, and shows what the sign would be holding as a
+result. `tools/signsim/README.md` has the details.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -119,12 +134,13 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
+Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
 
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/temperature \
+curl -X PUT http://localhost:5001/messages/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -132,7 +148,7 @@ curl -X PUT http://localhost:5001/v2/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/doorbell \
+curl -X PUT http://localhost:5001/messages/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
@@ -140,44 +156,25 @@ curl -X PUT http://localhost:5001/v2/messages/doorbell \
 Take the sign over for thirty seconds:
 
 ```
-curl -X POST http://localhost:5001/v2/alerts \
+curl -X POST http://localhost:5001/alerts \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API, including every markup token and display mode, is at `/docs`.
+The full API is at `/docs`. Every markup token, display mode, text position and
+control command is listed by the `/enumerations` reads there, which answer at
+request time rather than being frozen into the description.
 
 ### Writing messages
 
 A message is plain text plus tokens written as `<name>`: `<green>18.4<degree>` is a
-colour change, a number, and a degree symbol. `GET /v2/enumerations/markup-tokens` lists
+colour change, a number, and a degree symbol. `GET /enumerations/markup-tokens` lists
 them all.
 
 Text is encoded against the sign's own character table rather than as UTF-8, so `café`
-displays correctly. A character the sign cannot render is rejected with a 400 on `/v2`,
-and replaced with `?` on the simpler endpoints described below.
-
-## A simpler set of endpoints
-
-Alongside `/v2` there is a smaller surface: `POST /Write/Message`,
-`POST /Write/ControlCommand`, and the `/Enumerations` reads.
-
-These follow one convention that `/v2` does not. **Every response is HTTP 200**, with the
-outcome in the body:
-
-```json
-{"result": "OK", "result_message": "Message displayed on sign"}
-```
-
-That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The single exception is a
-missing or wrong API key, which is a 401: a caller the service will not talk to is not the
-same as a request that failed.
-
-`POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
-not touch the sign's **priority** file, which by protocol suppresses every other message on
-the sign. 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.
+displays correctly. A character the sign cannot render is rejected with a 400, as is an
+unknown token: a write is told what the sign would have made of it rather than being
+shown something it did not ask for.
 
 ## Configuration
 
@@ -200,6 +197,19 @@ the log, but they are not settings to fiddle with.
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
+Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
+that could write to it.
+
+The key is declared to the API description as a security scheme, so the Swagger UI at
+`/docs` has an **Authorize** button: enter the key once and every write on the page
+carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+or a Home Assistant `rest_command` changes.
+
+That page is configured to remember the key, so it survives a reload or a browser
+restart rather than needing to be pasted in again. Convenient on your own machine, and
+worth knowing before you use **Authorize** on a shared or kiosk browser, where the next
+person to open `/docs` inherits it. Use the browser's Logout in the Authorize dialog, or
+just do not authorize there.
 
 **Message content reaches the sign as protocol bytes**, so it is worth knowing what a
 client holding the key can do. The markup renderer emits bytes only for tokens it
@@ -249,26 +259,31 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
-## Licence
+`tools/signsim/` is the sign simulator, a PySide6 stand-in for the sign, described
+above. `tools/apiclient/` is the client, a PySide6 application for calling the API by
+hand: every endpoint, responses shown as text rather than JSON, and a vocabulary it
+loads from the service rather than one compiled into it. The tests of both are
+collected by the `pytest` run here and need no Qt installed; the applications do, and
+each is pinned separately so that nothing the service installs ever pulls Qt in.
 
-MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
+`scripts/run_with_simulator.py` starts the service and the simulator together, and
+with `--with-client` the client as well, so the whole loop comes up from one command.
+Both editors carry it as a launch configuration under the same name, "readerboard and
+the sign simulator", in `.vscode/launch.json` and in `.idea/runConfigurations/`, beside
+configurations for running the pieces separately. Both carry the three way one as
+"readerboard, the sign simulator and the client" as well.
 
-One caveat, recorded because it is easy to miss.
-`readerboard/protocol/constants.py` is vendored from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), and that
-repository carries no license file. No license is not the same as a permissive one: it
-means no copying permission has been granted at all. That module is therefore the one
-part of this project whose provenance is not cleanly MIT.
+## Licence
 
-In practice it is a table of byte values dictated by the protocol rather than authored
-expression, and `docs/protocol-notes.md` now cites the protocol document directly, so the
-table can be regenerated from the primary source if that ever needs settling properly.
+MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).
 
 ## Credits
 
-`readerboard/protocol/constants.py` came, with thanks, from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), with some
-corrections noted in the file.
+The protocol is documented in the Alpha Sign Communications Protocol, form 9708-8061,
+published by Adaptive Micro Systems. Every byte value in
+`readerboard/protocol/constants.py` is transcribed from that document, and
+`tests/test_constant_values.py` pins each one against it with a citation per assertion.
 
-The protocol itself is documented in the Alpha Sign Communications Protocol, form
-9708-8061, published by Adaptive Micro Systems.
+An earlier version of this project took that table from
+[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), which is
+recorded here with thanks even though no code from it remains.

{readerboard-0.1.4 → readerboard-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.1.4"
-description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync"
+version = "0.3.0"
+description = "An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, expiring messages and clock sync"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Home Automation",
     "Topic :: System :: Hardware",
     "Typing :: Typed",
@@ -36,7 +37,8 @@ classifiers = [
 #
 # The ceilings sit at the next major for the settled packages, and at the next
 # minor for the two still on 0.x, where a minor bump is where a breaking change
-# is allowed to live.
+# is allowed to live. tzdata is the exception and takes a floor only: it is a
+# calendar-versioned data package with no API to break.
 dependencies = [
     "fastapi>=0.141.1,<0.142",
     # Plain uvicorn, not the "standard" extra. That extra exists to make a busy
@@ -69,8 +71,9 @@ dev = [
 ]
 
 [project.scripts]
-# The whole command line. `python -m readerboard` runs the same thing out of a
-# checkout, which is what the systemd unit and the editor launch config use.
+# The whole command line, and what the systemd unit and the container image run.
+# `python -m readerboard` runs the same thing out of a checkout, which is what
+# the editor launch configurations use.
 readerboard = "readerboard.__main__:main"
 
 [project.urls]
@@ -80,8 +83,8 @@ Issues = "https://github.com/mjaksn/readerboard/issues"
 Changelog = "https://github.com/mjaksn/readerboard/blob/main/CHANGELOG.md"
 
 [tool.setuptools]
-# Named explicitly rather than auto-discovered: the flat layout puts `tests`
-# beside the package and it has an __init__.py, so discovery would ship it.
+# Named explicitly rather than auto-discovered: `tests`, `tools` and `scripts`
+# all sit beside the package in a flat layout, so what ships is decided here.
 packages = [
     "readerboard",
     "readerboard.api",
@@ -97,7 +100,12 @@ packages = [
 readerboard = ["py.typed"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+# The two tools under tools/ are collected too. Their tests import only the
+# pure half of each, never PySide6, so they run in CI where Qt is not installed.
+# The simulator's round trip is checked against the frame builders in this
+# package; the client's catalogue is checked against docs/openapi.json, so a
+# route added here fails that tool's tests in the same commit.
+testpaths = ["tests", "tools/signsim/tests", "tools/apiclient/tests"]
 addopts = "-q --strict-markers --strict-config"
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
@@ -132,12 +140,18 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-# The vendored constants table is a wall of assignments with trailing comments,
-# and rewriting it into docstring-bearing prose would only obscure its origin.
-"readerboard/protocol/constants.py" = ["E501", "RUF001", "RUF003"]
 # A test's name is its documentation, and a docstring repeating it would be
-# worse than none. Tests that need explaining have one anyway.
+# worse than none. Tests that need explaining have one anyway. The two tools'
+# tests are named separately because this glob is anchored at the project root
+# and does not reach into tools/.
 "tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+"tools/signsim/tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+"tools/apiclient/tests/*" = ["D100", "D101", "D102", "D103", "D105", "D107"]
+
+[tool.ruff.lint.isort]
+# The two tools are not under the project root, so import sorting would put
+# them in the third party block and then complain they are in the wrong one.
+known-first-party = ["readerboard", "signsim", "apiclient"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "pep257"
@@ -155,7 +169,7 @@ module = ["serial", "serial.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-# The vendored constants module is a flat table of byte literals; annotating
-# every one of them would add nothing a reader does not already see.
+# The constants module is a flat table of byte literals; annotating every one of
+# them would add nothing a reader does not already see.
 module = "readerboard.protocol.constants"
 disallow_untyped_defs = false

{readerboard-0.1.4 → readerboard-0.3.0}/readerboard/__init__.py

@@ -7,4 +7,4 @@ and against the release tag, before anything is published. See
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.4"
+__version__ = "0.3.0"

{readerboard-0.1.4 → readerboard-0.3.0}/readerboard/__main__.py

@@ -11,14 +11,14 @@ import argparse
 
 import uvicorn
 
-from readerboard import __version__, logging_setup
+from readerboard import __version__, logging_setup, names
 from readerboard.config import Settings
 
 
 def main() -> int:
     """Start the HTTP server."""
     parser = argparse.ArgumentParser(
-        prog="readerboard",
+        prog=names.IDENTIFIER,
         description=(
             "Serve the readerboard API, which drives a BetaBrite Classic sign. "
             "Settings come from the config file "
@@ -26,7 +26,7 @@ def main() -> int:
             "and from environment variables prefixed READERBOARD_."
         ),
     )
-    parser.add_argument("--version", action="version", version="readerboard %s" % __version__)
+    parser.add_argument("--version", action="version", version="%s %s" % (names.IDENTIFIER, __version__))
     parser.add_argument("--host", help="override the configured listen address")
     parser.add_argument("--port", type=int, help="override the configured port")
     parser.add_argument(

{readerboard-0.1.4 → readerboard-0.3.0}/readerboard/api/app.py

@@ -18,26 +18,19 @@ import contextlib
 import logging
 from collections.abc import AsyncIterator, Awaitable, Callable
 
-from fastapi import FastAPI, Request, status
+from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
 
-from readerboard import __version__, logging_setup
-from readerboard.api import routes_simple, routes_v2
+from readerboard import __version__, logging_setup, names
+from readerboard.api import errors, routes
 from readerboard.api.deps import get_alerts, get_clock, get_controller, get_registry
 from readerboard.api.models import HealthResponse, LinkHealth
 from readerboard.config import Settings
-from readerboard.protocol.frames import ProtocolError
-from readerboard.protocol.markup import MarkupError
-from readerboard.services import commands
-from readerboard.services.alerts import AlertService, AlertTooLong
+from readerboard.services.alerts import AlertService
 from readerboard.services.clock import ClockService
-from readerboard.services.registry import (
-    MessageRegistry,
-    MessageTooLong,
-    UnknownSlot,
-)
+from readerboard.services.registry import MessageRegistry
 from readerboard.sign.controller import SignController
-from readerboard.sign.layout import Layout, LayoutFull
+from readerboard.sign.layout import Layout
 from readerboard.sign.state import StateStore
 from readerboard.transport.base import Transport, TransportError
 from readerboard.transport.serial_link import SerialTransport
@@ -52,11 +45,18 @@ Several sources can share the sign at once. Each registers a named **slot**, and
 the sign rotates through the registered slots by itself. An **alert** takes the
 whole display over until it is released, then the rotation resumes.
 
-Every write needs an `X-API-Key` header. `GET /health` does not.
-
-The `/Write` and `/Enumerations` paths are a smaller surface for clients that
-would rather not read status codes: every response there is a 200 with the
-outcome in the body.
+Every write needs an `X-API-Key` header. Reads and `GET /health` do not. On this
+page, put the key in once with the **Authorize** button and every write below
+carries it.
+
+A failure is reported by the status code, with the reason in a `detail` field:
+400 for a command the sign does not have, a parameter it will not accept, a
+message too long for its slot or markup the sign cannot render, 401 for a
+missing or wrong `X-API-Key`, 404 for a slot nothing has registered, 409 when
+every message slot is already in use, 503 when the sign is unreachable or no
+API key is configured at all, 500 for something the service has no code for,
+and 422 for a body that is not the shape the endpoint declares, which includes
+a display mode or a text position the sign does not have.
 """
 
 
@@ -192,16 +192,19 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             logger.info("readerboard stopped")
 
     app = FastAPI(
-        title="readerboard",
+        title=names.DISPLAY_NAME,
         description=DESCRIPTION,
         version=__version__,
         lifespan=lifespan,
+        # Keep the key entered in the Swagger UI's Authorize dialog across a page
+        # reload. Without it every reload is another trip to the config file for
+        # somebody trying things out, which is most of what /docs is for.
+        swagger_ui_parameters={"persistAuthorization": True},
     )
     app.state.settings = settings
 
     _install_error_handlers(app)
-    app.include_router(routes_v2.router)
-    app.include_router(routes_simple.router)
+    app.include_router(routes.router)
 
     @app.get("/health", tags=["Health"], summary="Is the service talking to the sign")
     async def health(request: Request) -> HealthResponse:
@@ -238,7 +241,11 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
 
 
 def _install_error_handlers(app: FastAPI) -> None:
-    """Turn the service's own exceptions into the status codes they mean."""
+    """Turn the service's own exceptions into the status codes they mean.
+
+    Registered by walking the table in readerboard.api.errors, which is the one
+    place that decides what any of them means.
+    """
 
     def handler(code: int) -> Callable[[Request, Exception], Awaitable[JSONResponse]]:
         async def handle(_: Request, exc: Exception) -> JSONResponse:
@@ -248,15 +255,8 @@ def _install_error_handlers(app: FastAPI) -> None:
 
         return handle
 
-    app.add_exception_handler(MarkupError, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(ProtocolError, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(MessageTooLong, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(AlertTooLong, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(commands.UnknownCommand, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(commands.BadParameter, handler(status.HTTP_400_BAD_REQUEST))
-    app.add_exception_handler(UnknownSlot, handler(status.HTTP_404_NOT_FOUND))
-    app.add_exception_handler(LayoutFull, handler(status.HTTP_409_CONFLICT))
-    app.add_exception_handler(TransportError, handler(status.HTTP_503_SERVICE_UNAVAILABLE))
+    for kind, code in errors.STATUS_FOR_ERROR:
+        app.add_exception_handler(kind, handler(code))
 
 
 app = create_app()