uopi/docs/FUNCTIONAL_SPEC.md

Functional Specification — uopi

1. Purpose

uopi is a web-based HMI (Human-Machine Interface) for monitoring and controlling industrial/scientific systems, primarily EPICS-based control systems. It runs as a single server process and is accessed entirely through a web browser, making it suitable for SSH-tunnelled remote access.

---

2. Users and Roles

Role	Description
Operator	Uses interfaces in View mode; can interact with controls but cannot edit layouts
Engineer	Creates and edits interfaces in Edit mode; manages signal lists
Administrator	Manages server configuration, data sources, and saved interfaces

In the initial version all users share the same access level. Role-based access control is deferred to a future release.

---

3. System Modes

3.1 View Mode (default)

The default mode when opening the application.

Interface list pane (left, collapsible, resizable)

• Displays all interfaces saved on the server.
• Right-click on an interface: options to open in Edit mode or clone it.
• "New interface" button opens Edit mode with a blank canvas.
• The pane width can be adjusted by dragging the resize handle on its right edge.

Tabs

• HMI tab: the live widget canvas (described below).
• Plot tab: a dedicated live multi-signal plot panel (see §3.3).
• Info tab: signal info and metadata display for the last right-clicked signal.

HMI canvas (center)

• Renders the selected interface as a live, interactive panel.
• Widgets display real-time data; controls (set-value, buttons) are active.
• No drag, resize, or layout operations are possible in this mode.
• Right-clicking any widget opens a context menu:
  • Signal info — switches to the Info tab showing DS name, type, unit, range, current value and timestamp.
  • Copy signal name — copies the signal identifier to the clipboard.
  • Export data to CSV — downloads buffered data for the signal(s) used by the widget.
  • Plot — adds the signal(s) to the Plot tab.

Top toolbar

• Show/hide interface list pane.
• ⏱ History button: toggle historical time navigation bar.
• Zoom control (A− / % / A+): adjust the UI scale (see §3.4).
• Edit button: switch to Edit mode for the current interface.
• Connection status indicator.

Historical time navigation bar (shown when History is active)

• Date/time range pickers (start and end).
• Load button fetches archive data and replaces live data in all widgets.
• Live button discards archive data and resumes real-time streaming.
• Status shown on plot widgets: "Loading history…", "No archive data for this range", "Archive unavailable".

3.2 Edit Mode

Activated via the "New interface" button or by clicking Edit in the toolbar.

Signal tree pane (left, resizable and collapsible)

• Shows all signals known to each connected data source.
• Sources are shown as top-level nodes; signals are nested within.
• User can add custom entries:
  • For EPICS: manually enter a PV name.
  • For Synthetic: define a new synthetic signal via the Synthetic Wizard (see §5.2).
• Filter/search box to narrow the list.
• Synthetic signals show an edit (✎) button to reopen the wizard.

Widget canvas (center)

• Free-form canvas where widgets can be placed at arbitrary pixel positions.
• Background grid with snap-to-grid.

Properties pane (right, resizable and collapsible)

• Appears when one or more widgets are selected.
• Displays and edits all options for the selected widget (see §4).
• Width is adjustable by dragging the resize handle on its left edge.

Top toolbar

• Show/hide signal pane / properties pane.
• Undo / Redo (also Ctrl+Z / Ctrl+Shift+Z).
• Import / Export interface to/from local XML file.
• Save interface to server.
• Close (return to View mode).
• Zoom control (A− / % / A+).

3.3 Plot Tab (Live Multi-Signal Plot)

A dedicated panel for live time-series plotting of any signals, independent of the interface layout.

Adding signals: right-click any widget in the HMI tab → Plot. The signal is added to the Plot tab immediately.

Time window selector: 10s / 30s / 1m / 5m / 15m / 1h buttons control how much history is displayed.

Per-signal legend:

• Color swatch and signal name.
• Statistics table: Last / Min / Max / Mean over the current window.
• ✎ button opens an inline style editor:
  • Color: color picker.
  • Width: line width (none, 1, 1.5, 2, 3 px).
  • Line: solid / dashed / dotted.
  • Markers: none, S (3 px), M (5 px), L (8 px).
• ✕ button removes the signal from the plot.

Chart area: rendered with uPlot; auto-scaled Y axis; time axis tracks the rolling window in real time.

3.4 UI Zoom

The toolbar in both modes contains a zoom control (A− / nn% / A+) that adjusts the base font size of the entire UI:

• 11 zoom steps from 50% to 250% (50, 60, 75, 85, 100, 115, 130, 150, 175, 200, 250%).
• The selected zoom level is persisted in localStorage and restored on the next page load.
• At 100%, the base font size adapts to viewport height via clamp(13px, 1.5vh, 18px), making the UI naturally usable on 4K displays without any manual adjustment.

---

4. Widgets

4.1 Creating Widgets

Drag a signal from the signal tree and drop it onto the canvas. A picker appears showing all widget types compatible with the signal's data type. The user selects one and the widget is placed at the drop location with default size.

4.2 Selecting Widgets

• Single click: select one widget (deselects others).
• Ctrl+click: add/remove a widget from the current selection.
• Click-drag on empty canvas area: rubber-band area select.

When a widget is selected, a bounding box appears with:

