Cookbook · example 4

Reflux on a stirrer hotplate

Add a hotplate from the community registry, read its safety card, then bring a flask to 80 °C, hold for a while, and cool down. This example shows how an instrument gets into the lab and how limits protect you, using the IKA C-MAG HS 7 package's simulated twin.

You need: the setup from the cookbook front page, and git on your machine (the registry pulls packages from GitHub). About ten minutes.

  1. Ask whether a package exists

    Is there a package for the IKA C-MAG hotplate?

    The agent calls mhp_lab op="registry" and finds ika-c-mag-hs7: a serial driver using IKA's command set, with a simulated twin.

  2. Add the simulated twin

    Add its simulated twin so I can try it.

    The agent calls mhp_lab op="add" target="github:kushalsinha/openmhp/packages/ika-c-mag-hs7" sim=true. It clones the package and registers it as ika-c-mag-hs7-01-sim. Ask "what instruments do I have?" and the hotplate is now in the list, tagged simulated.

    For a real instrument the agent also asks where it stands, because a shared package cannot know, and records it with mhp_lab op="location" id="ika-c-mag-hs7-01" location="fume hood 2". That is what "find me an idle hotplate in hood 2" searches on later. A simulated twin stands nowhere and is labelled simulated.

  3. Read the safety card

    Is it safe to let you use the hotplate?

    The agent calls mhp_lab op="safety_card" and reads it to you:

    SAFETY CARD: ika-c-mag-hs7-01 (IKA C-MAG HS 7)

Limits the driver enforces (values are also type-checked):
  - target_temperature: 20 to 300 degC  (the instrument allows 500; this package caps at 300 for glassware)
  - stir_rpm: 0 to 1500 rpm
Actions and their gates:
  - start_heating, stop_heating, start_stirring, stop_stirring: no gate
  - shutdown: a person must confirm each time
Emergency stop: declared (sends STOP_1 and STOP_4, heater and stirrer off); not exercised by this card
Watchdog: 30 s while a client holds a lease; not exercised by this card
Probes (dry runs; nothing was actuated):
  - write target_temperature above-max: refused as expected: 301 above max 300
  - write target_temperature wrong-type: refused as expected: expected number, got str
  - write stir_rpm above-max: refused as expected: 1501 above max 1500
  - invoke shutdown: passes the gates once a person confirms

RESULT: no configuration errors found. Setting probes refused as expected: 6 of 6.
Not checked: emergency-stop behaviour, watchdog expiry, physical behaviour.
The owner must review this card; it is not a safety certification.

  4. Ask for the reflux

    Reflux the flask on the hotplate at 80 degrees for 2 minutes, stirring at 400 rpm, then cool it to room temperature.

    Two minutes stands in for an hour so you can watch the whole thing.

  5. The agent shows the plan

    It reads the hotplate's operating procedure (stir first, then heat), picks the timed-hold recipe for the hold, and rehearses:

    Plan
 1  ika-c-mag-hs7-01-sim  set stir_rpm = 400           ok
 2  ika-c-mag-hs7-01-sim  start_stirring               ok
 3  ika-c-mag-hs7-01-sim  set target_temperature = 80  ok
 4  ika-c-mag-hs7-01-sim  start_heating                ok
 5  ika-c-mag-hs7-01-sim  read plate_temperature until within 0.5 of 80
 6  hold 2 min, logging plate_temperature every 10 s
 7  ika-c-mag-hs7-01-sim  set target_temperature = 22  ok
 8  ika-c-mag-hs7-01-sim  stop_heating                 ok
 9  ika-c-mag-hs7-01-sim  stop_stirring                ok
Verdict: ok; no human confirmation needed. Run it?

  6. Say go

    Yes.

    The simulated plate warms at a few degrees a second, holds, and cools. The agent reports:

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

  7. See a refusal

    Set the hotplate to 350 degrees.

    The agent tries mhp_write and the driver refuses: target_temperature=350 above max 300. The agent tells you the limit and does not try another way. The refusal is in the run log.

  8. Try the confirmation gate

    Shut the hotplate down.

    shutdown needs a person's yes because the plate stays hot. You get the confirmation prompt; say yes and it runs.

Doing it on the real hotplate

  1. Add the package without sim: "add the IKA package". The agent asks which USB port it is on (/dev/ttyUSB0, /dev/tty.usbserial-… or COM3) and where it sits, and fills those in.
  2. A different hotplate with no package: say "onboard my hotplate". If it has a USB cable and a command table in the manual, the interview produces a serial driver; if not, a hand-operated one, where the agent tells the operator what to set and records what they read.
  3. Use real times: "hold for an hour". The run goes to the background and you ask for the result later.