readerboard 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: readerboard
-Version: 0.2.0
-Summary: An HTTP service for BetaBrite and Alpha protocol LED signs: several sources share one sign, with alerts, scheduling and clock sync
+Version: 0.4.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
 Project-URL: Homepage, https://github.com/mjaksn/readerboard
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Home Automation
 Classifier: Topic :: System :: Hardware
 Classifier: Typing :: Typed
@@ -36,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
@@ -65,15 +67,20 @@ until it is released, after which the rotation resumes.
 - **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.
-- **Errors are errors.** A dead serial link is a 503, not an HTTP 200 with the word
-  ERROR in the body.
+- **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.
 
 ## Requirements
 
@@ -120,6 +127,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.
@@ -175,13 +249,15 @@ 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:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/temperature \
+curl -X PUT http://localhost:5001/messages/temperature \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<green>18.4<degree> <red><time>", "display_mode": "HOLD"}'
 ```
@@ -189,7 +265,7 @@ curl -X PUT http://localhost:5001/v2/messages/temperature \
 Register a second one and the sign rotates between them:
 
 ```
-curl -X PUT http://localhost:5001/v2/messages/doorbell \
+curl -X PUT http://localhost:5001/messages/doorbell \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<amber>Someone at the door", "ttl_seconds": 300}'
 ```
@@ -197,46 +273,76 @@ curl -X PUT http://localhost:5001/v2/messages/doorbell \
 Take the sign over for thirty seconds:
 
 ```
-curl -X POST http://localhost:5001/v2/alerts \
+curl -X POST http://localhost:5001/alerts \
      -H 'X-API-Key: YOUR-KEY' -H 'Content-Type: application/json' \
      -d '{"message": "<red><flash_on>SMOKE ALARM", "ttl_seconds": 30}'
 ```
 
-The full API, including every markup token and display mode, is at `/docs`.
+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, 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
 
 A message is plain text plus tokens written as `<name>`: `<green>18.4<degree>` is a
-colour change, a number, and a degree symbol. `GET /v2/enumerations/markup-tokens` lists
+colour change, a number, and a degree symbol. `GET /enumerations/markup-tokens` lists
 them all.
 
 Text is encoded against the sign's own character table rather than as UTF-8, so `café`
-displays correctly. A character the sign cannot render is rejected with a 400 on `/v2`,
-and replaced with `?` on the simpler endpoints described below.
+displays correctly. A character the sign cannot render is rejected with a 400, as is an
+unknown token: a write is told what the sign would have made of it rather than being
+shown something it did not ask for.
 
-## A simpler set of endpoints
+### Recovering a sign that has stopped responding
 
-Alongside `/v2` there is a smaller surface: `POST /Write/Message`,
-`POST /Write/ControlCommand`, and the `/Enumerations` reads.
+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.
 
-These follow one convention that `/v2` does not. **Every response is HTTP 200**, with the
-outcome in the body:
+**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.
 
-```json
-{"result": "OK", "result_message": "Message displayed on sign"}
 ```
+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.
 
-That suits a client which finds branching on status codes awkward, such as a Home
-Assistant `rest_command` or a shell one-liner in a cron job. The exceptions are the
-requests that never reach the endpoint at all: a missing or wrong API key is a 401, a
-service with no API key configured is a 503, and a body that is not the shape the endpoint
-declares gets FastAPI's own 422. A caller the service will not talk to, and a body it
-cannot read, are not the same as a request that failed.
+**`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'
+```
 
-`POST /Write/Message` writes to one reserved slot, named `default`. It deliberately does
-not touch the sign's **priority** file, which by protocol suppresses every other message on
-the sign. Written to an ordinary slot it looks identical while it is the only message
-registered, and it shares the sign the moment anything else registers.
+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
 
@@ -249,8 +355,11 @@ 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.
+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.
 
 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
@@ -259,12 +368,15 @@ the log, but they are not settings to fiddle with.
 ## 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
@@ -321,35 +433,46 @@ claim. Read it before changing anything in `readerboard/protocol/`.
 `scripts/protocol_spike.py` settles the few questions the document cannot answer about
 this particular sign. It is destructive and refuses to run without `--confirm-erase`.
 
-`tools/signsim/` is a PySide6 stand-in for the sign, described above. Its own tests
-are collected by the `pytest` run here and need no Qt installed; the application does,
-and it is pinned separately so that nothing the service installs ever pulls Qt in.
-
-`scripts/run_with_simulator.py` starts the service and the simulator together. Both
-editors have it as a launch configuration, "API and sign simulator" in
-`.vscode/launch.json` and "API and simulator" in `.idea/runConfigurations/`, along with
-configurations for each half on its own.
+`tools/signsim/` is the sign simulator, a PySide6 stand-in for the sign, described
+above. `tools/apiclient/` is the client, a PySide6 application for calling the API by
+hand: every endpoint, responses shown as text rather than JSON, and a vocabulary it
+loads from the service rather than one compiled into it. The tests of both are
+collected by the `pytest` run here and need no Qt installed; the applications do, and
+each is pinned separately so that nothing the service installs ever pulls Qt in.
+
+`scripts/run_with_simulator.py` starts the service and the simulator together, and
+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.
+
+`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).
 
-One caveat, recorded because it is easy to miss.
-`readerboard/protocol/constants.py` is vendored from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), and that
-repository carries no license file. No license is not the same as a permissive one: it
-means no copying permission has been granted at all. That module is therefore the one
-part of this project whose provenance is not cleanly MIT.
-
-In practice it is a table of byte values dictated by the protocol rather than authored
-expression, and `docs/protocol-notes.md` now cites the protocol document directly, so the
-table can be regenerated from the primary source if that ever needs settling properly.
-
 ## Credits
 
-`readerboard/protocol/constants.py` came, with thanks, from
-[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), with some
-corrections noted in the file.
+The protocol is documented in the Alpha Sign Communications Protocol, form 9708-8061,
+published by Adaptive Micro Systems. Every byte value in
+`readerboard/protocol/constants.py` is transcribed from that document, and
+`tests/test_constant_values.py` pins each one against it with a citation per assertion.
 
-The protocol itself is documented in the Alpha Sign Communications Protocol, form
-9708-8061, published by Adaptive Micro Systems.
+An earlier version of this project took that table from
+[jonathankoren/readerboard](https://github.com/jonathankoren/readerboard), which is
+recorded here with thanks even though no code from it remains.