• 8 resize handles (corners + midpoints).
• A delete button (×) in the top-right corner.
• The widget can be moved by dragging its body.

4.3 Multi-selection Operations

When multiple widgets are selected:

• Drag any selected widget to move them all together.
• Del key deletes all selected widgets.
• An align/distribute toolbar appears above the canvas with:
  • Align left / center horizontal / right.
  • Align top / center vertical / bottom.
  • Distribute evenly (horizontal/vertical).

4.4 Widget Catalogue

Widget	Compatible signal types	Description
Text view	any scalar	Displays name: value unit
Gauge	numeric scalar	Circular or arc gauge with configurable range
Vertical bar	numeric scalar	Vertical level indicator
Horizontal bar	numeric scalar	Horizontal level indicator
Set value	numeric, string, or enum; writable	Input field or enum dropdown + Set button
LED	boolean / numeric	Coloured indicator with configurable condition and label
Multi-LED	integer (bitset)	One LED per bit with individual labels and conditions
Button	writable	Sends a fixed value or command on click
Plot	numeric scalar or array	Multi-signal plot; sub-types below
Text label	—	Static text annotation
Image	—	Static image
Link	—	Button navigating to another interface

Plot sub-types:

Sub-type	Signal requirement
Time series	numeric scalar(s)
FFT	1-D numeric array
Waterfall	1-D numeric array (repeated)
Histogram	numeric scalar(s)
Bar chart	numeric scalar(s)
Logic analyser	boolean / integer (bitset)

4.5 Widget Properties (Properties Pane)

Common to all:

• Label text, font size, text colour.
• Position (X, Y) and size (W, H) — editable numerically.
• Data source and signal name.

Per type:

• Gauge / Bar: min value, max value, alert thresholds with colours, unit label.
• LED / Multi-LED: condition expression (e.g. value > 0), colours for true/false states, label.
• Plot: plot sub-type selector, Y-axis range (auto or manual min/max), time window duration, legend position (top / bottom / none), value format string.
• Set value: no special options — enum mode is detected automatically from signal metadata.
• Link: target interface name.

4.6 Set-value Widget — Enum Mode

When the signal's metadata reports enum strings (e.g. EPICS mbbi/mbbo records):

• The input field is replaced by a <select> dropdown showing all enum options.
• The current live value is shown as the pre-selected option (display only).
• The user selects a value from the dropdown, then clicks Set to write it.
• The Set button is always required; changing the dropdown does not write immediately.

---

5. Data Sources

5.1 EPICS

• Connects to an EPICS environment via Channel Access (CA).
• On connect, retrieves full metadata from the PV name: data type, engineering units, display range, alarm limits, enum strings (for mbbi/mbbo records), read/write mode.
• Uses ca_add_event monitors — no polling.
• When an EPICS Archive Appliance is configured, the server can satisfy historical data requests from the toolbar time navigator.

5.2 Synthetic Signals

A signal defined by composing one or more input signals through a chain of processing nodes.

New Synthetic Signal Wizard:

1. Click "New synthetic signal" in the signal tree.
2. Name the signal and optionally set a unit.
3. Add processing nodes from the node type dropdown and connect them.
4. Configure each node's parameters inline.
5. Click Create — the signal appears in the tree and updates live.

The wizard dialog is resizable (drag its corner) and defaults to 600 px wide to accommodate the Lua editor.

Editing an existing synthetic signal: click the ✎ button next to the signal in the tree to reopen the wizard.

Built-in node types:

Node	Parameters	Description
Source	DS, signal name	Input from any data source
Gain	factor	Multiply by constant
Offset	value	Add constant
Moving average	window (samples)	Rolling mean
Low-pass filter	frequency (Hz), order (1–8)	IIR low-pass; correct for non-uniform sample rates
Formula	expression	Inline math (variables: a, b, …)
Lua script	script	Arbitrary Lua 5.1 with persistent state table

Lua editor: the Lua node parameter uses a code editor with syntax highlighting (keywords, strings, comments, numbers rendered in distinct colours). The editor is a full-height multi-line input that grows with the dialog.

---

6. Interface Persistence

• Interfaces are saved to the server in XML format and are available to all connected clients.
• Export/Import allows local file exchange of XML files.
• The XML schema records: widget type, position, size, signal bindings, and all property values.

---

7. Historical Data Navigation

When the server has archive access configured:

• The ⏱ History button in the View mode toolbar reveals a time range bar.
• Users set a start and end date/time and click Load.
• Plot widgets fetch and display the archived data for the selected range.
• Point-value widgets (text view, gauge, bar, LED) show the value at the end of the selected range.
• The Live button resumes real-time streaming.
• Status overlays on plot widgets indicate loading, empty, or error states.

---

8. Non-functional Requirements

Requirement	Target
Server binary	Single statically-linked executable; no runtime dependencies
Target platform	Linux x86-64; also aarch64 optional
Minimum server OS	RHEL/CentOS 7 (glibc 2.17) or equivalent
Concurrent clients	≥ 20 simultaneous browser clients
Data fan-out latency	< 5 ms added latency vs. raw EPICS update rate
Frontend responsiveness	60 fps canvas rendering during live updates
Screen DPI	UI scales with viewport height; manual zoom 50–250%
Plot buffer	200,000 samples per signal retained in-browser