docs(waveform): plotting ruleset

Automatically generated by python-semantic-release

CHANGELOG.md

@@ -1,6 +1,43 @@
 # CHANGELOG
 
 
+## v2.21.2 (2025-06-30)
+
+### Bug Fixes
+
+- **waveform**: Fix waveform categorisation for aborted scans
+  ([`09c5a44`](https://github.com/bec-project/bec_widgets/commit/09c5a443aac675f02fa1e38179deb9863af152e2))
+
+### Testing
+
+- Assert config for equality, not identity
+  ([`3f5ab14`](https://github.com/bec-project/bec_widgets/commit/3f5ab142a3cb5446261c4faebdc7b13f10ef4a80))
+
+
+## v2.21.1 (2025-06-29)
+
+### Bug Fixes
+
+- **sbb monitor**: Add missing pyproject file
+  ([`371bc48`](https://github.com/bec-project/bec_widgets/commit/371bc485d060404433082c9e3e00780961ce6ae3))
+
+
+## v2.21.0 (2025-06-28)
+
+### Features
+
+- **sbb monitor**: Add sbb monitor widget
+  ([`3d59c25`](https://github.com/bec-project/bec_widgets/commit/3d59c25aa93590a62ab4d31a4ab08589402bf407))
+
+
+## v2.20.1 (2025-06-28)
+
+### Bug Fixes
+
+- **signal input base**: Unregister callback to avoid accessing deleted qt objects
+  ([`7ba8863`](https://github.com/bec-project/bec_widgets/commit/7ba8863d6a0c21f772e4ef8a5d4180c2a7ab49cb))
+
+
 ## v2.20.0 (2025-06-26)
 
 ### Bug Fixes

bec_widgets/cli/client.py

@@ -49,6 +49,7 @@ _Widgets = {
     "ResetButton": "ResetButton",
     "ResumeButton": "ResumeButton",
     "RingProgressBar": "RingProgressBar",
+    "SBBMonitor": "SBBMonitor",
     "ScanControl": "ScanControl",
     "ScatterWaveform": "ScatterWaveform",
     "SignalComboBox": "SignalComboBox",
@@ -3249,6 +3250,12 @@ class RingProgressBar(RPCBase):
         """
 
 
+class SBBMonitor(RPCBase):
+    """A widget to display the SBB monitor website."""
+
+    ...
+
+
 class ScanControl(RPCBase):
     """Widget to submit new scans to the queue."""
 

bec_widgets/widgets/containers/dock/dock_area.py

@@ -169,6 +169,9 @@ class BECDockArea(BECWidget, QWidget):
                             tooltip="Add LogPanel - Disabled",
                             filled=True,
                         ),
+                        "sbb_monitor": MaterialIconAction(
+                            icon_name="train", tooltip="Add SBB Monitor", filled=True
+                        ),
                     },
                 ),
                 "separator_2": SeparatorAction(),
@@ -238,6 +241,9 @@ class BECDockArea(BECWidget, QWidget):
         # self.toolbar.widgets["menu_utils"].widgets["log_panel"].triggered.connect(
         #     lambda: self._create_widget_from_toolbar(widget_name="LogPanel")
         # )
+        self.toolbar.widgets["menu_utils"].widgets["sbb_monitor"].triggered.connect(
+            lambda: self._create_widget_from_toolbar(widget_name="SBBMonitor")
+        )
 
         # Icons
         self.toolbar.widgets["attach_all"].action.triggered.connect(self.attach_all)

bec_widgets/widgets/control/device_input/base_classes/device_signal_input_base.py

@@ -55,7 +55,7 @@ class DeviceSignalInputBase(BECWidget):
         self._hinted_signals = []
         self._normal_signals = []
         self._config_signals = []
-        self.bec_dispatcher.client.callbacks.register(
+        self._device_update_register = self.bec_dispatcher.client.callbacks.register(
             EventType.DEVICE_UPDATE, self.update_signals_from_filters
         )
 
@@ -289,3 +289,10 @@ class DeviceSignalInputBase(BECWidget):
         if config is None:
             return DeviceSignalInputBaseConfig(widget_class=self.__class__.__name__)
         return DeviceSignalInputBaseConfig.model_validate(config)
+
+    def cleanup(self):
+        """
+        Cleanup the widget.
+        """
+        self.bec_dispatcher.client.callbacks.remove(self._device_update_register)
+        super().cleanup()

bec_widgets/widgets/editors/sbb_monitor/register_sbb_monitor.py

@@ -0,0 +1,15 @@
+def main():  # pragma: no cover
+    from qtpy import PYSIDE6
+
+    if not PYSIDE6:
+        print("PYSIDE6 is not available in the environment. Cannot patch designer.")
+        return
+    from PySide6.QtDesigner import QPyDesignerCustomWidgetCollection
+
+    from bec_widgets.widgets.editors.sbb_monitor.sbb_monitor_plugin import SBBMonitorPlugin
+
+    QPyDesignerCustomWidgetCollection.addCustomWidget(SBBMonitorPlugin())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

bec_widgets/widgets/editors/sbb_monitor/sbb_monitor.py

@@ -0,0 +1,15 @@
+from bec_widgets.widgets.editors.website.website import WebsiteWidget
+
+
+class SBBMonitor(WebsiteWidget):
+    """
+    A widget to display the SBB monitor website.
+    """
+
+    PLUGIN = True
+    ICON_NAME = "train"
+    USER_ACCESS = []
+
+    def __init__(self, parent=None, **kwargs):
+        url = "https://free.oevplus.ch/monitor/?viewType=splitView&layout=1&showClock=true&showPerron=true&stationGroup1Title=Villigen%2C%20PSI%20West&stationGroup2Title=Siggenthal-Würenlingen&station_1_id=85%3A3592&station_1_name=Villigen%2C%20PSI%20West&station_1_quantity=5&station_1_group=1&station_2_id=85%3A3502&station_2_name=Siggenthal-Würenlingen&station_2_quantity=5&station_2_group=2"
+        super().__init__(parent=parent, url=url, **kwargs)

bec_widgets/widgets/editors/sbb_monitor/sbb_monitor.pyproject

@@ -0,0 +1 @@
+{'files': ['sbb_monitor.py']}

bec_widgets/widgets/editors/sbb_monitor/sbb_monitor_plugin.py

@@ -0,0 +1,54 @@
+# Copyright (C) 2022 The Qt Company Ltd.
+# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+from qtpy.QtDesigner import QDesignerCustomWidgetInterface
+
+from bec_widgets.utils.bec_designer import designer_material_icon
+from bec_widgets.widgets.editors.sbb_monitor.sbb_monitor import SBBMonitor
+
+DOM_XML = """
+<ui language='c++'>
+    <widget class='SBBMonitor' name='sbb_monitor'>
+    </widget>
+</ui>
+"""
+
+
+class SBBMonitorPlugin(QDesignerCustomWidgetInterface):  # pragma: no cover
+    def __init__(self):
+        super().__init__()
+        self._form_editor = None
+
+    def createWidget(self, parent):
+        t = SBBMonitor(parent)
+        return t
+
+    def domXml(self):
+        return DOM_XML
+
+    def group(self):
+        return ""
+
+    def icon(self):
+        return designer_material_icon(SBBMonitor.ICON_NAME)
+
+    def includeFile(self):
+        return "sbb_monitor"
+
+    def initialize(self, form_editor):
+        self._form_editor = form_editor
+
+    def isContainer(self):
+        return False
+
+    def isInitialized(self):
+        return self._form_editor is not None
+
+    def name(self):
+        return "SBBMonitor"
+
+    def toolTip(self):
+        return ""
+
+    def whatsThis(self):
+        return self.toolTip()

bec_widgets/widgets/plots/waveform/waveform.py

@@ -1683,9 +1683,14 @@ class Waveform(PlotBase):
                 return None
 
         if hasattr(self.scan_item, "live_data"):
-            readout_priority = self.scan_item.status_message.info["readout_priority"]  # live data
+            readout_priority = self.scan_item.status_message.info.get(
+                "readout_priority"
+            )  # live data
         else:
-            readout_priority = self.scan_item.metadata["bec"]["readout_priority"]  # history
+            readout_priority = self.scan_item.metadata["bec"].get("readout_priority")  # history
+
+        if readout_priority is None:
+            return None
 
         # Reset sync/async curve lists
         self._async_curves.clear()

docs/user/widgets/waveform/waveform_ruleset.md

@@ -0,0 +1,94 @@
+# Waveform Widget Plotting Ruleset
+
+The Waveform widget allows plotting data from scans generated within the BEC framework. Each scan produces a **scan item
+**, which includes measurement data from various devices, as well as additional metadata (e.g., devices driving the
+scan, such as `motor_x`, `motor_y`, etc.).
+
+The rules described below define how data from different devices and scans can be plotted together, depending on the
+selected `x_mode`.
+
+---
+
+## Types of Curves
+
+- **Live Curves**
+    - Continuously updated from the currently running scan.
+    - Dynamically adapt based on live data.
+
+- **History Curves**
+    - Static curves representing data from a specific completed scan (e.g., scan 110).
+    - Displayed only if compatible with the currently selected x-axis device.
+
+---
+
+## General Compatibility Rules
+
+- Data from devices within **the same scan item** can always be plotted against each other, provided they have the same
+  number of data points.
+    - Example: plotting `detector_1` against `detector_2` from scan 110 to check signal correlation is valid.
+
+- Data from **different scan items** cannot be plotted against each other.
+    - Example: plotting x-data from `motor_x` in scan 110 against y-data from `detector_1` in scan 111 is not allowed.
+
+---
+
+## Specific Rules for Each `x_mode`
+
+### 1. `x_mode='auto'` (default)
+
+- Automatically determines the device for x-axis scaling from the currently running (live) scan.
+- The primary device used for scaling is the first device listed in the current scan's `scan_report_devices` (usually a
+  positioner in the case of step scans).
+- **Live Curves**:
+    - Always plotted against the selected x-axis device from the current scan.
+- **History Curves**:
+    - Each history curve is linked to a specific scan item with scan ID.
+    - Waveform widget checks compatibility with the currently selected x-axis device from the live scan.
+    - If the selected x-axis device data exists in the history curve’s original scan item, the curve is displayed.
+    - If the selected x-axis device data does not exist in the original scan item, the history curve remains **hidden**
+      until a compatible device is selected again.
+
+_Example Scenario_:
+
+- The live scan currently uses `motor_x` as the x-axis device. Any history curve will only be displayed if its original
+  scan item contains data for `motor_x`. If not, the history curve is hidden.
+
+---
+
+### 2. `x_mode='timestamp'`
+
+- X-axis scaling is based on timestamps from each data point.
+- All curves, both live and history, are always compatible, as timestamps provide a universal and absolute reference for
+  the x-axis.
+- Curves from different scan items can appear simultaneously, regardless of the devices measured.
+
+---
+
+### 3. `x_mode='index'`
+
+- X-axis scaling uses data point indices (0, 1, 2, ..., N-1).
+- Allows plotting multiple curves of varying lengths in the same view.
+- All curves are always compatible, as indices represent relative positions, independent of device or timestamp, it is
+  up to the user to interpret the x-axis.
+
+---
+
+### 4. `x_mode='device'`
+
+- User explicitly selects a device to scale the x-axis.
+- The chosen device must exist in each curve’s respective scan item.
+- **Live Curves**:
+    - Continuously displayed if the selected device data is being measured in the current scan.
+- **History Curves**:
+    - Displayed only if the selected device exists in the scan item from which the history curve originates.
+    - Remain **hidden** if the selected device is not present in the original scan item, reappearing only when a
+      compatible device is chosen again.
+
+---
+
+## Key Technical Points
+
+- Each curve stores its own independent x and y data sets (as it is defined by `pg.PlotDataItem`, allowing simultaneous
+  plotting of multiple curves with different data lengths.
+- Compatibility checks ensure that plotting meaningful comparisons is always possible, avoiding combinations of
+  unrelated or non-compatible datasets.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bec_widgets"
-version = "2.20.0"
+version = "2.21.2"
 description = "BEC Widgets"
 requires-python = ">=3.10"
 classifiers = [

tests/unit_tests/test_device_signal_input.py

@@ -144,3 +144,12 @@ def test_signal_lineedit(device_signal_line_edit):
     assert device_signal_line_edit._is_valid_input is True
     device_signal_line_edit.setText("invalid")
     assert device_signal_line_edit._is_valid_input is False
+
+
+def test_device_signal_input_base_cleanup(qtbot, mocked_client):
+
+    widget = DeviceInputWidget(client=mocked_client)
+    widget.close()
+    widget.deleteLater()
+
+    mocked_client.callbacks.remove.assert_called_once_with(widget._device_update_register)

tests/unit_tests/test_rpc_server.py

@@ -29,4 +29,4 @@ def test_gui_server_get_service_config(gui_server):
     """
     Test that the server is started with the correct arguments.
     """
-    assert gui_server._get_service_config().config is ServiceConfig().config
+    assert gui_server._get_service_config().config == ServiceConfig().config