How-to guides › Model user interfaces

How-to guides

The product's user interface

A product often has a screen: a dashboard in a car, a touch panel on a machine, a small display on a sensor. In arche-lang you describe that screen in the model, next to what it shows. The component that owns the display gets a ui { } block. Each gauge, label and button in it is bound to the model: a variable, a message the part receives, or the state of a part beside it. When the model changes, archec tells you what the screen no longer matches.

This page is a guide. Every word and property is in the language reference. archec explain ui lists the checks.

A first screen#

component Dashboard "Driver display" {
  in bus:     data receives STATUS, BRAKE_FAULT
  out cmd:    data sends ENGAGE_REQ, STOP
  var lights: bool = false

  ui {
    display 800x480
    input touch
    theme dark

    screen Driving "Driving" {
      row {
        gauge speedo "Speed" { value bus.STATUS.speed }
        label mode { text "Mode: ${ctrl.state}" }
      }
      row {
        button engage "Engage" { enabled ctrl.state == Ready; on press send cmd ENGAGE_REQ(true) }
        button stop "Stop" { style danger; on press send cmd STOP(true) }
        button settings "Settings" { on press goto Settings }
      }
    }

    screen Settings "Settings" {
      toggle lights "Lights" { value lights }
      button done "Done" { on press back }
    }

    overlay Warnings {
      telltale brake "Brake fault" { on bus.BRAKE_FAULT; color amber }
    }
  }
}

Read it from the top:

  • The device: display 800x480 (in pixels), input touch (or encoder, keys, pointer), theme dark (or light). With dpi 160, archec can check that buttons are big enough for a finger. With no display, archec takes the display of the board the part is built on (its hardware { display … }).
  • Screens: what the display shows at one time. The UI starts on the first one, or on the one initial Settings names. goto Settings and back move between them. A dialog is shown over the current screen until it is left. An overlay is shown over every screen, so it is the place for warnings.
  • Layout: row (side by side), column (one under the other), grid (columns 3), stack (on top of each other), spacer (empty space). The direct children of a screen form a column. gap, padding, align, grow, width and height adjust the layout.
  • Elements: label, gauge, bar, chart, telltale, image, list, table, button, toggle, slider, select, input, stepper, and custom for one you draw yourself. The name after the word (speedo) is optional. The "Text" after it is what the element says.

These words are words only inside ui { }. Anywhere else, label, button or row are ordinary names: a part called label still works.

Try it#

The dashboard needs a model around it: the messages it reads and sends, and the controller it talks to. Put this in main.arche, followed by the Dashboard above:

message STATUS { speed: float32 unit km/h range 0..200; distance: float32 unit m }
message BRAKE_FAULT: bool
message ENGAGE_REQ: bool
message STOP { hard: bool }

component Ctrl "Controller" {
  in cmd: data receives ENGAGE_REQ, STOP
  out st: data sends STATUS, BRAKE_FAULT
  states {
    state Idle
    state Ready
    Idle -> Ready on ENGAGE_REQ
    Ready -> Idle on STOP
  }
}

system Car "Car" {
  part ctrl: Ctrl
  part dash: Dashboard
  dash.cmd -> ctrl.cmd
  ctrl.st -> dash.bus
}

archec check main.arche prints ✓ no errors. Then list the screens:

archec ui main.arche
Dashboard (Car.dash) — 800×480, touch, dark
  screen Driving "Driving"  ← start ~306×267
    row
      gauge speedo "Speed"  value bus.STATUS.speed : a float km/h · 0..200 km/h
      label mode "Mode: ${ctrl.state}"
    row
      button engage "Engage"  enabled ctrl.state == Ready : a bool
        on press: send cmd ENGAGE_REQ(true)
      button stop "Stop"
        on press: send cmd STOP(hard: true)
      button settings "Settings"
        on press: goto Settings
  screen Settings "Settings" ~149×128
    toggle lights "Lights"  value lights : a bool
    button done "Done"
      on press: back
  overlay Warnings ~177×72
    telltale brake "Brake fault"  on bus.BRAKE_FAULT : a bool
  navigation: Driving → Settings, Settings → back
  reads: bus.STATUS.speed (message-field), ctrl.state (part-state), lights (var), bus.BRAKE_FAULT (message)

Each element shows what it reads, with its type, unit and range from the model. To see the screens drawn, write a page:

archec ui preview main.arche
✓ screens.html — 2 screens with sample values; click an element to see where it is written

What an element shows: bindings#

value, enabled, visible and a telltale's on take an expression of the action language. It is the same language that ```arche bodies use. The names in the expression are what the display's part knows:

You write It is
lights a variable of the part
state the part's own state
bus.STATUS.speed the last STATUS received on port bus, its field speed
bus.BRAKE_FAULT the last value of a message that is one value (message BRAKE_FAULT : bool)
ctrl.state, ctrl.speed the state, or a variable, of a part beside it in the system. The preview and the simulator read them from the model; a real product gets them as messages.
MAX_SPEED a constant
DriveMode.MANUAL an enum value
page a variable of the ui
env.width, env.theme the device

