OpenSMI-Core 0.1__py3-none-any.whl

opensmi/core/subscription_manager.py

@@ -0,0 +1,190 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import contextlib
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import Any
+
+import structlog
+from asyncua import ua
+from asyncua.client.client import Client
+from asyncua.common.node import Node
+from asyncua.common.subscription import DataChangeNotif, Subscription
+from asyncua.ua import NodeId, UaStatusCodeError
+from asyncua.ua.uaerrors import BadAttributeIdInvalid
+
+from opensmi.core.protocols import UaEvent
+
+
+class UaDataChangeSubscriber(ABC):
+    """Interface for OPC UA data change subscribers."""
+
+    @abstractmethod
+    async def ua_on_data_change(self, node: Node, val: Any, data: DataChangeNotif) -> None:
+        """Handle OPC UA node data change notification."""
+
+
+class UaEventSubscriber(ABC):
+    """Interface for OPC UA event subscribers."""
+
+    @abstractmethod
+    async def ua_on_event(self, ua_event: UaEvent) -> None:
+        """Handle OPC UA event notification."""
+
+
+class SubscriptionManager:
+    """Centrally manages all OPC UA subscription needs.
+
+    It bundles subscriptions using only one subscription to an OPC UA server
+    to not stay within max. subscription limits of certain OPC UA servers.
+    """
+
+    _ua_client: Client
+    _ua_subscription: Subscription
+
+    def __init__(self) -> None:
+        """Create a new instance."""
+        self._data_subscription_map: dict[NodeId, list[UaDataChangeSubscriber]] = {}
+        """ Maps a OPC UA node to a list of handlers for data change notifications. """
+        self._event_subscription_map: dict[NodeId, list[UaEventSubscriber]] = {}
+        """ Maps a OPC UA node to a list of handlers for event notifications. """
+
+        self.period: float = 100
+        """Publishing interval in milliseconds for OPC UA subscription."""
+
+        self.logger = structlog.getLogger("opensmi.SubscriptionManager")
+
+    async def _create_subscription(self, ua_client: Client):
+        self._ua_subscription = await ua_client.create_subscription(period=self.period, handler=self)
+        self.logger.info("Created subscription!", parameters=self._ua_subscription.parameters)
+
+    async def init(self, ua_client: Client, period: float = 100) -> None:
+        self.period = period
+        self._ua_client = ua_client
+        await self._create_subscription(ua_client)
+
+        # subscribe to a node that always changes reliably, for example the current time of the server
+        # this is done to prevent the subscription from timing out
+        current_time_node = ua_client.get_node(ua.object_ids.ObjectIds.Server_ServerStatus_CurrentTime)
+        await self.subscribe_data_change(self, current_time_node)  # pyright: ignore[reportArgumentType]
+
+    # async def renew_subscriptions(self, ua_client: Client) -> None:
+    #     self.logger.info(f"Renewing {self.no_of_monitored_items} subscriptions...")
+    #     old_data_subscription_map = self._data_subscription_map.copy()
+    #     old_event_subscription_map = self._event_subscription_map.copy()
+    #
+    #     await self.clear_subscriptions()
+    #     await self._create_subscription(ua_client)
+    #
+    #     # add all old data change subscriptions back
+    #     for node_id, handlers in old_data_subscription_map.items():
+    #         for handler in handlers:
+    #             await self.subscribe_data_change(handler=handler, nodes=[ua_client.get_node(node_id)])
+    #
+    #     # add all old event subscriptions back
+    #     for node_id, handlers in old_event_subscription_map.items():
+    #         for handler in handlers:
+    #             await self.subscribe_event(handler=handler, source_node=node_id)
+
+    async def clear_subscriptions(self) -> None:
+        self.logger.info(f"Clearing {self.no_of_monitored_items} subscriptions...")
+        try:
+            await self._ua_subscription.delete()
+            self.logger.info("Deleted main OPC UA subscription!")
+        except ConnectionError:
+            pass  # we can safely ignore it since is no longer relevant
+        except AttributeError:
+            pass  # we can safely ignore it since there is no subscription to delete
+        except Exception as err:
+            self.logger.exception("Could not delete main OPC UA subscription!", reason=err)
+
+        with contextlib.suppress(NameError, AttributeError):
+            del self._ua_subscription
+
+        self._data_subscription_map.clear()
+        self._event_subscription_map.clear()
+
+    @property
+    def no_of_monitored_items(self) -> int:
+        """Return the number of monitored nodes."""
+        return len(self._data_subscription_map) + len(self._event_subscription_map)
+
+    async def subscribe_data_change(
+        self, handler: UaDataChangeSubscriber, nodes: Node | NodeId | Iterable[Node | NodeId]
+    ) -> None:
+        """Add given handler to receive data change notifications for given nodes."""
+        if not isinstance(nodes, Iterable):
+            nodes = [nodes]  # create a list out of the given single node or node id
+
+        for node in nodes:
+            if isinstance(node, NodeId):
+                node = self._ua_client.get_node(node)
+
+            if node.nodeid not in self._data_subscription_map:
+                self._data_subscription_map[node.nodeid] = []
+                try:
+                    await self._ua_subscription.subscribe_data_change(node)
+                    self._data_subscription_map[node.nodeid].append(handler)
+                    self.logger.debug("Added data change handler", handler=handler, node=node.nodeid.to_string())
+                except BadAttributeIdInvalid:
+                    self.logger.warning("Node does not support subscription!", node=node.nodeid.to_string())
+                except UaStatusCodeError as err:
+                    self.logger.exception("Unexpected UA error!", err=err)
+            else:
+                # We only need 1 subscription for n handlers.
+                self.logger.debug(
+                    "Added data change handler, reusing existing subscription.",
+                    handler=handler,
+                    node=node.nodeid.to_string(),
+                )
+                self._data_subscription_map[node.nodeid].append(handler)
+
+    async def subscribe_event(self, handler: UaEventSubscriber, source_node: Node | NodeId) -> None:
+        """Add given handler to receive event notifications for given node."""
+        # we only get the node ID in the notification
+        if isinstance(source_node, Node):
+            node_id: NodeId = source_node.nodeid
+        elif isinstance(source_node, NodeId):
+            node_id = source_node
+        else:
+            msg = f"Given source_node {source_node} is not supported!"
+            raise TypeError(msg)
+
+        if source_node not in self._event_subscription_map:
+            self._event_subscription_map[node_id] = []
+
+        await self._ua_subscription.subscribe_events(sourcenode=source_node)
+        self._event_subscription_map[node_id].append(handler)
+
+    ###########################################
+    # asyncua callbacks
+
+    async def datachange_notification(self, node: Node, val: Any, data: DataChangeNotif) -> None:
+        """Handle OPC UA data change notifications callback."""
+        try:
+            for handler in self._data_subscription_map[node.nodeid]:  # list of handlers
+                if handler == self:
+                    continue  # current time, not required for anything specific
+                await handler.ua_on_data_change(node, val, data)
+        except KeyError:
+            self.logger.warning(
+                "Received DataChange Notification with no handlers", key=node.nodeid.to_string(), value=val
+            )
+
+    async def status_change_notification(self, status: ua.StatusChangeNotification) -> None:
+        """Handle OPC UA status notifications callback."""
+        self.logger.info("Received status change notification", status=status)
+
+    async def event_notification(self, ua_event: UaEvent) -> None:
+        """Handle OPC UA event notifications callback."""
+        # TODO(CaHa): ua_event.emitting_node is always i=2253 (=Server)
+        # might be an asyncua problem
+        try:
+            for handler in self._event_subscription_map[ua_event.SourceNode]:
+                await handler.ua_on_event(ua_event)
+        except KeyError:
+            self.logger.warning("Received Event Notification with no handlers", ua_event=ua_event)

