readerboard 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.4.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,8 +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. 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
 
@@ -64,6 +68,10 @@ until it is released, after which the rotation resumes.
   automation owns `doorbell`, without either knowing about the other.
 - **The sign does the rotating.** Each message lives in its own sign file and the sign
   cycles them on its own, so rotation costs no serial traffic at all.
+- **Live values without a blink.** A message such as `Outside <var:temp><degree>F` calls
+  the variable `temp`, and a new value is one small write that the sign shows the next
+  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.
 - **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
@@ -76,8 +84,10 @@ until it is released, 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.
@@ -257,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"}'
 ```
@@ -265,11 +275,70 @@ 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:
+
+```
+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/slots/weather \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "Outside <var:temp><degree>F", "display_mode": "ROTATE"}'
+```
+
+From then on only the variable needs writing, and the message picks each new value up
+on its next pass across the sign.
+
 Take the sign over for thirty seconds:
 
 ```
@@ -296,8 +365,8 @@ Silence it with `{"command": "SPEAKER", "parameter": "OFF"}`, and turn it back o
 lives on the sign and survives a restart, so it is also the first thing to check if
 `SOUND` ever seems to do nothing.
 
-The full API is at `/docs`. Every markup token, display mode and control
-command is listed by the `/enumerations` reads there, which answer at
+The full API is at `/docs`. Every markup token, value token, display mode and
+control command is listed by the `/enumerations` reads there, which answer at
 request time rather than being frozen into the description.
 
 ### Writing messages
@@ -311,6 +380,59 @@ displays correctly. A character the sign cannot render is rejected with a 400, a
 unknown token: a write is told what the sign would have made of it rather than being
 shown something it did not ask for.
 
+### Live values: variables
+
+A variable lives in a small file of its own on the sign, and a message or an alert
+calls it with `<var:name>`. Writing a new value rewrites that file and nothing else,
+which the sign takes without blanking, so a message showing a temperature or a count can
+change every minute and never restart. In a scrolling mode the new value appears on the
+message's next pass. An alert carrying a live wind speed works the same way, and keeps
+the sign while the number changes.
+
+A few things are worth knowing, all of them measured on the sign:
+
+- **Create the variable before a message calls it.** A message or an alert naming a
+  variable that does not exist is refused with a 400, and a variable that a message or
+  the alert still calls cannot be deleted: that is a 409 naming what calls it.
+- **Formatting in a value carries on after it.** A value of `<red>DOWN` turns the rest
+  of the message red as well, and so does a character set or a speed. If the text after
+  the call matters, set it again in the message after the call.
+- **A value takes the message markup, less two tokens.** `<week_day>` draws as a literal
+  `9` from inside a variable, and a variable cannot call another. `GET
+  /enumerations/value-tokens` lists what is allowed.
+- **Keep a changing number from pushing the text around it.** With the sign's usual
+  proportional spacing, `11` and `88` are different widths and the text after them moves.
+  Put `<fixed_width>` in the message before the call and send values of the same length.
+  Fixed width also left-justifies the line.
+- **A value that stops arriving can go stale.** Give a `ttl_seconds` and a `stale_value`
+  such as `--`, and once the time passes without a new value the sign shows the stale
+  value instead. The variable itself stays, since messages call it.
+- **A value that does not fit is refused.** Each holds `variable_capacity` bytes after
+  rendering, 32 by default. The sign does not cut an overlong value short, it empties it,
+  so the service refuses one rather than send it.
+
+A Home Assistant `rest_command` that keeps a sensor on the sign:
+
+```yaml
+rest_command:
+  sign_temperature:
+    url: http://readerboard.local:5001/variables/temp
+    method: put
+    headers:
+      X-API-Key: !secret readerboard_key
+    content_type: application/json
+    payload: '{"value": "{{ value }}", "ttl_seconds": 1800, "stale_value": "--"}'
+```
+
+Call it from an automation triggered by the sensor, with the reading as `value`:
+
+```yaml
+actions:
+  - action: rest_command.sign_temperature
+    data:
+      value: "{{ states('sensor.outside_temperature') | round(0) | int }}"
+```
+
 ### Recovering a sign that has stopped responding
 
 A sign mounted out of reach can wedge: a stray bit corrupts what its decoder is