A state is compared by its name: ctrl.state == Ready. A text says values with ${…}: text "Obstacle ${bus.STATUS.distance} m".

archec knows each value's type, unit and range from the model. A gauge on bus.STATUS.speed (a float32 unit km/h range 0..200) takes its unit and its range from it. If the gauge says unit mph, archec reports it (ui-binding). It also reports a toggle bound to a number, and a name the part does not have.

A toggle, slider, select, input or stepper bound to a variable of its own part sets that variable when it changes. To do something else, write on change …. In it, value is the new value.

The ui's own state, and the device#

Which page of a screen is open, a text being typed: that is the display's business, no other part needs it. A var written in the ui is the ui's own:

ui {
  var page = "Vehicle"
  screen Details "Vehicle" {
    select show "Show" { options "Vehicle", "Steering"; value page }
    bar accel "Acceleration" { value adcu.accel; visible page == "Vehicle" }
    label health { text "Steering: ${steering.health}"; visible page == "Steering" }
  }
}
  • A binding reads it, a control bound to it sets it (value page), an action sets it (page = "Steering"). Its type is written (var n: uint8) or is its first value's; a typed one with no value starts at its zero.
  • It is never sent: no message, no set to the part (the web target's socket), no variable of the part in the simulators, the Arche project or the formal model (archec verify, NuSMV, UPPAAL).
  • Each target keeps it as UI state: a static of ui_<id>.c (a text in a buffer of its own), a property of the Slint global, a property of UiModel that the Qt Quick bridge never sends.
  • Its name is its own: a variable or a port of the part of that name is reported (ui-structure).
  • A preview may set it.

env is the device. It is read like any name, in any binding:

Name Is
env.width, env.height the display's pixels (800×480 when the ui says no size)
env.theme dark or light
env.input touch, encoder, keys or pointer
env.locale the language shown (en when the page chose none)

The first four are fixed per display, so archec works them out at build time: visible env.width < 400 is false on the car's 1280×480 display, and no target reads anything for it. "${env.width}" in a text is text. env.locale follows the language the page shows; the device targets, which write the texts in the model's language, take en.

What a press does: actions#

on press takes action-language statements, on its line or in a block. So do on release, on long-press and on change, and a screen's on enter and on exit:

button stop "Stop" {
  style danger
  on press {
    send cmd STOP(true)
    goto Driving
  }
}
Statement Does
send cmd STOP(true) sends a message on an out port; arguments in field order, or STOP { hard: true }
goto Settings shows another screen (or a dialog)
back goes back to the screen before
lights = not lights sets a variable of the part
if … { … } else { … } decides
reset() calls a function of the part

archec checks that the port sends that message, that the arguments fit its fields, and that the screen exists. It also checks that something receives the message. A press on a port with no link, or to a part that does not receive the message, is reported (ui-dead-press).

Elements of your own#

A screen often shows the same piece again and again: a tyre, a fault line, a setting. Write it once as an element, with typed parameters, and use it like a built-in one:

component Dashboard {
  in bus:     can receives TPMS
  var lights: bool = false

  ui {
    element Tyre(title: string, p: float32) {
      column {
        label { text title; size small }
        gauge g { value p; range 0..4; unit bar }
      }
    }
    element Setting(title: string, on: bind bool) {
      toggle { text title; value on }
    }
    screen Main "Main" {
      row {
        Tyre front("Front", bus.TPMS.front)
        Tyre rear("Rear", bus.TPMS.rear) { grow 1 }
      }
      Setting("Lights", lights)
    }
  }
}
  • Where. In the ui, beside the screens, or at the top of a file. One at the top of a file is for every ui of the project. A UI kit can ship elements too.
  • A use is the element's name, then its arguments in brackets, with no space before them: Tyre("Front", bus.TPMS.front). An argument may be named: Tyre(title: "Front", p: bus.TPMS.front). A use may also say its visible, its place in the layout around it (grow, width, height, align), and the size and color of what it holds.
  • Expanded before the IR. archec replaces each use with what the element holds, its parameters given. The UI model (archec ui --json), the previews, the simulator and the four targets see only built-in elements. They need no code for yours.
  • Names. A use with a name (Tyre front(…)) gives that name to the one thing the element holds. The ids inside it then start with it (front_g). Without a name, the ids are kept as written. So an element with ids, used twice in a screen, needs a name on each use.
  • bind. A bind parameter is two-way. It takes something a change can set: a variable of the part. A toggle or slider bound to it sets that variable. So does on = value in an on change. Any other parameter is read only.

archec checks what each use gives, against the parameters:

  • the number of arguments, their names, and their types;
  • a bind parameter given something that cannot be set;
  • a use of an element that does not exist (it suggests the nearest name);
  • an element that holds itself, through any number of others.

The checks of what the element holds follow the parameters. For example, a gauge in bar given a value in km/h is reported at the use. The message says where it is in the element, and the editor shows that place too. The editor completes your elements in a screen, with their parameters, and hovering a use shows its parameters.

The car's HMI (examples/autonomous-car) shows its readouts with a Readout element. Its four targets are the same as with the labels written out. The smaller panels of the other examples (listed below) write their elements out.

Drawn from the model: for and if#

A fault list shows the faults that are there. A part of a screen exists only in one state. for and if write them in a layout:

column {
  for f in bus.FAULTS.active max 8 {
    row {
      label code { text "${f.code}  ${f.text}" }
      button ack "Ack" { on press send cmd ACK(f.code) }
    }
  }
  if bus.FAULTS.count == 0 { label ok "No fault" }
  else { label n { text "${bus.FAULTS.count} faults" } }
}
  • for f in <list> max N { … } draws what it holds once for each item of a list: a message's array field, or a variable that is an array. The item has a name (f), and the bindings and actions inside use it (${f.code}, send cmd ACK(f.code)). The rows go into the row or column around the for.
  • max is required. An embedded display has no heap to spare. So the model says the most rows a screen can hold. archec checks it against the array's declared length (ui-bound): Fault[9] with max 8 is reported, and so is a for with no max. An array with no length (Fault[]) gets a hint.
  • How many are there. A C array is always its full length. So when the record has a count beside the list, the rows stop there. The count is <list>_count, n_<list> or <list>_len. It can also be count or len when the record has no other list without its own count. The UI model names it (count on the node).
  • if <condition> { … }, else if … { … }, else { … } show what they hold while their condition holds. They are only a visible on each thing they hold: the UI model has no if, and the targets need nothing for it.

In the UI model, a for is a node of kind repeat. Its value is the list. Its repeat is { item, max, length }, and its one child is the row (a column when the for holds several things). In the runtime and the tests, a node of a row has the row's index after the repeat's path: Main.column0.repeat0[2].row0.ack.

Target A for is
the runtime, the previews, ui-web its rows, drawn again when their number changes
ui-qml a Repeater whose delegate is the row, its item the delegate's modelData
ui-slint Slint's for, over a property the glue sets from the list (at most max), its item a Slint struct. A press in a row is not made: a note says so
ui-lvgl a pool of max rows, made once (static memory only). Each update shows the rows the list has, fills them from their items and hides the rest. A press in a row knows its row

A list or a table bound to a list of the part is filled the same way: Qt Quick and the web always did, and now LVGL and Slint do too. A list shows numbers, bools or texts; a table shows a list of records, a column per field.

Dialogs the model opens#

In a product, the screens that matter most are not reached by a press: a fault brings them up. when after a dialog's title says what opens it:

dialog BrakeFault "Brake fault" when alerts.BRAKE_FAULT {
  label advice { text "Take over and stop the car safely." }
  button ok "OK" { enabled not alerts.BRAKE_FAULT; on press back }
}
  • The dialog is shown when its condition becomes true, over the screen that is up then. It stays until it is left (back, or a goto); leaving it puts that screen back. The condition must become false, then true again, to open it again.
  • The condition is any binding: a message that is one bool (alerts.BRAKE_FAULT), a message that is a record (open once one is received), adcu.state == MinimalRisk.
  • ui-unreachable counts it as reached from every screen.
  • Safety (ui-safety). A dialog opened by a safety condition must not be dismissible while the condition holds. A safety condition is a message the safety analysis names (as for telltales, below), a value a telltale in an overlay reads, or the state of a part tagged safety or with an ASIL. Each button of the dialog that leaves it needs an enabled that says the opposite: enabled not alerts.BRAKE_FAULT, or the opposite comparison (adcu.state != MinimalRisk), alone or with others joined by and.
  • The generated UI tests (TP-GEN-UI) raise each condition. A message is sent by the part wired to the ui's port, a variable of a part is set. The case checks that the dialog is up, and that its way out is disabled until the condition clears.

Every target watches the conditions: the runtime under the previews, the simulators and ui-web; LVGL at each ui_<id>_update(); Slint in watch(), which the glue's main.rs calls after receive(); Qt Quick with a property bound to the condition.

The autonomous car's HMI opens BrakeFault when the brake ECU reports a fault.

The checks#

Code Finds
ui-structure a word that is not one of a screen (guage), two elements of one name, no screen, a display that is not WxH, a use of an element that does not exist, an element that holds itself, a style that is not a constant record, a key no style sets
ui-binding a name the UI cannot see, the wrong type for the element, a unit other than the element's, a send its port does not make, a goto to no screen, an element given the wrong number or type of arguments, a bind parameter given what cannot be set
ui-dead-press a press nothing receives; a button with no action (a hint)
ui-unreachable a screen no goto reaches (a dialog with when is reached from every screen); a screen with no way out (the quick fix adds a Back button)
ui-safety a message a hazard or a safety goal names, shown on some screens only and not by a telltale in an overlay; a dialog a safety condition opens that a button leaves while the condition holds
ui-bound a for whose list can hold more items than its max (the quick fix draws them all), a for with no max, a list with no declared length (a hint)
ui-fit a screen whose content needs more than the display, a text wider than it, a touch target under 9 mm, a fits none of whose layouts fits
ui-a11y contrast under WCAG AA, a button with no text, a telltale that says it by its color alone
ui-text a text not translated when the project's other texts are
ui-test a test step that presses or reads what no ui has (press hmi.engag, expect hmi.mode.colour), a change of a button (Testing a UI)

archec check reports them with the others. The editor shows them as you type. It also completes:

  • the element words inside a screen, and your own elements, with their parameters;
  • the names a binding can read: bus. gives its messages, bus.STATUS. their fields;
  • the screens after goto.

Hovering an element says what it is bound to. Hovering a use of your own element shows its parameters.

In the diagram: the palette#

The diagram's palette has a User interface section: Screen, Dialog, Overlay, the layouts (row, column, grid, stack, spacer) and every element. Drop one on a block, and it is written into the ui { } of the block's definition (for a part, the component it is a copy of), as one undoable edit:

  • a Screen (a dialog, an overlay) asks its name and goes at the end of the ui — and the block gets a ui { } when it has none;
  • an element or a layout goes into the screen (asked when the ui has several), at its end, with a first binding of what the ui can read: a gauge the first number (value bus.STATUS.speed), a toggle a bool variable of the part, a telltale a bool message. A block with no ui gets one, with a screen Main.

Select the block: its panel lists its ui — each screen, layout and element. Click one for its form, made from the word's own entry (the same as completion and hover): value, enabled, visible (and a telltale's on) suggest the names the ui can read, of the kind the element shows (bus.STATUS.speed, ctrl.state, lights), and take any expression; style, size and align are choices; text, range, unit, format, gap… are fields. The actions (on press …) are written in the source.

