readerboard 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.3.0
+Version: 0.5.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
@@ -37,6 +37,7 @@ Provides-Extra: dev
 Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
 Requires-Dist: pytest-asyncio<2,>=1.4.0; extra == "dev"
 Requires-Dist: httpx2<3,>=2.10.0; extra == "dev"
+Requires-Dist: anyio<4.15,>=4.14.2; extra == "dev"
 Requires-Dist: ruff<0.17,>=0.16.2; extra == "dev"
 Requires-Dist: mypy<3,>=2.3.0; extra == "dev"
 Dynamic: license-file
@@ -54,8 +55,10 @@ 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 registered slots by itself. A **variable** is a value that messages
+call by name, such as a temperature, and changing it does not blank the sign or restart
+the message showing it. An **alert** takes the whole display over until it is released,
+after which the rotation resumes.
 
 ## What it does
 
@@ -63,16 +66,24 @@ 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
-  does so at no particular minute.
+  does so at no particular minute. The sign is set one minute fast on purpose: the
+  protocol has no seconds field, so a sign told the current minute reads behind for the
+  rest of it and never ahead, and a minute of lead puts the error on the side that reads
+  as a clock being a touch fast rather than most of a minute slow.
 - **It does not redraw the sign for nothing.** A write of bytes the sign already holds is
   suppressed, so a source re-sending an unchanged temperature does not make the display
   flicker.
-- **It survives restarts and outages.** The registered messages are persisted, and a
-  write that arrives while the sign is unreachable is accepted and delivered when the
-  link returns.
+- **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.
 - **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.
@@ -122,6 +133,73 @@ other, and stops both on Ctrl+C. The simulator decodes each transmission, says
 what every byte of it means, and shows what the sign would be holding as a
 result. `tools/signsim/README.md` has the details.
 
+## Running it against a real sign
+
+From a checkout, with the sign on a cable or on an Ethernet to RS-232 adapter:
+
+```
+pip install -e ".[dev]"
+pip install --require-hashes -r tools/apiclient/requirements.lock
+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,
+and closing the client leaves the service running.
+
+Both editors carry it as a launch configuration named "readerboard against the
+real sign and the client". **The sign's address is an argument in those, not a
+setting in a file**, so changing which sign is driven means editing the
+Parameters field in PyCharm's run configuration dialog, or `args` in
+`.vscode/launch.json`. They also pass `--api-port 5002`, so a second checkout of
+this repository on the same machine can run beside them; the launcher checks
+that port before it starts anything rather than letting the service bind, fail
+and stop after the client has been pointed at whatever else answered.
+
+### Writing the address
+
+It is a pyserial URL, and **there is no slash between the host and the port**.
+`socket://192.168.2.51/:4001` looks close enough to right and is not: pyserial
+answers it with a bare `TypeError` from deep inside a connection attempt, naming
+neither the setting nor the value. The launcher checks the address before it
+opens anything and says which part is wrong. The four forms are:
+
+```
+socket://192.168.2.51:4001   an Ethernet to RS-232 adapter passing raw TCP
+rfc2217://192.168.2.51:23    an adapter speaking the telnet serial protocol
+COM3                         a cable on Windows
+/dev/ttyUSB0                 a cable on Linux
+```
+
+Most adapters pass raw TCP, so try `socket://` first. If the link opens but the
+sign shows nothing or shows rubbish, and the adapter answers on port 23, it is
+probably negotiating telnet rather than passing bytes through, and `rfc2217://`
+is the form that speaks that.
+
+### The API key, and config.local.toml
+
+The key is not an argument. A launch configuration is a tracked file and a
+command line is a shell history, and anyone holding the key can write to the
+sign. It lives in `config.local.toml` at the root of the checkout, which
+`.gitignore` covers and which the launcher writes with a generated key the first
+time it runs. Given no `--serial-url`, the address is read from there too.
+
+### The first run erases the sign
+
+Writing a memory configuration erases every message on the sign, and the service
+writes one whenever it has no record of the configuration already applied. The
+first run against a sign this machine has never driven therefore erases it,
+which is also the only way to allocate the files it then writes into. Every run
+after that reads the record and leaves the sign alone.
+
+That record is `.local-sign-state.json`, and it belongs to this launcher alone.
+`scripts/run_with_simulator.py` deletes its own `.local-state.json` on every
+launch, because the simulator starts empty every time and the service has to
+reconfigure it. If the two shared one file, a simulator session would throw the
+sign's record away and the next run against the sign would erase it.
+
 ## Installing it properly
 
 Two ways, which do the same job. Pick whichever suits the machine.
@@ -177,8 +255,10 @@ docker run ... --device /dev/ttyUSB0 --group-add 20 \
 
 ## Using it
 
