Draft an instrument control script from its programming manual

A test engineer bringing up step 3 of a production test spec needs a script for the electronic load: set it to constant current, enable it, read the board back, disable it. The commands are in the load’s own programming manual, a PDF of tables and a worked example, and writing them by hand means paging through it for every keyword, every unit, every argument order. That’s the job: turn a manual into a script, for one instrument, without hand-typing every line.

The walkthrough below is a production test step, because that is the script this bench’s manual prints a worked example for. The same loop is worth more at low volume: a one-off characterization script runs five times, has no golden run to be checked against, and costs a person their afternoon if it is wrong. Volume changes the economics, not the level and not one of the four steps below.

The trap is that this bench has two instrument vendors whose SCPI dialects disagree. Maridun Instruments’ supply and meter accept VOLTage or VOLT and ON or 1, and answer a query with a bare number. Tarnley Test Systems’ load and scope take the short keyword and 1/0 only, and answer with a unit stuck to the number: 1.0000A. An engineer who has just written the supply’s script types CURRent and INP ON out of habit, and the load takes neither.

Walking a draft through the bench

No recorded trace exists for this page; docs/EVALS.md explains why. The numbers below come from running the example on StubModel, scripted to make exactly the mistake a Maridun-trained habit makes, against run.TASK: set the load to 1.000 A, enable it, read it back, disable it.

Draft 1, sent to a scratch TRN-2400 with no board wired to it at all:

MODE CC CURRent 1.000 INP ON MEAS:VOLT? MEAS:CURR? INP OFF

CURRent is the Maridun long form; Tarnley firmware takes the short form only and answers with -113,"Undefined header". INP ON and INP OFF are the Maridun boolean words; Tarnley wants 1 and 0 and answers both with -224,"Illegal parameter value". Both come back only when the script asks SYST:ERR?, not as anything that looks like a crash.

Draft 2, after the two exact SYST:ERR? lines go back to the model and nothing else:

MODE CC CURR 1.000 INP 1 MEAS:VOLT? MEAS:CURR? INP 0

Clean. Now, and only now, code runs it for real: the supply brings the board to 24.000 V with a 4.000 A current limit approved by the test engineer, CURR 1.000 is checked against SafetyEnvelope before it is sent, INP 1 needs its own matching approval, and the load reads back 4.9930V and 1.0000A. Those are not invented numbers: they are what the DUT model in examples/common/bench.py computes at 24 V in, 1.000 A out, and they match the load manual’s own worked example exactly, because both describe the same board. Neither went through the model. It drafted the commands that took them, and that is where its output stops: a model never produces a reported measurement, an uncertainty, a margin or a verdict.

What it costs

Illustrative, not measured: no result file exists for this technique yet, so every number below is a worked example. See docs/EVALS.md for how a real run is recorded and scored.

Those are the illustrative run’s own numbers, counted by examples/common/model.py’s count_tokens estimate rather than a provider’s real tokenizer. It is a per-script cost in both settings, and the reader’s own unit decides which line matters.

Per unit, in production: zero. Once a draft runs clean, running it against the next board and all 50 a day costs no model call at all, so the model is paid for once and the comparison is against the seconds the test step itself takes.

Per session, at low volume: those same 1,575 tokens are the whole model cost of the afternoon, because a characterization script runs five times and there is nothing to amortize over. The comparison is against the hour of manual-paging the draft replaced, and against the afternoon lost if the draft was wrong. That second cost is larger here, not smaller: in production a wrong keyword is caught by the golden run, and at five runs there is no golden run, so step 2 above is the only thing between a Maridun habit and a wasted afternoon.

How this fails on a real bench

How to evaluate it

Whether a drafted script is acceptable is a pass or fail a simulator already computes, never a model’s opinion of its own work: did it run clean within the revision cap, and once run for real, did the reading land where the DUT model says it should. In production there is a set to collect: one drafting task per test step per instrument, eight steps across four manuals, each with a known-good script as the answer key, scored on how many converge within the cap and how many revisions each took. A script that never converges is not a partial credit case; it is the “Stop: revision cap reached” step in the trace, and it means a person looks at the manual next, not the model again.

At low volume that set does not exist: one script, no answer key. The check to do first costs nothing and is mechanical. Every command in the final script appears in the instrument’s own command table, and every reading lands where the datasheet says. A script that runs clean and measures the wrong node is the failure no simulator catches, in either setting.

Adapting it to your own instrument

Every instrument on this bench is one send(command: str) -> str method, the shape PyVISA’s write and query pair covers, so the command-checking and revision-loop code above does not change; only the transport underneath send does. Nothing here has been run against real hardware, and this page does not claim it has.

What does not port: the TRN-2400’s own command table, its two dialect quirks, and the DUT model that makes 4.9930V the right answer at 24 V and 1.000 A. Your instrument has its own manual and your board has its own datasheet, and checking a drafted command against those, not against this one, is the entire lesson.

The shape is draft, check, revise against a fixed rule, and it shows up anywhere a draft has to meet a standard that code, not a person’s read of the draft, can check: code checked against its own tests, a SQL query checked against the schema it queries, a report checked against a required template. What is unusual about an instrument script is only that a rejected command can reach a mains-powered board, which is why the fourth step, here, is a person and not another check.

Design choices

Build it

def _check_against_manual(commands: list[str], tracer: Tracer) -> list[tuple[str, str]]:
    """Try a draft against a scratch TRN-2400: unwired, no board, safe to send anything.

    This is the documented command set for the instrument, not a copy of it: `ElectronicLoad`
    accepts exactly what `trn2400-programming-manual.md` documents and rejects everything else,
    so a command the manual does not support fails here the same way it would on the real load.
    """
    scratch = ElectronicLoad()
    errors: list[tuple[str, str]] = []
    for command in commands:
        scratch.send(command)
        error = scratch.send("SYST:ERR?")
        if error != NO_ERROR:
            errors.append((command, error))
    detail = "clean" if not errors else "; ".join(f"{c!r} -> {e}" for c, e in errors)
    tracer.record(
        kind="code", decided_by="code",
        title="Check commands against the documented command set", detail=detail,
    )
    return errors

def _enable_load(load: GuardedLoad, approval: Approval) -> None:
    """Enable the TRN-2400's input: the one command in this script that puts current through the
    board, and so the one command a person has to have approved.

    The gate itself is `GuardedLoad.input_on` in `examples/common/bench.py`, next to the identical
    one `GuardedSupply.output_on` puts in front of `OUTP ON`. It refuses an enable with no
    `Approval`, one that names a rail or a current the bench is not actually at, and one that has
    already been spent, and it re-checks the load's own set point against `SafetyEnvelope` on the
    way through. This recipe adds nothing of its own to that; it names the step, because a reader
    following the drafted script needs to see where the model's line stops being the model's.
    """
    load.input_on(approval)

def parse_reading(reply: str) -> float:
    """Parse one numeric reply, Maridun's bare or Tarnley's suffixed (`"1.0000A"` -> `1.0000`).

    `float()` is tried first, which is the correct parse for a Maridun reply and the good failure
    for a Tarnley one: it raises rather than silently returning a wrong number, which is what
    slicing a fixed number of characters off the reply would do instead.
    """
    try:
        return float(reply)
    except ValueError:
        return float(_UNIT_SUFFIX_RE.sub("", reply))