Operator UI

The operator UI is a per-phase component set the runtime renders to the operator. Inputs collect data and block the phase until the operator submits, while displays stream values from Python in real time. The same declaration renders identically in CLI and on a factory Station, so what you build on your laptop is what an operator sees on the floor.

Anatomy

A phase declares its UI under a ui block, and that block holds a list of components plus a few top-level fields.

main:
  - name: Scan Unit
    python: phases.scan_unit
    ui:
      components:
        - key: serial_number
          type: text_input
          label: "Serial Number"
          bind: unit.serial_number
        - key: live_voltage
          type: text
          label: "Live Voltage"
          size: xl

Component fields

Every component supports the base fields below, so you can lean on them before reaching for type-specific knobs.

Type-specific fields are documented in each component section below.

Catalog

Inputs block phase completion until the operator submits a value that passes validation, while displays update in real time when Python assigns ui.<key> = value.

Inputs

text_input

A single-line text field with optional validation. The value type is string.

- key: serial_number
  type: text_input
  label: "Serial Number"
  pattern: "^SN-[0-9]{8}$"
  required: true

textarea

A multi-line text field with the same constraints as text_input plus a rows field for visible height.

- key: notes
  type: textarea
  label: "Operator Notes"
  rows: 4
  max_length: 500
  required: false

number_input

A numeric field with stepper buttons. The value type is number.

The operator must enter a number between min and max inclusive and a multiple of step, because the field validates on submit.

- key: target_voltage
  type: number_input
  label: "Target Voltage"
  min: 0
  max: 12
  step: 0.1
  suffix: "V"

slider

A numeric input with a draggable handle and visible min/max labels. The value type is number.

- key: torque
  type: slider
  label: "Torque"
  min: 0
  max: 10
  step: 0.5

switch

A boolean toggle. The value type is boolean, and when required: true the operator must explicitly flip the switch because the initial unset state fails validation.

- key: cover_closed
  type: switch
  label: "Cover Closed"
  required: true

radio

A single selection from a vertical list. The value type is string, and it requires options.

- key: outcome
  type: radio
  label: "Visual Inspection"
  required: true
  options:
    - { label: "Pass", value: pass }
    - { label: "Cosmetic defect", value: cosmetic }
    - { label: "Fail", value: fail }

select

A single selection from a dropdown. The value type is string, and it requires options.

- key: line
  type: select
  label: "Production Line"
  placeholder: "Choose a line"
  options:
    - { label: "Line A", value: a }
    - { label: "Line B", value: b }

checklist

Multiple selections rendered as checkboxes. The value type is string[], and it requires options.

When required: true, the operator must select at least one item.

- key: pre_flight
  type: checklist
  label: "Pre-flight Checks"
  required: true
  options:
    - { label: "Power supply connected", value: power }
    - { label: "USB cable seated", value: usb }
    - { label: "Antenna installed", value: antenna }

multiselect

Multiple selections from a dropdown. The value type is string[], it requires options, and you reach for it over checklist when you have many options or limited vertical space.

- key: defects
  type: multiselect
  label: "Observed Defects"
  required: false
  options:
    - { label: "Scratch", value: scratch }
    - { label: "Dent", value: dent }
    - { label: "Missing label", value: label }

image_choice

A single selection from a grid of image cards. The value type is string, and each option carries an image field that accepts a relative path or a data URI.

- key: cable_type
  type: image_choice
  label: "Cable Type"
  required: true
  options:
    - { label: "FFC", value: ffc, image: "./images/cable-ffc.jpg" }
    - { label: "Ribbon", value: ribbon, image: "./images/cable-ribbon.jpg" }
    - { label: "Harness", value: harness, image: "./images/cable-harness.jpg" }

image_checklist

Multiple selections from a grid of image cards. The fields match image_choice, and the value type is string[].

- key: defects
  type: image_checklist
  label: "Tick all defects you see"
  required: false
  options:
    - { label: "Scratch", value: scratch, image: "./images/scratch.svg" }
    - { label: "Dent", value: dent, image: "./images/dent.svg" }
    - { label: "Looks OK", value: ok, image: "./images/ok.svg" }

Displays

Displays do not gate phase completion, so you assign ui.<key> = value in the phase function to update them live.

text

Read-only text where the value type is string, and updates re-render immediately on the operator screen.

- key: live_voltage
  type: text
  label: "Live Voltage"
  size: 3xl
  color: lime
  font: monospace

def measure(ui, multimeter):
    ui.live_voltage = f"{multimeter.read():.2f} V"

image

A static or dynamic image where the value type is string (relative path or data URI). Assign a new path or data URI from Python to swap the image in place.

- key: reference
  type: image
  default_value: "./images/reference.png"
  width: "80%"
  aspect: "16/9"
  fit: contain

progress

A progress bar where the value type is number, which is useful for long-running phases like firmware flashing where you want the operator to see steady forward motion.

def flash_firmware(ui, programmer):
    for percent in programmer.flash():
        ui.progress = percent

Binding

Inputs can bind their value to a Measurement or a unit field, so bound values appear on the Run automatically and you do not need to assign them from Python.

- key: voltage
  type: number_input
  bind: measurements.voltage
- key: serial
  type: text_input
  bind: unit.serial_number

Require continue

Phases with only display components auto-continue once their Python body returns, so you set requires_input when you want to force a Continue button anyway (for example, when the operator has to read a briefing before moving on).

ui:
  requires_input: true
  components:
    - key: briefing
      type: text
      label: "Read before continuing"
      default_value: "Disconnect power before opening the enclosure."