How it works

Control

Where the bean temperature loop runs, the device contract, leases and the safe state, approvals.

How Roastwarden controls a roaster: what you can set by hand, how the bean temperature is held, what stops the heater when something goes wrong, and what scripts and agents may do. The server runs the roast (profiles, Profile drive, alarms, fan assist, the roast sequence); the roaster measures, switches its heater and fan, and keeps itself safe when the server is gone.

How much control a roaster gets

Each roaster has a control level, set under Roasters → the roaster → Control → Control (roaster setup):

A command the level does not allow is refused. Features that need more than the level quietly skip the roaster (the roast sequence, fan assist) or refuse to start (Profile drive, autotune). A heater or fan % is kept to the output's range, and while the heater is on, a fan below the roaster's fan floor is raised to it.

The Control tab

On the Roast page, the Control tab holds the roaster's controls:

• Manual / Auto (PID). In Manual you set the heater % and the setpoint is not used. In Auto the roaster's PID moves the heater to hold BT at the setpoint; the heater slider shows what the PID does. Switching to Auto starts the PID from the current heater, so there is no jump.
• Setpoint: the BT the PID holds in Auto.
• Fan and Heater sliders, in %.
• Power: heater power, the master switch. Off cuts the heater in any mode. Drop and completing the roast switch it off for you.
• Advanced: PID gains: Kp, Ki and Kd, and Apply gains now. With the gain schedule on, the next fan change replaces them.

While a profile drives, touching the setpoint, heater, fan or mode pauses that channel only.

Where the PID runs

During Profile drive, the loop that holds BT runs in one place, set by PID runs:

• On the roaster: the roaster runs its own PID and the server sends the setpoint once a second. The loop runs next to the heater, at the sensor's rate, and is not bothered by Wi-Fi delays. Best when the roaster has a PID.
• On the server: the server runs the PID once a second and sends heater %. It works with any roaster that takes a heater %: a TC4, Modbus I/O.
• Auto (the default) picks the roaster when it can.

The server keeps the PID gains. If the roaster reboots and comes up with other gains, the server sends its own back.

Emergency stop and safety

The red STOP button in the header shows while the selected roaster has something to stop. It switches heater power off, sets the heater to 0 % and sends the roaster's emergency stop: heater off, fan to full. Once the roaster has cooled, the button becomes Fan off.

A roaster must keep itself safe without the server. Its own firmware has to cut the heater on an over-temperature, a failed thermocouple, too little airflow, or a lost connection (hardware integration guide). On a roaster with a control lease, Profile drive renews the lease every 3 s; if the server goes quiet, the roaster cuts its heater after 10 s and goes to its safe state (heater off, fan to full). The drive also stops when the roaster's readings stop coming.

Roasters → the roaster → Overview → Device contract shows what the roaster reports: its firmware, whether its readings have BT, ET, heater and fan, what it supports, and whether its PID gains match the ones the server holds. roast roaster contract <roaster> gives the same.

Scripts and agents

The owner key, and a browser signed in with it, may control any roaster its level allows. API tokens (Settings → Tokens) have a preset (Read-only, Roast, Inventory, Admin) and an expiry, and are held back from real hardware:

• Tokens may control this roaster (Roasters → the roaster → Control) is off for every physical roaster until you switch it on; only the owner key can. While it is off, a token may read the roaster but not command it, start or change its roasts, or change its tuning. It may still fill in a finished roast's record: weights, landmarks, cupping. The virtual roaster is always open to tokens, for practice.
• Ask first (on by default for a new token) holds some calls for your approval: starting a roast on a physical roaster, and deletes. A label print and switching a roaster's control on always wait for you, whatever the token. The request goes out through your notification channels and waits an hour under Settings → Approvals, where you Approve or Deny it. An agent can never approve its own request.
• Settings → Audit lists every change made through the API, who made it and whether it was refused, kept for a year.

Live control (heater, fan, setpoint, mode, stop) has no roast command on purpose: it is for the person at the roaster. roast audit reads the audit log and roast approval <id> --wait waits for an answer (the roast CLI).