readerboard 0.6.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.6.0
+Version: 0.7.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
@@ -28,7 +28,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastapi<0.142,>=0.141.1
-Requires-Dist: uvicorn<0.53,>=0.52.1
+Requires-Dist: uvicorn<0.54,>=0.52.1
 Requires-Dist: pydantic<3,>=2.13.4
 Requires-Dist: pydantic-settings<3,>=2.15.0
 Requires-Dist: pyserial<4,>=3.5
@@ -73,6 +73,8 @@ the rotation resumes.
   time it draws the message, with no blank and no restart. One variable can appear in
   any number of messages, and a value that stops arriving can be made to go stale.
 - **Alerts.** Take the display over, optionally with a deadline, then hand it back.
+  A caller that must not overwrite somebody else's alert can ask to be refused
+  instead.
 - **It keeps the sign's clock right**, at startup, hourly, and whenever the link comes
   back. That last trigger is the one that matters: a sign returning from a power cut
   does so at no particular minute. The sign is set one minute fast on purpose: the
@@ -149,8 +151,8 @@ python scripts/run_against_a_sign.py --serial-url socket://192.168.2.51:4001
 
 That starts the service and the client together, with no simulator. The service
 comes up on <http://127.0.0.1:5001> with `/docs` beside it, the client comes up
-pointed at that address, and the API key to paste into the client is printed in
-the same window. `--no-client` leaves the client out. Ctrl+C stops everything,
+pointed at that address with the API key already in its box, and the key is
+printed in the same window for anything else that needs it. `--no-client` leaves the client out. Ctrl+C stops everything,
 and closing the client leaves the service running.
 
 Both editors carry it as a launch configuration named "readerboard against the
@@ -223,6 +225,19 @@ again after pulling a new version: your config file and key are left alone.
 your registered messages, so reinstalling puts the sign back as it was. Add `--purge` to
 remove those too.
 
+The unit restarts the service whenever it stops, and gives up after ten failed starts in
+five minutes. Almost nothing here fails permanently, which is what makes the exceptions
+worth stopping for: a memory pool too big for the sign fails identically every time, and
+each attempt puts a read on the wire that stalls a scrolling message. `systemctl status
+readerboard` says which failure it was. Once the configuration is fixed, clearing the
+give-up and starting it again are two commands, because `reset-failed` clears the counter
+and leaves the unit stopped:
+
+```
+sudo systemctl reset-failed readerboard
+sudo systemctl start readerboard
+```
+
 ### With Docker
 
 The image is published to both registries on every release, for `linux/amd64`,