opensmi/core/ua.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""OPC UA helper stuff."""
+
+from dataclasses import dataclass
+
+from asyncua import ua
+
+
+@dataclass(frozen=True, slots=True, eq=True)
+class NodeIdDefinition:
+    """Definition of an unresolved OPC UA node."""
+
+    ns_uri: str
+    id: ua.Int32

opensmi/core/ua_enums.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Common enumerations with OPC UA LocalizedText representation."""
+
+from enum import Enum
+
+from asyncua import ua
+
+
+class LocalizedTextEnum(Enum):
+    """Enum that return their str values in form of an OPC UA LocalizedText."""
+
+    @property
+    def localized_text(self) -> ua.LocalizedText:
+        """Return the OPC UA localized text of the enum member."""
+        return ua.LocalizedText(Text=self.value, Locale="en-US")
+
+
+class SkillState(Enum):
+    """Represents the state of a skill (`BaseSkill`).
+
+    State values according to the skill node-set specification.
+    """
+
+    HALTED = (11, "Halted")
+    """State indicating that the skill is halted (=stopped). To leave this state, the skill needs to be reset.
+    **Note**: Skills can halt for various reasons, e.g. internal failures, external safety trigger, etc."""
+    READY = (12, "Ready")
+    """State indicating that the skill is ready to be started."""
+    RUNNING = (13, "Running")
+    """State indicating that the skill is running."""
+    SUSPENDED = (14, "Suspended")
+    """State indicating that the skill is suspended."""
+    COMPLETED = (15, "Completed")
+    """State indicating that the skill is completed. 
+    Only used for finite skills, because continuous skills do not complete."""
+
+    STARTING = (16, "Starting")
+    """Intermediate state leading to `SkillState.RUNNING` on success or `SkillState.HALTING` on failure."""
+    HALTING = (17, "Halting")
+    """Intermediate state always leading to `SkillState.HALTED`."""
+    COMPLETING = (18, "Completing")
+    """Intermediate state leading to `SkillState.COMPLETED` on success or `SkillState.HALTING` on failure.
+    Only used for finite skills, because continuous skills do not complete."""
+    RESETTING = (19, "Resetting")
+    """Intermediate state leading to `SkillState.READY` on success or `SkillState.HALTING` on failure."""
+    SUSPENDING = (20, "Suspending")
+    """Intermediate state leading to `SkillState.SUSPENDING` on success or `SkillState.HALTING` on failure."""
+
+    @property
+    def localized_text(self) -> ua.LocalizedText:
+        """Return the OPC UA localized text of the enum member."""
+        return ua.LocalizedText(Text=self.value[1], Locale="en-US")
+
+    @property
+    def id(self) -> int:
+        """Return the state ID number of the enum member."""
+        return self.value[0]
+
+
+class MachineryItemState(LocalizedTextEnum):
+    """Represents the state of a machinery item (`BaseMachineryItem`).
+
+    Documentation from https://reference.opcfoundation.org/Machinery/v103/docs/12.2
+    """
+
+    NOT_AVAILABLE = "NotAvailable"
+    """The machine is not available and does not perform any activity (e.g., switched off, in energy saving mode)"""
+    OUT_OF_SERVICE = "OutOfService"
+    """The machine is not functional and does not perform any activity (e.g., error, blocked)"""
+    NOT_EXECUTING = "NotExecuting"
+    """The machine is available & functional and does not perform any activity. 
+    It waits for an action from outside to start or restart an activity."""
+    EXECUTING = "Executing"
+    """The machine is available & functional and is actively performing an activity (pursues a purpose)."""
+
+
+class MachineryOperationMode(LocalizedTextEnum):
+    """Represents the operation mode of a machinery item (`BaseMachineryItem`).
+
+    Documentation from https://reference.opcfoundation.org/Machinery/v103/docs/13.2
+    """
+
+    NONE = "None"
+    """No machinery operation mode available."""
+    MAINTENANCE = "Maintenance"
+    """Mode with the intention to carry out maintenance or servicing activities."""
+    SETUP = "Setup"
+    """Mode with the intention to carry out setup, preparation or postprocessing activities of a production process."""
+    PROCESSING = "Processing"
+    """Mode with the intention to carry out the value adding activities."""

