MTPPy2.0 0.1.5__py3-none-any.whl

mtppy/pea/mtp_generator/mtp_generator_test.py

@@ -0,0 +1,518 @@
+"""test suite for the mtp_generator."""
+
+# ruff: noqa: S101
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+import time
+import random
+import xml.etree.ElementTree as ET
+from types import SimpleNamespace
+
+import pytest
+
+from mtppy.pea.pea import PEA
+from mtppy.pea.mtp_generator.mtp_generator import MTPGenerator
+from mtppy.part5.definitions.w3c_xml_data_types import W3cXmlDataTypes
+from mtppy.part3.data_assembly_set.active_elements.pid.pid_ctrl import PIDCtrl
+from mtppy.part3.data_assembly_set.indicator_elements.views.ana_view import AnaView
+from mtppy.part3.data_assembly_set.indicator_elements.views.bin_view import BinView
+from mtppy.part3.data_assembly_set.indicator_elements.views.dint_view import DIntView
+from mtppy.part3.data_assembly_set.indicator_elements.views.string_view import (
+    StringView,
+)
+from mtppy.part4.automation_services.service import Service
+from mtppy.part4.automation_services.procedure import Procedure
+from mtppy.part4.automation_services.service_elements.service_control import (
+    ServiceControl,
+)
+from mtppy.part4.automation_services.service_elements.parameter_elements.dint_serv_param import (
+    DIntServParam,
+)
+from mtppy.part6.alarm_set.alarm import Alarm
+
+
+class RandomNumberGenerator(Service):
+    def __init__(self, tag_name, tag_description):
+        super().__init__(tag_name, tag_description)
+
+        # Procedure definition
+        proc_0 = Procedure(1, "cont", is_self_completing=False)
+
+        # Adding two procedure parameters
+        proc_0.add_procedure_parameter(
+            DIntServParam(
+                "lower_bound", v_min=0, v_max=100, v_scl_min=0, v_scl_max=100, v_unit=23
+            )
+        )
+        proc_0.add_procedure_parameter(
+            DIntServParam(
+                "upper_bound", v_min=0, v_max=100, v_scl_min=0, v_scl_max=100, v_unit=23
+            )
+        )
+
+        # Adding procedure report value
+        proc_0.add_report_value(
+            AnaView("generated_value", v_scl_min=0, v_scl_max=100, v_unit=23),
+        )
+
+        # Allocating procedure to the service
+        self.add_procedure(proc_0)
+
+    def idle(self):
+        print("- Idle -")
+        cycle = 0
+        while self.is_state("idle"):
+            print(f"Idle cycle {cycle}")
+            print("Doing nothing...")
+            cycle += 1
+            time.sleep(1)
+
+    def starting(self):
+        print("- Starting -")
+        print("Applying procedure parameters...")
+        self.state_change()
+
+    def execute(self):
+        print("- Execute -")
+        cycle = 0
+        while self.is_state("execute"):
+            print(f"Execute cycle {cycle}")
+
+            # Read procedure parameters
+            lower_bound = (
+                self.service_control.procedures[0]
+                .procedure_parameters["lower_bound"]
+                .get_v_out()
+            )
+            upper_bound = (
+                self.service_control.procedures[0]
+                .procedure_parameters["upper_bound"]
+                .get_v_out()
+            )
+
+            # Execute random number generation
+            generated_number = random.randint(lower_bound, upper_bound)
+
+            # Return report value
+            self.service_control.procedures[0].report_values["generated_value"].set_v(
+                generated_number
+            )
+
+            cycle += 1
+            time.sleep(0.1)
+
+    def completing(self):
+        self.state_change()
+
+    def completed(self):
+        pass
+
+    def pausing(self):
+        pass
+
+    def paused(self):
+        pass
+
+    def resuming(self):
+        pass
+
+    def holding(self):
+        pass
+
+    def held(self):
+        pass
+
+    def unholding(self):
+        pass
+
+    def stopping(self):
+        pass
+
+    def stopped(self):
+        pass
+
+    def aborting(self):
+        pass
+
+    def aborted(self):
+        pass
+
+    def resetting(self):
+        print("- Resetting -")
+        self.state_change()
+
+
+def init_empty_pea():
+    pea = PEA(endpoint="opc.tcp://localhost:4060/")
+
+    # Service definition
+    service_1 = RandomNumberGenerator(
+        "rand_num_gen", "This services generates random number"
+    )
+    pea.add_service(service_1)
+
+    # Active element
+    pid_ctrl = PIDCtrl("pid_ctrl")
+    pea.add_data_assembly(pid_ctrl)
+
+    return pea
+
+
+def test_mtp_generator():
+    pea = init_empty_pea()
+    try:
+        pea.start()
+        mtp_generator = MTPGenerator()
+        mtp_generator.generate(pea)
+    finally:
+        pea.pea_opcua_server.opcua_server.stop()
+        time.sleep(1)
+
+
+def _capture_manifest(pea: PEA) -> ET.Element:
+    """Generate and parse the manifest without writing an MTP archive."""
+    mtp_generator = MTPGenerator()
+    captured: list[bytes] = []
+
+    def capture(content: bytes, **_kwargs: object) -> None:
+        captured.append(content)
+
+    mtp_generator._mtp_writer.write_mtp = capture  # noqa: SLF001
+    mtp_generator.generate(pea)
+
+    assert len(captured) == 1
+    return ET.fromstring(captured[0])  # noqa: S314
+
+
+def _required_element(parent: ET.Element, path: str) -> ET.Element:
+    """Return a required XML element with a useful assertion failure."""
+    element = parent.find(path)
+    assert element is not None, f"Missing generated element: {path}"
+    return element
+
+
+def test_generate_serializes_alarm_set_base_with_resolved_links() -> None:
+    """Generated Base alarms link their group, trigger and message targets."""
+    pea = PEA()
+    trigger_assembly = BinView("LevelHigh")
+    trigger_item = trigger_assembly.get_item(BinView.V_)
+    # Model the existing node hosted by the PEA OPC UA server. This is not a
+    # connection to an external OPC UA device.
+    trigger_item.comm_obj = SimpleNamespace(
+        _node_id=SimpleNamespace(
+            nodeid=SimpleNamespace(Identifier="LevelHigh.V"),
+        ),
+    )
+    pea.add_data_assembly(trigger_assembly)
+    pea.add_alarm(
+        Alarm(
+            tag_name="LevelHigh.Alarm",
+            data_assembly=trigger_assembly,
+            trigger=trigger_item,
+            trigger_value=True,
+            message="Level is too high.",
+            ack_required=True,
+            severity=500,
+        ),
+    )
+
+    root = _capture_manifest(pea)
+    data_assembly = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='DataAssemblies']/"
+        "{*}InternalElement[@Name='LevelHigh']",
+    )
+    trigger = _required_element(
+        data_assembly,
+        "{*}Attribute[@Name='V']",
+    )
+    alarm_group = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='Alarms']/"
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/AlarmGroup']",
+    )
+    alarm = _required_element(
+        alarm_group,
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/Alarm']",
+    )
+    message = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='Texts']/"
+        "{*}InternalElement["
+        "@RefBaseSystemUnitPath='MTPTextSUCLib/TextDefinition/AlarmMessage']",
+    )
+    alarm_text = _required_element(
+        message,
+        "{*}InternalElement["
+        "@RefBaseSystemUnitPath="
+        "'MTPTextSUCLib/TextDefinition/AlarmMessage/AlarmText']",
+    )
+
+    assert alarm_group.get("Name") == "LevelHigh_AlarmGroup"
+    assert alarm_group.findtext("{*}Attribute[@Name='RefID']/{*}Value") == (
+        data_assembly.findtext("{*}Attribute[@Name='RefID']/{*}Value")
+    )
+    assert alarm.get("Name") == "LevelHigh.Alarm"
+    assert alarm.findtext("{*}Attribute[@Name='AckRequired']/{*}Value") == "true"
+    assert alarm.findtext("{*}Attribute[@Name='Severity']/{*}Value") == "500"
+    assert alarm.findtext("{*}Attribute[@Name='Trigger']/{*}Value") == trigger.get(
+        "ID",
+    )
+    assert trigger.get("AttributeDataType") == "xs:string"
+    assert alarm.findtext("{*}Attribute[@Name='TriggerValue']/{*}Value") == ("true")
+    assert alarm.findtext("{*}Attribute[@Name='MessageRef']/{*}Value") == (
+        message.get("ID")
+    )
+    assert alarm_text.findtext("{*}Attribute[@Name='Text']/{*}Value") == (
+        "Level is too high."
+    )
+
+    trigger_reference = _required_element(
+        alarm,
+        "{*}Attribute[@Name='Trigger']",
+    )
+    message_reference = _required_element(
+        alarm,
+        "{*}Attribute[@Name='MessageRef']",
+    )
+    trigger_value = _required_element(
+        alarm,
+        "{*}Attribute[@Name='TriggerValue']",
+    )
+    classification = _required_element(
+        alarm,
+        "{*}Attribute[@Name='Classification']",
+    )
+    assert trigger_reference.get("RefAttributeType") == (
+        "MTPATLib/IDReferenceType/IDLinkAttributeType"
+    )
+    assert message_reference.get("RefAttributeType") == (
+        "MTPTextATLib/TextRefAttributeType"
+    )
+    assert trigger_value.get("AttributeDataType") == "xs:boolean"
+    assert classification.get("RefAttributeType") == (
+        "AutomationMLBaseAttributeTypeLib/OrderedListType"
+    )
+
+    object_ids = {element.get("ID") for element in root.iter() if element.get("ID")}
+    assert trigger_reference.findtext("{*}Value") in object_ids
+    assert message_reference.findtext("{*}Value") in object_ids
+    pea_server_reference = trigger.findtext("{*}Value")
+    pea_server_item = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='ServerAssemblies']/"
+        "{*}InternalElement/"
+        f"{{*}}ExternalInterface[@ID='{pea_server_reference}']",
+    )
+    assert pea_server_item.findtext(
+        "{*}Attribute[@Name='Identifier']/{*}Value",
+    ) == ("LevelHigh.V")
+    assert alarm.find("{*}Attribute[@Name='AlarmMgmtRef']") is None
+    assert (
+        alarm.find(
+            "{*}SupportedRoleClass[@RefRoleClassPath='MTPAlarmRCLib/IsManaged']",
+        )
+        is None
+    )
+    assert (
+        root.find(
+            ".//{*}InternalElement["
+            "@RefBaseSystemUnitPath="
+            "'MTPDataAssemblySUCLib/DataAssembly/AlarmElement/AlarmMgmt']",
+        )
+        is None
+    )
+
+
+def test_generate_rejects_alarm_with_unregistered_data_assembly() -> None:
+    """Generator fails instead of emitting a dangling AlarmGroup RefID."""
+    pea = PEA()
+    trigger_assembly = BinView("NotRegistered")
+    pea.add_alarm(
+        Alarm(
+            tag_name="NotRegistered.Alarm",
+            data_assembly=trigger_assembly,
+            trigger=trigger_assembly.get_item(BinView.V_),
+            trigger_value=True,
+            message="Unregistered trigger.",
+            ack_required=False,
+            severity=100,
+        ),
+    )
+    mtp_generator = MTPGenerator()
+    mtp_generator._mtp_writer.write_mtp = lambda *_args, **_kwargs: None  # noqa: SLF001
+
+    with pytest.raises(ValueError, match="registered DataAssembly"):
+        mtp_generator.generate(pea)
+
+
+def test_generate_revalidates_mutated_alarm_trigger_type() -> None:
+    """Generator rejects an Alarm whose mutable DataItem changed after creation."""
+    pea = PEA()
+    trigger_assembly = BinView("Mutated")
+    alarm = Alarm(
+        tag_name="Mutated.Alarm",
+        data_assembly=trigger_assembly,
+        trigger=trigger_assembly.get_item(BinView.V_),
+        trigger_value=True,
+        message="Mutated trigger.",
+        ack_required=False,
+        severity=100,
+    )
+    pea.add_data_assembly(trigger_assembly)
+    pea.add_alarm(alarm)
+    alarm.trigger.w3c_xml_data_type = W3cXmlDataTypes.FLOAT
+    mtp_generator = MTPGenerator()
+    mtp_generator._mtp_writer.write_mtp = lambda *_args, **_kwargs: None  # noqa: SLF001
+
+    with pytest.raises(TypeError, match="trigger type"):
+        mtp_generator.generate(pea)
+
+
+def test_alarm_links_stay_with_multiply_registered_data_assembly() -> None:
+    """Alarm group and trigger links resolve within the same DataAssembly."""
+    pea = PEA()
+    service = RandomNumberGenerator(
+        "DuplicatedService",
+        "Service control registered through two public paths",
+    )
+    target = service.service_control
+    trigger = target.get_item(ServiceControl.PROC_PARAM_APPLY_EN)
+    pea.add_data_assembly(target)
+    pea.add_service(service)
+    pea.add_alarm(
+        Alarm(
+            tag_name="DuplicatedService.Alarm",
+            data_assembly=target,
+            trigger=trigger,
+            trigger_value=False,
+            message="Duplicate target.",
+            ack_required=False,
+            severity=100,
+        ),
+    )
+
+    root = _capture_manifest(pea)
+    data_assemblies = root.findall(
+        ".//{*}InstanceHierarchy[@Name='DataAssemblies']/"
+        "{*}InternalElement[@Name='DuplicatedService']",
+    )
+    alarm_group = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='Alarms']/"
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/AlarmGroup']",
+    )
+    alarm = _required_element(
+        alarm_group,
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/Alarm']",
+    )
+    group_ref = alarm_group.findtext("{*}Attribute[@Name='RefID']/{*}Value")
+    trigger_id = alarm.findtext("{*}Attribute[@Name='Trigger']/{*}Value")
+    referenced_assemblies = [
+        assembly
+        for assembly in data_assemblies
+        if assembly.findtext("{*}Attribute[@Name='RefID']/{*}Value") == group_ref
+    ]
+
+    assert len(referenced_assemblies) == 1
+    assert (
+        referenced_assemblies[0].find(
+            f"{{*}}Attribute[@ID='{trigger_id}']",
+        )
+        is not None
+    )
+
+
+def test_generate_groups_alarms_by_referenced_data_assembly() -> None:
+    """Alarms sharing a DataAssembly share one generated AlarmGroup."""
+    pea = PEA()
+    first_assembly = BinView("First")
+    second_assembly = BinView("Second")
+    pea.add_data_assembly(first_assembly)
+    pea.add_data_assembly(second_assembly)
+    for tag_name, assembly, trigger_value in (
+        ("First.High", first_assembly, True),
+        ("First.Normal", first_assembly, False),
+        ("Second.High", second_assembly, True),
+    ):
+        pea.add_alarm(
+            Alarm(
+                tag_name=tag_name,
+                data_assembly=assembly,
+                trigger=assembly.get_item(BinView.V_),
+                trigger_value=trigger_value,
+                message=f"{tag_name} message.",
+                ack_required=False,
+                severity=100,
+            ),
+        )
+
+    root = _capture_manifest(pea)
+    alarm_hierarchy = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='Alarms']",
+    )
+    groups = alarm_hierarchy.findall(
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/AlarmGroup']",
+    )
+    assert {group.get("Name") for group in groups} == {
+        "First_AlarmGroup",
+        "Second_AlarmGroup",
+    }
+    alarm_counts = {
+        group.get("Name"): len(
+            group.findall(
+                "{*}InternalElement[" "@RefBaseSystemUnitPath='MTPAlarmSUCLib/Alarm']",
+            ),
+        )
+        for group in groups
+    }
+    assert alarm_counts == {"First_AlarmGroup": 2, "Second_AlarmGroup": 1}
+
+    first_data_assembly = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='DataAssemblies']/"
+        "{*}InternalElement[@Name='First']",
+    )
+    assert len(first_data_assembly.findall("{*}Attribute[@Name='V']")) == 1
+
+
+@pytest.mark.parametrize(
+    ("assembly_type", "trigger_value", "xml_type"),
+    [(DIntView, 12, "xs:short"), (StringView, "ALARM", "xs:string")],
+)
+def test_generate_preserves_trigger_value_xml_type(
+    assembly_type: type[DIntView] | type[StringView],
+    trigger_value: int | str,
+    xml_type: str,
+) -> None:
+    """TriggerValue carries the concrete W3C type of integer and string data."""
+    pea = PEA()
+    trigger_assembly = assembly_type("TypedTrigger")
+    pea.add_data_assembly(trigger_assembly)
+    pea.add_alarm(
+        Alarm(
+            tag_name="TypedTrigger.Alarm",
+            data_assembly=trigger_assembly,
+            trigger=trigger_assembly.get_item(trigger_assembly.V_),
+            trigger_value=trigger_value,
+            message="Typed trigger.",
+            ack_required=False,
+            severity=100,
+        ),
+    )
+
+    root = _capture_manifest(pea)
+    trigger_value_attribute = _required_element(
+        root,
+        ".//{*}InstanceHierarchy[@Name='Alarms']/"
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/AlarmGroup']/"
+        "{*}InternalElement[@RefBaseSystemUnitPath='MTPAlarmSUCLib/Alarm']/"
+        "{*}Attribute[@Name='TriggerValue']",
+    )
+    assert trigger_value_attribute.get("AttributeDataType") == xml_type
+    assert trigger_value_attribute.findtext("{*}Value") == str(trigger_value)

