Martino Ferrari
272 lines
12 KiB
Markdown
272 lines
12 KiB
Markdown
# 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 |
|