@@ -433,6 +448,40 @@ actions:
       value: "{{ states('sensor.outside_temperature') | round(0) | int }}"
 ```
 
+### Icons
+
+A message can draw one of 148 built-in bitmaps where a tag sits. `<icon:sun> FINE`
+puts a sun in front of the word, and `<icon:lock:red>` retints an icon that is drawn
+in a single ink; the colour words are the colour tokens' own, down to `dimred` and
+`dimgreen`, so a message that can say `<red>` needs no second spelling. An icon
+drawn in its own colours, such as the sun, takes no tint and asking for one is
+refused rather than ignored. `GET /enumerations/icons` lists every icon with its
+group, its width and whether it takes a tint.
+
+Icons are off until `picture_count` is set, because each one on the sign needs a
+picture file of its own and allocating those reallocates the sign's memory, which
+erases every message on it. Set it once, alongside the other pool settings, and
+16 is a comfortable number.
+
+Four things are worth knowing, and the first is the one that decides how to use them:
+
+- **An icon is not a live value.** Every write to a picture file blanks the display
+  and restarts a scrolling message. A weather slot stepping from sun to cloud to rain
+  pays that each time it lands on an icon the sign is not already holding. Something
+  that changes every minute belongs in a variable, which costs no blank at all.
+- **The pool is smaller than the library, and that is the design.** A picture file is
+  claimed by whichever icon a message calls, and kept after its last caller goes, so a
+  source alternating between two icons costs nothing after the first write. When every
+  file is holding an icon something still calls and a new one is asked for, the write
+  is refused with a 409. `GET /health` reports pictures used against pictures total,
+  and a full pool is the resting state rather than a warning.
+- **A tint makes a second picture.** `<icon:check:green>` and `<icon:check:red>` are
+  two bitmaps and take two files.
+- **An icon can be parted from its word.** A line too wide for the display breaks onto
+  a second page in HOLD, and the last word can arrive there without the icon labelling
+  it. The service cannot warn about this: it would have to know the width of the sign's
+  proportional font.
+
 ### Recovering a sign that has stopped responding
 
 A sign mounted out of reach can wedge: a stray bit corrupts what its decoder is
@@ -483,11 +532,32 @@ telnet serial protocol, `/dev/ttyUSB0` or `COM3` for a cable plugged straight in
 and the port, and pyserial's answer to one that has a slash names neither the setting
 nor the value.
 
-Four settings reallocate the sign's memory when changed, and **that erases every message
-on it**: `slot_count`, `slot_capacity`, `variable_count` and `variable_capacity`. The
-service will do it, and say so loudly in the log, but they are not settings to fiddle
-with. With `variable_count` at 0, `variable_capacity` allocates nothing, so changing it
-alone reallocates nothing either.
+Five settings reallocate the sign's memory when changed, and **that erases every message
+on it**: `slot_count`, `slot_capacity`, `variable_count`, `variable_capacity` and
+`picture_count`. The service will do it, and say so loudly in the log, but they are not
+settings to fiddle with. With `variable_count` at 0, `variable_capacity` allocates
+nothing, so changing it alone reallocates nothing either. `picture_count` starts at 0,
+which switches icons off, so turning them on is one deliberate erase.
+
+All five come out of one memory pool, which a BetaBrite Classic reported as 5482 bytes,
+and each file costs thirteen bytes beyond its own size. The defaults take 2518 of that,
+and each icon takes 69 on top, so the defaults with sixteen icons take 3622.
+
+That 5482 is a ceiling, and it is checked in two places that do different jobs. A
+configuration bigger than it is refused when the settings are read, on any machine,
+whether or not a sign is attached; that is the ceiling, and no sign can raise it. Then,
+on a start that is about to reallocate the sign's memory and only then, the service asks
+the sign for its own figure, and a sign reporting less than 5482 is believed. So the
+second check can lower the limit and never raise it. A sign with a bigger pool than this
+hardware's would need `ASSUMED_SIGN_MEMORY_POOL` in `readerboard/sign/pool.py` raised
+before it could use the extra.
+
+A sign that answers and does not have the room stops the service starting, with a message
+naming what was configured, what it needs and what there is; that is the one failure that
+does stop it, because the alternative is erasing every message on the sign to write a pool
+that could never work. A sign that says nothing does not stop anything. `POST /sign/reboot`
+asks the same question before it clears the sign, and answers 409 rather than erasing it,
+except when the sign is too wedged to answer, which is the case that endpoint exists for.
 
 ## Security
 
@@ -568,8 +638,9 @@ each is pinned separately so that nothing the service installs ever pulls Qt in.
 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.
+configurations for running the pieces separately, the client among them as
+"readerboard client". Both carry the three way one as "readerboard, the sign simulator
+and the client" as well.
 
 `scripts/run_against_a_sign.py` is the other one, for when the sign is real: the
 service and the client, no simulator, and the sign's address passed as an argument so

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

@@ -29,6 +29,8 @@ the rotation resumes.
   time it draws the message, with no blank and no restart. One variable can appear in
   any number of messages, and a value that stops arriving can be made to go stale.
 - **Alerts.** Take the display over, optionally with a deadline, then hand it back.
+  A caller that must not overwrite somebody else's alert can ask to be refused
+  instead.
 - **It keeps the sign's clock right**, at startup, hourly, and whenever the link comes
   back. That last trigger is the one that matters: a sign returning from a power cut
   does so at no particular minute. The sign is set one minute fast on purpose: the
@@ -105,8 +107,8 @@ python scripts/run_against_a_sign.py --serial-url socket://192.168.2.51:4001
 
 That starts the service and the client together, with no simulator. The service
 comes up on <http://127.0.0.1:5001> with `/docs` beside it, the client comes up
-pointed at that address, and the API key to paste into the client is printed in
-the same window. `--no-client` leaves the client out. Ctrl+C stops everything,
+pointed at that address with the API key already in its box, and the key is
+printed in the same window for anything else that needs it. `--no-client` leaves the client out. Ctrl+C stops everything,
 and closing the client leaves the service running.
 
 Both editors carry it as a launch configuration named "readerboard against the
@@ -179,6 +181,19 @@ again after pulling a new version: your config file and key are left alone.
 your registered messages, so reinstalling puts the sign back as it was. Add `--purge` to
 remove those too.
 
+The unit restarts the service whenever it stops, and gives up after ten failed starts in
+five minutes. Almost nothing here fails permanently, which is what makes the exceptions
+worth stopping for: a memory pool too big for the sign fails identically every time, and
+each attempt puts a read on the wire that stalls a scrolling message. `systemctl status
+readerboard` says which failure it was. Once the configuration is fixed, clearing the
+give-up and starting it again are two commands, because `reset-failed` clears the counter
+and leaves the unit stopped:
+
+```
+sudo systemctl reset-failed readerboard
+sudo systemctl start readerboard
+```
+
 ### With Docker
 
 The image is published to both registries on every release, for `linux/amd64`,
@@ -389,6 +404,40 @@ actions:
       value: "{{ states('sensor.outside_temperature') | round(0) | int }}"
 ```
 