@@ -339,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
 
@@ -361,9 +483,11 @@ 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.
 
-Two settings reallocate the sign's memory when changed, and **that erases every message
-on it**: `slot_count` and `slot_capacity`. The service will do it, and say so loudly in
-the log, but they are not settings to fiddle with.
+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.
 
 ## Security
 

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

@@ -11,8 +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. 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
 
@@ -20,6 +24,10 @@ until it is released, after which the rotation resumes.
   automation owns `doorbell`, without either knowing about the other.
 - **The sign does the rotating.** Each message lives in its own sign file and the sign
   cycles them on its own, so rotation costs no serial traffic at all.
+- **Live values without a blink.** A message such as `Outside <var:temp><degree>F` calls
+  the variable `temp`, and a new value is one small write that the sign shows the next
+  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.
 - **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
@@ -32,8 +40,10 @@ until it is released, 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.
@@ -213,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"}'
 ```
@@ -221,11 +231,70 @@ 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:
+
+```
+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/slots/weather \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"message": "Outside <var:temp><degree>F", "display_mode": "ROTATE"}'
+```
+
+From then on only the variable needs writing, and the message picks each new value up
+on its next pass across the sign.
+
 Take the sign over for thirty seconds:
 
 ```
@@ -252,8 +321,8 @@ Silence it with `{"command": "SPEAKER", "parameter": "OFF"}`, and turn it back o
 lives on the sign and survives a restart, so it is also the first thing to check if
 `SOUND` ever seems to do nothing.
 
-The full API is at `/docs`. Every markup token, display mode and control
-command is listed by the `/enumerations` reads there, which answer at
+The full API is at `/docs`. Every markup token, value token, display mode and
+control command is listed by the `/enumerations` reads there, which answer at
 request time rather than being frozen into the description.
 
 ### Writing messages
@@ -267,6 +336,59 @@ displays correctly. A character the sign cannot render is rejected with a 400, a
 unknown token: a write is told what the sign would have made of it rather than being
 shown something it did not ask for.
 
+### Live values: variables
+
+A variable lives in a small file of its own on the sign, and a message or an alert
+calls it with `<var:name>`. Writing a new value rewrites that file and nothing else,
+which the sign takes without blanking, so a message showing a temperature or a count can
+change every minute and never restart. In a scrolling mode the new value appears on the
+message's next pass. An alert carrying a live wind speed works the same way, and keeps
+the sign while the number changes.
+
+A few things are worth knowing, all of them measured on the sign:
+
+- **Create the variable before a message calls it.** A message or an alert naming a
+  variable that does not exist is refused with a 400, and a variable that a message or
+  the alert still calls cannot be deleted: that is a 409 naming what calls it.
+- **Formatting in a value carries on after it.** A value of `<red>DOWN` turns the rest
+  of the message red as well, and so does a character set or a speed. If the text after
+  the call matters, set it again in the message after the call.
+- **A value takes the message markup, less two tokens.** `<week_day>` draws as a literal
+  `9` from inside a variable, and a variable cannot call another. `GET
+  /enumerations/value-tokens` lists what is allowed.
+- **Keep a changing number from pushing the text around it.** With the sign's usual
+  proportional spacing, `11` and `88` are different widths and the text after them moves.
+  Put `<fixed_width>` in the message before the call and send values of the same length.
+  Fixed width also left-justifies the line.
+- **A value that stops arriving can go stale.** Give a `ttl_seconds` and a `stale_value`
+  such as `--`, and once the time passes without a new value the sign shows the stale
+  value instead. The variable itself stays, since messages call it.
+- **A value that does not fit is refused.** Each holds `variable_capacity` bytes after
+  rendering, 32 by default. The sign does not cut an overlong value short, it empties it,
+  so the service refuses one rather than send it.
+
+A Home Assistant `rest_command` that keeps a sensor on the sign:
+
+```yaml
+rest_command:
+  sign_temperature:
+    url: http://readerboard.local:5001/variables/temp
+    method: put
+    headers:
+      X-API-Key: !secret readerboard_key
+    content_type: application/json
+    payload: '{"value": "{{ value }}", "ttl_seconds": 1800, "stale_value": "--"}'
+```
+
+Call it from an automation triggered by the sensor, with the reading as `value`:
+
+```yaml
+actions:
+  - action: rest_command.sign_temperature
+    data:
+      value: "{{ states('sensor.outside_temperature') | round(0) | int }}"
+```
+
 ### Recovering a sign that has stopped responding
 
 A sign mounted out of reach can wedge: a stray bit corrupts what its decoder is
