Operator UI

Last updated on November 19, 2026

Operator UI Preview (two components in one phase)
  Text:   Measured Voltage = 3.287 V (lg, green)
  Switch: Power Supply Connected = on
          Help: Confirm the device is connected to the power supply

You can create rich and interactive UIs without any external frontend library to install or skills using TofuPilot Operator UI.

ui:
  components:
    - key: voltage_reading
      type: text
      label: "Measured Voltage"
      default_value: "0.00 V"
      size: xl
      color: lime
    - key: power_connected
      type: switch
      label: "Power Supply Connected"
      bind: measurements.power_status

TofuPilot provides pre-made components to prompt operator input with bindings and display real-time feedback updated directly from your Python phases.

Key

You can identify each component with a unique key field.

main:
  - name: Scan Unit
    python: phases.scan_unit
    ui:
      components:
        - key: serial_number
          type: text_input
          label: "Serial Number"

TofuPilot uses the key to reference components in Python when retrieving input or updating displays. Studio auto-generates keys when adding components, but you must provide them when writing YAML manually.

Type

TofuPilot provides pre-made components you can select using the type field.

main:
  - name: Scan Unit
    python: phases.scan_unit
    ui:
      components:
        - key: serial_number
          type: text_input
          label: "Serial Number"

Each component type has its own configuration options documented in dedicated pages.

Input

Components

You can use input components to collect operator input during test execution. Their choices and limits are declared in the YAML, and a phase can change them while the screen is open, see Update Properties.

Bind to Measurements

You can bind input component values to measurements, unit properties, or the run's operator attribution using the bind field: measurements.<key> records the answer as that measurement, unit.serial_number / unit.part_number route it into the unit, and run.operated_by records it as the run's operator, for example from a badge scanner.

main:
  - name: Scan Unit
    ui:
      components:
        - key: serial_number 
          type: text_input 
          label: "Serial Number" 
          bind: unit.serial_number
        - key: operator_badge
          type: text_input
          label: "Operator Badge"
          bind: run.operated_by
  - name: Read Multimeter
    measurements:
      - name: voltage
    ui:
      components:
        - key: meas_input
          type: number_input 
          label: "Voltage" 
          bind: measurements.voltage

Bindings apply on every surface that answers a prompt: the kiosk, the dashboard, the terminal UI, and headless runs driven with --json or --ui-values. A bound answer is recorded the same way whichever surface sent it.

Display

Components

You can use display components to show real-time information and feedback to operators.

Require Continue

By default, phases with only display components auto-continue without waiting for operator interaction. You can override this with requires_input: true to force a Continue button, even without input components.

main:
  - name: Read Instructions
    ui:
      requires_input: true
      components:
        - key: instructions
          type: text
          label: Instructions
          default_value: "Please verify the test setup before continuing."
          size: lg

This is useful for acknowledgement steps where the operator must read information before proceeding.

Update Display

You can update display components in real-time by assigning values to the ui object.

main:
  - name: Long Running Test
    python: phases.show_progress
    ui:
      components:
        - key: progress
          type: progress
          label: "Test Progress"
          default_value: 0 # Initial value
import time

def show_progress(ui):
    for i in range(0, 101, 10):
        ui.progress = i 
        time.sleep(0.5)

Update Properties

A phase can also change a component's properties, not only its value: the options of a select, the label of a text, the bounds of a number input. The component itself stays what the YAML declared, same key and same type. Call ui.set(key, ...) with the properties to change. Several properties in one call reach the screen together, and None clears a property.

This is how you fill a choice list from your own systems at run time. Declare the component in procedure.yaml without options, fill it from Python, and read the operator's choice in the next phase by naming the first phase as a parameter.

main:
  - key: pick_order
    name: Pick Manufacturing Order
    python: phases.orders:pick_order
    ui:
      components:
        - key: mo
          type: select
          label: "Manufacturing Order"
          required: true
          bind: measurements.mo # The choice is recorded as a measurement
  - key: reserve_order
    name: Reserve Order
    python: phases.orders:reserve_order
    depends_on: [pick_order] # Runs after the operator has chosen
from mes_client import fetch_open_orders, reserve

def pick_order(ui):
    orders = fetch_open_orders()  # Your MES, ERP or database
    ui.set("mo", 
        options=[{"value": str(o.id), "label": o.name} for o in orders], 
        placeholder="Choose an order") 

