readerboard 0.5.0__tar.gz → 0.6.0__tar.gz

{readerboard-0.5.0/readerboard.egg-info → readerboard-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.5.0
+Version: 0.6.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
@@ -55,10 +55,12 @@ An HTTP service that drives a BetaBrite Classic sign, either through a serial ca
 through an Ethernet to RS-232 adapter.
 
 Several sources can share the sign at once. Each registers a named **slot**, and the sign
-rotates through the registered slots by itself. A **variable** is a value that messages
-call by name, such as a temperature, and changing it does not blank the sign or restart
-the message showing it. An **alert** takes the whole display over until it is released,
-after which the rotation resumes.
+rotates through the slots that are showing by itself. A slot can be hidden without being
+given up, so a message can be taken off the display and put back without being sent again,
+unless it was the last one showing. A **variable** is a value that messages call by name,
+such as a temperature, and changing it does not blank the sign or restart the message
+showing it. An **alert** takes the whole display over until it is released, after which
+the rotation resumes.
 
 ## What it does
 
@@ -82,8 +84,10 @@ after which the rotation resumes.
   flicker.
 - **It survives restarts and outages.** The registered messages are persisted and
   pushed to the sign again whenever the link returns, so a restart or a power cut leaves
-  the rotation intact. A write that arrives while the sign is unreachable is refused with
-  a 503 rather than silently held, so the caller learns it did not land.
+  the rotation intact. A message or a variable write that arrives while the sign is
+  unreachable is refused with a 503 rather than silently held, so the caller learns it did
+  not land. Deleting or hiding a message, or deleting a variable, is accepted and carried
+  out when the link returns.
 - **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.
@@ -263,7 +267,7 @@ service's other reads and `GET /health` do not. In the Swagger UI at `/docs`, th
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/messages/temperature \
+curl -X PUT http://localhost:5001/slots/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -271,11 +275,55 @@ curl -X PUT http://localhost:5001/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/messages/doorbell \
+curl -X PUT http://localhost:5001/slots/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
 
+Take a message off the display without giving up its slot, and put it back later:
+
+```
+curl -X PUT http://localhost:5001/slots/doorbell/active \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"active": false}'
+```
+
+A hidden message keeps its slot, its place in the order and its text, so showing it again
+takes `{"active": true}` and no copy of what it said. Hiding or showing one is a single run
+sequence write. That does disturb the display briefly, but far less than rewriting a
+message does: enough less that it is easy to miss unless you are watching for it on a
+static screen. The exception is the last message showing: its file is emptied as it goes,
+because a sign whose run sequence names nothing freezes on what it was drawing, so
+putting that one back costs the text as well as the sequence.
+
+`active` is a field on the message endpoint too, where leaving it out is the point: a
+source re-sending the same content every few minutes says nothing about it and so cannot
+switch back on something that was deliberately hidden. Sending it moves the message.
+
+A `ttl_seconds` can hide a message instead of deleting it, which suits anything that comes
+back later, such as a bin day or a school notice:
+
+```
+curl -X PUT http://localhost:5001/slots/bins \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "<green>BINS OUT TONIGHT", "ttl_seconds": 43200,
+          "delete_on_expiry": false}'
+```
+
+Put those together and a recurring notification is one call per event, sent in the same
+shape every time. This shows the alarm's state for a minute whenever it changes, then takes
+it off the rotation until the next one:
+
+```
+curl -X PUT http://localhost:5001/slots/alarm \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "<red>ALARM NOW <var:arm_state>", "ttl_seconds": 60,
+          "delete_on_expiry": false, "active": true}'
+```
+
+The deadline clears itself as it hides the message, so each event gets a fresh minute
+rather than the message vanishing again on a deadline the last one left behind.
+
 Show a live value. Create the variable first, then a message that calls it:
 
 ```
@@ -283,7 +331,7 @@ curl -X PUT http://localhost:5001/variables/temp \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"value": "72", "ttl_seconds": 1800, "stale_value": "--"}'
 
-curl -X PUT http://localhost:5001/messages/weather \
+curl -X PUT http://localhost:5001/slots/weather \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "Outside <var:temp><degree>F", "display_mode": "ROTATE"}'
 ```
@@ -413,10 +461,10 @@ from the service's own record, so the display still comes back to what it was.
 curl -X POST http://localhost:5001/sign/reboot -H 'X-API-Key: YOUR-KEY'
 ```
 
-Reach for it only when a soft reset was not enough. The sign is blank for about ten
-seconds while it resets. Neither is a way to clear messages: `DELETE /messages` does
-that without resetting anything. The client fronts the reboot with a warning-coloured
-confirmation for the same reason.
+Reach for it only when a soft reset was not enough. The sign is blank for twelve seconds
+or more while it resets, longer with a lot of messages to put back. Neither is a way to
+clear messages: `DELETE /slots` does that without resetting anything. The client
+fronts the reboot with a warning-coloured confirmation for the same reason.
 
 ## Configuration
 

{readerboard-0.5.0 → readerboard-0.6.0}/README.md

@@ -11,10 +11,12 @@ An HTTP service that drives a BetaBrite Classic sign, either through a serial ca
 through an Ethernet to RS-232 adapter.
 
 Several sources can share the sign at once. Each registers a named **slot**, and the sign
-rotates through the registered slots by itself. A **variable** is a value that messages
-call by name, such as a temperature, and changing it does not blank the sign or restart
-the message showing it. An **alert** takes the whole display over until it is released,
-after which the rotation resumes.
+rotates through the slots that are showing by itself. A slot can be hidden without being
+given up, so a message can be taken off the display and put back without being sent again,
+unless it was the last one showing. A **variable** is a value that messages call by name,
+such as a temperature, and changing it does not blank the sign or restart the message
+showing it. An **alert** takes the whole display over until it is released, after which
+the rotation resumes.
 
 ## What it does
 
@@ -38,8 +40,10 @@ after which the rotation resumes.
   flicker.
 - **It survives restarts and outages.** The registered messages are persisted and
   pushed to the sign again whenever the link returns, so a restart or a power cut leaves
-  the rotation intact. A write that arrives while the sign is unreachable is refused with
-  a 503 rather than silently held, so the caller learns it did not land.
+  the rotation intact. A message or a variable write that arrives while the sign is
+  unreachable is refused with a 503 rather than silently held, so the caller learns it did
+  not land. Deleting or hiding a message, or deleting a variable, is accepted and carried
+  out when the link returns.
 - **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.
@@ -219,7 +223,7 @@ service's other reads and `GET /health` do not. In the Swagger UI at `/docs`, th
 Register a message:
 
 ```
-curl -X PUT http://localhost:5001/messages/temperature \
+curl -X PUT http://localhost:5001/slots/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -227,11 +231,55 @@ curl -X PUT http://localhost:5001/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/messages/doorbell \
+curl -X PUT http://localhost:5001/slots/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
 
+Take a message off the display without giving up its slot, and put it back later:
+
+```
+curl -X PUT http://localhost:5001/slots/doorbell/active \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"active": false}'
+```
+
+A hidden message keeps its slot, its place in the order and its text, so showing it again
+takes `{"active": true}` and no copy of what it said. Hiding or showing one is a single run
+sequence write. That does disturb the display briefly, but far less than rewriting a
+message does: enough less that it is easy to miss unless you are watching for it on a
+static screen. The exception is the last message showing: its file is emptied as it goes,
+because a sign whose run sequence names nothing freezes on what it was drawing, so
+putting that one back costs the text as well as the sequence.
+
+`active` is a field on the message endpoint too, where leaving it out is the point: a
+source re-sending the same content every few minutes says nothing about it and so cannot
+switch back on something that was deliberately hidden. Sending it moves the message.
+
+A `ttl_seconds` can hide a message instead of deleting it, which suits anything that comes
+back later, such as a bin day or a school notice:
+
+```
+curl -X PUT http://localhost:5001/slots/bins \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "<green>BINS OUT TONIGHT", "ttl_seconds": 43200,
+          "delete_on_expiry": false}'
+```
+
+Put those together and a recurring notification is one call per event, sent in the same
+shape every time. This shows the alarm's state for a minute whenever it changes, then takes
+it off the rotation until the next one:
+
+```
+curl -X PUT http://localhost:5001/slots/alarm \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "<red>ALARM NOW <var:arm_state>", "ttl_seconds": 60,
+          "delete_on_expiry": false, "active": true}'
+```
+
+The deadline clears itself as it hides the message, so each event gets a fresh minute
+rather than the message vanishing again on a deadline the last one left behind.
+
 Show a live value. Create the variable first, then a message that calls it:
 
 ```
@@ -239,7 +287,7 @@ curl -X PUT http://localhost:5001/variables/temp \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"value": "72", "ttl_seconds": 1800, "stale_value": "--"}'
 
-curl -X PUT http://localhost:5001/messages/weather \
+curl -X PUT http://localhost:5001/slots/weather \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "Outside <var:temp><degree>F", "display_mode": "ROTATE"}'
 ```
@@ -369,10 +417,10 @@ from the service's own record, so the display still comes back to what it was.
 curl -X POST http://localhost:5001/sign/reboot -H 'X-API-Key: YOUR-KEY'
 ```
 
-Reach for it only when a soft reset was not enough. The sign is blank for about ten
-seconds while it resets. Neither is a way to clear messages: `DELETE /messages` does
-that without resetting anything. The client fronts the reboot with a warning-coloured
-confirmation for the same reason.
+Reach for it only when a soft reset was not enough. The sign is blank for twelve seconds
+or more while it resets, longer with a lot of messages to put back. Neither is a way to
+clear messages: `DELETE /slots` does that without resetting anything. The client
+fronts the reboot with a warning-coloured confirmation for the same reason.
 
 ## Configuration
 

{readerboard-0.5.0 → readerboard-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.5.0"
+version = "0.6.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"

{readerboard-0.5.0 → readerboard-0.6.0}/readerboard/__init__.py

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

{readerboard-0.5.0 → readerboard-0.6.0}/readerboard/api/app.py

@@ -28,7 +28,7 @@ from readerboard.api.models import HealthResponse, LinkHealth
 from readerboard.config import Settings
 from readerboard.services.alerts import AlertService
 from readerboard.services.clock import ClockService
-from readerboard.services.registry import MessageRegistry
+from readerboard.services.registry import SlotRegistry
 from readerboard.sign.controller import SignController
 from readerboard.sign.layout import Layout
 from readerboard.sign.state import StateStore
@@ -42,8 +42,10 @@ Drives a BetaBrite Classic sign over the Alpha protocol, either through a serial
 cable or through an Ethernet to RS-232 adapter.
 
 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.
+the sign rotates through the slots that are showing by itself. A slot can be
+hidden without being given up, so a message can be taken off the display and put
+back without being sent again. An **alert** takes the whole display over until it
+is released, then the rotation resumes.
 
 A **variable** is a value a slot's message or an alert calls with `<var:name>`.
 Changing it rewrites only the variable, so the sign shows the new value without
@@ -82,10 +84,10 @@ def build_transport(settings: Settings) -> Transport:
 async def _refresh_loop(app: FastAPI, interval: float) -> None:
     """Push everything to the sign again, periodically.
 
-    See ``MessageRegistry.refresh`` for why blind re-pushing is the only thing
+    See ``SlotRegistry.refresh`` for why blind re-pushing is the only thing
     that repairs a sign power cycled behind a still-connected adapter.
     """
-    registry: MessageRegistry = app.state.registry
+    registry: SlotRegistry = app.state.registry
     alerts: AlertService = app.state.alerts
 
     while True:
@@ -105,7 +107,7 @@ async def _refresh_loop(app: FastAPI, interval: float) -> None:
 
 async def _sweep_loop(app: FastAPI, interval: float) -> None:
     """Expire slots and alerts, and turn variables stale, once their deadlines pass."""
-    registry: MessageRegistry = app.state.registry
+    registry: SlotRegistry = app.state.registry
     alerts: AlertService = app.state.alerts
 
     while True:
@@ -149,13 +151,8 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             settings.variable_capacity,
         )
         alerts = AlertService(controller, store, state)
-        registry = MessageRegistry(
-            controller, layout, store, state, alert_active=lambda: alerts.active is not None
-        )
-        # An alert holding the sign makes the registry hold back run sequence
-        # writes; releasing it is what lets them through.
-        alerts.set_release_hook(registry.flush_deferred)
-        # And an alert calling a variable is rendered by the registry, under its
+        registry = SlotRegistry(controller, layout, store, state)
+        # An alert calling a variable is rendered by the registry, under its
         # lock, so the variable cannot be deleted while the alert calls it.
         alerts.set_rendering(registry.rendering)
         clock = ClockService(

{readerboard-0.5.0 → readerboard-0.6.0}/readerboard/api/deps.py

@@ -16,7 +16,7 @@ from fastapi.security import APIKeyHeader
 
 from readerboard.services.alerts import AlertService
 from readerboard.services.clock import ClockService
-from readerboard.services.registry import MessageRegistry
+from readerboard.services.registry import SlotRegistry
 from readerboard.sign.controller import SignController
 
 API_KEY_HEADER = "X-API-Key"
@@ -55,9 +55,9 @@ def get_controller(request: Request) -> SignController:
     return controller
 
 
-def get_registry(request: Request) -> MessageRegistry:
+def get_registry(request: Request) -> SlotRegistry:
     """Return the registered messages."""
-    registry: MessageRegistry = request.app.state.registry
+    registry: SlotRegistry = request.app.state.registry
     return registry
 
 
@@ -107,7 +107,7 @@ def require_api_key(
 
 
 ControllerDep = Annotated[SignController, Depends(get_controller)]
-RegistryDep = Annotated[MessageRegistry, Depends(get_registry)]
+RegistryDep = Annotated[SlotRegistry, Depends(get_registry)]
 AlertsDep = Annotated[AlertService, Depends(get_alerts)]
 ClockDep = Annotated[ClockService, Depends(get_clock)]
 RequireApiKey = Depends(require_api_key)

{readerboard-0.5.0 → readerboard-0.6.0}/readerboard/api/models.py

@@ -52,7 +52,7 @@ def _normalise_mode(value: str) -> str:
     return upper
 
 
-class MessageRequest(BaseModel):
+class SlotRequest(BaseModel):
     """A message registered into a slot."""
 
     model_config = ConfigDict(extra="forbid")
@@ -64,7 +64,9 @@ class MessageRequest(BaseModel):
             "the message, including markup tokens such as <red> and <degree>, and "
             "<var:name> to call a variable, which has to exist first. It cannot be "
             "empty: an empty message holds a slot open around nothing, and the sign "
-            "cycles to a file with no text in it. Use DELETE to give the slot back"
+            "gives a file with no text in it no turn of its own but does hold the "
+            "message before it several seconds longer, so the slot would be spent and "
+            "the rotation would drag. Use DELETE to give the slot back"
         ),
     )
     display_mode: str = Field(default="HOLD", description="how the sign presents the message")
@@ -75,7 +77,30 @@ class MessageRequest(BaseModel):
     ttl_seconds: float | None = Field(
         default=None,
         gt=0,
-        description="drop the message this many seconds from now; omit to keep it until replaced",
+        description=(
+            "act on the message this many seconds from now, deleting or hiding it "
+            "according to delete_on_expiry. Omit it for no deadline, which leaves the "
+            "message in place until something replaces or removes it"
+        ),
+    )
+    delete_on_expiry: bool = Field(
+        default=True,
+        description=(
+            "what happens when ttl_seconds passes. True gives the slot back. False keeps "
+            "the message registered and takes it off the display, clearing the deadline "
+            "with it, so it can be shown again without being sent afresh. Nothing "
+            "without a ttl_seconds"
+        ),
+    )
+    active: bool | None = Field(
+        default=None,
+        description=(
+            "whether the sign should be playing it. Omit it and the message keeps "
+            "whatever it already was, which is what a source re-sending the same "
+            "content on a timer wants: repeating itself cannot switch back on "
+            "something that was deliberately hidden. true shows it, false hides it, "
+            "and a new message nobody says anything about is shown"
+        ),
     )
     source: str | None = Field(
         default=None,
@@ -86,6 +111,20 @@ class MessageRequest(BaseModel):
     _check_mode = field_validator("display_mode")(_normalise_mode)
 
 
+class SlotActiveRequest(BaseModel):
+    """Whether the sign should be playing a slot."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    active: bool = Field(
+        description=(
+            "true to put the message into the rotation, false to take it off the display "
+            "while it stays registered, keeping its slot, its file, its text and its place "
+            "in the order"
+        )
+    )
+
+
 class SlotResponse(BaseModel):
     """A registered slot."""
 
@@ -94,6 +133,12 @@ class SlotResponse(BaseModel):
     message: str
     display_mode: str
     order: int
+    active: bool = Field(
+        description="whether the sign is playing it; a false one stays registered and hidden"
+    )
+    delete_on_expiry: bool = Field(
+        description="whether ttl_seconds gives the slot back, or only hides the message"
+    )
     source: str | None
     expires_at: datetime | None
     updated_at: datetime
@@ -107,6 +152,8 @@ class SlotResponse(BaseModel):
             message=slot.message,
             display_mode=slot.mode,
             order=slot.order,
+            active=slot.active,
+            delete_on_expiry=slot.delete_on_expiry,
             source=slot.source,
             expires_at=slot.expires_at,
             updated_at=slot.updated_at,

{readerboard-0.5.0 → readerboard-0.6.0}/readerboard/api/routes.py

@@ -24,9 +24,10 @@ from readerboard.api.models import (
     AlertResponse,
     ClockResponse,
     ControlCommandRequest,
-    MessageRequest,
     SignInformationResponse,
+    SlotActiveRequest,
     SlotKey,
+    SlotRequest,
     SlotResponse,
     TokenInfo,
     VariableName,
@@ -43,12 +44,12 @@ from readerboard.protocol.tokens import (
     Token,
 )
 from readerboard.services import commands
-from readerboard.services.registry import MessageRegistry
+from readerboard.services.registry import SlotRegistry
 from readerboard.sign.state import VariableState
 
 router = APIRouter()
 
-messages = APIRouter(prefix="/messages", tags=["Messages"])
+slots = APIRouter(prefix="/slots", tags=["Slots"])
 variables = APIRouter(prefix="/variables", tags=["Variables"])
 alerts_routes = APIRouter(prefix="/alerts", tags=["Alerts"])
 sign_routes = APIRouter(prefix="/sign", tags=["Sign"])
@@ -56,30 +57,40 @@ enumerations = APIRouter(prefix="/enumerations", tags=["Enumerations"])
 
 
 # ===========================================================================
-# Messages
+# Slots
 # ===========================================================================
 
 
-@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."""
+@slots.get("", summary="List the slots sharing the sign")
+async def list_slots(registry: RegistryDep) -> list[SlotResponse]:
+    """Return every registered slot, in rotation order, hidden ones included.
+
+    A hidden slot is listed like any other, with `active` false. It is still
+    registered and still holding its file; it is simply not one the sign plays.
+    """
     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:
+@slots.get("/{key}", summary="Read one slot")
+async def get_slot(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
+@slots.put("/{key}", summary="Register or replace a slot", dependencies=[RequireApiKey])
+async def put_slot(
+    key: SlotKey, body: SlotRequest, 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.
+    The sign rotates through the slots that are showing on its own, so
+    registering a second slot does not displace the first.
+
+    Leave `active` out and a hidden slot stays hidden, which is what a source
+    re-sending the same content every few minutes wants: repeating itself cannot
+    switch back on something that was deliberately hidden. Send it and the slot
+    moves, so one call can write the text, set a deadline and put it up.
+    `PUT /slots/{key}/active` does the same without resending the message.
     """
     slot = await registry.upsert(
         key,
@@ -87,30 +98,63 @@ async def put_message(
         mode=body.display_mode,
         order=body.order,
         ttl_seconds=body.ttl_seconds,
+        delete_on_expiry=body.delete_on_expiry,
+        active=body.active,
         source=body.source,
     )
     return SlotResponse.of(slot)
 
 
-@messages.delete(
+@slots.put(
+    "/{key}/active",
+    summary="Show or hide a slot without giving it up",
+    dependencies=[RequireApiKey],
+)
+async def set_slot_active(
+    key: SlotKey, body: SlotActiveRequest, registry: RegistryDep
+) -> SlotResponse:
+    """Take a slot off the display, or put it back, keeping it registered either way.
+
+    A hidden slot stays registered. It keeps its file, its text and its place in
+    the order, and is simply left out of the rotation the sign cycles, so showing
+    it again needs no copy of what it said. `PUT /slots/{key}`
+    can move it too, by sending `active`; this endpoint is for when the caller
+    does not have the message text to resend, and a caller who omits `active`
+    there cannot move it by accident.
+
+    Hiding or showing one is a single run sequence write. That does disturb the
+    display, but far less than rewriting a message does: briefly enough to be
+    missed unless you are watching a static screen for it. The hidden slot's own
+    file keeps its text, so showing it again sends nothing but the sequence.
+    The exception is the last slot showing: that one's file is emptied as it
+    goes, because a sign whose sequence names nothing freezes on what it was
+    drawing.
+
+    404 when no slot by that name is registered.
+    """
+    slot = await registry.set_active(key, body.active)
+    return SlotResponse.of(slot)
+
+
+@slots.delete(
     "/{key}",
-    summary="Take a message off the sign",
+    summary="Give up one slot",
     status_code=status.HTTP_204_NO_CONTENT,
     dependencies=[RequireApiKey],
 )
-async def delete_message(key: SlotKey, registry: RegistryDep) -> Response:
+async def delete_slot(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(
+@slots.delete(
     "",
-    summary="Take every message off the sign",
+    summary="Give up every slot",
     status_code=status.HTTP_204_NO_CONTENT,
     dependencies=[RequireApiKey],
 )
-async def clear_messages(registry: RegistryDep) -> Response:
+async def clear_slots(registry: RegistryDep) -> Response:
     """Remove every slot, leaving the sign showing nothing."""
     await registry.clear()
     return Response(status_code=status.HTTP_204_NO_CONTENT)
@@ -183,7 +227,7 @@ async def delete_variable(name: VariableName, registry: RegistryDep) -> Response
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
 
-def _variable_response(registry: MessageRegistry, variable: VariableState) -> VariableResponse:
+def _variable_response(registry: SlotRegistry, variable: VariableState) -> VariableResponse:
     """Describe a variable along with everything that calls it."""
     return VariableResponse.of(
         variable,
@@ -273,6 +317,17 @@ async def sign_information(controller: ControllerDep) -> SignInformationResponse
     useful as a source of troubleshooting information", which is a fair summary:
     nothing here changes anything.
 
+    Changing nothing is not the same as costing nothing, and what a read costs
+    the display was measured on 2026-09-12. Six reads were put to the sign, the
+    four special functions along with a TEXT file read and a STRING file read,
+    and every one of them left a message that was holding still completely
+    undisturbed and cost a message that was scrolling about half a second of
+    stall and blank. The `F"` this endpoint sends was not one of the six: it is
+    the same kind of command as the four that were measured and nothing suggests
+    it differs, but that is an expectation rather than a measurement. On it, this
+    is free to call as often as you like on a sign whose slots all hold, and a
+    brief interruption to whichever slot happens to be scrolling when it lands.
+
     This is the only read in the service, so it is also the only place a silent
     sign is distinguishable from an unplugged one. A sign that does not answer
     within a few seconds is a 503, the same as a sign that cannot be written to,
@@ -333,9 +388,10 @@ async def reboot_sign(registry: RegistryDep, alerts: AlertsDep) -> Response:
     Use it for a sign that has stopped responding to writes or is showing
     garbage, the wedged-decoder state a unit mounted out of reach can fall into
     from a stray bit and that cannot be fixed by power cycling it by hand. Do
-    not use it to clear the sign: `DELETE /messages` takes every message off
-    without resetting anything, and this puts them all straight back. Expect a
-    blank display for roughly ten seconds before the rotation returns.
+    not use it to clear the sign: `DELETE /slots` gives up every slot without
+    resetting anything, and this puts them all straight back. Expect a
+    blank display for twelve seconds or more before the rotation returns,
+    longer with a lot of messages to put back.
 
     503 if the sign cannot be reached, since a sign that is not answering cannot
     be rebooted.
@@ -394,7 +450,7 @@ async def control_commands() -> list[TokenInfo]:
     return _as_info(CONTROL_COMMANDS)
 
 
-router.include_router(messages)
+router.include_router(slots)
 router.include_router(variables)
 router.include_router(alerts_routes)
 router.include_router(sign_routes)