@@ -295,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
 
@@ -317,9 +439,11 @@ 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.
 
-Two settings reallocate the sign's memory when changed, and **that erases every message
-on it**: `slot_count` and `slot_capacity`. The service will do it, and say so loudly in
-the log, but they are not settings to fiddle with.
+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.
 
 ## Security
 

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

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

{readerboard-0.4.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,14 @@ 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
+blanking or restarting what calls 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
@@ -53,13 +59,14 @@ 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 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, 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 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.
 """
 
 
@@ -77,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:
@@ -99,8 +106,8 @@ async def _refresh_loop(app: FastAPI, interval: float) -> None:
 
 
 async def _sweep_loop(app: FastAPI, interval: float) -> None:
-    """Expire slots and alerts whose deadlines have passed."""
-    registry: MessageRegistry = app.state.registry
+    """Expire slots and alerts, and turn variables stale, once their deadlines pass."""
+    registry: SlotRegistry = app.state.registry
     alerts: AlertService = app.state.alerts
 
     while True:
@@ -137,14 +144,17 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
         )
         store = StateStore(settings.state_path)
         state = store.load()
-        layout = Layout(settings.slot_count, settings.slot_capacity)
-        alerts = AlertService(controller, store, state)
-        registry = MessageRegistry(
-            controller, layout, store, state, alert_active=lambda: alerts.active is not None
+        layout = Layout(
+            settings.slot_count,
+            settings.slot_capacity,
+            settings.variable_count,
+            settings.variable_capacity,
         )
-        # 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)
+        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)
         clock = ClockService(
             controller,
             interval_seconds=settings.clock_sync_interval_seconds,
@@ -240,6 +250,7 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
         clock = get_clock(request)
 
         used, total = registry.occupancy
+        variables_used, variables_total = registry.variable_occupancy
         return HealthResponse(
             status="ok" if controller.is_connected else "degraded",
             version=__version__,
@@ -253,6 +264,8 @@ def create_app(settings: Settings | None = None, transport: Transport | None = N
             ),
             slots_used=used,
             slots_total=total,
+            variables_used=variables_used,
+            variables_total=variables_total,
             sign_in_sync=registry.in_sync,
             alert_active=alerts.active is not None,
             clock_last_synced_at=clock.last_sync_at,

{readerboard-0.4.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.4.0 → readerboard-0.6.0}/readerboard/api/errors.py

@@ -18,7 +18,14 @@ 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.registry import MessageTooLong, UnknownSlot
+from readerboard.services.registry import (
+    MessageTooLong,
+    UnknownSlot,
+    UnknownVariable,
+    VariableInUse,
+    VariablesDisabled,
+    VariableTooLong,
+)
 from readerboard.sign.layout import LayoutFull
 from readerboard.transport.base import TransportError
 
@@ -26,11 +33,18 @@ STATUS_FOR_ERROR: tuple[tuple[type[Exception], int], ...] = (
     (MarkupError, status.HTTP_400_BAD_REQUEST),
     (ProtocolError, status.HTTP_400_BAD_REQUEST),
     (MessageTooLong, status.HTTP_400_BAD_REQUEST),
+    (VariableTooLong, status.HTTP_400_BAD_REQUEST),
+    (VariablesDisabled, 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),
+    # 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),
     (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