opensmi/core/ua_node_util.py

@@ -0,0 +1,239 @@
+# SPDX-FileCopyrightText: 2026 OpenSMI Contributors
+#
+# SPDX-License-Identifier: MIT
+
+"""Utility functions for ``ua.Node``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import structlog.stdlib
+from asyncua import ua
+from asyncua.common.node import Node
+from asyncua.ua import QualifiedName
+from asyncua.ua.uaerrors import BadTypeMismatch
+
+from opensmi.core import Unit
+
+NULL_NODE_ID = ua.NodeId()
+""" This node id indicates an invalid Node ID and should be treated as 'None'. """
+
+
+async def read_value(node: Node) -> Any:
+    """Read the value of the given node and transforms the NULL_NODE_ID into None."""
+    value = await node.read_value()
+    if isinstance(value, ua.NodeId) and value.is_null():
+        return None
+    return value
+
+
+# async def read_all_variables(location: Node) -> dict[str, Any]:
+#     """Return all variables of the given node in dictionary form."""
+#     assert location is not None
+#
+#     ret = {}
+#     for node in await location.get_children():
+#         name, value = await asyncio.gather(node.read_browse_name(), node.read_value())
+#         ret[str(name.Name)] = value
+#     return ret
+
+
+async def _write_value(node: Node, value: Any, *, variant_type: ua.VariantType) -> None:
+    # convert node id string to NodeId, this is not done automatically by asyncua
+    if variant_type == ua.VariantType.NodeId and isinstance(value, str):
+        if value == "":
+            await node.write_value(NULL_NODE_ID)
+        else:
+            await node.write_value(ua.NodeId.from_string(value))
+    elif variant_type == ua.VariantType.NodeId and value is None:
+        await node.write_value(NULL_NODE_ID)  # we cannot write None here, it needs to be an (invalid) node id instead!
+    elif variant_type == ua.VariantType.LocalizedText and isinstance(value, str):
+        # just writing the raw string does not fail immediately in asyncua, but later when a client tries to read it.
+        await node.write_value(ua.LocalizedText(value, "en-US"))
+    else:
+        await node.write_value(value, variant_type)
+
+
+async def write_value(node: Node, value: Any, *, variant_type: ua.VariantType | None = None) -> None:
+    """Write the given value to the given node. Will try to use existing variant type of the node."""
+    # Note: asyncua is very strict, e.g. float is not automatically cast to double and trying to write that will fail!
+    try:
+        if isinstance(value, ua.Variant):
+            await _write_value(node, value, variant_type=value.VariantType)
+        if variant_type is not None:
+            await _write_value(node, value, variant_type=variant_type)
+        else:
+            # we need to figure out the correct variant type to use ourselves
+            data_value_value = (await node.read_data_value()).Value
+            if data_value_value is None:
+                await node.write_value(value)  # try without variant type, might fail
+            else:
+                await _write_value(node, value, variant_type=data_value_value.VariantType)
+    except BadTypeMismatch as err:  # the exception has 0 useful information on its own
+        expected_variant_type = await node.read_data_type_as_variant_type()
+        err.add_note(f"{node=}")
+        err.add_note(f"Expected variant_type={expected_variant_type!r}")
+        err.add_note(f"Given {value=!r} ; {variant_type=!r}")
+        raise
+
+
+# async def get_all_variables_with_browse_name(node: Node) -> dict[str, Node]:
+#     """Gather all child variables for given node and store them in a dict."""
+#     node_dict = {}
+#     for child in await node.get_variables():
+#         node_dict[str((await child.read_browse_name()).Name)] = child
+#     return node_dict
+
+
+@dataclass(slots=True)
+class PropertiesResult:
+    """Results of ``get_unit_and_range()``."""
+
+    unit: ua.EUInformation | None = None
+    range: ua.Range | None = None
+
+
+async def get_properties(node: Node, *, logger: structlog.stdlib.BoundLogger | None = None) -> PropertiesResult:
+    """Retrieve the supported OPC UA properties of the given node."""
+    assert node is not None, "No node given!"
+    result = PropertiesResult()
+
+    for property_node in await node.get_properties():
+        property_browse_name_data_value, property_value_data_value = await property_node.read_attributes(
+            [ua.attribute_ids.AttributeIds.BrowseName, ua.attribute_ids.AttributeIds.Value]
+        )
+        property_name: str = property_browse_name_data_value.Value.Value.Name  # type: ignore
+        property_value = property_value_data_value.Value.Value  # type: ignore
+
+        if property_name == "EngineeringUnits" and isinstance(property_value, ua.EUInformation):
+            if logger is not None:
+                logger.debug("Found EngineeringUnits", unit=property_value)
+            result.unit = property_value
+        elif property_name == "EURange" and isinstance(property_value, ua.Range):
+            if logger is not None:
+                logger.debug("Found EURange", range=property_value)
+            result.range = property_value
+        elif logger is not None:
+            logger.warning(
+                "Found unsupported property, ignoring!",
+                ua_property_node_id=property_node.nodeid.to_string(),
+                ua_node_id=node.nodeid.to_string(),
+            )
+
+    return result
+
+
+async def get_type_definition(ua_node: Node) -> str:
+    """Return the browse name of the OPC UA type definition of the given node."""
+    try:
+        type_definition_list = await ua_node.get_references(
+            ua.object_ids.ObjectIds.HasTypeDefinition,
+            ua.BrowseDirection.Forward,
+        )
+        return type_definition_list[0].BrowseName.Name
+    except Exception as ex:
+        msg = f"Could not find type definition for node {ua_node.nodeid.to_string()}!"
+        raise RuntimeError(msg) from ex
+
+
+def get_node_id(
+    ua_location: Node | ua.NodeId,
+    *,
+    name: QualifiedName | str,
+    ns_idx: int | None = 1,
+) -> ua.NodeId:
+    """Return a (new) Node ID in the standard hierarchical format based on given parameters.
+
+    :param ua_location: OPC UA parent node in the hierarchy
+    :param name: (Browse)Name of the new Node ID.
+    :param ns_idx: (optional) OPC UA namespace index, if ``None``, the namespace index of the location node
+        id will be used.
+    """
+    assert ua_location is not None, "No location node given!"
+    if isinstance(ua_location, Node):
+        ua_location = ua_location.nodeid
+    assert isinstance(ua_location, ua.NodeId)
+
+    if ns_idx is None:
+        ns_idx = ua_location.NamespaceIndex
+
+    if isinstance(name, QualifiedName):
+        name = name.Name
+
+    if isinstance(ua_location.Identifier, str):
+        identifier = ua.String(f"{ua_location.Identifier!s}.{name}")
+    else:
+        identifier = ua.String(name)
+
+    return ua.NodeId(Identifier=identifier, NamespaceIndex=ua.Int16(ns_idx))
+
+
+async def get_child_without_ns(parent: Node, *, display_name: str) -> Node:
+    """Return the first child node with given display name while ignoring the namespace index.
+
+    :raises BadNoMatch: If no child with given display name exists.
+    """
+    for child in await parent.get_children():
+        child_display_name = (await child.read_display_name()).Text
+        # print(parent.nodeid.to_string(), display_name, child_display_name)
+        if child_display_name == display_name:
+            return child
+    raise ua.uaerrors.BadNoMatch
+
+
+async def write_range(node: Node, range_: tuple[float, float] | ua.Range) -> None:
+    """Write given ``range`` to given ``node``."""
+    assert node is not None, "No node given!"
+    assert range_ is not None, "No range given!"
+
+    if not isinstance(range_, ua.Range):
+        range_ = ua.Range(*range_)
+
+    ua_range_node = await node.get_child("0:EURange")
+    await ua_range_node.write_value(range_)
+
+
+async def write_unit(
+    ua_node: Node, unit: Unit | str | int | ua.EUInformation, *, engineering_unit: str = "EngineeringUnits"
+) -> None:
+    """Write given ``unit`` to given ``node``."""
+    assert ua_node is not None, "No node given!"
+    assert unit is not None, "No unit given!"
+
+    if isinstance(unit, Unit):
+        unit = unit.ua_eu_information
+    elif isinstance(unit, str):
+        if unit == "%":  # backwards compatibility
+            unit = "pct"
+        unit = Unit.from_symbol(unit).ua_eu_information
+    elif isinstance(unit, int):
+        unit = Unit.from_ua_unit_id(unit).ua_eu_information
+
+    assert isinstance(unit, ua.EUInformation)
+    ua_engineering_unit_node = await ua_node.get_child(f"0:{engineering_unit}")
+    await ua_engineering_unit_node.write_value(unit)
+
+
+async def read_unit(ua_node: Node, *, engineering_unit: str = "EngineeringUnits") -> ua.EUInformation:
+    """Read the engineering unit from the given node."""
+    assert ua_node is not None, "No node given!"
+
+    ua_engineering_unit_node = await ua_node.get_child(f"0:{engineering_unit}")
+    unit = await ua_engineering_unit_node.read_value()
+
+    assert isinstance(unit, ua.EUInformation), f"Expected EUInformation, got {type(unit).__name__}"
+
+    return unit
+
+
+async def get_children_browse_names(ua_node: Node) -> Mapping[Node, ua.QualifiedName]:
+    """Return a mapping from child nodes to qualified names."""
+    result = {}
+    for ref in await ua_node.get_children_descriptions():
+        node = Node(session=ua_node.session, nodeid=ref.NodeId)
+        result[node] = ref.BrowseName
+
+    return result