def reserve_order(pick_order, log):
    mo = pick_order.measurements.mo  # The operator's choice
    reserve(mo)
    log.info(f"Reserved {mo}")

Until the options arrive, the operator sees "Waiting for options". A required choice cannot be submitted while the list is empty. When the list changes, a selection that is still offered stays selected and one that is not is cleared. The answer is checked against the list the phase sent, so a value outside it is refused.

What a phase can set depends on the component:

PropertyComponents
label, descriptionEvery component
placeholderText input, textarea, number input, select, multiselect, radio, checklist, image
optionsSelect, multiselect, radio, checklist, switch
prefix, suffixText input, number input
min, maxNumber input, slider, progress
stepNumber input, slider
min_length, max_length, pattern, pattern_messageText input, textarea

The key, the type, bind, required, the layout and the styling stay in the YAML. Setting a property the component does not have raises an error in the phase before anything reaches the screen. A call the component cannot take as a whole, such as a min above its max or a pattern that does not compile, leaves the screen unchanged and writes an error to the phase log.

An option is a plain string, or a dict with a string value, an optional label (defaults to the value) and an optional image. The same limits as the YAML apply: 200 characters per value or label, 12 options when they carry images.

Stations need CLI 1.7.15 or newer. An older station has no ui.set and refuses to load a choice component declared without options. A component filled at run time cannot be answered with --ui-values: its list is empty when the prompt opens.

Wait for the Operator

A phase can ask the operator while it runs and react to the answer, without splitting into several phases. Call ui.wait(): it blocks until the operator clicks Continue, then returns the answer. Use it when the operator and the phase take turns, such as a calibration where each offset the operator enters is applied to the DUT and the new reading is shown before the next try.

main:
  - key: calibrate
    name: Calibrate Offset
    python: phases.calibrate:calibrate
    ui:
      components:
        - key: offset
          type: number_input
          label: "Offset"
          required: true
          bind: measurements.offset # Records the last answer
        - key: done
          type: switch
          label: "Reading is in tolerance"
        - key: reading
          type: text
          label: "Reading"
def calibrate(ui, dut):
    while True:
        answer = ui.wait()  # Blocks until the operator clicks Continue
        if answer["done"]:
            break  # The operator confirmed the reading on screen
        dut.set_offset(answer["offset"])
        ui.reading = f"{dut.read_voltage():.3f} V"  # Shown on the next screen

The first ui.wait() answers the screen shown at phase start. Each later call shows it again with the operator's last answer and every ui.<key> = or ui.set change made since.

The answer is a dict keyed by component: numbers and sliders come as float, switches as bool, multiselects and checklists as a list, everything else as str. An empty number, select or radio reads None.

A screen with only display components gets a Continue button for each call. Once a phase has called ui.wait(), it ends without a final Continue, and bind records the last answer only.

When the run is stopped, the phase times out or the operator presses Esc in the terminal UI, ui.wait() raises ui.WaitCancelled. Let it propagate: after a timeout the phase has already ended and plug calls are refused. An answer submitted after the phase timed out is dropped and never recorded by bind.

ui.wait() has no timeout argument: the phase timeout bounds the wait.

CallRaisesWhy
ui.wait() in a phase without ui.componentsRuntimeErrorThere is no screen to wait on
ui.wait() from a second thread while another is waitingRuntimeErrorOne phase waits on one screen at a time
ui.wait() when the run, the slot or the prompt is cancelledui.WaitCancelledThe answer can never come

Stations need CLI 1.11.1 or newer, and CLI 1.11.4 for the fixes above (late answers, concurrent waits). The dashboard operator view needs dashboard 2.44.8 to show the Continue of a display-only screen.

Timing

When a phase with operator UI runs:

  1. UI displays immediately to the operator in an expanded phase row
  2. Your Python code runs concurrently and can update component values (ui.<key> = value) and properties (ui.set) in real time, and wait for the operator's answer (ui.wait())
  3. After Python finishes:
    • Phases that called ui.wait() end right away
    • Phases with input components wait for operator to click Continue
    • Phases with only display components continue automatically

In the terminal UI, Esc cancels the prompt of a phase on any screen: the phase ends with the ERROR outcome and the message "The operator cancelled the prompt", and a phase blocked in ui.wait() gets ui.WaitCancelled. On the unit identification form, Esc ends the run.

How is this guide?

On this page