Initial commit

docs/FUNCTIONAL_SPEC.md

@@ -0,0 +1,213 @@
+# 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)**
+- Displays all interfaces saved on the server, grouped into a tree by folder.
+- Right-click on an interface: options to open in Edit mode or clone it.
+- "New interface" button opens Edit mode with a blank canvas.
+- "Import" option loads an interface from a local XML file.
+
+**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** — floating window 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/historical data for the signal(s) used by the widget.
+
+**Top toolbar**
+- Show/hide interface list pane.
+- Time selector: navigate to a past timestamp (enabled only when the server has archive access for all signals on the canvas).
+- "Live" button: return to real-time data after historical navigation.
+
+### 3.2 Edit Mode
+
+Activated via the "New interface" button or by right-clicking an existing interface.
+
+**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 (see §5.2).
+- User can load a CSV file with columns `NAME, DataSource, DS_PARAMETERS` to import a batch of signals.
+- Filter/search box to narrow the list.
+
+**Widget canvas (center)**
+- Free-form canvas where widgets can be placed at arbitrary pixel positions.
+- Background grid with optional snap-to-grid.
+
+**Properties pane (right, collapsible)**
+- Appears when one or more widgets are selected.
+- Displays and edits all options for the selected widget (see §4).
+
+**Top toolbar**
+- Show/hide signal pane.
+- Show/hide properties pane.
+- Undo / Redo (also Ctrl+Z / Ctrl+Shift+Z).
+- Save interface to server.
+- Load interface from server.
+- Export interface to local XML file.
+- Import interface from local XML file.
+- "Add text" tool — inserts a static text label.
+- "Add image" tool — inserts a static image (uploaded to server or embedded as base64).
+- "Add link" tool — inserts a button that opens another interface.
+
+---
+
+## 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 (iconised). 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 — by center spacing (horizontal/vertical).
+  - Distribute evenly — by gap size (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 or string, writable | Shows `name: [input field] current_value unit` + 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 (read-only after creation; reassignable via drag).
+
+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.
+- **Plot**: plot sub-type selector, Y-axis range (auto or manual), time window duration, legend position, colour per signal, line style.
+- **Set value**: input type (numeric / string / enum), confirmation prompt toggle.
+- **Link**: target interface name.
+
+---
+
+## 5. Data Sources
+
+### 5.1 EPICS
+
+- Connects to an EPICS environment via Channel Access (CA) or PVAccess (PVA).
+- On connect, retrieves full metadata from the PV name: data type, engineering units, display range (DRVL/DRVH, LOPR/HOPR), alarm limits, enum strings (for mbbi/mbbo records), read/write mode, acquisition mode.
+- Prefers monitor/subscription over polling. Falls back to polling only when monitors are unavailable.
+- Attempts to enumerate available PV names from the IOC (e.g. via PV lists or Channel Finder). Unknown PVs can still be manually added by the user.
+- When an EPICS Archive Appliance or Channel Archiver is configured, the server can satisfy historical data requests.
+
+### 5.2 Synthetic
+
+A signal defined by composing one or more input signals (from any data source) through a chain of processing functions.
+
+**Built-in processing functions (non-exhaustive):**
+- Arithmetic: gain, offset, add, subtract, multiply, divide.
+- Signal processing: moving average (N samples or time window), RMS, bandpass filter (IIR/FIR), lowpass / highpass filter, derivative, integral.
+- FFT, inverse FFT.
+- Peak detection, threshold crossing.
+- Custom formula: inline expression (`a * sin(b) + c`).
+- Lua script block: arbitrary Lua code with access to input values and state.
+
+**User workflow:**
+1. Click "New synthetic signal" in the signal tree.
+2. Name the signal and choose input signals.
+3. Build a processing pipeline by chaining function blocks (UI similar to a node graph or an ordered list).
+4. Optionally write a Lua snippet for custom logic.
+5. The synthetic signal appears in the tree and can be used like any other signal.
+
+---
+
+## 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 for all signals on the current canvas:
+- The top toolbar shows a date/time picker.
+- Selecting a past time replays data from the archive into all widgets.
+- The "Live" button resumes real-time streaming.
+- Widgets that support time-axis (plots) show the historical range; point-value widgets show the value at the selected time.
+
+---
+
+## 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 | Frontend adapts to device pixel ratio |