readerboard 0.4.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.4.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
@@ -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,7 +68,13 @@ 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.
+  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
@@ -76,8 +86,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.
@@ -139,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
@@ -213,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`,
@@ -257,7 +282,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 +290,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 +380,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 +395,93 @@ 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 }}"
+```
+
+### 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
@@ -339,10 +510,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 +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.
 
-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.
+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
 
@@ -444,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.4.0 → readerboard-0.7.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,7 +24,13 @@ 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.
+  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
@@ -32,8 +42,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.
@@ -95,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
@@ -169,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`,
@@ -213,7 +238,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 +246,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 +336,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 +351,93 @@ 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 }}"
+```
+
+### 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
@@ -295,10 +466,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 +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.
 
-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.
+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
 
@@ -400,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