MTPPy2.0 0.1.5__py3-none-any.whl

mtppy/part4/automation_services/procedure_test.py

@@ -0,0 +1,185 @@
+"""Test Suite for Procedure."""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+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.part3.data_assembly_set.data_assembly import DataAssembly
+from mtppy.part4.process_values.input_elements.bin_process_value_in import BinProcessValueIn
+from mtppy.part4.process_values.input_elements.string_process_value_in import StringProcessValueIn
+from mtppy.part4.automation_services.procedure import Procedure
+from mtppy.part4.automation_services.service_elements.parameter_elements.ana_serv_param import AnaServParam
+from mtppy.part4.automation_services.service_elements.parameter_elements.bin_serv_param import BinServParam
+from mtppy.part4.automation_services.service_elements.parameter_elements.dint_serv_param import DIntServParam
+from mtppy.part4.automation_services.service_elements.parameter_elements.string_serv_param import StringServParam
+
+
+operation_elements = [
+    AnaServParam(
+        "serv_param_ana", v_min=0, v_max=50, v_scl_min=0, v_scl_max=10, v_unit=23
+    ),
+    DIntServParam(
+        "serv_param_dint", v_min=-10, v_max=10, v_scl_min=0, v_scl_max=-10, v_unit=23
+    ),
+    BinServParam("serv_param_bin", v_state_0="state_0", v_state_1="state_1"),
+    StringServParam("serv_param_str"),
+]
+
+indicator_elements = [
+    AnaView("proc_rv_ana", v_scl_min=0, v_scl_max=10, v_unit=23),
+    DIntView("proc_rv_dint", v_scl_min=0, v_scl_max=-10, v_unit=23),
+    BinView("proc_rv_bin", v_state_0="state_0", v_state_1="state_1"),
+    StringView("proc_rv_str"),
+]
+
+
+def create_dummy_procedure():
+    return Procedure(1, "DummyProcedure", "procedure for testing", False)
+
+
+def test_procedure_initialization():
+    procedure = Procedure(7, "TestProcedure", "Test description", True)
+
+    assert procedure.procedure_id == 7
+    assert procedure.name == "TestProcedure"
+    assert procedure.is_self_completing is True
+    assert procedure.procedure_parameters == {}
+    assert procedure.process_value_ins == {}
+    assert procedure.process_value_outs == {}
+    assert procedure.report_values == {}
+    assert procedure.required_equipment == {}
+
+
+def test_add_procedure_parameter_list_and_dict():
+    procedure = create_dummy_procedure()
+    parameters = [
+        AnaServParam("Parameter1", v_min=0, v_max=10, v_scl_min=0, v_scl_max=10, v_unit=23),
+        DIntServParam("Parameter2", v_min=-10, v_max=10, v_scl_min=-10, v_scl_max=10, v_unit=23),
+    ]
+
+    procedure.add_procedure_parameter(parameters)
+    procedure.add_procedure_parameter({"parameter": parameters[0]})
+
+    assert procedure.procedure_parameters == {
+        parameter.tag_name: parameter for parameter in parameters
+    }
+
+
+def test_add_procedure_parameter():
+    valid_parameters = operation_elements
+    invalid_parameters = indicator_elements
+
+    procedure = create_dummy_procedure()
+    for valid_parameter in valid_parameters:
+        procedure.add_procedure_parameter(valid_parameter)
+        assert (
+            procedure.procedure_parameters[valid_parameter.tag_name] == valid_parameter
+        )
+
+    procedure = create_dummy_procedure()
+    for invalid_parameter in invalid_parameters:
+        try:
+            procedure.add_procedure_parameter(invalid_parameter)
+            assert False
+        except TypeError:
+            assert True
+
+
+def test_add_report_values():
+    valid_parameters = indicator_elements
+    invalid_parameters = operation_elements
+
+    procedure = create_dummy_procedure()
+    for valid_parameter in valid_parameters:
+        procedure.add_report_value(valid_parameter)
+        assert procedure.report_values[valid_parameter.tag_name] == valid_parameter
+
+    procedure = create_dummy_procedure()
+    for invalid_parameter in invalid_parameters:
+        try:
+            procedure.add_report_value(invalid_parameter)
+            assert False
+        except TypeError:
+            assert True
+
+
+def test_add_value_outs():
+    valid_parameters = indicator_elements
+    invalid_parameters = operation_elements
+
+    procedure = create_dummy_procedure()
+    for valid_parameter in valid_parameters:
+        procedure.add_process_value_out(valid_parameter)
+        assert procedure.process_value_outs[valid_parameter.tag_name] == valid_parameter
+
+    procedure = create_dummy_procedure()
+    for invalid_parameter in invalid_parameters:
+        try:
+            procedure.add_process_value_out(invalid_parameter)
+            assert False
+        except TypeError:
+            assert True
+
+
+def test_add_process_value_ins_single_and_list():
+    procedure = create_dummy_procedure()
+    process_value_in = BinProcessValueIn("Input1", "Binary input")
+    process_value_ins = [
+        StringProcessValueIn("Input2", "String input"),
+        StringProcessValueIn("Input3", "Another string input"),
+    ]
+
+    procedure.add_process_value_in(process_value_in)
+    procedure.add_process_value_in(process_value_ins)
+
+    assert procedure.process_value_ins == {
+        "Input1": process_value_in,
+        "Input2": process_value_ins[0],
+        "Input3": process_value_ins[1],
+    }
+
+
+def test_add_process_value_in_rejects_wrong_type():
+    procedure = create_dummy_procedure()
+
+    try:
+        procedure.add_process_value_in(indicator_elements[0])
+        assert False
+    except TypeError:
+        assert True
+
+
+def test_add_required_equipment_single_list_dict_and_none():
+    equipment = [DataAssembly("Equipment1"), DataAssembly("Equipment2")]
+    procedure = Procedure(
+        1,
+        "ProcedureWithEquipment",
+        required_equipment={"first": equipment[0], "second": equipment[1]},
+    )
+
+    procedure.add_required_equipment(equipment)
+    procedure.add_required_equipment(None)
+
+    assert procedure.required_equipment == {
+        "Equipment1": equipment[0],
+        "Equipment2": equipment[1],
+    }
+
+
+def test_apply_procedure_parameters(monkeypatch):
+    procedure = create_dummy_procedure()
+    parameter = AnaServParam(
+        "Parameter1", v_min=0, v_max=10, v_scl_min=0, v_scl_max=10, v_unit=23
+    )
+    update_calls = []
+    monkeypatch.setattr(parameter, "update_v_out", lambda: update_calls.append(parameter))
+    procedure.add_procedure_parameter(parameter)
+
+    procedure.apply_procedure_parameters()
+
+    assert update_calls == [parameter]

