machine-logic-sdk 3.0.2__tar.gz → 3.1.0__tar.gz

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: machine-logic-sdk
-Version: 3.0.2
+Version: 3.1.0
 Summary: SDK for controlling Vention hardware
 License: Proprietary
 Keywords: Vention,MachineLogic,SDK,Robot,Automation
@@ -16,13 +16,12 @@ Requires-Dist: numpy (>=1.21,<2.0)
 Requires-Dist: paho-mqtt (>=1.5,<2.0)
 Requires-Dist: python-statemachine (>=2.5,<3.0)
 Requires-Dist: requests (>=2.28,<3.0)
-Requires-Dist: roslibpy (>=1.4,<2.0)
 Requires-Dist: scipy (>=1.8,<2.0)
 Requires-Dist: toml (>=0.10,<0.11)
 Requires-Dist: typing_extensions (>=4.8,<5.0)
 Requires-Dist: urllib3 (>=2.6.3)
-Requires-Dist: uv (>=0.6,<0.7)
-Requires-Dist: vention-firmware-grpc-client (==0.1.1)
+Requires-Dist: uv (>=0.9.6,<0.10)
+Requires-Dist: vention-firmware-grpc-client (==1.1.0)
 Project-URL: Documentation, https://vention.io/resources/guides/machinelogic-python-programming-514
 Description-Content-Type: text/markdown
 
@@ -38,18 +37,6 @@ Provides a programmatic interface in Python to control Vention hardware and coor
 - **Real-time Monitoring**: Access live robot positions, states, and sensor data
 - **Safety Integration**: Built-in safety state monitoring and emergency stops
 