Themes and UI kits#

theme dark and theme light are archec's; colors { … } changes some. A theme of your own is a constant record, base the theme it starts from:

component Panel "Front panel" {
  ui {
    theme ACME
    screen Main "Main" { label hello { text "Hello" } }
  }
}

/// Ours: light, with the company's blue.
const ACME = { base: "light", primary: "#0d47a1", background: "#fafafa" }
Diagram: Front panel
What archec draws from this code: Front panel

A UI kit of the Arche Store ships one: theme "acme/automotive-dark" takes the theme of the kit the project uses by that name. A kit can also ship elements: a project that uses the kit uses them in its screens, with no include.

Styles, and layouts that fit#

A style of your own is a constant record, as a theme is. A button or a label takes it with style:

component Panel {
  out cmd: data sends STOP
  ui {
    screen Main "Main" {
      button stop "Stop" { style WARN; on press send cmd STOP(true) }
    }
  }
}

/// How a warning action looks, on every screen.
const WARN = { color: "amber", size: "large", icon: "warning", style: "danger" }

A style sets color, size, icon, format, width, height, grow and align, and its own style is one of the built-in ones (primary, danger, quiet), which still work as before. What the element says itself wins over its style. A key that is none of these is reported (ui-structure).

size and color on a layout pass to what it holds, unless those say their own: column { size large; color teal; … } makes its labels large and teal. A use of an element of your own takes them too: Readout("…") { size large }.