-Every write needs an `X-API-Key` header. Reads and `GET /health` do not. In the
-Swagger UI at `/docs`, the **Authorize** button puts it in once for the whole page.
+Every write needs an `X-API-Key` header, and so does `GET /sign/information`,
+which asks the sign a question rather than reading the service's own record. The
+service's other reads and `GET /health` do not. In the Swagger UI at `/docs`, the
+**Authorize** button puts it in once for the whole page.
 
 Register a message:
 
@@ -196,6 +276,21 @@ curl -X PUT http://localhost:5001/messages/doorbell \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
 
+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/messages/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:
 
 ```
@@ -204,7 +299,25 @@ curl -X POST http://localhost:5001/alerts \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API is at `/docs`. Every markup token, display mode, text position and
+Make a noise, which is worth pairing with an alert if the sign is somewhere nobody
+is watching it:
+
+```
+curl -X POST http://localhost:5001/sign/command \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"command": "SOUND", "parameter": "BEEPS"}'
+```
+
+`BEEPS` is three short beeps and `TONE` is one continuous tone of about two seconds.
+Those are the only two sounds there are: the sign has a fixed-pitch buzzer, so there
+is no pitch or volume to choose.
+
+Silence it with `{"command": "SPEAKER", "parameter": "OFF"}`, and turn it back on with
+`ON`. That is a real mute: `SOUND` is still accepted and makes no noise. The setting
+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, 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.
 
@@ -219,6 +332,92 @@ 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
+showing, it stops responding to writes, and there is no power switch within reach.
+There are two recoveries, and they are not interchangeable. Try the gentle one first.
+
+**A soft reset restarts the sign and erases nothing.** The sign runs the same power-up
+diagnostics it runs when you plug it in, then carries on showing what it was showing.
+Its memory, its file table and its messages all survive; this was verified on the sign
+by reading them back either side of a reset.
+
+```
+curl -X POST http://localhost:5001/sign/command \
+     -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
+     -d '{"command": "SOFT_RESET"}'
+```
+
+The call waits out the diagnostics before answering, so a 204 means the sign is
+listening again rather than that the bytes went out.
+
+**`POST /sign/reboot` is the escalation, and it is destructive.** It clears the sign
+outright, waits for it to restart, then re-pushes every message and the run sequence
+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.
+
 ## Configuration
 
 Settings come from `/etc/readerboard/config.toml`, overridden by environment variables
@@ -230,22 +429,30 @@ and usually absent, which is not an error. `READERBOARD_CONFIG_FILE` moves the f
 you want it somewhere other than the default.
 
 The sign's address is a full pyserial URL in `serial_url`: `socket://192.168.2.51:4001`
-for an Ethernet to RS-232 adapter, `/dev/ttyUSB0` for a cable plugged straight in, or
-`loop://` to run the service with no sign attached.
-
-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.
+for an Ethernet to RS-232 adapter, `rfc2217://192.168.2.51:23` for one speaking the
+telnet serial protocol, `/dev/ttyUSB0` or `COM3` for a cable plugged straight in, or
+`loop://` to run the service with no sign attached. There is no slash between the host
+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.
 
 ## Security
 
 An API key is required on every write, compared in constant time, and never logged.
-Reads and `GET /health` need none, so a monitor can watch the sign without holding a key
-that could write to it.
+`GET /sign/information` needs one too: it is a read of the sign itself rather than of the
+service, so it sends a question over the wire, holds the sign until the answer arrives,
+and reports the hardware's firmware and how full its memory is. The service's own reads
+and `GET /health` need none, so a monitor can watch the slots without holding a key that
+could write to them.
 
 The key is declared to the API description as a security scheme, so the Swagger UI at
-`/docs` has an **Authorize** button: enter the key once and every write on the page
-carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
+`/docs` has an **Authorize** button: enter the key once and everything on the page that
+needs it carries it. It is the same `X-API-Key` header a client sends, so nothing about a script
 or a Home Assistant `rest_command` changes.
 
 That page is configured to remember the key, so it survives a reload or a browser
@@ -316,6 +523,21 @@ the sign simulator", in `.vscode/launch.json` and in `.idea/runConfigurations/`,
 configurations for running the pieces separately. 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
+that it can be edited in a run configuration dialog. Both editors carry it as
+"readerboard against the real sign and the client". The section above has the rest,
+including the one thing about it that is dangerous. The two launchers share their
+process supervision through `scripts/_supervise.py` and differ in what each child is
+given, which is the part that matters: the simulator launcher discards its state file
+on every run and this one never discards anything.
+
+Every one of those that starts the service sets `READERBOARD_OPEN_DOCS`, so `/docs`
+opens in a browser once the port answers. The service does the waiting and the
+opening, which is why it lands on the port actually bound rather than one repeated in
+a launch file. The setting is off unless asked for, so an installed service opens
+nothing.
+
 ## Licence
 
 MIT. See [LICENSE](https://github.com/mjaksn/readerboard/blob/main/LICENSE).