+### Icons
+
+A message can draw one of 148 built-in bitmaps where a tag sits. `<icon:sun> FINE`
+puts a sun in front of the word, and `<icon:lock:red>` retints an icon that is drawn
+in a single ink; the colour words are the colour tokens' own, down to `dimred` and
+`dimgreen`, so a message that can say `<red>` needs no second spelling. An icon
+drawn in its own colours, such as the sun, takes no tint and asking for one is
+refused rather than ignored. `GET /enumerations/icons` lists every icon with its
+group, its width and whether it takes a tint.
+
+Icons are off until `picture_count` is set, because each one on the sign needs a
+picture file of its own and allocating those reallocates the sign's memory, which
+erases every message on it. Set it once, alongside the other pool settings, and
+16 is a comfortable number.
+
+Four things are worth knowing, and the first is the one that decides how to use them:
+
+- **An icon is not a live value.** Every write to a picture file blanks the display
+  and restarts a scrolling message. A weather slot stepping from sun to cloud to rain
+  pays that each time it lands on an icon the sign is not already holding. Something
+  that changes every minute belongs in a variable, which costs no blank at all.
+- **The pool is smaller than the library, and that is the design.** A picture file is
+  claimed by whichever icon a message calls, and kept after its last caller goes, so a
+  source alternating between two icons costs nothing after the first write. When every
+  file is holding an icon something still calls and a new one is asked for, the write
+  is refused with a 409. `GET /health` reports pictures used against pictures total,
+  and a full pool is the resting state rather than a warning.
+- **A tint makes a second picture.** `<icon:check:green>` and `<icon:check:red>` are
+  two bitmaps and take two files.
+- **An icon can be parted from its word.** A line too wide for the display breaks onto
+  a second page in HOLD, and the last word can arrive there without the icon labelling
+  it. The service cannot warn about this: it would have to know the width of the sign's
+  proportional font.
+
 ### Recovering a sign that has stopped responding
 
 A sign mounted out of reach can wedge: a stray bit corrupts what its decoder is
@@ -439,11 +488,32 @@ telnet serial protocol, `/dev/ttyUSB0` or `COM3` for a cable plugged straight in
 and the port, and pyserial's answer to one that has a slash names neither the setting
 nor the value.
 