fits lists layouts, the widest first. For the display the ui is built for, archec keeps the first one that fits and leaves the others out:

fits {
  row { gauge s1 { value speed }; gauge r1 { value rpm }; gauge s2 { value speed } }
  column { gauge s3 { value speed }; gauge r3 { value rpm } }
  label compact { text "${speed} km/h  ${rpm} rpm" }
}

The display is the ui's display, or the display part beside it. So one HMI, included by a product with an 800×480 screen and by one with a 320×240 screen, builds the row for the first and the label for the second, with no screen written twice. The size of each layout is the estimate ui-fit uses. When none fits, the last one is kept and ui-fit says so.

Requirements and translations#

satisfies REQ-HMI-3 on a screen or an element traces the requirement to the UI. Texts are translated like every text of the model: "Driving" fr "Conduite" where it is written, or a translations fr { "Driving" "Conduite" } block.

Seeing it: archec ui#

archec ui main.arche          # the screens, element by element, with what each reads and does
archec ui main.arche --json   # the resolved model

The build writes the same model to ui/<component>.json in the Arche project. It is the one thing previews, simulators, tests and code generators read — the UiModel type in src/ui.ts: the device and theme, each screen's element tree with sizes, every binding as a small expression tree and as JavaScript, every action as checked statements, the navigation, the texts with their translations, and where each element is written.

The autonomous car's HMI has one: examples/autonomous-car/components.arche. Smaller ones, each a model of its own beside the example's main.arche, with its ui tests and its goldens:

  • the kettle's front panel, examples/kettle/panel.arche: the water's temperature, the kettle's state, a Done lamp and a Stop button.
  • the brake-by-wire bench's diagnostic panel, examples/brake-by-wire/panel.arche: the pressure the brake ECU reports, both ECUs' states, a fault lamp and a test brake.
  • the greenhouse's status screen, examples/greenhouse/screen.arche: the air's temperature, the fan's state and lamp, and a second screen with the thresholds.

