How it works
Autotune
The server's autotune: a relay experiment, a fitted model of the roaster, and PI gains designed from it.
Autotune measures how your roaster responds to its heater, then suggests PID gains: the numbers the roaster's temperature control (auto mode, or a profile driving BT) uses to chase a setpoint. Good gains follow a profile closely without the heater hunting. The server runs the test, so it works on any roaster that takes a heater % and reports BT, the virtual roaster included.
When to run one
- Once for each fan speed you roast at, near the bean temperature that fan is used at in a roast (below first crack). Two or three tests cover a roast; the gain schedule fills in between.
- When the roaster changes: a new heater, sensor, or firmware that reads the sensor differently.
- When BT overshoots, lags behind a profile, or the heater swings in big jumps.
Running a test
Roasters → the roaster → Autotune. It needs the Tuning module (Settings → Modules) and a roaster with control set to full (roaster setup). No roast or profile drive may be running on it.
- Load beans as for a roast (old or junk beans are fine).
- Set Test at bean temperature and Fan. The fan is set before the test starts and stays there; it cannot go below the roaster's fan floor.
- Click Start autotune.
The test goes through three phases, shown with a live chart:
| Phase | What happens |
|---|---|
| Heating to the test level | full heater until BT reaches the level. If the roaster cannot get there at this fan, the test runs where BT levels off, and says so |
| Finding the holding power | the heater switches above and below the level until it finds the heater % that holds it |
| Measuring the response | the heater swings unevenly around that power, while every sample is recorded |
It takes about 5 minutes after the heat-up. The roaster stays in manual under a control lease: if the server goes quiet, the roaster cuts its own heater. The test stops by itself if BT goes 20 °C over the level, a phase stalls, the roaster stops sending, a roast or a drive starts, or it runs 45 minutes. Stop the test ends it at any time. At the end the heater goes off and the fan stays where it is, so the beans cool as after a roast. You can close the page: the test carries on, and opening the page again picks it up.
Advanced holds Heat-up power, Largest heater swing, Asymmetry and the switching band. The defaults suit most roasters.
Reading the result
The result opens with a quality badge, Good, Acceptable or Poor, and any warnings. A poor result cannot be applied. The common warnings:
- The holding power moved during the test: the roaster was still warming up, or the beans were drying. Start the test with the roaster warm.
- The best model leaves the sensor's noise unexplained: the roaster changed during the test. Run it again warm.
- The process could not reach the level asked: the heater could not get BT there at this fan, so the test ran where BT levelled off. Ask for a lower level, or test with less fan.
Then a sentence on what the roaster acts like near the test level, and a chart of the measured BT against the model: where the dashed model follows BT, the designs can be trusted.
Below it you pick a design:
| Field | What it means |
|---|---|
| Rule | SIMC PI (recommended), AMIGO PI (conservative), and two classic rules for comparison |
| Tight ↔ Smooth | how fast the loop is asked to be. Tight follows the profile closest and moves the heater most; smooth is calmer and copes better with more beans or another fan. 1.5 is a good start |
| Kp, Ki | the gains. The test designs PI only (no D term) |
| Ms | the safety margin: 1.2–1.4 robust, up to 1.8 balanced. Above 1.8 it warns; above 2.0 it cannot be applied |
| Margins | gain margin, phase margin and delay margin |
| Heater jitter | how much the heater moves from the sensor's noise alone |
| Ramp lag | how far BT trails a 10 °C/min ramp. A profile drive's lookahead closes most of it |
| If the roaster changes | Ms if the roaster's gain or its dead time doubles |
All designs lists every rule side by side.
Using the result
- Add to schedule at N % fan adds the gains as a row of the gain schedule (Roasters → the roaster → Control → Gain schedule by fan). With the schedule on, the roaster's gains follow the fan: yours, a profile's or fan assist's, blended between rows.
- Store on the roaster sends the gains to the roaster as its stored gains, used when no schedule is on.
Tuning history, under the test, lists every run and every change to the stored gains, and Undo last change restores the gains before it.
From the command line, roast roaster tuning <roaster> shows the gains, the schedule and the
runs; --run <id> reads one run's result in words, and --tau-c or --rule preview another
design. Starting a test has no command of its own: it drives the heater, so you start it
from the dashboard.