mtppy/part4/automation_services/service.py

@@ -0,0 +1,463 @@
+"""Service is an abstract class implementing the concepts specified in
+PNO MTP 2.0 Part 4, Sections 8.2.
+"""
+
+__copyright__ = (
+    "Copyright (c) 2026 Dresden University of Technology, Process-to-Order Group"
+)
+__license__ = "MIT"
+
+from abc import ABC, abstractmethod
+
+from mtppy.part3.data_assembly_set.data_assembly import DataAssembly
+from mtppy.part4.automation_services.base_functions.service_operation_mode import (
+    ServiceOperationMode,
+)
+from mtppy.part4.automation_services.helpers.state_machine import StateMachine
+from mtppy.part4.automation_services.helpers.thread_control import ThreadControl
+from mtppy.part4.automation_services.procedure import Procedure
+from mtppy.part4.automation_services.service_elements.parameter_elements.parameter_element import (
+    ParameterElement,
+)
+from mtppy.part4.automation_services.service_elements.service_control import (
+    ServiceControl,
+)
+from mtppy.utils.logging import logger
+
+
+def _has_zero_id(
+    procedure: Procedure | list[Procedure | None] | dict[str, Procedure | None] | None,
+) -> bool:
+    """Check whether a procedure or procedure collection contains ID zero.
+
+    Args:
+        procedure: A procedure, a list of procedures, a mapping of procedures,
+            or ``None``.
+
+    Returns:
+        ``True`` if any supplied procedure has an ID of zero; otherwise,
+        ``False``.
+    """
+    logger.info(f"procedure={procedure}")
+    if procedure is None:  # No procedure does no harm
+        return False
+    if isinstance(procedure, dict):
+        # Check if any value in the dict has procedure_id == 0, ignoring None values
+        return any(p is not None and p.procedure_id == 0 for p in procedure.values())
+    if isinstance(procedure, list):
+        # Check if any element in the list has procedure_id == 0, ignoring None values
+        if all(p is None for p in procedure):
+            return False
+        return any(p is not None and p.procedure_id == 0 for p in procedure)
+    # For a single Procedure object
+    return procedure.procedure_id == 0
+
+
+class Service(ABC):
+    """Abstract Base class implementing the Service specification.
+
+    This abstract base class provides the foundational structure for
+    implementing services according to PNO MTP 2.0 Part 4 specifications.
+    It handles state management, procedure execution, and configuration
+    parameter handling through a state machine and thread control system.
+
+    It provides functions for all the defined states, such as
+    `idle`, `starting`, ..., `resetting`, a.s.o, that shall be implemented
+    by instantiable derivatives.
+
+
+    Attributes:
+        thread_ctrl: Thread control manager for service operations.
+        configuration_parameters: Dictionary of configuration parameters.
+        procedures: Dictionary mapping procedure IDs to Procedure objects.
+        service_control: Service control instance managing operation modes.
+        state_machine: State machine for service state transitions.
+    """
+
+    thread_ctrl: ThreadControl
+    configuration_parameters: dict[str, ParameterElement]
+    procedures: dict[int, Procedure]
+    service_control: ServiceControl
+    state_machine: StateMachine
+    tag_name: str
+
+    def __init__(self, tag_name: str, tag_description: str = "") -> None:
+        """Initialize a service instance.
+
+        Args:
+            tag_name: Tag name of the service.
+            tag_description: Optional description of the service.
+        """
+        super().__init__()
+        self.tag_name = tag_name
+        self.tag_description = tag_description
+        self.thread_ctrl = ThreadControl()
+
+        self.configuration_parameters = {}
+        self.procedures = {}
+
+        self.service_control = ServiceControl(
+            tag_name,
+            tag_description,
+            execution_procedure=self.command_execution,
+        )
+        self.state_machine = StateMachine(
+            service_control=self.service_control,
+            execution_routine=self._state_change_callback,
+        )
+
+        self.service_control.service_op_mode.add_enter_offline_callback(
+            self.state_machine.command_en_ctrl.disable_all,
+        )
+        self.service_control.service_op_mode.add_exit_offline_callback(
+            self.state_machine.command_en_ctrl.set_default,
+        )
+        self.service_control.service_op_mode.add_exit_offline_callback(
+            self.apply_configuration_parameters,
+        )
+        self.service_control.service_op_mode.add_exit_offline_callback(
+            self._init_idle_state,
+        )
+
+        self.state_machine.activate()
+
+    # Backwards compatibility
+    @property
+    def name(self) -> str:
+        """Return the service tag name.
+
+        Returns:
+            The current service tag name.
+        """
+        return self.tag_name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """Set the service tag name.
+
+        Args:
+            value: New service tag name.
+        """
+        self.tag_name = value
+
+    def command_execution(self, value: int) -> None:
+        """Forward a command to the service state machine.
+
+        Args:
+            value: Command value defined by the service control interface.
+        """
+        self.state_machine.command_execution(value)
+
+    def _init_idle_state(self) -> None:
+        """Initialize the service's idle state."""
+        logger.debug(f"Initialize service {self.tag_name}'s idle_state")
+        self._state_change_callback()
+
+    def _state_change_callback(self) -> None:
+        """Handle a service state change requested by the state machine."""
+        msg = f"{self.tag_name},som={self.service_control.service_op_mode.items()}"
+        logger.info(msg)
+
+        if self.service_control.service_op_mode[ServiceOperationMode.STATE_OFF_ACT]:
+            logger.info(
+                f"service {self.tag_name} not initializable, StateOffAct = True",
+            )
+            return
+
+        state_str = self.state_machine.get_current_state_str()
+        logger.info(f"{self.tag_name} in state={state_str}")
+        if state_str != "undefined":
+            if state_str == "starting":  # PNO MTP 2.0 Part 4, Section 8.2.4.4
+                # we assume that service_control did set Procedure_Cur
+                self.apply_procedure_parameters()
+
+            function_to_execute = getattr(self, state_str)
+            self.thread_ctrl.request_state(state_str, function_to_execute)
+            self.thread_ctrl.reallocate_running_thread()
+
+        if state_str == "idle":
+            self.service_control.service_op_mode.allow_switch_to_offline_mode(
+                allow_flag=True,
+            )
+        else:
+            self.service_control.service_op_mode.allow_switch_to_offline_mode(
+                allow_flag=False,
+            )
+
+    def is_state(self, state_str: str) -> bool:
+        """Check whether the service is in a specified state.
+
+        If the current state differs, the running thread is reallocated.
+
+        Args:
+            state_str: State name to compare with the current state.
+
+        Returns:
+            ``True`` if the service is in ``state_str``; otherwise, ``False``.
+        """
+        if state_str == self.state_machine.get_current_state_str():
+            return True
+        self.thread_ctrl.reallocate_running_thread()
+        return False
+
+    def state_change(self) -> None:
+        """Request a state change from a cyclic state to the next one."""
+        self.state_machine.state_change()
+
+    def get_param(self, param_name: str) -> DataAssembly | None:
+        """Return a named item from the current procedure.
+
+        Args:
+            param_name: Name of the procedure parameter or value to retrieve.
+
+        Returns:
+            The matching data assembly, or ``None`` if no item has that name.
+
+        Raises:
+            RuntimeError: If the service has no current procedure.
+        """
+        proc: Procedure = self.get_current_procedure()
+        if param_name in proc.procedure_parameters:
+            return proc.procedure_parameters[param_name]
+        if param_name in proc.process_value_ins:
+            return proc.process_value_ins[param_name]
+        if param_name in proc.process_value_outs:
+            return proc.process_value_outs[param_name]
+        if param_name in proc.report_values:
+            return proc.report_values[param_name]
+        if param_name in proc.required_equipment:
+            return proc.required_equipment[param_name]
+        return None
+
+    def add_configuration_parameter(
+        self,
+        configuration_parameter: ParameterElement,
+    ) -> None:
+        """Add a configuration parameter to the service.
+
+        Args:
+            configuration_parameter: Parameter to add, keyed by its tag name.
+        """
+        self.configuration_parameters[configuration_parameter.tag_name] = (
+            configuration_parameter
+        )
+
+    def apply_configuration_parameters(self) -> None:
+        """Apply all configuration parameters to the service.
+
+        Each parameter is updated through its ``update_v_out`` method.
+        """
+        logger.debug(f"values={self.configuration_parameters.values()}")
+        for configuration_parameter in self.configuration_parameters.values():
+            configuration_parameter: ParameterElement
+            configuration_parameter.update_v_out()
+
+    def add_procedure(
+        self,
+        procedure: (
+            Procedure | list[Procedure | None] | dict[str, Procedure | None] | None
+        ),
+    ) -> None:
+        """Add one or more procedures to the service.
+
+        Args:
+            procedure: A procedure, a list of procedures, a mapping of names to
+                procedures, or ``None``.
+
+        Raises:
+            ValueError: If any procedure has an ID of zero.
+        """
+        if procedure is None:
+            return
+        if _has_zero_id(procedure):
+            msg = "Bad ProcedureID, shall not be 0"
+            raise ValueError(msg)
+        if isinstance(procedure, dict):
+            for proc in procedure.values():
+                if proc is not None:
+                    self.procedures[proc.procedure_id] = proc
+                    self.service_control.add_procedure_key(proc.procedure_id)
+        elif isinstance(procedure, list):
+            for proc in procedure:
+                if proc is not None:
+                    self.procedures[proc.procedure_id] = proc
+                    self.service_control.add_procedure_key(proc.procedure_id)
+        else:
+            self.procedures[procedure.procedure_id] = procedure
+            self.service_control.add_procedure_key(procedure.procedure_id)
+
+    def _lookup_procedure_cur_name(self) -> str:
+        """Return the name of the currently selected procedure.
+
+        Returns:
+            The current procedure name, or ``"undefined"`` when no procedure
+            is selected.
+        """
+        procedure_cur: int = self.service_control.get_procedure_cur()
+        if procedure_cur == 0:
+            return "undefined"
+        procedure_name = self.procedures[procedure_cur].name
+        logger.debug(
+            f"procedureCur={procedure_cur}, procedure_name={procedure_name}",
+        )
+        return procedure_name
+
+    def get_current_procedure(self) -> Procedure:
+        """Return the currently selected procedure.
+
+        Returns:
+            The procedure selected by ``PROCEDURE_CUR``.
+
+        Raises:
+            RuntimeError: If no current procedure is selected.
+        """
+        procedure_cur: int = self.service_control.get_procedure_cur()
+        if procedure_cur == 0:
+            msg = "No current procedure selected"
+            raise RuntimeError(msg)
+        return self.procedures[procedure_cur]
+
+    def _get_procedures(self) -> dict[int, Procedure]:
+        """Return the service's procedure mapping.
+
+        Returns:
+            A mapping from procedure IDs to procedure objects.
+        """
+        return self.procedures
+
+    def apply_procedure_parameters(self) -> None:
+        """Apply parameters for the currently selected procedure."""
+        msg = f"Applying procedure parameters for service={self.name}"
+        logger.debug(msg)
+
+        current_procedure_id: int = self.service_control.get_procedure_cur()
+        if current_procedure_id > 0:
+            self.procedures[current_procedure_id].apply_procedure_parameters()
+
+    @abstractmethod
+    def idle(self) -> bool:
+        """Execute idle state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def starting(self) -> bool:
+        """Execute starting state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def execute(self) -> bool:
+        """Execute execution state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def completing(self) -> bool:
+        """Execute completing state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def completed(self) -> bool:
+        """Execute completed state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def pausing(self) -> bool:
+        """Execute pausing state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def paused(self) -> bool:
+        """Execute paused state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def resuming(self) -> bool:
+        """Execute resuming state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def holding(self) -> bool:
+        """Execute holding state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def held(self) -> bool:
+        """Execute held state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def unholding(self) -> bool:
+        """Execute unholding state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def stopping(self) -> bool:
+        """Execute stopping state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def stopped(self) -> bool:
+        """Execute stopped state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def aborting(self) -> bool:
+        """Execute aborting state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def aborted(self) -> bool:
+        """Execute aborted state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """
+
+    @abstractmethod
+    def resetting(self) -> bool:
+        """Execute resetting state logic.
+
+        Returns:
+            ``True`` if the state transition is successful; otherwise, ``False``.
+        """

mtppy/part4/automation_services/service_elements/__init__.py

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

mtppy/part4/automation_services/service_elements/parameter_elements/__init__.py

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