-Four settings reallocate the sign's memory when changed, and **that erases every message
-on it**: `slot_count`, `slot_capacity`, `variable_count` and `variable_capacity`. The
-service will do it, and say so loudly in the log, but they are not settings to fiddle
-with. With `variable_count` at 0, `variable_capacity` allocates nothing, so changing it
-alone reallocates nothing either.
+Five settings reallocate the sign's memory when changed, and **that erases every message
+on it**: `slot_count`, `slot_capacity`, `variable_count`, `variable_capacity` and
+`picture_count`. The service will do it, and say so loudly in the log, but they are not
+settings to fiddle with. With `variable_count` at 0, `variable_capacity` allocates
+nothing, so changing it alone reallocates nothing either. `picture_count` starts at 0,
+which switches icons off, so turning them on is one deliberate erase.
+
+All five come out of one memory pool, which a BetaBrite Classic reported as 5482 bytes,
+and each file costs thirteen bytes beyond its own size. The defaults take 2518 of that,
+and each icon takes 69 on top, so the defaults with sixteen icons take 3622.
+
+That 5482 is a ceiling, and it is checked in two places that do different jobs. A
+configuration bigger than it is refused when the settings are read, on any machine,
+whether or not a sign is attached; that is the ceiling, and no sign can raise it. Then,
+on a start that is about to reallocate the sign's memory and only then, the service asks
+the sign for its own figure, and a sign reporting less than 5482 is believed. So the
+second check can lower the limit and never raise it. A sign with a bigger pool than this
+hardware's would need `ASSUMED_SIGN_MEMORY_POOL` in `readerboard/sign/pool.py` raised
+before it could use the extra.
+
+A sign that answers and does not have the room stops the service starting, with a message
+naming what was configured, what it needs and what there is; that is the one failure that
+does stop it, because the alternative is erasing every message on the sign to write a pool
+that could never work. A sign that says nothing does not stop anything. `POST /sign/reboot`
+asks the same question before it clears the sign, and answers 409 rather than erasing it,
+except when the sign is too wedged to answer, which is the case that endpoint exists for.
 
 ## Security
 
@@ -524,8 +594,9 @@ each is pinned separately so that nothing the service installs ever pulls Qt in.
 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.
+configurations for running the pieces separately, the client among them as
+"readerboard client". Both carry the three way one as "readerboard, the sign simulator
+and the client" as well.
 
 `scripts/run_against_a_sign.py` is the other one, for when the sign is real: the
 service and the client, no simulator, and the sign's address passed as an argument so

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "readerboard"
-version = "0.6.0"
+version = "0.7.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"
@@ -52,7 +52,7 @@ dependencies = [
     # watchfiles, which only makes --reload quicker. That flag is for working on
     # the service rather than for running one, and uvicorn polls the tree
     # without it.
-    "uvicorn>=0.52.1,<0.53",
+    "uvicorn>=0.52.1,<0.54",
     "pydantic>=2.13.4,<3",
     "pydantic-settings>=2.15.0,<3",
     "pyserial>=3.5,<4",
@@ -175,6 +175,15 @@ files = ["readerboard"]
 strict = true
 warn_unreachable = true
 enable_error_code = ["redundant-expr", "truthy-bool", "ignore-without-code"]
+# `files` above still names only the service, so checking a tool is a separate
+# invocation, `mypy tools/signsim/signsim` or `mypy tools/apiclient/apiclient`.
+# Naming both tool roots here means one of those resolves the tool's own
+# package (`import signsim`, `import apiclient`) on its own, no MYPYPATH
+# needed by hand or in CI. The directory-level invocations above already found
+# their root by crawling up from the package's own `__init__.py`; what this
+# actually buys is the narrower case that crawl finds nothing for, such as
+# `mypy` on a single file under a tool's `tests/`, which has none.
+mypy_path = ["tools/signsim", "tools/apiclient"]
 
 [[tool.mypy.overrides]]
 # pyserial ships no type information.

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

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

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

@@ -9,12 +9,18 @@ Nothing here fails to start because the sign is unreachable. A service that
 refused to boot with the sign unplugged would need someone to notice and restart
 it once the sign came back, which is precisely the situation it exists to
 survive.
+
+There is one thing that does stop it, and it is not that. A sign that is
+answering and has less memory than the configured pool needs is a configuration
+somebody has to change, and going ahead would erase every message on the sign to
+write a pool that cannot work. See readerboard.sign.pool.
 """
 
 from __future__ import annotations
 
 import asyncio
 import contextlib
+import functools
 import logging
 from collections.abc import AsyncIterator, Awaitable, Callable
 
@@ -29,6 +35,7 @@ from readerboard.config import Settings
 from readerboard.services.alerts import AlertService
 from readerboard.services.clock import ClockService
 from readerboard.services.registry import SlotRegistry
+from readerboard.sign import pool
 from readerboard.sign.controller import SignController
 from readerboard.sign.layout import Layout
 from readerboard.sign.state import StateStore
@@ -51,6 +58,13 @@ 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
 blanking or restarting what calls it.
 
+An **icon** is one of the built-in bitmaps, drawn where `<icon:name>` sits in a
+message or an alert. `GET /enumerations/icons` lists them. There is a fixed pool
+of picture files on the sign and it is far smaller than the library, so a file is
+claimed by whichever icon a message calls and kept until another icon needs it.
+Icons are off until `picture_count` is raised, because raising it reallocates the
+sign's memory and clears it.
+
 Every write needs an `X-API-Key` header, and so does `GET /sign/information`,
 which reads the sign rather than the service: it puts a question on the wire and
 holds the sign until the answer comes back. The service's own reads and
@@ -59,14 +73,17 @@ holds the sign until the answer comes back. The service's own reads and
 
 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 or value too long for its file, markup the sign cannot render or a call
-to a variable that does not exist, 401 for a missing or wrong `X-API-Key`, 404
-for a slot or variable that does not exist, 409 when every slot or every
-variable is already in use or a variable something still calls is deleted, 503
-when the sign is unreachable, stops partway through an answer or answers with
-something the service cannot read, 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 the sign does not have.
+message or value too long for its file, markup the sign cannot render, a call to
+a variable that does not exist, an icon nobody has, a colour asked for on an icon
+drawn in fixed colours, or an icon called while icons are switched off, 401 for a
+missing or wrong `X-API-Key`, 404 for a slot or variable that does not exist, 409
+when every slot, every variable or every picture file is already in use, a
+variable something still calls is deleted, or an alert is raised with
+`fail_if_active` while one is already up, 503 when the sign is unreachable,
+stops partway through an answer or answers with something the service cannot
+read, 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 the sign does not have.
 """
 
 
@@ -81,6 +98,26 @@ def build_transport(settings: Settings) -> Transport:
     )
 
 