-## Table of Contents
-
-1. [Installation](#installation)
-2. [Quick Start](#quick-start)
-3. [Requirements](#requirements)
-4. [Basic Usage](#basic-usage)
-5. [Examples](#examples)
-6. [Development](#development)
-7. [Documentation](#documentation)
-8. [Contributing](#contributing)
-9. [Support](#support)
-
 ## Installation
 
 Install the machine-logic-sdk from PyPI:
@@ -63,7 +50,7 @@ pip install machine-logic-sdk
 Please pay close attention to the compatibility table provided in the [Official machine-logic-sdk Documentation](https://docs.vention.io/docs/en/vention-python-api)
 to determine which version of the sdk is compatible with your version of MachineMotion.
 
-For development installations, see the [Development](#development) section below.
+For development installations, see the Development section below.
 
 ## Quick Start
 

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/README.md

@@ -10,18 +10,6 @@ Provides a programmatic interface in Python to control Vention hardware and coor
 - **Real-time Monitoring**: Access live robot positions, states, and sensor data
 - **Safety Integration**: Built-in safety state monitoring and emergency stops
 
-## Table of Contents
-
-1. [Installation](#installation)
-2. [Quick Start](#quick-start)
-3. [Requirements](#requirements)
-4. [Basic Usage](#basic-usage)
-5. [Examples](#examples)
-6. [Development](#development)
-7. [Documentation](#documentation)
-8. [Contributing](#contributing)
-9. [Support](#support)
-
 ## Installation
 
 Install the machine-logic-sdk from PyPI:
@@ -35,7 +23,7 @@ pip install machine-logic-sdk
 Please pay close attention to the compatibility table provided in the [Official machine-logic-sdk Documentation](https://docs.vention.io/docs/en/vention-python-api)
 to determine which version of the sdk is compatible with your version of MachineMotion.
 
-For development installations, see the [Development](#development) section below.
+For development installations, see the Development section below.
 
 ## Quick Start
 

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/event_listener.py

@@ -2,8 +2,6 @@
 
 from typing import Callable, Optional
 
-import paho.mqtt.client as mqtt
-
 from .handle import Handle
 
 EventCallback = Callable[[str, Optional[str]], None]
@@ -76,5 +74,5 @@ class EventListenerManager:
             message (str): Message
         """
         for listener in self._listeners:
-            if mqtt.topic_matches_sub(listener.topic, topic):
+            if listener.topic == topic:
                 listener.callback(topic, message)

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/iactuator.py

@@ -43,12 +43,14 @@ class ActuatorState:
 
     @property
     def end_sensors(self) -> Tuple[bool, bool]:
-        """A tuple representing the state of the [ home, end ] sensors."""
+        """A tuple representing the state of the [ home, end ] sensors.
+        On machines without end sensors wired, both values remain False."""
         return self._end_sensors
 
     @property
     def move_in_progress(self) -> bool:
-        """The boolean is True if a move is in progress, otherwise False."""
+        """The boolean is True if the actuator has not yet reached its target position, otherwise False.
+        Always False during continuous moves, which have no target position."""
         return self._move_in_progress
 
 
@@ -183,6 +185,8 @@ class IActuator(ABC):
         """
         Moves absolute synchronously to the specified position.
 
+        Absolute positions are only meaningful after the actuator has been homed.
+
         Args:
             position (float): The position to move to.
             motion_profile (MotionProfile): The motion profile to move with. See MotionProfile class.
@@ -242,6 +246,9 @@ class IActuator(ABC):
         """
         Home the Actuator synchronously.
 
+        Homing establishes the actuator's position reference. Absolute positions are
+        only meaningful after the actuator has been homed.
+
         Args:
             timeout (float): The timeout in seconds.
 

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/iactuator_group.py

@@ -22,7 +22,7 @@ class ActuatorGroupState:
 
     @property
     def move_in_progress(self) -> bool:
-        """The boolean is True if the ActuatorGroup has at least one Actuator in progress"""
+        """The boolean is True if at least one Actuator in the ActuatorGroup has not yet reached its target position."""
         for actuator_state in self._actuator_states:
             if actuator_state.move_in_progress:
                 return True

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/icalibration_frame.py

@@ -43,7 +43,8 @@ class ICalibrationFrameConfiguration(ABC):
     @abstractmethod
     def calibrated_value(self) -> Union[CartesianPose, None]:
         """The calibrated value of the Calibration Frame,
-        in mm and degrees, where the angles are extrinsic Euler angles in XYZ order."""
+        in mm and degrees, where the angles are extrinsic Euler angles in XYZ order.
+        None until the frame has been calibrated at runtime."""
 
 
 class ICalibrationFrame(ABC):
@@ -61,7 +62,9 @@ class ICalibrationFrame(ABC):
 
     @abstractmethod
     def get_default_value(self) -> CartesianPose:
-        """Gets the calibration frame's default values.
+        """Gets the calibration frame's default (nominal) value, as defined in the scene.
+        This value is always available and is the safe fallback when
+        get_calibrated_value() returns None.
 
         Raises:
             SceneException: If failed to get the default value
@@ -75,12 +78,23 @@ class ICalibrationFrame(ABC):
     def get_calibrated_value(self) -> Union[CartesianPose, None]:
         """Gets the calibration frame's calibrated values.
 
+        Returns None until the frame has been calibrated at runtime (for example by a
+        camera calibration routine or by set_calibrated_value). Always fall back to the
+        nominal value when no calibration exists:
+
+            pose = frame.get_calibrated_value() or frame.get_default_value()
+
+        Passing the result of get_calibrated_value() directly into a robot move is not
+        recommended: if the frame has not been calibrated the value is None and the
+        move will fail.
+
         Raises:
             SceneException: If failed to get the calibrated value
 
         Returns:
-            CartesianPose: The calibrated value of the calibration frame
-                in mm and degrees, where the angles are extrinsic Euler angles in XYZ order.
+            Union[CartesianPose, None]: The calibrated value of the calibration frame
+                in mm and degrees, where the angles are extrinsic Euler angles in XYZ order,
+                or None if the frame has not been calibrated.
         """
 
     @abstractmethod

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/idigital_input.py

@@ -1,4 +1,5 @@
 from abc import ABC
+from datetime import datetime
 from typing import Callable, Optional, Union
 
 from ..decorators.future_api import future_api
@@ -79,12 +80,25 @@ class IDigitalInput(ABC):
 
     def _set_value(self, new_value: bool) -> None:
         """
-        Sets the DigitalInput state to the provided new_value. Listeners
-        will be notified.
+        Sets the DigitalInput state to the provided new_value.
+        Listeners will be notified.
 
         Args:
             new_value (bool): The new value for the DigitalInput state.
         """
-        # move honest new_value into the state object.
-        self._state._value = bool(new_value)  # pylint: disable=protected-access
+        self._state._value = new_value
+        self._state._timestamp = datetime.now()
+        self._event_listener_manager.notify_listeners("onchange")
+
+    def _set_value_with_timestamp(self, new_value: bool, timestamp: datetime) -> None:
+        """
+        Sets the DigitalInput state value and timestamp from a gRPC stream update.
+        Listeners will be notified.
+
+        Args:
+            new_value (bool): The new value for the DigitalInput state.
+            timestamp (datetime): The timestamp of the state update from gRPC.
+        """
+        self._state._value = new_value
+        self._state._timestamp = timestamp
         self._event_listener_manager.notify_listeners("onchange")

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/idigital_io_shared.py

@@ -1,5 +1,8 @@
 from abc import ABC
-from typing import Literal
+from datetime import datetime
+from typing import Literal, Optional
+
+IO_MODULE_DEVICE_TYPES = frozenset({"digitalIOModule", "pushButtonModule", "powerSwitchModule"})
 
 
 class DigitalIOState:
@@ -12,6 +15,7 @@ class DigitalIOState:
         # attribute (and have it work throughout the application).
         self._configuration = configuration
         self._value: bool = False  # honest value, ignoring "active_high" flips.
+        self._timestamp: Optional[datetime] = None
 
     @property
     def value(self) -> bool:
@@ -23,6 +27,14 @@ class DigitalIOState:
             return not self._value
         return self._value
 
+    @property
+    def timestamp(self) -> Optional[datetime]:
+        """
+        Timestamp of the last state update.
+        Returns None if no update has been received yet.
+        """
+        return self._timestamp
+
 
 class DigitalIOConfiguration(ABC):
     """
@@ -40,6 +52,7 @@ class DigitalIOConfiguration(ABC):
         controller_port: int,
         pin: int | Literal["A", "B"],
         active_high: bool,
+        device_type: str = "",
     ) -> None:
         self._uuid: str = uuid
         self._name: str = name
@@ -48,6 +61,7 @@ class DigitalIOConfiguration(ABC):
         self._controller_port: int = controller_port
         self._pin: int | Literal["A", "B"] = pin
         self._active_high: bool = active_high
+        self._device_type: str = device_type
 
     @property
     def name(self) -> str:
@@ -88,3 +102,12 @@ class DigitalIOConfiguration(ABC):
     def uuid(self) -> str:
         """The unique ID of the DigitalInput/DigitalOutput."""
         return self._uuid
+
+    @property
+    def device_type(self) -> str:
+        """The device type string (e.g. 'digitalIOModule', 'pushButtonModule', 'powerSwitchModule', 'motor')."""
+        return self._device_type
+
+    @property
+    def _is_io_module(self) -> bool:
+        return self._device_type in IO_MODULE_DEVICE_TYPES

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/idigital_output.py

@@ -1,4 +1,5 @@
 from abc import ABC, abstractmethod
+from datetime import datetime
 
 from ..decorators.future_api import future_api
 from .idigital_io_shared import DigitalIOConfiguration, DigitalIOState
@@ -74,4 +75,18 @@ class IDigitalOutput(ABC):
         Args:
             new_value (bool): The new value for the Output state.
         """
-        self._state._value = new_value  # pylint: disable=protected-access
+        # pylint: disable=protected-access
+        self._state._value = new_value
+        self._state._timestamp = datetime.now()
+
+    def _set_value_with_timestamp(self, new_value: bool, timestamp: datetime) -> None:
+        """
+        Sets the Output state value and timestamp from a gRPC output event stream.
+
+        Args:
+            new_value (bool): The new value for the Output state.
+            timestamp (datetime): The timestamp of the state update from gRPC.
+        """
+        # pylint: disable=protected-access
+        self._state._value = new_value
+        self._state._timestamp = timestamp

machine_logic_sdk-3.1.0/machinelogic/ivention/iethernet_ip.py

@@ -0,0 +1,79 @@
+"""Interface for the EtherNet/IP communication module."""
+
+from abc import ABC, abstractmethod
+from typing import Callable
+
+from machinelogic.decorators.undocumented import undocumented
+
+
+class IEthernetIp(ABC):
+    """
+    A software representation of an EtherNet/IP (EIP) communication interface.
+
+    EtherNet/IP allows the Machine to exchange data with external PLCs.
+    User Inputs are values sent from the Machine to the PLC, and User Outputs
+    are values received from the PLC.
+
+    It is not recommended that you construct this object yourself.
+    Instead, access it via the Machine instance:
+
+    E.g.:
+        machine = Machine()
+        machine.ethernet_ip.connect()
+    """
+
+    @abstractmethod
+    def connect(self) -> None:
+        """
+        Establish a connection to the EtherNet/IP service.
+
+        This must be called before any other EtherNet/IP operations.
+
+        Raises:
+            RuntimeError: If the connection cannot be established.
+        """
+
+    @abstractmethod
+    def set_user_input(self, parameter_name: str, value: int) -> None:
+        """
+        Set a User Input value to be sent to the PLC.
+
+        Args:
+            parameter_name (str): The name of the User Input param as defined in the EDS file.
+            value (int): The integer value to set.
+
+        Raises:
+            RuntimeError: If not connected.
+        """
+
+    @abstractmethod
+    def on_user_output(self, parameter_name: str, callback: Callable[[int], None]) -> int:
+        """
+        Register a callback that fires whenever the specified User Output value
+        changes. When the PLC changes the User Output values, the callback receives
+        the corresponding new integer value.
+
+        Args:
+            parameter_name (str): The name of the User Output parameter as defined in the EDS file.
+            callback (Callable[[int], None]): A function that receives the new User Output value as an integer.
+
+        Returns:
+            int: A handle that can be passed to ``remove_on_user_output_callback`` to unregister.
+
+        Raises:
+            RuntimeError: If not connected.
+        """
+
+    @abstractmethod
+    def remove_on_user_output_callback(self, callback_id: int) -> None:
+        """
+        Remove a previously registered callback for User Output changes.
+
+        Args:
+            callback_id (int): The ID of the callback to remove.
+        """
+
+    @abstractmethod
+    @undocumented
+    def _cleanup(self) -> None:
+        """Release all resources and close the connection."""

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/imachine.py

@@ -4,6 +4,9 @@ from abc import ABC, abstractmethod
 from enum import Enum
 from typing import Callable, Optional, Union
 
+from machinelogic.machinelogic.communication.mqtt_client import MqttClient
+
+from ..decorators.deprecated import deprecated
 from ..decorators.future_api import future_api
 from .exception import MachineException, MachineMotionException
 from .iac_motor import IACMotor
@@ -11,11 +14,12 @@ from .iactuator import IActuator
 from .icamera import ICamera
 from .idigital_input import IDigitalInput
 from .idigital_output import IDigitalOutput
+from .iethernet_ip import IEthernetIp
 from .imachine_motion import IMachineMotion
+from .imqtt import IMqtt
 from .ipneumatic import IPneumatic
 from .irobot import IRobot
 from .iscene import IScene
-from .mqtt_client import MqttClient
 
 
 class MachineOperationalState(Enum):
@@ -71,22 +75,36 @@ class IMachine(ABC):
         machine_motions: list[IMachineMotion],
         mqtt_client: MqttClient,
         scene: IScene,
+        ethernet_ip: IEthernetIp,
     ) -> None:
         """
         Args:
             machine_motions (list[IMachineMotion]): The list of MachineMotions.
             mqtt_client (MqttClient): The Mqtt client.
             scene (IScene): The scene instance.
+            ethernet_ip (IEthernetIp): The EthernetIP communication interface.
         """
         self._machine_motions = machine_motions
         self._mqtt_client = mqtt_client
         self._scene = scene
+        self._mqtt_event_callback_ids: dict[str, int] = {}
+        self._ethernet_ip = ethernet_ip
+
+    @property
+    def ethernet_ip(self) -> IEthernetIp:
+        """The EthernetIP communication interface for exchanging data with external PLCs."""
+        return self._ethernet_ip
 
     @property
     @abstractmethod
     def state(self) -> IMachineState:
         """The state of the Machine."""
 
+    @property
+    @abstractmethod
+    def mqtt(self) -> IMqtt:
+        """The MQTT interface for subscribing to and publishing events."""
+
     @abstractmethod
     def reset(self) -> bool:
         """
@@ -208,6 +226,10 @@ class IMachine(ABC):
         """
         Retrieves an DigitalInput by name.
 
+        The name must match the input pin's friendly name exactly as it appears in the
+        machine configuration (for example "Input C0"), not the display name of a device
+        wired to it.
+
         Args:
             name (str): The name of the DigitalInput.
 
@@ -229,6 +251,10 @@ class IMachine(ABC):
         """
         Retrieves an Output by name.
 
+        The name must match the output pin's friendly name exactly as it appears in the
+        machine configuration (for example "Output C0"), not the display name of a device
+        wired to it.
+
         Args:
             name (str): The name of the Output
 
@@ -297,21 +323,38 @@ class IMachine(ABC):
             callback (Callable[[MachineOperationalState, MachineSafetyState], None]): The callback
         """
 
-    def on_mqtt_event(self, topic: str, callback: Callable[[str, Optional[str]], None]) -> None:
+    @deprecated
+    def on_mqtt_event(self, topic: str, callback: Optional[Callable[[str, Optional[str]], None]]) -> None:
         """
         Attach a callback function to an MQTT topic.
 
+        .. deprecated::
+            Use ``machine.mqtt.on_event`` instead. To remove a callback, use
+            ``machine.mqtt.remove_on_event_callback`` with the ID returned by ``on_event``.
+
         Args:
             topic (str): The topic to listen on.
-            callback (Union[Callable[[str, str], None], None]): A callback where the first argument is the topic and the second is the message.
-
+            callback (Optional[Callable[[str, str], None]]): A callback where the first argument is the topic and the second is the message. Pass ``None`` to remove the callback.
         """
-        self._mqtt_client.subscribe(topic, callback)
+        if callback is None:
+            callback_id = self._mqtt_event_callback_ids.pop(topic, None)
+            if callback_id is not None:
+                self.mqtt.remove_on_event_callback(callback_id)
+            return
 
+        if topic in self._mqtt_event_callback_ids:
+            self.mqtt.remove_on_event_callback(self._mqtt_event_callback_ids[topic])
+
+        self._mqtt_event_callback_ids[topic] = self.mqtt.on_event(topic, callback)
+
+    @deprecated
     def publish_mqtt_event(self, topic: str, message: Optional[str] = None) -> None:
         """
         Publish an MQTT event.
 
+        .. deprecated::
+            Use ``machine.mqtt.publish_event`` instead.
+
         Args:
             topic (str): Topic to publish.
             message (Optional[str], optional): Optional message. Defaults to None.

{machine_logic_sdk-3.0.2 → machine_logic_sdk-3.1.0}/machinelogic/ivention/imachine_motion.py

@@ -221,6 +221,17 @@ class IMachineMotion(ABC):
 
         raise MachineMotionException(f"Failed to find AC motor with name: {name}")
 
+    @undocumented
+    def has_io_module_devices(self) -> bool:
+        """Whether this MachineMotion has any inputs or outputs hosted on an IO Module."""
+        for input_item in self._input_list:
+            if input_item.configuration._is_io_module:
+                return True
+        for output_item in self._output_list:
+            if output_item.configuration._is_io_module:
+                return True
+        return False
+
     @undocumented
     def list_components(
         self,

machine_logic_sdk-3.1.0/machinelogic/ivention/imqtt.py

@@ -0,0 +1,62 @@
+"""Interface for the MQTT communication module."""
+
+from abc import ABC, abstractmethod
+from typing import Callable, Optional
+
+from ..decorators.undocumented import undocumented
+
+
+class IMqtt(ABC):
+    """
+    A software representation of the MQTT communication interface.
+
+    MQTT allows the Machine to subscribe to and publish events on topics.
+
+    It is not recommended that you construct this object yourself.
+    Instead, access it via the Machine instance:
+
+    E.g.:
+        machine = Machine()
+        callback_id = machine.mqtt.on_event("my/topic", my_callback)
+        machine.mqtt.publish_event("my/topic", "my message")
+        machine.mqtt.remove_on_event_callback(callback_id)
+    """
+
+    @abstractmethod
+    def on_event(self, topic: str, callback: Callable[[str, Optional[str]], None]) -> int:
+        """
+        Register a callback that fires whenever a message is received on the given topic.
+
+        Multiple callbacks can be registered on the same topic.
+
+        Args:
+            topic (str): The MQTT topic to subscribe to. Supports wildcards (e.g. ``"sensor/+/value"``).
+            callback (Callable[[str, Optional[str]], None]): A function called with ``(topic, message)`` when a message arrives.
+
+        Returns:
+            int: A callback ID that can be passed to ``remove_on_event_callback`` to unregister.
+        """
+
+    @abstractmethod
+    def remove_on_event_callback(self, callback_id: int) -> None:
+        """
+        Remove a previously registered event callback.
+
+        Args:
+            callback_id (int): The ID returned by ``on_event``.
+        """
+
+    @abstractmethod
+    def publish_event(self, topic: str, message: Optional[str] = None) -> None:
+        """
+        Publish a message to an MQTT topic.
+
+        Args:
+            topic (str): The topic to publish to.
+            message (Optional[str]): The message payload. Defaults to ``None``.
+        """
+
+    @abstractmethod
+    @undocumented
+    def _cleanup(self) -> None:
+        """Release all resources and close the connection."""