OpenReactor: Browser UI and HTTP API
openreactor serve runs the controller and serves two things from the same
process: a browser UI at /, and an HTTP API at /api/v1. It prints each
event as it happens, as run does, and holds the same lock as the other
device commands (usage.md).
openreactor serve -c ~/openreactor.tomlBy default it listens on 127.0.0.1:8080, so only the Pi itself can reach
it. Serving on the lab network describes how to
open it to other machines.
The browser UI
Section titled “The browser UI”Every page except sign-in has a Stop all button, which sends stop-all to every slice at once. If any slice fails to go safe, the page names it.
| Page | Path | What it shows |
|---|---|---|
| Dashboard | / |
Live values, a chart of the values since the page opened, each device’s status, and the current run. |
| Controls | /controls |
A setpoint form for each RLHT channel, and a duty form for each DCMT motor. |
| Runs | /runs |
Start and stop a run, run and abort a profile, and export the recorded runs. |
| Devices | /devices |
Each device’s status, EZO calibration, and Clear trip for a DCMT whose watchdog trip is held. |
| About | /about |
The version, the licence, and the included browser libraries. |
The UI loads nothing from the internet, so it works on a lab network with no internet access. The few browser files it uses ship inside the package (development.md).
The HTTP API
Section titled “The HTTP API”All endpoints are under /api/v1, and all of them sit behind the same
sign-in as the UI. The OpenAPI description is at /api/v1/openapi.json.
| Method | Path | What it does |
|---|---|---|
GET |
/status |
The version, the current run, each device’s status, each RLHT slice in detail under slices, and each DCMT under dcmt_slices. |
GET |
/channels |
The latest value of every channel. |
PUT |
/channels/{channel}/setpoint |
Set an RLHT channel’s setpoint in deg C, or a DCMT motor’s duty in %. The body is {"value": 40}. |
POST |
/devices/{device}/clear-trip |
Clear a DCMT’s held watchdog trip. Its motors stay stopped. Answers with the event; 404 for a device that is not a DCMT, 409 when no trip is held, 502 when the send fails, 503 when the slice is not in use. |
POST |
/stop-all |
Send stop-all, and return one event per slice. |
GET |
/runs |
List the recorded runs. |
POST |
/runs |
Start a run. The body is {"name": "...", "notes": "..."}; notes is optional. Answers 201 with the run’s id. |
POST |
/runs/current/stop |
Stop the recording run, aborting a profile that drives it. Answers with its id and status. |
POST |
/profile |
Run a profile. The body is {"profile": "<TOML text>", "name": "...", "notes": "..."}; name and notes are optional. Answers 201 with the new run’s id. |
GET |
/profile |
The running profile: its run, name, elapsed_s and duration_s, or null. |
POST |
/profile/abort |
Abort the running profile. Answers with its run’s id and status. |
GET |
/runs/{run}/export |
Download the run as run-N.zip. |
GET |
/ezo/{device}/calibration |
Show a circuit’s calibration. |
POST |
/ezo/{device}/calibration |
Calibrate one point. The body is {"point": "mid", "value": 7.0}. |
DELETE |
/ezo/{device}/calibration |
Erase a circuit’s calibration. |
For example, from the Pi:
curl -s localhost:8080/api/v1/statuscurl -s -X PUT localhost:8080/api/v1/channels/jacket/setpoint \ -H 'Content-Type: application/json' -d '{"value": 40}'curl -s -X POST localhost:8080/api/v1/stop-allThe calibration points for each family are in usage.md.
Setpoints
Section titled “Setpoints”You set an RLHT channel’s setpoint from the API or the Controls page, in
deg C. The slice works in tenths of a degree, so openreactor rounds the value
to the nearest 0.1 deg C. It accepts values from 0 up to the channel’s
max_setpoint, or up to 3276.7 deg C when the configuration sets none.
openreactor sends the setpoint to the slice at once, and records it as an event in the run, whether the send worked or not.
A setpoint stays the one openreactor wants until one of these happens:
- You set it again.
- Stop-all, an e-stop, or a slice reboot sets it to 0.
- The slice is found running other setpoints with no trip or reboot to explain it, and openreactor sets it to 0.
- openreactor stops. It does not restore setpoints when it starts again.
After a plain watchdog trip, openreactor sends the setpoint again. safety.md describes each case.
Profiles
Section titled “Profiles”usage.md describes the profile format and how a
profile runs. POST /api/v1/profile answers 422 with every problem the
validator finds, including a value outside a channel’s range, 409 while a
run is recording or a slice it uses has its e-stop or a DCMT trip held, and
503 when a slice the profile uses is not in use or is unreachable. A
profile’s TOML text can be up to 20,000 characters. For example:
python3 -c 'import json, sys; print(json.dumps({"profile": open(sys.argv[1]).read()}))' \ examples/profiles/ramp-and-hold.toml > profile.jsoncurl -s -X POST localhost:8080/api/v1/profile \ -H 'Content-Type: application/json' --data @profile.jsoncurl -s -X POST localhost:8080/api/v1/profile/abortMotor duties
Section titled “Motor duties”A DCMT motor’s setpoint is its duty, from -100 to 100 %: negative runs it in reverse, and 0 brakes it. The slice works in PWM steps of 1/255, so openreactor rounds the duty to the nearest step (50 % runs as 50.2 %), and a duty under 0.2 % rounds to 0 and brakes the motor.
Before it sends a duty, openreactor reads the slice. The slice takes both motors’ duties in one command, so if the slice rebooted or its e-stop was pressed since the last poll, sending would restart the other motor at its old duty. In that case openreactor refuses with 409, checks the slice at its next poll, and stops both motors. Unlike an RLHT setpoint, a duty is never sent again: after an e-stop, a watchdog trip, a reboot or stop-all, the motors stay stopped until you set them again.
A PUT to /channels/{channel}/setpoint answers with one of these:
| Status | When |
|---|---|
| 204 | The setpoint was sent. |
| 404 | No actuated channel has that name. |
| 409 | The slice’s e-stop is held. Release it, then set the setpoint again. |
| 409 | The slice is read-only, because it has no command watchdog. |
| 409 | The slice is running setpoints other than those wanted, or changed since it was last checked (a reboot, a trip or an e-stop no poll has seen yet), and openreactor is checking why. Try again a moment later. |
| 409 | On a DCMT: a watchdog trip is held. |
| 409 | A running profile drives the channel. Abort the profile first. |
| 422 | The value is not a JSON number, is below 0, or is above the limit. For a motor, it is outside -100 to 100. |
| 502 | Sending failed. The slice may still have applied it, so the next polls compare what it runs with what is wanted. |
| 503 | The slice is unreachable, could not be read just before the send, did not finish start-up, or is not in use. |
| 504 | The controller did not start the action within 30 seconds, or started it and did not finish within 30 more. |
Any endpoint can also answer 401 when you are not signed in, 403 when the
Origin check fails or, on a server with no password, when the request is
not addressed to a loopback name, 413 when the request body is over 64 KiB,
and 429 when another password check from the same address is running or
another client’s check did not finish in time.
The other endpoints use the same codes for the same kinds of problem: 404 for an unknown device or run, 409 for an action that does not fit the current state (such as starting a run while one records), 422 for a bad value, 502 when an EZO circuit refuses a command or does not answer, 503 when the database or the controller cannot be used, and 504 for a timeout.
Serving on the lab network
Section titled “Serving on the lab network”Without server.password_hash, serve listens only on a loopback address,
and it answers only requests addressed to localhost, 127.0.0.1 or
[::1].
To serve the lab network:
-
Make a password hash, and paste it into the configuration:
Terminal window openreactor hash-password[server]host = "0.0.0.0"password_hash = "scrypt$32768$8$1$..." -
Start
openreactor serveagain. -
Open
http://<pi>:8080/from another machine, and sign in.
Plain HTTP carries the password and the session cookie unencrypted. Use it only on a lab network you trust, or put a TLS proxy in front of openreactor.
The proxy must run on the same machine, keep the original Host header, and
send X-Forwarded-Proto. Otherwise browser sign-in fails its Origin check.
Never put a proxy in front of a server that has no password. Such a server trusts every request that reaches it under a loopback host name, and a proxy on the same machine sends exactly those.
Signing in
Section titled “Signing in”A browser signs in with the password on the sign-in page, which posts to
POST /login, and gets a session cookie. The session lasts until
POST /logout, 12 hours, or a server restart.
A script sends the password on each request instead:
curl -s -H 'Authorization: Bearer <password>' http://<pi>:8080/api/v1/statusopenreactor checks one password at a time. Each client address has at most one check in progress: a second guess from the same address gets 429 at once, and other clients wait up to 2 seconds for their turn.
A request that changes something is refused if its Origin header names
another site. A browser request signed in by cookie must carry an Origin
header.