+async def _refresh_and_reassert(registry: SlotRegistry, alerts: AlertService) -> None:
+    """Push everything to the sign again, and make sure any alert is back on it.
+
+    Both of the places that re-push go through here, the timer below and the
+    reconnect hook, because both are answering the same question: the sign may
+    have been power cycled and nothing the controller believes about it holds.
+
+    The refresh puts the slots back, and it puts the alert back too when it had
+    to hand the sign over to write a picture. It says which, and that is why
+    this asks rather than always re-asserting: re-asserting an alert that is
+    already back on the priority file restarts it on the display for nothing,
+    which is a visible flicker every refresh interval for as long as the alert
+    is up. In the case where the refresh did not touch the priority file, which
+    is a service with no icons, the re-assert is the only thing that would put
+    the alert on a sign that came back blank.
+    """
+    if not await registry.refresh():
+        await alerts.reassert()
+
+
 async def _refresh_loop(app: FastAPI, interval: float) -> None:
     """Push everything to the sign again, periodically.
 
@@ -93,12 +130,7 @@ async def _refresh_loop(app: FastAPI, interval: float) -> None:
     while True:
         await asyncio.sleep(interval)
         try:
-            await registry.refresh()
-            # The refresh puts the slots back, but an alert lives in the
-            # priority file, which the registry does not touch. Without this a
-            # sign power cycled mid-alert would stay blank until the alert's
-            # deadline, and an alert with no deadline would stay blank for good.
-            await alerts.reassert()
+            await _refresh_and_reassert(registry, alerts)
         except TransportError as err:
             logger.debug("periodic refresh skipped, sign unreachable: %s", err)
         except Exception:
@@ -149,12 +181,19 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             settings.slot_capacity,
             settings.variable_count,
             settings.variable_capacity,
+            settings.picture_count,
         )
         alerts = AlertService(controller, store, state)
         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)
+        # And the other way: the registry hands the sign back before it writes a
+        # picture, because the sign will not take one while a priority message
+        # is running. Both directions are wired here rather than either service
+        # reaching for the other, and the lock order is what the two of them
+        # have to agree on: the registry's first, then this one's.
+        registry.set_priority_hold(alerts.lifted)
         clock = ClockService(
             controller,
             interval_seconds=settings.clock_sync_interval_seconds,
@@ -169,6 +208,23 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
 
         await controller.start()
 
+        # Only when a reconfiguration is due, which is the one moment the pool
+        # can be got wrong and the one moment the sign is about to be erased. An
+        # ordinary restart asks the sign nothing, costs the display nothing, and
+        # behaves exactly as it did before this check existed. Nothing here can
+        # bring on a reallocation either: the only thing it can do is stop one.
+        if layout.needs_reconfiguration(state.layout):
+            budget = await pool.measure(controller, fallback=pool.ASSUMED_SIGN_MEMORY_POOL)
+            try:
+                pool.check_fits(layout, budget)
+            except pool.PoolTooLarge as err:
+                # Logged as well as raised, because the traceback uvicorn prints
+                # around a failed startup buries the one sentence that says what
+                # to do about it.
+                logger.error("refusing to start: %s", err)
+                await controller.stop()
+                raise
+
         # The sign may be unreachable, and that is not a reason to refuse to
         # start. What is put back below happens again on the next reconnect.
         try:
@@ -201,7 +257,12 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             controller.on_reconnect(clock.sync_quietly)
         # A link that just came back may be in front of a sign that was power
         # cycled, so nothing the controller believes about its contents holds.
-        controller.on_reconnect(registry.refresh)
+        # The alert goes back on with everything else: it was only the slots
+        # before, so a reconnect to a sign that had lost an alert left the
+        # priority file empty until the next tick of the timer above.
+        controller.on_reconnect(
+            functools.partial(_refresh_and_reassert, registry, alerts)
+        )
 
         if settings.clock_sync_enabled:
             await clock.start()
@@ -251,6 +312,7 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
 
         used, total = registry.occupancy
         variables_used, variables_total = registry.variable_occupancy
+        pictures_used, pictures_total = registry.picture_occupancy
         return HealthResponse(
             status="ok" if controller.is_connected else "degraded",
             version=__version__,
@@ -266,6 +328,8 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             slots_total=total,
             variables_used=variables_used,
             variables_total=variables_total,
+            pictures_used=pictures_used,
+            pictures_total=pictures_total,
             sign_in_sync=registry.in_sync,
             alert_active=alerts.active is not None,
             clock_last_synced_at=clock.last_sync_at,

{readerboard-0.6.0 → readerboard-0.7.0}/readerboard/api/errors.py

@@ -13,13 +13,16 @@ from __future__ import annotations
 
 from fastapi import status
 
+from readerboard.icons import IconError
 from readerboard.protocol.frames import ProtocolError
 from readerboard.protocol.markup import MarkupError
 from readerboard.protocol.replies import ReplyError
 from readerboard.services import commands
-from readerboard.services.alerts import AlertTooLong
+from readerboard.services.alerts import AlertAlreadyActive, AlertTooLong
 from readerboard.services.registry import (
+    IconsDisabled,
     MessageTooLong,
+    PicturePoolFull,
     UnknownSlot,
     UnknownVariable,
     VariableInUse,
@@ -27,6 +30,7 @@ from readerboard.services.registry import (
     VariableTooLong,
 )
 from readerboard.sign.layout import LayoutFull
+from readerboard.sign.pool import PoolTooLarge
 from readerboard.transport.base import TransportError
 
 STATUS_FOR_ERROR: tuple[tuple[type[Exception], int], ...] = (
@@ -35,16 +39,35 @@ STATUS_FOR_ERROR: tuple[tuple[type[Exception], int], ...] = (
     (MessageTooLong, status.HTTP_400_BAD_REQUEST),
     (VariableTooLong, status.HTTP_400_BAD_REQUEST),
     (VariablesDisabled, status.HTTP_400_BAD_REQUEST),
+    (IconsDisabled, status.HTTP_400_BAD_REQUEST),
+    # An icon nobody has, or a tint on one drawn in fixed colours. The library
+    # raises these rather than the renderer, because the renderer is not told
+    # which icons exist; mapping the one base they share is what keeps a
+    # misspelled icon name a 400 rather than a 500.
+    (IconError, status.HTTP_400_BAD_REQUEST),
     (AlertTooLong, status.HTTP_400_BAD_REQUEST),
     (commands.UnknownCommand, status.HTTP_400_BAD_REQUEST),
     (commands.BadParameter, status.HTTP_400_BAD_REQUEST),
     (UnknownSlot, status.HTTP_404_NOT_FOUND),
     (UnknownVariable, status.HTTP_404_NOT_FOUND),
     (LayoutFull, status.HTTP_409_CONFLICT),
+    # Only POST /sign/reboot can raise this: the sign has less memory than the
+    # configuration needs, found by asking it just before the reboot would have
+    # erased it. The state of the hardware rather than anything wrong with the
+    # request, which is what makes it a conflict, and nothing was written.
+    (PoolTooLarge, status.HTTP_409_CONFLICT),
     # Deleting a variable a message still calls would leave that message
     # calling a file the next variable could be given. Not the caller's
     # request being malformed, which is what makes it a conflict.
     (VariableInUse, status.HTTP_409_CONFLICT),
+    # Every picture file is holding an icon something still calls. Like a full
+    # slot pool and unlike a bad icon name, this is the state of the sign rather
+    # than anything wrong with the request.
+    (PicturePoolFull, status.HTTP_409_CONFLICT),
+    # An alert is already up and the caller asked to be refused rather than
+    # replace it. The same request would have been accepted a moment earlier, so
+    # it is the state of the sign that decides this and not the body.
+    (AlertAlreadyActive, status.HTTP_409_CONFLICT),
     (TransportError, status.HTTP_503_SERVICE_UNAVAILABLE),
     # A sign that answers with something unreadable is as unusable as one
     # that does not answer, and neither is the caller's doing. The route

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

@@ -61,7 +61,8 @@ class SlotRequest(BaseModel):
         min_length=1,
         max_length=4096,
         description=(
-            "the message, including markup tokens such as <red> and <degree>, and "
+            "the message, including markup tokens such as <red> and <degree>, "
+            "<icon:name> to draw one of the built-in icons, 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 "
             "gives a file with no text in it no turn of its own but does hold the "
@@ -293,7 +294,8 @@ class AlertRequest(BaseModel):
         description=(
             "the alert text. The sign's priority file holds 125 bytes once markup has "
             "been rendered, and cannot be resized. It can call variables with "
-            "<var:name>, as a message can. It cannot be empty: a write with no "
+            "<var:name> and draw icons with <icon:name>, as a message can. An icon "
+            "costs the alert two of those 125 bytes. It cannot be empty: a write with no "
             "text still carries the formatting bytes around it, which the sign reads as "
             "a blank priority message and displays, so the sign would sit blank with "
             "the rotation suppressed behind it and an alert reported as active"
@@ -308,6 +310,16 @@ class AlertRequest(BaseModel):
             "sign until something releases it explicitly"
         ),
     )
+    fail_if_active: bool = Field(
+        default=False,
+        description=(
+            "refuse with a 409 if an alert is already holding the sign, rather than "
+            "replacing it. For a caller that is one of several raising alerts and has "
+            "no business overwriting somebody else's alert. An alert whose deadline has "
+            "already passed does not count as holding the sign. Release the alert that "
+            "is up, or send the same call without this, to get past a refusal"
+        ),
+    )
 
     _check_mode = field_validator("display_mode")(_normalise_mode)
 
@@ -376,6 +388,14 @@ class HealthResponse(BaseModel):
     slots_total: int
     variables_used: int
     variables_total: int = Field(description="0 when variables are switched off")
+    pictures_used: int = Field(
+        description=(
+            "picture files holding an icon, which includes ones nothing calls any more: "
+            "a file is kept after its last caller goes, and given up only when another "
+            "icon needs it"
+        )
+    )
+    pictures_total: int = Field(description="0 when icons are switched off")
     sign_in_sync: bool = Field(
         description=(
             "false when the sign is behind the service's record, which is a removal or "
@@ -392,3 +412,28 @@ class TokenInfo(BaseModel):
 
     name: str
     description: str
+
+
+class IconInfo(BaseModel):
+    """One icon from the built-in library.
+
+    ``name`` is the whole tag rather than the bare icon name, which is what
+    every other enumeration answers too: the caller writes what it is given,
+    and a client that had to wrap the answer in ``<icon:`` first would be a
+    client that knows a piece of syntax nobody told it.
+
+    The three fields after the description are the same facts in a form
+    something can sort or filter on without reading prose.
+    """
+
+    name: str
+    description: str
+    group: str = Field(description="what it is listed with, such as 'weather' or 'arrows'")
+    width: int = Field(description="how many dots wide it is drawn; every icon is 7 high")
+    tintable: bool = Field(
+        description=(
+            "whether a colour may be asked for, as <icon:check:red>. False for an icon "
+            "whose own colours are the point of it, and asking for one anyway is refused "
+            "rather than ignored"
+        )
+    )