Instruments

Last updated on November 19, 2026

PreviewThis feature is in preview, so its scope and behavior may change. Request access.

Instruments is in preview and is currently not available in the dashboard. Runs already record their instruments, and the API returns them.

An instrument is a physical device a test used: a power supply, a multimeter, a fixture, identified by its maker, model and serial number. Each plug of a procedure opens one, and every run records which one, so a result can always be traced back to the instrument that measured it.

What a run records

Every uploaded run lists the plugs it used, whether the instrument is known to TofuPilot or not. For each plug:

FieldExampleNotes
keypsuThe plug's key in the procedure.
namePower SupplyThe plug's display name.
pythoninstruments.psu:PowerSupplyThe plug class, as written in the procedure.
scopestationslot, execution or station.
manufacturerKeysight TechnologiesFirst field of the *IDN? answer.
modelE36312ASecond field.
serial_numberMY59001234Third field.
firmware2.1.3-1.0.4Fourth field.

The four identity fields are optional: a mock or a relay board reports none and is listed without them. How a plug reports its instrument (an automatic *IDN?, attributes, identify() or the procedure's identity:) is described in Instrument identity.

Two more links tie a run's data to its instruments:

  • Measurements: each phase records the plugs it received. Every measurement of the phase is tied to those instruments.
  • Logs: the lines a plug writes during the run are uploaded with the run's logs, under the plug's key. A run keeps the first 1,000 lines of each plug.

In the dashboard

The Instruments page lists every instrument your runs used, one row per maker, model and serial number. A plug that reported no serial number gets one row per plug key and class. Each row shows the latest firmware, the stations the instrument was used on, its run count and its last use. Search by serial number, model, maker or plug.

The page of an instrument shows:

  • Identity: maker, model, serial number, firmware, plug, class and scope, as of its most recent run.
  • Usage: runs, pass rate, measurements taken and plug warnings over the last 30 days.
  • Measurements: for each measurement taken with the instrument, the count, failures, minimum, mean, maximum and last value, over its 500 most recent runs.
  • Logs: what its plug wrote during its 500 most recent runs, newest first.
  • Firmware history: each firmware version and when it was first seen.
  • Runs: the 100 latest runs that used it, across all procedures.

The run page lists its plugs in a Plugs section, each opening the page of its instrument.

Limits

A few hard limits apply to the plugs of a run.

  • 200 plugs per run, each key unique within the run.
  • Key, name and class: 1-200 characters.
  • Manufacturer, model, serial number and firmware: 1-255 characters.
  • A phase's plug keys and a log line's plug key name one of the run's plugs. A key the run does not list is dropped: the phase or the line is stored without that link, with a warning in the request's API log.

API

Runs created with POST /v2/runs carry their plugs in plugs, each phase its plug_keys and each log line its plug_key. GET /v2/runs/{id} returns plugs. The TofuPilot CLI fills them from the plugs it opened. See the REST API reference for schemas.

create a run with its instruments
curl https://www.tofupilot.app/api/v2/runs \
  -H "Authorization: Bearer $TOFUPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "procedure_id": "<procedure id>",
    "serial_number": "PCB-0001",
    "part_number": "PCB",
    "outcome": "PASS",
    "started_at": "2026-11-13T10:00:00Z",
    "ended_at": "2026-11-13T10:01:00Z",
    "plugs": [
      { "key": "psu", "name": "Power Supply", "scope": "station",
        "manufacturer": "Keysight Technologies", "model": "E36312A",
        "serial_number": "MY59001234", "firmware": "2.1.3" }
    ],
    "phases": [
      { "name": "Power rail", "outcome": "PASS", "plug_keys": ["psu"],
        "started_at": "2026-11-13T10:00:00Z", "ended_at": "2026-11-13T10:00:30Z",
        "measurements": [{ "name": "rail_voltage", "outcome": "PASS", "measured_value": 3.3, "units": "V" }] }
    ]
  }'

OpenHTF runs record their plugs too, when the phases are wrapped in record_plugs.

How is this guide?

On this page