Seeing the screens: archec ui preview#

archec ui preview main.arche                      # screens.html: each named preview, every screen, drawn
archec ui preview main.arche --screen Settings    # one
archec ui preview main.arche --preview Faulted    # one named preview
archec ui preview main.arche --png screens.png    # a picture of them (headless Chrome)

One page, nothing to install, no external URL: each screen and dialog of each ui at the display's size (scaled to fit), the overlays over them, in the theme's colors. Each element shows a sample value: the model's own first values (each part's variables and state at the start of a run of the browser simulator — the car's mode label says Mode: Boot), its constants, and for a message not received yet a value within its type's range. Click an element: the page says what it is, what it reads (value bus.STATUS.speed, its unit), what a press does, and the file and line it is written on.

--png asks Chrome or Chromium (--chrome <path>, $CHROME, else the usual places). archec doc --html shows the same screens as figures, in a chapter User interface.

In VS Code, UI Preview (the button in the editor's title bar of a model with a ui, or Arche: UI Preview) shows the screens beside the editor and draws them again as you type; a click on an element shows its line.

Named previews#

A screen is reviewed in the states that matter: parked, cruising, a brake fault at speed. A preview in the ui names one, by what the display reads set to a value, or by a keyframe of the system it starts from:

ui {
  …
  preview Cruising "Autonomous at 88 km/h" {
    adcu.state = Autonomous
    adcu.speed = 24.45
    adcu.obstacle_m = 60
  }
  preview Faulted "Brake fault at 88 km/h" {
    adcu.state = Autonomous
    adcu.speed = 24.45
    alerts.BRAKE_FAULT = true
  }
  preview Boot "Cold start" from keyframe parked
}
  • Each line is name = value. The name is one the ui reads: a variable of the part, a message or one of its fields (bus.STATUS.speed), the state or a variable of a part beside it, a variable of the ui. The value is a number, a text, true or false, a state, an enum value or a constant, of the name's type (ui-binding). A name nothing on the screens reads is reported: the preview would show the same without it.
  • from keyframe parked starts from the system's keyframe: its variables set, then what the preview sets over them. Both may be written.
  • What is not set comes from the start of a run, as for the screens.

Where they are used:

  • archec ui preview draws each preview, side by side, before the screens. A preview shows what its values bring up: the screen the ui starts on, and a dialog its values open. --preview Faulted draws one.
  • VS Code's UI Preview shows them side by side too.
  • archec ui snapshot keeps a golden of each: ui/screenshots/Hmi/preview-Faulted.png, beside those of the screens.
  • A test case starts from one: case TC-7 "Fault at speed" from preview Faulted { … }. The run starts from the preview's keyframe. Then, at 0, what it sets: a variable of a part, a part's state (no entry action runs), a message as if the part had received it. The case runs on the browser simulator.
  • The store's "Try it" opens the screens on the first preview. A choice above them picks another, or the live run. Play, or a step, gives the screens to the run.

The autonomous car has three, with their goldens.

Simulating them#

The screens run with the model in the browser simulator:

  • archec sim main.arche --html sim.html — the page shows the screens above the block diagram. Their values come from the run: the part's variables and state, the last message each of its ports received, the parts beside it. A press sends its message into the run, where the port's links take it; goto and back move between the screens. Engage on the car's dashboard: the ADCU goes Autonomous, and the mode label says so.
  • VS Code ▶ Run (the diagram's Run, Simulate): the UI Preview opens beside and shows the screens live — press the buttons there.
  • The store's "Try it" page of a package with a ui: the same.

A test drives them with no page#

The runtime under all of them is headless (src/uiruntime.ts): it holds the screen shown and the way back, works out what each element shows from a value source, and runs presses and changes. It interprets the model's expression trees — no eval — so it runs in a webview, in a page, or in a test:

const { buildUi, createUiRuntime } = require('arche-lang');
const rt = createUiRuntime(buildUi(program)[0], {
  values: (key) => values[key],                  // 'ctrl.state', 'bus.STATUS.speed', …
  send: (port, message, fields) => sent.push({ port, message, fields }),
});
rt.screen;                     // 'Driving'
rt.element('engage');          // { text: 'Engage', enabled: false, visible: true, … }
rt.press('engage');            // { ok: false, why: 'Driving.row1.engage is disabled' }
rt.change('Settings.lights', true);
rt.snapshot();                 // the screen, the way back, every element shown

uiSimLink().create(model, simProgram, live) is the value source and the send over the live browser simulator (src/websimlive.ts).

Testing a UI#

A test case drives the screens as the driver would, in its do and expect lines. Name an element by the part that has the ui, then the element's id: hmi.engage. When two screens have an element of that name, write hmi.Screen.id.

test-plan TP-UI "Driver HMI, on the screen" {
  case TC-UI-01 "Engage, then take over" {
    at 5ms "Ready" expect hmi.engage.enabled
    at 5ms expect hmi.mode.text == "Mode: Ready"
    at 5ms "Engage" do press hmi.engage
    at 10ms expect hmi.mode.text == "Mode: Autonomous"
    at 10ms expect sent("ENGAGE_REQ") == 1
    at 10ms expect not hmi.mrm.on
  }
  case TC-UI-02 "Details and back" {
    at 0ms do press hmi.details
    at 0ms expect hmi.screen == Details
    at 0ms do press hmi.back
    at 0ms expect hmi.screen == Driving
  }
}
Line Does
do press hmi.engage presses it (long-press, release the same): what its on press does — a send into the run, a goto, a back. A press on an element hidden, disabled or not on the screen shown fails the case, saying why
do change hmi.limit 80 a toggle, slider, select, input or stepper set (True, "text", a constant): its variable, its on change
expect hmi.mode.text == "…" what an element shows: text, label, value, display (formatted, with its unit), enabled, visible, on (a telltale), shown (visible, on a screen shown), options
expect hmi.screen == Details the screen shown (a screen by its name, or "Details")
expect within 50ms: sent("ENGAGE_REQ") >= 1 the messages sent so far, a press's among them

A case can start from a named preview: case TC-7 "Fault at speed" from preview Faulted { … }.

These lines also go in a timeline (at 5ms do press hmi.engage), with the rest of the case's Python (adcu.state == "Manual"). The checker knows them as you type. A name that is no element, a part with no ui, or a change of a button is an error (ui-test).

Where they run. Arche's Python simulator has no screen, no enabled and no text formatting. So a case with a ui step runs on the browser simulator: the model's behaviour in node (src/websimrt.ts), with the ui's runtime over it. This is the same pair as archec sim --html and ▶ Run.

  • archec test runs those cases there, and the other cases in arche-cli, in one report. When every case it runs has a ui step, it needs no arche-cli at all.
  • --sim web runs every case on the browser simulator. A case that reaches Python the action language can't say, with no python3 to run it, is inconclusive, never a pass (sim).
  • In the Arche project, the ui lines are written as Python that stops the case and says that it runs on the browser simulator. Run from Arche, such a case fails. It never passes for nothing.

Generated. archec gen --target tests writes a plan TP-GEN-UI, beside the plans for the transitions and the limits. It has:

  • a case per button. The case makes the presses that bring the ui to the button's screen, by the shortest way of gotos from where the ui starts. If the button has a condition, it waits and checks expect … .enabled. Then it presses, and checks what the press must do: its sent("MSG"), or the screen after a goto or a back;
  • a case per screen, that reaches it;
  • a case per dialog the model opens: its condition raised, the dialog up, its way out disabled until the condition clears.

A screen that no goto reaches is written with a TODO. It is listed in tests/generated.allow, like the transitions that nothing brings.

In CI. archec ci has a ui gate. A binding, a press or a ui step that does not hold fails it. For example: a message renamed while a button still sends the old name (ui-binding), or a press that nothing receives (ui-dead-press). The test gate runs the ui cases on the browser simulator, even when arche-cli is not there.

Golden screenshots#

archec ui snapshot main.arche --update   # ui/screenshots/Hmi/Driving.png, Details.png, preview-Faulted.png
archec ui snapshot main.arche            # each screen drawn again, compared
archec test main.arche --ui-golden       # the cases, then the same comparison

A golden is the reference picture of a screen, committed beside the model. Each screen and dialog is drawn as archec ui preview --png draws it: in headless Chrome, with the sample values. Then it is compared, pixel by pixel, with its golden.

  • A pixel whose channels are within 24 of the golden's counts as the same. This allows for a text's antialiasing.
  • A screen fails when more than --tolerance percent of its pixels changed (0.1 by default). Its diff is written to arche-out/.archec/ui-diff/Hmi/Driving.png: the golden faded, and what changed in red. Driving.now.png is beside it.
  • When the change is meant, run with --update.

The web target: gen --target ui-web#

archec gen main.arche --target ui-web -o out    # out/ui-web/index.html, ui.js, ui.css, ui.json

This writes a folder that runs on its own: open index.html, or serve the folder. By default the values come from the model. The page simulates, in real time, the system that the ui's part is in: it boots, and the buttons send into the run. ui.json holds the UI models, the sample values and the simulator's program, for other tools.

With index.html?ws=ws://host:port, the values come from a WebSocket instead: the real product, a bridge to a CAN bus, a test bench. Each frame is one JSON object:

From Message Means
the server {"type":"value","key":"bus.STATUS.speed","value":72.5} a ref's value now (key: a key of the model's refs)
the server {"type":"values","values":{"ctrl.state":"Ready","bus.STATUS.speed":72.5}} several at once
the page {"type":"hello","uis":["Dashboard"],"keys":{"Dashboard":["bus.STATUS.speed","ctrl.state","lights"]}} on connecting: the keys it reads
the page {"type":"send","ui":"Dashboard","port":"cmd","message":"STOP","fields":{"hard":true}} a press sent a message (one that is one value: "fields":{"value":true})
the page {"type":"set","ui":"Dashboard","key":"lights","value":true} the UI set a variable of its part (a toggle); never one of the ui's own

Any message may carry "ui" to name one ui of several. The page reconnects when the socket closes.

Code for a device: ui-lvgl and ui-slint#

archec gen main.arche --target c -o generated        # the parts, as C
archec gen main.arche --target ui-lvgl -o generated  # the ui, for LVGL 9, beside it
archec gen main.arche --target ui-slint -o generated # the ui, in Slint, as a Rust crate

LVGL (ui-lvgl/) gets two kinds of file. ui_<id>.c/.h, for each ui, is written again at each run. ui_<id>_task.c is written once; after that it is yours.

  • Screens. Each screen is an LVGL screen. A dialog is a box over it, on lv_layer_top. An overlay is on lv_layer_top too, over every screen. row, column and grid are flex containers. The children of a stack are centred on one another. The theme's colors are used for the screens, the text and the buttons.
  • Building and updating. ui_<id>_create(&part) builds the screens for the part the ui belongs to (its C struct from --target c). ui_<id>_update() reads every binding again, and opens a dialog whose when became true. Call it in the ui's thread, before lv_timer_handler().
  • Where values come from.
    • A variable is the part's: self->lights. A variable of the ui is a static of the file: ui_<id>_uivar_page.
    • A message is the last one received. The part keeps the last of each message its ui reads: arche_ui_bus_status in its struct. It is set by dashboard_ui_got_bus_status(), which the wiring calls as each message comes.
    • A state or a variable of a part beside it (ctrl.state) is in ui_<id>_peers. With a deployment, the wiring copies it from that part when the part runs in the same binary. Otherwise, set ui_<id>_peers_hook. A real product gets the value over a message.
  • Events are callbacks.
    • send cmd STOP(true) calls the part's send function, the one the C target writes (dashboard_send_cmd_stop).
    • goto and back use a navigation stack: ui_<id>_goto, ui_<id>_back, and each screen's on enter and on exit.
    • lights = not lights sets the part's variable.
    • A toggle, slider, select, input or stepper bound to a variable sets it as it changes.
  • The thread. ui_<id>_task.c is the ui's thread: lv_init, the display, then the loop. On a host with LV_USE_SDL the display is an SDL window. Otherwise it is a buffer, and the flush callback that your panel's driver gives. A binary of a deployment built with -DARCHE_UI starts the thread from <binary>_start.

Slint (ui-slint/<id>/) is a Rust crate.

  • ui/<id>.slint has:

    • a global <Id>State: a property for each name the ui reads, the screen shown, and a callback for each event;
    • a component per screen, dialog and overlay;
    • the <Id>Window.

    The bindings are Slint expressions over the global.

  • src/<id>_glue.rs is the model behind it:

    • Received: each message the ui reads, and each part beside it;
    • Sent: each message it sends;
    • <Id>Ui, with the values, receive(), apply() to the window, watch() (the dialogs the model opens), and the events in Rust;
    • bind(), which installs the callbacks.
  • src/main.rs, Cargo.toml and build.rs are written once. They make a host binary that feeds Received from a channel and prints each Sent. Connect it to your bus.

What each makes. Every element word has an entry in each target's list (src/gen/uitargets.ts). When a target makes an element only in part, archec gen says so in a note. It never drops it.

Element LVGL Slint
row column grid stack spacer flex containers layouts
label button toggle slider select input lv_label, lv_button, lv_switch, lv_slider (its step), lv_dropdown, lv_textarea Text, Button, Switch, Slider, ComboBox, LineEdit
gauge lv_arc, its value in it its value and a ProgressIndicator (no dial in Slint)
bar chart lv_bar, lv_chart (a point each window/60) ProgressIndicator, a Path the glue draws
telltale lv_led and its text, hidden while off a dot and its text, while on
stepper lv_spinbox with − and + SpinBox (its step 1)
image lv_image of the file through LVGL's file system (UI_IMAGE_DRIVE) Image (@image-url, beside the .slint)
list table their fixed options and columns; a list of the part's numbers, bools or texts, and a table of its records, filled at each update the same, in a ListView and a StandardTableView
for a pool of max rows made once, shown and filled at each update Slint's for, its rows without their events
custom its lvgl code its slint code

release is a click in Slint. A long press is not made there (archec gives a note). Texts are in the language they are written in.

The display. When the ui has no display, a display part beside the ui's part gives the size, the density and the input. That part is in the same system, or in the platform of its deployment. The store has an ILI9341 (320×240, touch), ST7789s (240×320, 240×240), the SSD1306 (128×64) and an HDMI display (boards). The rover template (archec new --template rover-esp32) has a status screen on an ILI9341.

On a Linux board: Qt Quick (--target ui-qml)#

archec gen main.arche --target ui-qml -o generated
cd generated/ui-qml/Dashboard
cmake -B build && cmake --build build && ./build/dashboard_ui     # C++, Qt 6.5+
python3 main.py                                                 # or PySide6

Each ui { } becomes a Qt Quick application in ui-qml/<component>/. It is written from the resolved model, never from the source:

File What it is
Main.qml the window at the display's size: a StackView of the screens (goto shows one, back to it when it is under the current one; back pops), a Popup for the dialogs, the overlays over everything, the theme's colors
<Screen>Screen.qml a component per screen (<D>Dialog.qml, <O>Overlay.qml): row, column, grid as RowLayout, ColumnLayout, GridLayout; on enter / on exit on StackView.onActivated / onDeactivated
uimodel.h, uimodel.py UiModel, the object the bindings read: a property per name the UI reads (bus.STATUS.speed → bus_STATUS_speed), in C++ (Q_PROPERTY) and for PySide6
uibridge.h, bridge.py the bridge to the product (below)
main.cpp, CMakeLists.txt, main.py the application — written once, then yours
README.md the properties and the protocol

The elements are Qt Quick Controls, in the Basic style, with the theme as its palette:

Element QML
label a Label
gauge an arc on a Canvas
bar a ProgressBar
chart a sparkline on a Canvas, over its window
telltale a lit Rectangle, shown while its condition holds
image an Image
list a ListView
table a TableView, with a column per field of columns
button a Button; style danger uses the theme's danger color
toggle, slider, select a Switch, a Slider, a ComboBox
input, stepper a TextField, a SpinBox
custom its qml block, handed value
for a Repeater, its item the delegate's modelData

Each element has its path in the UI model as its objectName, for example Driving.column0.row1.stop. A test finds it by that name.

A binding is a QML binding on root.model.<name>. An event is the checked statements, as JavaScript: root.model.send("cmd", "STOP", { "hard": true }), root.nav.goto("Settings"), root.nav.back(), root.model.lights = !root.model.lights. A control bound to a variable of its part sets it when it changes.

What QML cannot show is said in a note, never dropped:

  • a custom with no qml block: a placeholder is shown;
  • an image, which you copy next to the QML;
  • a table whose columns are not known: it is shown as a list;
  • a SpinBox, which holds whole numbers only;
  • translations: the texts are in the language of the model.

The bridge#

On a Raspberry Pi or a Jetson, the UI talks to the rest of the product through UiModel. Set its values, and connect to its sent signal. Two bridges are written:

  • WebSocket, JSON text frames: ARCHE_UI_WS=ws://host:8765. In C++ when Qt WebSockets is installed, and in Python.
    • in {"type":"value","key":"bus.STATUS.speed","value":42} sets a value the UI reads;
    • out {"type":"send","port":"cmd","message":"STOP","fields":{"hard":true}} for a press;
    • out {"type":"value","key":"lights","value":true} when the UI changes a variable of its part.
  • SocketCAN, in Python (pip install python-can cantools): ARCHE_UI_CAN=can0 ARCHE_UI_DBC=bus.dbc python3 main.py, with the DBC from archec gen --target dbc.
    • A received frame sets the keys its message is read by (uimodel.RECEIVES, by signal name). A field a.b is the signal a_b.
    • A press is encoded by its message's name.
    • The state or a variable of a part beside the display is not on a bus. It comes over the WebSocket.

Limits#

  • A for in LVGL and Slint repeats over a list of the part (a message's field, a variable), one level deep in LVGL. A for inside another's row is drawn by the runtime and Qt Quick only.
  • In Slint, a press in a row of a for is not made. LVGL, Qt Quick and the web make it.
  • fits measures each layout against the whole screen (the display, less the screen's padding), not against the room left where it is written. One ui is built for one display: a product with two screens has two builds.
  • An element of your own is checked where it is used. An element that nothing uses is not checked.
  • Its parameters are given to bindings (value, enabled, visible, on), texts (text, ${…}) and words (size, color, icon, style). They are not given to range or options, and an action cannot be one.
  • Arche's Python simulator has no screen. A case with a ui step runs on the browser simulator, and fails when it is run from Arche.
  • --png and the golden screenshots need Chrome or Chromium. With neither, the comparison is skipped, and archec says so.
  • Goldens drawn on one machine may differ on another, because of its fonts. Make them where the comparison runs.
  • Slint has no dial for a gauge, and a long press is not made there.
  • The LVGL, Slint and Qt Quick targets write the texts in the language of the model. They do not carry the translations.
  • The state or a variable of a part beside the display does not travel on CAN. The Qt Quick bridge takes it over the WebSocket.
  • With no display size, env.width and env.height are 800 and 480 for every target, as the web target draws it.
  • A dialog's condition is seen when the ui looks: at each update (LVGL, a page's frame), at each event of a test's run. A condition that rises and falls between two looks opens nothing. A Slint main.rs written before dialogs had when must call watch() itself.