Skip to content

Getting started

Installation

pip install anywidget-instruments-industrial            # when released (see below to install from source)
pip install "anywidget-instruments-industrial[units]"   # + pint support

From a clone of the repository:

npm install && npm run build   # bundle the front end
pip install -e ".[dev]"

Common API

Every widget derives from InstrumentWidget and exposes:

Trait Meaning
value current state (synchronized)
mode "control" (user input) or "indicator" (display only)
label, tooltip plain text (never interpreted as HTML)
disabled, visible greyed + input rejected / hidden
size (width, height) in CSS pixels
style "modern", "classic" or "system" (follows the host theme)
skin optional SVG parts: background, housing, knob, needle

Callbacks: widget.on_change(callback) (also as a decorator, optionally with names=) or the traitlets observe API. Exceptions raised by callbacks are logged and never break the widget. ai.batch() groups updates; callbacks of an EmergencyStop run first.

Numeric widgets

min, max, step, unit, scale (linear/log), ticks, minor_ticks, format (%.2f, %.3e, %.3g, %.3n engineering, %.3s SI prefix; %04X hexadecimal, %016b binary, %o octal for registers, the entry field and keypad then take values in that base), coerce, alarm limits lolo, lo, hi, hihi with deadband and the computed alarm_level, show_limits, engineering scaling raw_min/raw_max/eng_min/eng_max with set_raw(), animate.

p = ai.Gauge(unit="bar", max=10, raw_min=4, raw_max=20, eng_min=0, eng_max=10, hi=8)
p.set_raw(12.0)  # 4-20 mA -> 5 bar
p.value = 9  # -> alarm_level == "hi"

With pint installed, quantities are converted to the widget unit:

import pint

ureg = pint.UnitRegistry()
t = ai.Thermometer(unit="degC")
t.value = ureg.Quantity(300, "kelvin")  # 26.85 °C

Boolean widgets and mechanical actions

mechanical_action is one of switch_when_pressed, switch_when_released, switch_until_released, latch_when_pressed, latch_when_released, latch_until_released. Latched values are consumed by read_latched(); latch_timeout expires unread latches (on_latch_expired).

start = ai.PushButton(text="START", mechanical_action="latch_when_released")
if start.read_latched():
    ...

Two ways to set a value

Every control can be operated in two ways (API-014): directly on its drawing (drag, click, mouse wheel, arrow keys) or through a form entry.

Widget On the drawing Form entry
Numeric controls: Knob, Dial, FillSlide, and every numeric indicator switched to mode="control" (Gauge, Meter, Compass, Tank, Thermometer, VUMeter, SevenSegment, AnalogIndicator) drag the pointer, needle, level or display; wheel; arrow keys value field
SelectorSwitch click a position, arrow keys list of positions
PIDFaceplate drag the SP marker (AUTO) or the OP bar (MAN) SP / OP fields
Valve (control valve, faceplate) position slider position field
Graph cursors drag the cursor cursor position field
Graph axis ranges (CHART-108) zoom box, pan, wheel; double-click resets ↕ Axes: X and Y limits, Apply, Auto
PolarPlot radial range mouse wheel on the plot r max field, Auto
RecipeTable cells an entry field (number or text), a list or a check box per cell
SvgPanel step controls click (Shift+click down), arrow keys an entry field per value

The value field accepts 12.5, 12,5, 1e3, SI prefixes (4.7 k, 250 m) and the widget unit (250 mV for a unit of V). A confirmed entry (Enter, or leaving the field) is snapped to step; a text that is not a number or a value outside [min, max] is rejected with a message giving the range (with coerce=True it is clamped instead) (NUM-010). The kernel applies the same check to every value received from the front end. Escape restores the current value. Set entry=False to hide the field.

Two-state controls (switches, push buttons, emergency stop), whose drawing already is the input, and display-only objects have no form entry.

Keyboard

Controls are operable with the keyboard: arrows (± step), Page Up/Down (± 10 steps), Home/End (min/max), Space/Enter (Boolean controls, faceplates). Host shortcuts (JupyterLab, Notebook 7) are suppressed while a widget has the focus.

Units

import pint

ureg = pint.UnitRegistry()
t = ai.Thermometer(unit="degC")
t.value = ureg.Quantity(300, "kelvin")  # pint quantities are converted (26.85 °C)

Install pint with pip install "anywidget-instruments-industrial[units]".

Styles and theming

style is "modern", "classic" or "system". The system style follows the host colors, including dark mode. ai.set_default_style("classic") changes the default style of the widgets created afterwards. Every color is a CSS custom property scoped to .awi-root (for example --awi-fill, --awi-needle, --awi-alarm-hi), so you can override it per page or per widget.

Light and dark theme

theme is "light" or "dark" (whatever the host theme), "system" (follows the host or the operating system color scheme) or "auto" (the style decides: the "system" style follows the host, the others stay light) (STYLE-007). ai.set_theme("dark") switches every open widget and the ones created afterwards.

ai.theme_switch() returns a three-position switch, ☀ Light · ◐ System · ☾ Dark, shown at the top of every example and demo (STYLE-008). In marimo the whole page follows it; JupyterLab and Notebook 7 keep their own theme setting (Settings ▸ Theme), which the "system" position follows.

ai.theme_switch()  # light / system / dark
ai.set_theme("dark")  # or from code

marimo

import marimo as mo

knob = mo.ui.anywidget(ai.Knob(label="Gain"))
knob  # other cells that read knob.value re-run when it changes

Callbacks (on_change) run after their cell has finished, when marimo has already dropped the cell's private names (those starting with _): refer to the widget through change["owner"] or a public name.

_button = ai.PushButton(text="OUTPUT", mechanical_action="switch_when_pressed", lamp=False)
_button.on_change(lambda change: setattr(change["owner"], "lamp", change["new"]))

Kernel loss

If the kernel is restarted or lost, the widgets show a STALE badge and reject input. A notebook reopened without its kernel shows the saved values as read-only (see Hosts and liveness).