mtppy/pea/pea.py

@@ -0,0 +1,139 @@
+"""The PEA (Process Equipment Assembly)."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from mtppy.pea.pea_opcua_server.opcua_options_provider.instances.basic_opcua_options_provider import (
+    BasicOPCUAOptionsProvider,
+)
+from mtppy.pea.pea_opcua_server.pea_opcua_server import PeaOPCUAServer
+from mtppy.pea.pea_opcua_server.subscription_list import SubscriptionList
+
+from mtppy.part3.data_assembly_set.data_assembly import DataAssembly
+from mtppy.part3.data_assembly_set.indicator_elements.indicator_element import (
+    IndicatorElement,
+)
+from mtppy.part3.data_assembly_set.pea_elements.pea_information_label.pea_information_label import (
+    PeaInformationLabel,
+)
+from mtppy.part4.process_values.input_elements.input_element import InputElement
+from mtppy.part4.automation_services.service import Service
+from mtppy.part6.alarm_set.alarm import Alarm
+
+from mtppy.utils.data_assembly_dict import DataAssemblyDict
+
+
+class PEA:
+    """Main Process Equipment Assembly (PEA) class.
+
+    The PEA class serves as the central coordinator for managing all aspects of a
+    Process Element Assembly, including data assemblies, process values, services,
+    and OPC UA server functionality. It provides methods to add components and control
+    the overall operation of the PEA system.
+
+    Attributes:
+        service_set: Dictionary of service instances managed by this PEA
+        data_assemblies: Dictionary of data assemblies managed by this PEA
+        process_value_ins: Dictionary of input process values managed by this PEA
+        process_value_outs: Dictionary of output process values managed by this PEA
+        alarms: Dictionary of alarm instances managed by this PEA
+        endpoint: OPC UA server endpoint address
+        opcua_options_provider: Provider for OPC UA server options
+        pea_opcua_server: OPC UA server instance for this PEA
+        subscription_list: List of active subscriptions
+        web_server_url: URL for web server access
+        pea_information_label: Information label containing PEA metadata
+    """
+
+    def __init__(self, endpoint: str = "opc.tcp://localhost:4840/") -> None:
+        """Initializes the PEA with default or specified OPC UA endpoint.
+
+        Args:
+            endpoint: Endpoint of the OPC UA server. If not specified, opc.tcp://localhost:4840/ is used.
+        """
+        self.service_set = DataAssemblyDict(Service)
+        self.data_assemblies = DataAssemblyDict(DataAssembly)
+        self.process_value_ins = DataAssemblyDict(InputElement)
+        self.process_value_outs = DataAssemblyDict(IndicatorElement)
+        self.alarms = DataAssemblyDict(Alarm)
+        self.endpoint = endpoint
+        self.opcua_options_provider = BasicOPCUAOptionsProvider()
+        self.pea_opcua_server = PeaOPCUAServer(
+            self.opcua_options_provider, self.endpoint
+        )
+        self.subscription_list = SubscriptionList()
+        self.web_server_url = None
+
+        self.pea_information_label = PeaInformationLabel("PeaInformationLabel", "")
+
+    def add_data_assembly(
+        self,
+        data_assembly: DataAssembly | list[DataAssembly] | dict[str, DataAssembly],
+    ) -> None:
+        """Add a DataAssembly to the PEA.
+
+        Args:
+            data_assembly: The DataAssembly instance to add
+        """
+        self.data_assemblies.add(data_assembly)
+
+    def add_alarm(self, alarm: Alarm) -> None:
+        """Add a static AlarmSet.Base alarm to the PEA.
+
+        Args:
+            alarm: Alarm description to register.
+
+        Raises:
+            TypeError: If alarm is not an Alarm instance.
+            ValueError: If an alarm with the same tag name is already registered.
+        """
+        if not isinstance(alarm, Alarm):
+            msg = f"{getattr(alarm, 'tag_name', repr(alarm))} is not an Alarm"
+            raise TypeError(msg)
+        if alarm.tag_name in self.alarms:
+            msg = f"Alarm {alarm.tag_name!r} is already registered"
+            raise ValueError(msg)
+        self.alarms.add(alarm)
+
+    def add_process_value_in(self, process_value_in: InputElement):
+        """Add an input ProcessValue to the PEA.
+
+        Args:
+            process_value_in: The InputElement instance to add as input process value
+        """
+        self.process_value_ins.add(process_value_in)
+
+    def add_process_value_out(self, process_value_out: IndicatorElement):
+        """Add an output ProcessValue to the PEA.
+
+        Args:
+            process_value_out: The output process value to add.
+        """
+        self.process_value_outs.add(process_value_out)
+
+    def add_service(self, service: Service):
+        """Add a Service to the PEA.
+
+        Args:
+            service: The Service instance to add
+        """
+        self.service_set.add(service)
+
+    def start(self):
+        """Start the OPC UA server instance and begin PEA operation.
+
+        Initializes and starts the OPC UA server with the configured data assemblies
+        and services, making the PEA available for communication and operation.
+        """
+        self.pea_opcua_server.init_opcua_server()
+        self.pea_opcua_server.run_opcua_server(self.data_assemblies, self.service_set)
+
+    def stop(self):
+        """Stop the OPC UA server instance and shut down PEA operation.
+
+        Stops the OPC UA server and performs cleanup operations to properly
+        terminate the PEA's operation.
+        """
+        self.pea_opcua_server.opcua_server.stop()

mtppy/pea/pea_opcua_server/__init__.py

@@ -0,0 +1,4 @@
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"