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(orencoder,keys,pointer),theme dark(orlight). Withdpi 160, archec can check that buttons are big enough for a finger. With nodisplay, archec takes the display of the board the part is built on (itshardware { display … }). - Screens: what the display shows at one time. The UI starts on the first
one, or on the one
initial Settingsnames.goto Settingsandbackmove between them. Adialogis shown over the current screen until it is left. Anoverlayis 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,widthandheightadjust the layout. - Elements:
label,gauge,bar,chart,telltale,image,list,table,button,toggle,slider,select,input,stepper, andcustomfor 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
setto 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 ofUiModelthat 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 itsvisible, its place in the layout around it (grow,width,height,align), and thesizeandcolorof 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. Abindparameter 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 doeson = valuein anon 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
bindparameter 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 thefor.maxis 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]withmax 8is reported, and so is aforwith nomax. 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 becountorlenwhen the record has no other list without its own count. The UI model names it (counton the node). if <condition> { … },else if … { … },else { … }show what they hold while their condition holds. They are only avisibleon each thing they hold: the UI model has noif, 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 agoto); 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-unreachablecounts 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 taggedsafetyor with an ASIL. Each button of the dialog that leaves it needs anenabledthat says the opposite:enabled not alerts.BRAKE_FAULT, or the opposite comparison (adcu.state != MinimalRisk), alone or with others joined byand. - 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 screenMain.
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" }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,trueorfalse, 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 parkedstarts 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 previewdraws 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 Faulteddraws one.- VS Code's UI Preview shows them side by side too.
archec ui snapshotkeeps 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;gotoandbackmove 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 testruns 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 webruns every case on the browser simulator. A case that reaches Python the action language can't say, with nopython3to 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: itssent("MSG"), or the screen after agotoor aback; - 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
--tolerancepercent of its pixels changed (0.1 by default). Its diff is written toarche-out/.archec/ui-diff/Hmi/Driving.png: the golden faded, and what changed in red.Driving.now.pngis 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
dialogis a box over it, onlv_layer_top. Anoverlayis onlv_layer_toptoo, over every screen.row,columnandgridare flex containers. The children of astackare 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 whosewhenbecame true. Call it in the ui's thread, beforelv_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_statusin its struct. It is set bydashboard_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 inui_<id>_peers. With a deployment, the wiring copies it from that part when the part runs in the same binary. Otherwise, setui_<id>_peers_hook. A real product gets the value over a message.
- A variable is the part's:
- Events are callbacks.
send cmd STOP(true)calls the part's send function, the one the C target writes (dashboard_send_cmd_stop).gotoandbackuse a navigation stack:ui_<id>_goto,ui_<id>_back, and each screen'son enterandon exit.lights = not lightssets 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.cis the ui's thread:lv_init, the display, then the loop. On a host withLV_USE_SDLthe 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_UIstarts the thread from<binary>_start.
Slint (ui-slint/<id>/) is a Rust crate.
ui/<id>.slinthas:- 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.
- a global
src/<id>_glue.rsis 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.tomlandbuild.rsare written once. They make a host binary that feedsReceivedfrom a channel and prints eachSent. 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
customwith noqmlblock: 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.
- in
- SocketCAN, in Python (
pip install python-can cantools):ARCHE_UI_CAN=can0 ARCHE_UI_DBC=bus.dbc python3 main.py, with the DBC fromarchec gen --target dbc.- A received frame sets the keys its message is read by (
uimodel.RECEIVES, by signal name). A fielda.bis the signala_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.
- A received frame sets the keys its message is read by (
Limits#
- A
forin LVGL and Slint repeats over a list of the part (a message's field, a variable), one level deep in LVGL. Aforinside another's row is drawn by the runtime and Qt Quick only. - In Slint, a press in a row of a
foris not made. LVGL, Qt Quick and the web make it. fitsmeasures 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 torangeoroptions, 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.
--pngand 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.widthandenv.heightare 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.rswritten before dialogs hadwhenmust callwatch()itself.