Cookbook · no-code instrument

Reflux on a stirrer hotplate

Bring a flask to 80 °C, hold it for an hour while logging the plate temperature, then cool to room temperature and switch off. The hotplate is either operated by a person or connected by a USB cable; neither needs code.

Instruments

Role	Simulated twin	Real
Stirrer hotplate	`ika-c-mag-hs7-01-sim`, added with `mhp_lab op="add" target="github:kushalsinha/openmhp/packages/ika-c-mag-hs7" sim=true`	the same package with the USB port set, or any hotplate onboarded by interview as `serial` or `manual`

Getting the hotplate in

Two sentences. "Is there a package for the IKA C-MAG?" The agent searches the registry, adds the package, and asks you for the port and where it sits. Or, for any other model: "Onboard my hotplate." The interview asks how it is controlled; "by hand" gives a manual driver, "USB cable" gives a serial driver whose commands you paste from the manual. Either way the agent reads you a safety card at the end:

SAFETY CARD: ika-c-mag-hs7-01 (IKA C-MAG HS 7, fume hood 2)
Limits the driver enforces:
  - target_temperature: 20 to 300 degC  (Plate setpoint. The instrument allows up to 500; this package caps at 300 for glassware.)
  - stir_rpm: 0 to 1500 rpm
Actions and their gates:
  - start_heating: no gate
  - shutdown: human must confirm each time
Emergency stop: yes, E-stop sends STOP_1 and STOP_4 (heater and stirrer off).
Watchdog: 30 s
Probes (nothing was actuated):
  - write target_temperature 301: refused: target_temperature=301 above max 300
VERDICT: ready for agent use once the owner signs off

What you say

"Reflux the flask on the hood hotplate at 80 degrees for an hour, stirring at 400, then cool it down and shut off."

The plan

mhp_run recipe="timed-hold" plan=true
        params={"device": "ika-c-mag-hs7-01", "setting": "target_temperature", "signal": "plate_temperature",
                "setpoint": 80, "hold_minutes": 60, "log_every_s": 60, "safe_setpoint": 22}

verdict: ok; no human confirmation needed
 1  ika-c-mag-hs7-01  write  target_temperature = 80   ok
 2  ika-c-mag-hs7-01  read   plate_temperature
 ...
 n  ika-c-mag-hs7-01  write  target_temperature = 22   ok

The recipe holds the temperature and logs; stirring and heater enable are two extra calls the agent adds before it, from the package's operating procedure: stir_rpm 400, start_stirring, start_heating. If it also wants to invoke shutdown at the end, that step is marked asks human, because the package says the plate stays hot.

On a hand-operated hotplate

With a manual driver the same recipe produces instructions instead of commands. The agent tells the operator "set the target to 80 and start heating", asks them to read the plate display every minute (or as often as they can), records each reading with the record action, and at the end asks them to set 22 and switch off. The safety limits, the plan and the run log are identical; only the hands differ.

What comes back

held 80 for 60 min; readings in readings.csv; now 22.4

Variations

Ramp instead of step. Copy the recipe and write setpoints in a loop with a delay.
A circulator or oil bath. Same recipe; the setting and signal names come from that package.
Raise the cap. The 300 °C limit lives in the package's descriptor. Changing it is a code review, not something an agent can do at run time.