--- title: "Machine-Logic-sdk v3.1.0" slug: "vention-python-api" description: "Explore compatibility of Python package versions with Vention's MachineMotion and Pendant, including updates and new features in version 2.0.x." updated: 2026-04-30T20:10:03Z published: 2026-04-30T20:10:03Z --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.vention.io/llms.txt > Use this file to discover all available pages before exploring further. # Machine-Logic-sdk v3.0.x ## Compatibility This table specifies the compatibility of the Python package versions with the Vention's MachineMotion and Pendant versions. | Package | MachineMotion | Pendant | | --- | --- | --- | | v1.12.x* | v2.13.x | v3.2, v3.3 | | v1.13.0 | >= v2.14.x, < v3.0.0 | >= v3.4 | | v1.13.1 | >= v2.15.x, < v3.0.0 | >= v3.5 | | v1.13.2 | >= v2.15.x, < v3.0.0 | >= v3.5 | | v2.0.x | >= v3.0.0, < v3.1.0 | N/A** | | v2.1.x | >= v3.1.0, < v3.2.0 | N/A** | | v2.2.x | >= v3.2.0, < v3.3.0 | N/A** | | v3.0.x | >= v3.3.0, <=3.4.0 | N/A** | *Package versions before 1.13.0 were published to PyPi under the package name machine-code-python-sdk **Post MMAI release (MachineMotion v3.0.0), machine-logic-sdk is no longer dependent on Pendant version. ## Change Log ****Version 3.0.x**** ### Version 3.0.1 #### Changed: - Conveyor motor support: DigitalInputConfiguration pin type hint to include new 'A' and 'B' type pins on conveyor motors. #### Updated: - Bumped version of vention-firmware-grpc-client to "0.1.1". #### Documented: - Conveyor motor support: Added comments about possible device types that input peripherals can connect to, especially new conveyor motor. ### Version 3.0.0 #### Added: - `Robot.set_to_normal()` - Set the robot to normal operational state. Replaces `reset()`. - `Robot.set_to_freedrive()` - Put the robot into freedrive mode. Replaces `teach_mode()`. - `Robot.remove_log_alarm_callback(callback_id)` - Remove previously registered log alarm callbacks. - `Robot.remove_system_state_change_callback(callback_id)` - Remove previously registered state change callbacks. #### Changed: - `RobotState.cartesian_position_data` and `RobotState.joint_angles_data` now return standard `datetime` instead of custom.`Timestamp` type. - `Robot.execute_sequence()` return type changed from `bool` to `None`. - `Robot.execute_sequence_async()` return type changed from `bool` to `None`. - `Robot.wait_for_motion_completion()` return type changed from `bool` to `None`, timeout parameter removed. - `Robot.set_payload()` signature changed: now requires `center_of_mass: Vector` and optional `inertia: Inertia` parameters, returns `None` instead of `bool`. - `RobotOperationalState` enum completely redesigned for new robot stack compatibility: - | Old | New | | --- | --- | | OFFLINE = 0 | ❌ Removed | | NON_OPERATIONAL = 1 | NON_OPERATIONAL = 6 (value changed) | | FREEDRIVE = 2 | FREEDRIVE = 4 (value changed) | | NORMAL = 3 | ❌ Removed | | UNKNOWN = 4 | UNKNOWN = 0 (value changed) | | NEED_MANUAL_INTERVENTION = 5 | ❌ Removed | | - | IDLE = 1 ✨ New | | - | RUNNING = 2 ✨ New | | - | JOGGING = 3 ✨ New | | - | STOPPING = 5 ✨ New | - `RobotSafetyState` enum redesigned for new robot stack compatibility: - | Old | New | | --- | --- | | NORMAL = 0 | NORMAL = 1 (value changed) | | EMERGENCY_STOP = 2 | EMERGENCY_STOP = 2 (same) | | REDUCED_SPEED = 3 | REDUCED_SPEED = 3 (same) | | SAFEGUARD_STOP = 4 | ❌ Removed | | UNKNOWN = 5 | UNKNOWN = 0 (value changed) | | - | RECOVERABLE_FAULT = 4 ✨ New | #### Deprecated: - `Robot.reset()` - Use `set_to_normal()` instead. - `RobotConfiguration.cartesian_velocity_limit` - Returns default 250.0 mm/s. - `RobotConfiguration.joint_velocity_limit` - Returns default 120.0 deg/s. #### Removed: - `Robot.teach_mode()` - Use `set_to_freedrive()` and `set_to_normal()` instead. - `Robot.set_tool_digital_output()`. - `RobotState.cartesian_position` - Use `cartesian_position_data` instead (was deprecated in 1.14.0). - `RobotState.joint_angles` - Use `joint_angles_data` instead (was deprecated in 1.14.0). - `RobotState.get_digital_input_value()`. - `timeout` parameter from `wait_for_motion_completion()`. ## Machine A software representation of the entire Machine. A Machine is defined as any number of MachineMotions, each containing their own set of axes, outputs, inputs, pneumatics, and AC Motors. The Machine class offers a global way to retrieve these various components using the friendly names that you've defined in your MachineLogic configuration. To create a new Machine with default settings, you can simply write: ```python machine = Machine() ``` If you need to connect to services running on a different machine or IP address, you can specify the IP address as follows: ```python machine = Machine("192.168.7.2") ``` You should only ever have a single instance of this object in your program. ****state**** - **Description** The state of the Machine. - **Type** [MachineState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machinestate) ****get_ac_motor**** - **Description** Retrieves an AC Motor by name. - **Parameters** - **name** - **Description** The name of the AC Motor. - **Type** str - **Returns** - **Description** The AC Motor that was found. - **Type** [ACMotor](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#acmotor) - **Raises** - **Type** [MachineMotionException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machinemotionexception) - **Description** If it is not found. ****get_actuator**** - **Description** Retrieves an Actuator by name. - **Parameters** - **name** - **Description** The name of the Actuator. - **Type** str - **Returns** - **Description** The Actuator that was found. - **Type** [Actuator](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuator) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If we cannot find the Actuator. ```python from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) start_position = my_actuator.state.position print("starting at position: ", start_position) TARGET_DISTANCE = 150  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) my_actuator.move_relative(    distance=TARGET_DISTANCE,    motion_profile=new_motion_profile, ) # first_move_end_position is approx. equal to start_position + target_distance. first_move_end_position = my_actuator.state.position print("first move finished at position: ", first_move_end_position) # move back to starting position TARGET_DISTANCE = -1 * TARGET_DISTANCE my_actuator.move_relative(    distance=TARGET_DISTANCE,    motion_profile=new_motion_profile, ) # approx. equal to start_position, end_position = my_actuator.state.position print("finished back at position: ", end_position) ``` ****get_input**** - **Description** Retrieves an DigitalInput by name. - **Parameters** - **name** - **Description** The name of the DigitalInput. - **Type** str - **Returns** - **Description** The DigitalInput that was found. - **Type** [DigitalInput](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitalinput) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If we cannot find the DigitalInput. ```python from machinelogic import Machine machine = Machine() my_input = machine.get_input("Input") if my_input.state.value:    print(f"{my_input.configuration.name} is HIGH") else:    print(f"{my_input.configuration.name} is LOW") ``` ****get_machine_motion**** - **Description** Retrieves an IMachineMotion instance by name. - **Parameters** - **name** - **Description** The name of the MachineMotion. - **Type** str - **Returns** - **Description** The MachineMotion that was found. - **Type** [MachineMotion](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machinemotion) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If we cannot find the MachineMotion. ```python from machinelogic import Machine machine = Machine() my_controller_1 = machine.get_machine_motion("Controller 1") configuration = my_controller_1.configuration print("Name:", configuration.name) ``` ****get_output**** - **Description** Retrieves an Output by name. - **Parameters** - **name** - **Description** The name of the Output - **Type** str - **Returns** - **Description** The Output that was found. - **Type** IOutput - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If we cannot find the Output. ```python from machinelogic import Machine machine = Machine() my_output = machine.get_output("Output") my_output.write(True)  # Write "true" to the Output my_output.write(False)  # Write "false" to the Output ``` ****get_pneumatic**** - **Description** Retrieves a Pneumatic by name. - **Parameters** - **name** - **Description** The name of the Pneumatic. - **Type** str - **Returns** - **Description** The Pneumatic that was found. - **Type** [Pneumatic](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#pneumatic) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If we cannot find the Pneumatic. ```python import time from machinelogic import Machine machine = Machine() my_pneumatic = machine.get_pneumatic("Pneumatic") # Idle my_pneumatic.idle_async() time.sleep(1) # Push my_pneumatic.push_async() time.sleep(1) # Pull my_pneumatic.pull_async() time.sleep(1) ``` ****get_robot**** - **Description** Retrieves a Robot by name. If no name is specified, then returns the first Robot. - **Parameters** - **name** - **Description** The Robot name. If it's `None`, then the first Robot in the Robot list is returned. - **Type** str - **Returns** - **Description** The Robot that was found. - **Type** [Robot](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robot) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If the Robot is not found. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Example of use: moving robot to specified joint angles in deg my_robot.movej([0, -90, 120, -90, -90, 0]) ``` ****get_scene**** - **Description** Returns the scene instance - **Returns** - **Description** The instance of the scene containing the scene assets. - **Type** [Scene](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#scene) - **Raises** - **Type** [MachineException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineexception) - **Description** If failed to find the scene ****on_mqtt_event**** - **Description** Attach a callback function to an MQTT topic. - **Parameters** - **topic** - **Description** The topic to listen on. - **Type** str - **callback** - **Description** A callback where the first argument is the topic and the second is the message. - **Type** Union[Callable[[str, str], None], None] ```python import time from machinelogic import Machine machine = Machine() my_event_topic = "my_custom/event/topic" # A "callback" function called everytime a new mqtt event on my_event_topic is received. def event_callback(topic: str, message: str):    print("new mqtt event:", topic, message) machine.on_mqtt_event(my_event_topic, event_callback) machine.publish_mqtt_event(my_event_topic, "my message") time.sleep(2) machine.on_mqtt_event(my_event_topic, None)  # remove the callback. ``` ****on_system_state_change**** - **Description** Adds a change listener to execute when the Machine state changes. - **Parameters** - **callback** - **Description** The callback - **Type** Callable[[[MachineOperationalState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineoperationalstate), [MachineSafetyState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machinesafetystate)], None] ```python from machinelogic import Machine from machinelogic.types import MachineOperationalState, MachineSafetyState machine = Machine() # Callback function called everytime a new system state is received. def on_machine_state_change_callback(operational_state: MachineOperationalState, safety_state: MachineSafetyState):    print("New Machine Operational State", operational_state)    print("New Machine Safety State", safety_state) # To set an on_system_state_change callback machine.on_system_state_change(on_machine_state_change_callback) # To remove the callback machine.on_system_state_change(None) ``` ****publish_mqtt_event**** - **Description** Publish an MQTT event. - **Parameters** - **topic** - **Description** Topic to publish. - **Type** str - **message** - **Description** Optional message. Defaults to None. - **Type** Optional[str] ```python import json import time from machinelogic import Machine machine = Machine() # Example for publishing a cycle-start and cycle-end topic and message # to track application cycles in MachineAnalytics cycle_start_topic = "application/cycle-start" cycle_end_topic = "application/cycle-end" cycle_message = {"applicationId": "My Python Application", "cycleId": "default"} json_cycle_message = json.dumps(cycle_message) while True:    machine.publish_mqtt_event(cycle_start_topic, json_cycle_message)    print("Cycle Start")    time.sleep(5)    machine.publish_mqtt_event(cycle_end_topic, json_cycle_message)    time.sleep(1)    print("Cycle end") ``` ****reset**** - **Description** Reset the machine by trying to clear drive errors. - **Returns** - **Description** True if the machine was reset successfully, False otherwise. - **Type** bool ```python from machinelogic import Machine machine = Machine() # Example for resetting the machine if the MachineOperationalState is # NON_OPERATIONAL. The reset programmatically tries to clear drive errors if machine.state.operational_state == "NON_OPERATIONAL":    machine.reset()    print("Machine Reset") ``` ## MachineState A representation of the state of the Machine. ****operational_state**** - **Description** The operational state of the Machine. - **Type** [MachineOperationalState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machineoperationalstate) ****safety_state**** - **Description** The safety state of the Machine. - **Type** [MachineSafetyState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#machinesafetystate) ## **MachineOperationalState** **Description**: The machine's operational state. - **NON_OPERATIONAL**= 0 - **NORMAL**= 1 ## **MachineSafetyState** **Description**: The machine's safety state. - **ERROR**= -1 - **NONE**= 0 - **EMERGENCY_STOP**= 1 - **NORMAL**= 2 ## MachineMotion A software representation of a MachineMotion controller. The MachineMotion is comprised of many actuators, inputs, outputs, pneumatics, and ac motors. It keeps a persistent connection to MQTT as well. You should NEVER construct this object yourself. Instead, it is best to rely on the Machine instance to provide you with a list of the available MachineMotions. ****configuration**** - **Description** MachineMotionConfiguration: The representation of the configuration associated with this MachineMotion. - **Type** MachineMotionConfiguration ## Actuator A software representation of an Actuator. An Actuator is defined as a motorized axis that can move by discrete distances. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance: E.g.: ```python machine = Machine() my_actuator = machine.get_actuator("Actuator") ``` In this example, "New actuator" is the friendly name assigned to the Actuator in the MachineLogic configuration page. ****configuration**** - **Description** The representation of the configuration associated with this MachineMotion. - **Type** [ActuatorConfiguration](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorconfiguration) ****state**** - **Description** The representation of the current state of this MachineMotion. - **Type** [ActuatorState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorstate) ****home**** - **Description** Home the Actuator synchronously. - **Parameters** - **timeout** - **Description** The timeout in seconds. - **Type** float - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the home was unsuccessful or request timed out. ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") my_actuator.home(timeout=10) ``` ****move_absolute**** - **Description** Moves absolute synchronously to the specified position. - **Parameters** - **position** - **Description** The position to move to. - **Type** float - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the move was unsuccessful. ```python from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) TARGET_POSITION = 150.0  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER my_actuator.move_absolute(    position=TARGET_POSITION,  # millimeters    motion_profile=MotionProfile(        velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK    ), ) ``` ****move_absolute_async**** - **Description** Moves absolute asynchronously. - **Parameters** - **position** - **Description** The position to move to. - **Type** float - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the move was unsuccessful. ```python import time from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) TARGET_POSITION = 150.0  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) # move_absolute_async will start the move and return without waiting for the move to complete. my_actuator.move_absolute_async(    position=TARGET_POSITION, motion_profile=new_motion_profile ) while my_actuator.state.move_in_progress:    print("move is in progress...")    time.sleep(1) # end_position will be approx. equal to target_position. end_position = my_actuator.state.position print("finished at position: ", end_position) ``` ****move_continuous_async**** - **Description** Starts a continuous move. The Actuator will keep moving until it is stopped. - **Parameters** - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. Note: Actuator.move_continuous_async does not support jerk. If jerk is provided in the MotionProfile, a warning will be raised and the move will continue without jerk. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the move was unsuccessful. ```python import time from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) # Continuous motion profile only uses velocity and acceleration. VELOCITY = 100.0  # mm/s ACCELERATION = 100.0  # mm/s^2 new_motion_profile = MotionProfile(velocity=VELOCITY, acceleration=ACCELERATION) # move_continuous_async will start the move and return without waiting for the move to complete. my_actuator.move_continuous_async(motion_profile=new_motion_profile) time.sleep(10)  # move continuously for ~10 seconds. my_actuator.stop()  # decelerate to stopped. ``` ****move_relative**** - **Description** Moves relative synchronously by the specified distance. - **Parameters** - **distance** - **Description** The distance to move. - **Type** float - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the move was unsuccessful. ```python from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) start_position = my_actuator.state.position print("starting at position: ", start_position) TARGET_DISTANCE = 150  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) my_actuator.move_relative(    distance=TARGET_DISTANCE,    motion_profile=new_motion_profile, ) # first_move_end_position is approx. equal to start_position + target_distance. first_move_end_position = my_actuator.state.position print("first move finished at position: ", first_move_end_position) # move back to starting position TARGET_DISTANCE = -1 * TARGET_DISTANCE my_actuator.move_relative(    distance=TARGET_DISTANCE,    motion_profile=new_motion_profile, ) # approx. equal to start_position, end_position = my_actuator.state.position print("finished back at position: ", end_position) ``` ****move_relative_async**** - **Description** Moves relative asynchronously by the specified distance. - **Parameters** - **distance** - **Description** The distance to move. - **Type** float - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the move was unsuccessful. ```python import time from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) start_position = my_actuator.state.position print("starting at position: ", start_position) TARGET_DISTANCE = 150  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) # move_relative_async will start the move and return without waiting for the move to complete. my_actuator.move_relative_async(    distance=TARGET_DISTANCE, motion_profile=new_motion_profile ) while my_actuator.state.move_in_progress:    print("move is in progress...")    time.sleep(1) # end_position will be approx. equal to start_position + target_distance. end_position = my_actuator.state.position print("finished at position", end_position) ``` ****stop**** - **Description** Stops movement on this Actuator as quickly as possible. - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the Actuator failed to stop. ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") my_actuator.stop() # The actuator will stop as quickly as possible. ``` ****wait_for_move_completion**** - **Description** Waits for motion to complete before commencing the next action. - **Parameters** - **timeout** - **Description** The timeout in seconds, after which an exception will be thrown. - **Type** float - **Raises** - **Type** [ActuatorException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorexception) - **Description** If the request fails or the move did not complete in the allocated amount of time. ```python from machinelogic import Machine, MotionProfile machine = Machine() my_actuator = machine.get_actuator("Actuator") # Always home the actuator before starting to ensure position is properly calibrated. my_actuator.home(timeout=10) TARGET_POSITION = 150.0  # millimeters VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 new_motion_profile = MotionProfile(velocity=VELOCITY, acceleration=ACCELERATION) # move_absolute_async will start the move and return without waiting for the move to complete. my_actuator.move_absolute_async(    position=TARGET_POSITION, motion_profile=new_motion_profile ) print("move started...") my_actuator.wait_for_move_completion(timeout=10) print("motion complete.") # end_position will be approx. equal to target_position. end_position = my_actuator.state.position print("finished at position: ", end_position) ``` ## ActuatorState Representation of the current state of an Actuator instance. The values in this class are updated in real time to match the physical reality of the Actuator. ****end_sensors**** - **Description** A tuple representing the state of the [ home, end ] sensors. - **Type** typing.Tuple[bool, bool] ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.state.end_sensors) ``` ****move_in_progress**** - **Description** The boolean is True if a move is in progress, otherwise False. - **Type** bool ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.state.move_in_progress) ``` ****output_torque**** - **Description** The current torque output of the Actuator. - **Type** dict ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.state.output_torque) ``` ****position**** - **Description** The current position of the Actuator. - **Type** float ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.state.position) ``` ****speed**** - **Description** The current speed in mm/s of the Actuator. - **Type** float (mm/s) ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.state.speed) ``` ## ActuatorConfiguration Representation of the configuration of an Actuator instance. This configuration defines what your Actuator is and how it should behave when work is requested from it. ****actuator_type**** - **Description** The type of the Actuator. - **Type** typing.Literal['belt', 'rack_and_pinion', 'rack_and_pinion_v2', 'ball_screw', 'enclosed_ball_screw', 'enclosed_lead_screw', 'indexer', 'indexer_v2', 'electric_cylinder', 'belt_conveyor', 'roller_conveyor', 'pneumatic', 'ac_motor_with_vfd', 'enclosed_timing_belt', 'belt_rack', 'heavy_duty_roller_conveyor', 'timing_belt_conveyor', 'telescopic_column', 'custom'] ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.configuration.actuator_type) ``` ****controller_id**** - **Description** The controller id of the Actuator - **Type** str ****home_sensor**** - **Description** The home sensor port, either A or B. - **Type** typing.Literal['A', 'B'] ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.configuration.home_sensor) ``` ****name**** - **Description** The name of the Actuator. - **Type** str ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.configuration.name) ``` ****units**** - **Description** The units that the Actuator functions in. - **Type** typing.Literal['deg', 'mm'] ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.configuration.units) ``` ****uuid**** - **Description** The Actuator's ID. - **Type** str ```python from machinelogic import Machine machine = Machine() my_actuator = machine.get_actuator("Actuator") print(my_actuator.configuration.uuid) ``` ## ActuatorGroup A helper class used to group N-many Actuator instances together so that they can be acted upon as a group. An ActuatorGroup may only contain Actuators that are on the same MachineMotion controller. E.g.: ```python machine = Machine() my_actuator_1 = machine.get_actuator("Actuator 1") my_actuator_2 = machine.get_actuator("Actuator 2") actuator_group = ActuatorGroup(my_actuator_1, my_actuator_2) ``` ****state**** - **Description** The state of the ActuatorGroup. - **Type** ActuatorGroupState ****move_absolute**** - **Description** Moves absolute synchronously to the tuple of positions. - **Parameters** - **position** - **Description** The positions to move to. Each value corresponds 1-to-1 with the actuators tuple provided to the constructor. - **Type** Tuple[float, ...] - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If the request fails or the timeout occurs. ```python from machinelogic import ActuatorGroup, Machine, MotionProfile machine = Machine() my_actuator_1 = machine.get_actuator("Actuator 1") my_actuator_2 = machine.get_actuator("Actuator 2") # Always home the actuators before starting to ensure position is properly calibrated. my_actuator_1.home(timeout=10) my_actuator_2.home(timeout=10) actuator_group = ActuatorGroup(my_actuator_1, my_actuator_2) TARGET_POSITIONS = (100.0, 200.0)  # (mm - actuator1, mm - actuator2) VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) actuator_group.move_absolute(    position=TARGET_POSITIONS, motion_profile=new_motion_profile ) ``` ****move_absolute_async**** - **Description** Moves absolute asynchronously to the tuple of positions. - **Parameters** - **distance** - **Description** The positions to move to. Each value corresponds 1-to-1 with the actuators tuple provided to the constructor. - **Type** Tuple[float, ...] - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If the request fails. ```python from machinelogic import ActuatorGroup, Machine, MotionProfile machine = Machine() my_actuator_1 = machine.get_actuator("Actuator 1") my_actuator_2 = machine.get_actuator("Actuator 2") # Always home the actuators before starting to ensure position is properly calibrated. my_actuator_1.home(timeout=10) my_actuator_2.home(timeout=10) actuator_group = ActuatorGroup(my_actuator_1, my_actuator_2) TARGET_POSITIONS = (75.0, 158.0)  # (mm - actuator1, mm - actuator2) VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) # move_absolute_async will start the move and return without waiting for the move to complete. actuator_group.move_absolute_async(    position=TARGET_POSITIONS, motion_profile=new_motion_profile ) print("move started..") actuator_group.wait_for_move_completion() print("motion completed.") ``` ****move_relative**** - **Description** Moves relative synchronously by the tuple of distances. - **Parameters** - **distance** - **Description** The distances to move each Actuator. Each value corresponds 1-to-1 with the actuators tuple provided to the constructor. - **Type** Tuple[float, ...] - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If the request fails or the timeout occurs ```python from machinelogic import ActuatorGroup, Machine, MotionProfile machine = Machine() my_actuator_1 = machine.get_actuator("Actuator 1") my_actuator_2 = machine.get_actuator("Actuator 2") # Always home the actuators before starting to ensure position is properly calibrated. my_actuator_1.home(timeout=10) my_actuator_2.home(timeout=10) actuator_group = ActuatorGroup(my_actuator_1, my_actuator_2) TARGET_DISTANCES = (-120.0, 240.0)  # (mm - actuator1, mm - actuator2) VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) actuator_group.move_relative(    distance=TARGET_DISTANCES, motion_profile=new_motion_profile ) ``` ****move_relative_async**** - **Description** Moves relative asynchronously by the tuple of distances. - **Parameters** - **distance** - **Description** The distances to move each Actuator. Each value corresponds 1-to-1 with the actuators tuple provided to the constructor. - **Type** Tuple[float, ...] - **motion_profile** - **Description** The motion profile to move with. See MotionProfile class. - **Type** [MotionProfile](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#motionprofile) - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If the request fails. ```python import time from machinelogic import ActuatorGroup, Machine, MotionProfile machine = Machine() actuator1 = machine.get_actuator("My Actuator #1") actuator2 = machine.get_actuator("My Actuator #2") # Always home the actuators before starting to ensure position is properly calibrated. actuator1.home(timeout=10) actuator2.home(timeout=10) actuator_group = ActuatorGroup(actuator1, actuator2) TARGET_DISTANCES = (-120.0, 240.0)  # (mm - actuator1, mm - actuator2) VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) # move_relative_async will start the move and return without waiting for the move to complete. actuator_group.move_relative_async(    distance=TARGET_DISTANCES, motion_profile=new_motion_profile ) while actuator_group.state.move_in_progress:    print("motion is in progress..")    time.sleep(1) print("motion complete") ``` ****stop**** - **Description** Stops movement on all Actuators in the group. - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If any of the Actuators in the group failed to stop. ****wait_for_move_completion**** - **Description** Waits for motion to complete on all Actuators in the group. - **Parameters** - **timeout** - **Description** The timeout in seconds, after which an exception will be thrown. - **Type** float - **Raises** - **Type** [ActuatorGroupException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#actuatorgroupexception) - **Description** If the request fails or the move did not complete in the allocated amount of time. ```python from machinelogic import ActuatorGroup, Machine, MotionProfile machine = Machine() my_actuator_1 = machine.get_actuator("Actuator 1") my_actuator_2 = machine.get_actuator("Actuator 2") # Always home the actuators before starting to ensure position is properly calibrated. my_actuator_1.home(timeout=10) my_actuator_2.home(timeout=10) actuator_group = ActuatorGroup(my_actuator_1, my_actuator_2) TARGET_POSITIONS = (75.0, 158.0)  # (mm - actuator1, mm - actuator2) VELOCITY = 150.0  # mm/s ACCELERATION = 150.0  # mm/s^2 JERK = 150.0  # mm/s^3 OPTIONAL PARAMETER new_motion_profile = MotionProfile(    velocity=VELOCITY, acceleration=ACCELERATION, jerk=JERK ) # move_absolute_async will start the move and return without waiting for the move to complete. actuator_group.move_absolute_async(    position=TARGET_POSITIONS, motion_profile=new_motion_profile ) print("move started..") actuator_group.wait_for_move_completion() print("motion completed.") ``` ## MotionProfile MotionProfile: A dataclass that represents the motion profile of a move. args: ```python velocity (float): The velocity of the move in mm/s acceleration (float): The acceleration of the move in mm/s^2 jerk (float | None): The jerk of the move in mm/s^3. Defaults to None ``` If used in a continuous_move, only velocity and acceleration are required. If jerk is defined, an s-curve profile will be generated. Jerk option is commonly used to limit vibration due to sharp changes in motion profile. ## Robot A software representation of a Robot. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance: E.g.: ```python machine = Machine() my_robot = machine.get_robot("Robot") ``` In this example, "Robot" is the friendly name assigned to the actuator in the MachineLogic configuration page. ****configuration**** - **Description** The Robot configuration. - **Type** RobotConfiguration ****state**** - **Description** The current Robot state. - **Type** [RobotState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotstate) ****compute_forward_kinematics**** - **Description** Computes the forward kinematics from joint angles. - **Parameters** - **joint_angles** - **Description** The 6 joint angles, in degrees. - **Type** JointAnglesDegrees - **Returns** - **Description** Cartesian pose, in mm and degrees - **Type** CartesianPose - **Raises** - **Type** ValueError - **Description** Throws an error if the joint angles are invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** Throws an error if the resulted forward kinematics computation not successful ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Joint angles, in degrees joint_angles = [    176.68,  # j1    -35.95,  # j2    86.37,  # j3    -150.02,  # j4    -90.95,  # j5    -18.58,  # j6 ] computed_robot_pose = my_robot.compute_forward_kinematics(joint_angles) print(computed_robot_pose) ``` ****compute_inverse_kinematics**** - **Description** Computes the inverse kinematics from a Cartesian pose. - **Parameters** - **cartesian_position** - **Description** The end effector's pose, in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **joint_constraints** - **Description** A list of joint constraints. Length of list can be between 1 and number of joints on robot. - **Type** Optional[List[[GenericJointConstraint](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#genericjointconstraint)]] - **seed_position** - **Description** The seed joint angles, in degrees (as start position for IK search) - **Type** Optional[JointAnglesDegrees] - **Returns** - **Description** Joint angles, in degrees. - **Type** JointAnglesDegrees - **Raises** - **Type** ValueError - **Description** Throws an error if the inverse kinematic solver fails. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") cartesian_position = [    648.71,  # x in millimeters    -313.30,  # y in millimeters    159.28,  # z in millimeters    107.14,  # rx in degrees    -145.87,  # ry in degrees    15.13,  # rz in degrees ] computed_joint_angles = my_robot.compute_inverse_kinematics(cartesian_position) print(computed_joint_angles) ``` ****create_sequence**** - **Description** Creates a RobotMoveSequence object. - **Returns** - **Description** A RobotMoveSequence object with which you can chain movements. - **Type** [RobotMoveSequence](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotmovesequence) ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Create an arbitrary Cartesian waypoint, that is 10mm or 10 degrees away from the current position cartesian_waypoint = [i + 10 for i, _ in my_robot.state.cartesian_position_data] # Create an arbitrary joint waypoint, that is 10 degrees away from the current joint angles joint_waypoint = [i + 10 for i, _ in my_robot.state.joint_angles_data] cartesian_velocity = 100.0  # millimeters per second cartesian_acceleration = 100.0  # millimeters per second squared blend_radius_1 = 5.0  # millimeters reference_frame = [    23.56,  # x in millimeters    -125.75,  # y in millimeters    5.92,  # z in millimeters    0.31,  # rx in degrees    0.65,  # ry in degrees    90.00,  # rz in degrees ] joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared blend_radius_2 = 5.0  # millimeters with my_robot.create_sequence() as seq:    seq.append_movel(        cartesian_waypoint,        cartesian_velocity,        cartesian_acceleration,        blend_radius_1,        reference_frame,    )    seq.append_movej(joint_waypoint, joint_velocity, joint_acceleration, blend_radius_2) # Alternate Form: seq = my_robot.create_sequence() seq.append_movel(cartesian_waypoint) seq.append_movej(joint_waypoint) my_robot.execute_sequence(seq) ``` ****execute_sequence**** - **Description** Moves the robot through a specific sequence of joint and linear motions. - **Parameters** - **sequence** - **Description** The sequence of target points. - **Type** [RobotMoveSequence](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotmovesequence) - **Raises** - **Type** ValueError - **Description** If the sequence is invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Create an arbitrary Cartesian waypoint, that is 10mm or 10 degrees away from the current position cartesian_waypoint = [i + 10 for i, _ in my_robot.state.cartesian_position_data] # Create an arbitrary joint waypoint, that is 10 degrees away from the current joint angles joint_waypoint = [i + 10 for i, _ in my_robot.state.joint_angles_data] cartesian_velocity = 100.0  # millimeters per second cartesian_acceleration = 100.0  # millimeters per second squared blend_radius_1 = 5.0  # millimeters joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared blend_radius_2 = 5.0  # millimeters seq = my_robot.create_sequence() seq.append_movel(    cartesian_waypoint, cartesian_velocity, cartesian_acceleration, blend_radius_1 ) seq.append_movej(joint_waypoint, joint_velocity, joint_acceleration, blend_radius_2) my_robot.execute_sequence(seq) ``` ****execute_sequence_async**** - **Description** Moves the robot through a specific sequence of joint and linear motions asynchronously. - **Parameters** - **sequence** - **Description** The sequence of target points. - **Type** [RobotMoveSequence](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotmovesequence) - **Raises** - **Type** ValueError - **Description** If the sequence is invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Create an arbitrary Cartesian waypoint, that is 10mm or 10 degrees away from the current position cartesian_waypoint = [i + 10 for i, _ in my_robot.state.cartesian_position_data] # Create an arbitrary joint waypoint, that is 10 degrees away from the current joint angles joint_waypoint = [i + 10 for i, _ in my_robot.state.joint_angles_data] cartesian_velocity = 100.0  # millimeters per second cartesian_acceleration = 100.0  # millimeters per second squared blend_radius_1 = 5.0  # millimeters joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared blend_radius_2 = 5.0  # millimeters # Method 1: Manual execution with execute_sequence_async seq = my_robot.create_sequence() seq.append_movel(    cartesian_waypoint, cartesian_velocity, cartesian_acceleration, blend_radius_1 ) seq.append_movej(joint_waypoint, joint_velocity, joint_acceleration, blend_radius_2) my_robot.execute_sequence_async(seq) print("Robot is executing sequence asynchronously.") my_robot.wait_for_motion_completion() print("Robot has finished executing sequence.") # Method 2: Context manager with execute_async_on_exit (alternative) with my_robot.create_sequence().execute_async_on_exit() as seq:    seq.append_movel(cartesian_waypoint, cartesian_velocity, cartesian_acceleration, blend_radius_1)    seq.append_movej(joint_waypoint, joint_velocity, joint_acceleration, blend_radius_2) # Executes asynchronously when context exits print("Robot is executing sequence asynchronously.") my_robot.wait_for_motion_completion() print("Robot has finished executing sequence.") ``` ****move_stop**** - **Description** Stops the robot current movement. - **Returns** - **Description** True if the robot was successfully stopped, False otherwise. - **Type** bool ```python from machinelogic import Machine import time machine = Machine() my_robot = machine.get_robot("Robot") joint_angles = [0.0, -45.0, 45.0, 0.0, 45.0, 0.0] # Use an async move to allow move_stop to be called while the robot is moving. # Synchronous moves (movej, movel) block until completion, so stopping mid-motion would require threads. my_robot.movej_async(joint_angles) # Simulate a condition that requires stopping (e.g., sensor trigger, user input) time.sleep(1.0) my_robot.move_stop() ``` ****movej**** - **Description** Moves the robot to a specified joint position. - **Parameters** - **target** - **Description** The target joint angles, in degrees. - **Type** JointAnglesDegrees - **velocity** - **Description** The joint velocity to move at, in degrees per second. - **Type** DegreesPerSecond - **acceleration** - **Description** The joint acceleration to move at, in degrees per second squared. - **Type** DegreesPerSecondSquared - **Raises** - **Type** ValueError - **Description** If the target joint angles are invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared # Joint angles, in degrees joint_angles = [    86.0,  # j1    0.0,  # j2    88.0,  # j3    0.0,  # j4    91.0,  # j5    0.0,  # j6 ] my_robot.movej(    joint_angles,    joint_velocity,    joint_acceleration, ) ``` ****movej_async**** - **Description** Moves the robot to a specified joint position asynchronously. - **Parameters** - **target** - **Description** The target joint angles, in degrees. - **Type** JointAnglesDegrees - **velocity** - **Description** The joint velocity to move at, in degrees per second. - **Type** DegreesPerSecond - **acceleration** - **Description** The joint acceleration to move at, in degrees per second squared. - **Type** DegreesPerSecondSquared - **Raises** - **Type** ValueError - **Description** If the target joint angles are invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared # Joint angles, in degrees joint_angles = [    86.0,  # j1    0.0,  # j2    88.0,  # j3    0.0,  # j4    91.0,  # j5    0.0,  # j6 ] my_robot.movej_async(    joint_angles,    joint_velocity,    joint_acceleration, ) print("Robot is moving asynchronously to the specified joint angles.") my_robot.wait_for_motion_completion() print("Robot has finished moving to the specified joint angles.") ``` ****movel**** - **Description** Moves the robot to a specified Cartesian position relative to the robot base, - **Parameters** - **target** - **Description** The end effector's pose, in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **velocity** - **Description** The velocity to move at, in mm/s. - **Type** MillimetersPerSecond - **acceleration** - **Description** The acceleration to move at, in mm/s^2. - **Type** MillimetersPerSecondSquared - **reference_frame** - **Description** The reference frame to move relative to. If None, the robot's base frame is used. - **Type** Optional[CartesianPose] - **Raises** - **Type** ValueError - **Description** If the target Cartesian position is invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") linear_velocity = 100.0  # millimeters per second linear_acceleration = 100.0  # millimeters per second squared # Target Cartesian pose, in millimeters and degrees cartesian_pose = [    -267.8,  # x in millimeters    -89.2,  # y in millimeters    277.4,  # z in millimeters    -167.8,  # rx in degrees    0,  # ry in degrees    -77.8,  # rz in degrees ] reference_frame = [    23.56,  # x in millimeters    -125.75,  # y in millimeters    5.92,  # z in millimeters    0.31,  # rx in degrees    0.65,  # ry in degrees    90.00,  # rz in degrees ] my_robot.movel(    cartesian_pose,    linear_velocity,  # Optional    linear_acceleration,  # Optional    reference_frame,  # Optional ) ``` ****movel_async**** - **Description** Moves the robot to a specified Cartesian position asynchronously. - **Parameters** - **target** - **Description** The end effector's pose, in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **velocity** - **Description** The velocity to move at, in mm/s. - **Type** MillimetersPerSecond - **acceleration** - **Description** The acceleration to move at, in mm/s^2. - **Type** MillimetersPerSecondSquared - **reference_frame** - **Description** The reference frame to move relative to. If None, the robot's base frame is used. - **Type** Optional[CartesianPose] - **Raises** - **Type** ValueError - **Description** If the target Cartesian position is invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the move does not complete successfully. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") linear_velocity = 100.0  # millimeters per second linear_acceleration = 100.0  # millimeters per second squared # Target Cartesian pose, in millimeters and degrees cartesian_pose = [    -267.8,  # x in millimeters    -89.2,  # y in millimeters    277.4,  # z in millimeters    -167.8,  # rx in degrees    0,  # ry in degrees    -77.8,  # rz in degrees ] reference_frame = [    23.56,  # x in millimeters    -125.75,  # y in millimeters    5.92,  # z in millimeters    0.31,  # rx in degrees    0.65,  # ry in degrees    90.00,  # rz in degrees ] my_robot.movel_async(    cartesian_pose,    linear_velocity,  # Optional    linear_acceleration,  # Optional    reference_frame,  # Optional ) print("Robot is moving asynchronously to the specified Cartesian pose.") my_robot.wait_for_motion_completion() print("Robot has finished moving to the specified Cartesian pose.") ``` ****on_log_alarm**** - **Description** Set one or multiple callbacks to the log alarm which replaces the default callback. If no callback is set, the default callback is used. - **Parameters** - **callback** - **Description** A callback function to be called when a robot alarm is received. - **Type** Callable[[[RobotAlarm](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotalarm)], None] - **Returns** - **Description** The callback ID. - **Type** int ```python from machinelogic import Machine from machinelogic.types import RobotAlarm machine = Machine() my_robot = machine.get_robot("Robot") # The functon defined here is called when the specified alarm occurs def handle_log_alarm(alarm: RobotAlarm):    print(alarm.level, alarm.error_code, alarm.description) my_robot.on_log_alarm(handle_log_alarm) ``` ****on_system_state_change**** - **Description** Registers a callback for system state changes. - **Parameters** - **callback** - **Description** The callback function. - **Type** Callable[[OperationalState, [RobotSafetyState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotsafetystate)], None] - **Returns** - **Description** The callback ID. - **Type** int ```python from machinelogic import Machine from machinelogic.types import RobotOperationalState, RobotSafetyState machine = Machine() my_robot = machine.get_robot("Robot") # The function defined here is called when the specified state change occurs def handle_state_change(    robot_operational_state: RobotOperationalState, safety_state: RobotSafetyState ):    print(robot_operational_state, safety_state) callback_id = my_robot.on_system_state_change(handle_state_change) print(callback_id) ``` ****reconnect**** - **Description** It will disconnect then reconnect the MachineMotion to the robot. - **Parameters** - **timeout** - **Description** The timeout in seconds, after which an exception will be thrown, default is 15 seconds. - **Type** Union[float, None] - **Returns** - **Description** True if successful. - **Type** bool ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # if no timeout argument is provided, the default timeout is 15 seconds did_reconnect = my_robot.reconnect() print(did_reconnect) ``` ****remove_log_alarm_callback**** - **Description** Remove a previously registered log alarm callback. - **Parameters** - **callback_id** - **Description** The ID of the callback to remove. - **Type** int ```python from machinelogic import Machine, RobotAlarm machine = Machine() my_robot = machine.get_robot("Robot") def handle_log_alarm(alarm: RobotAlarm):    print(f"Alarm received: {alarm.level}, {alarm.error_code}, {alarm.description}") callback_id = my_robot.on_log_alarm(handle_log_alarm) print(f"Callback registered with ID: {callback_id}") my_robot.remove_log_alarm_callback(callback_id) print(f"Callback {callback_id} has been removed") ``` ****remove_system_state_change_callback**** - **Description** Removes a previously registered system state change callback. - **Parameters** - **callback_id** - **Description** The ID of the callback to remove. - **Type** int ```python from machinelogic import Machine from machinelogic.types import RobotOperationalState, RobotSafetyState machine = Machine() my_robot = machine.get_robot("Robot") # The function defined here is called when the specified state change occurs def handle_state_change(    robot_operational_state: RobotOperationalState, safety_state: RobotSafetyState ):    print(robot_operational_state, safety_state) callback_id = my_robot.on_system_state_change(handle_state_change) print(f"Callback registered with ID: {callback_id}") my_robot.remove_system_state_change_callback(callback_id) print(f"Callback {callback_id} has been removed") ``` ****reset**** - **Description** Deprecated: Use set_to_normal() instead. - **Returns** - **Description** True if successful. - **Type** bool ****set_active_tcp**** - **Description** Sets the active tool center point (TCP) by name. - **Parameters** - **tcp_name** - **Description** The name of the TCP to set as active. Must be defined in the robot configuration. - **Type** str - **Raises** - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the TCP name does not exist in the robot configuration. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Set a new active TCP by name # Note: The TCP must be defined in your robot configuration tcp_name = "gripper_tcp"  # Replace with your actual TCP name my_robot.set_active_tcp(tcp_name) print(f"Successfully set active TCP to: {tcp_name}") # Verify the change new_active_tcp = my_robot.state.active_tcp print(f"New active TCP: {new_active_tcp}") ``` ****set_payload**** - **Description** Sets the payload of the robot. - **Parameters** - **payload** - **Description** The payload, in kg. - **Type** Kilograms - **center_of_mass** - **Description** List of the center of mass, in mm [x, y, z]. - **Type** Vector - **inertia** - **Description** List of the inertia tensor, in kg*mm^2 [ixx, ixy, ixz, iyy, iyz, izz]. Defaults to None. - **Type** Optional[Inertia] - **Raises** - **Type** ValueError - **Description** If the center of mass or inertia tensor are invalid. - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the set payload call fails. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Weight in Kilograms weight = 2.76 my_robot.set_payload(weight, [10,10,10]) print("Robot set payload was successful") ``` ****set_tcp_offset**** - **Description** Deprecated: Use set_active_tcp() instead. - **Parameters** - **tcp_offset** - **Description** The tool center point (TCP) offset, in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **Returns** - **Description** True if the TCP offset was successfully set, False otherwise. - **Type** bool ****set_to_freedrive**** - **Description** Put the robot into freedrive mode. ```python import time from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Put the robot in free drive mode my_robot.set_to_freedrive() time.sleep(5) print(my_robot.state.operational_state) time.sleep(1) # Set the robot to normal operational state my_robot.set_to_normal() time.sleep(1) print(my_robot.state.operational_state) ``` ****set_to_normal**** - **Description** Set the robot to normal operational state. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Set the robot to normal operational state # This is useful after freedrive mode or other non-standard states my_robot.set_to_normal() # Robot state should be 'Normal' print(my_robot.state.operational_state) ``` ****wait_for_motion_completion**** - **Description** Waits for the robot to complete its current motion. Used in asynchronous movements. - **Raises** - **Type** [RobotException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotexception) - **Description** If the request fails or the move did not complete in the allocated amount of time. ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") joint_velocity = 10.0  # degrees per second joint_acceleration = 10.0  # degrees per second squared # Joint angles, in degrees joint_angles = [    86.0,  # j1    0.0,  # j2    88.0,  # j3    0.0,  # j4    91.0,  # j5    0.0,  # j6 ] my_robot.movej_async(    joint_angles,    joint_velocity,    joint_acceleration, ) print("Robot is moving asynchronously to the specified joint angles.") my_robot.wait_for_motion_completion() print("Robot has finished moving to the specified joint angles.") ``` ## RobotState A representation of the robot current state. ****active_tcp**** - **Description** The name of the currently active tool center point (TCP). - **Type** str | None ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Get the name of the currently active TCP active_tcp_name = my_robot.state.active_tcp print(f"Active TCP: {active_tcp_name}") ``` ****cartesian_position_data**** - **Description** A tuple of the robot current Cartesian position and the timestamp as a datetime object. - **Type** Tuple[CartesianPose, datetime] ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") end_effector_pose, timestamp = my_robot.state.cartesian_position_data end_effector_position_mm = end_effector_pose[:3] end_effector_orientation_euler_xyz_deg = end_effector_pose[-3:] print(f"End effector's pose: {end_effector_pose}") print(f"End effector's Cartesian position: {end_effector_position_mm}") print(f"End effector's Euler XYZ orientation: {end_effector_orientation_euler_xyz_deg}") print(f"Timestamp: {timestamp.isoformat()}") ``` ****joint_angles_data**** - **Description** A tuple of the robot current joint angles and the timestamp as a datetime object. - **Type** Tuple[JointAnglesDegrees, datetime] ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") joint_angles, timestamp = my_robot.state.joint_angles_data print(f"Joint angles: {joint_angles}") print(f"Timestamp: {timestamp.isoformat()}") ``` ****move_in_progress**** - **Description** Check if the robot is currently moving. - **Type** bool ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") print(my_robot.state.move_in_progress) ``` ****operational_state**** - **Description** The current robot operational state. - **Type** [RobotOperationalState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotoperationalstate) ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") print(my_robot.state.operational_state) ``` ****safety_state**** - **Description** The current robot safety state. - **Type** [RobotSafetyState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotsafetystate) ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") print(my_robot.state.safety_state) ``` ****tcp_offset**** - **Description** The tool center point (TCP) offset, in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose ```python from machinelogic import Machine machine = Machine() my_robot = machine.get_robot("Robot") # Get the current TCP offset current_tcp_offset = my_robot.state.tcp_offset tcp_position_mm = current_tcp_offset[:3] tcp_orientation_euler_xyz_deg = current_tcp_offset[3:] print(f"Current TCP offset: {current_tcp_offset}") print(f"TCP position offset (mm): {tcp_position_mm}") print(f"TCP orientation offset (degrees): {tcp_orientation_euler_xyz_deg}") ``` ## RobotAlarm A representation of the robot alarm. ****description**** - **Description** The description of the alarm. - **Type** str ****error_code**** - **Description** The error code of the alarm. - **Type** int ****level**** - **Description** The severity level of the alarm. UNKNOWN = 0 INFO = 1 WARNING = 2 ERROR = 3 CRITICAL = 4 - **Type** [RobotAlarmLevel](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#robotalarmlevel) ****timestamp**** - **Description** The timestamp of the alarm. - **Type** datetime ## **RobotAlarmLevel** **Description**: An enumeration. - **UNKNOWN**= 0 - **INFO**= 1 - **WARNING**= 2 - **ERROR**= 3 - **CRITICAL**= 4 ## RobotMoveSequence A class representing a sequence of robot movements. This class allows you to build up a sequence of joint and linear movements that can be executed together with blending. Supports method chaining for a fluent API. Example Usage: ```python # 1. Manual execution (explicit control): seq = robot.create_sequence() seq.append_movej([0, 0, 0, 0, 0, 0]) seq.append_movel([100, 100, 100, 0, 0, 0]) robot.execute_sequence(seq) # 2. Context manager (auto-execution on exit): with robot.create_sequence() as seq: seq.append_movej([0, 0, 0, 0, 0, 0]) seq.append_movel([100, 100, 100, 0, 0, 0]) # Executes automatically when context exits # 3. Async execution: with robot.create_sequence().execute_async_on_exit() as seq: seq.append_movej([0, 0, 0, 0, 0, 0]) # Executes asynchronously when context exits ``` ****append_movej**** - **Description** Append a joint move to the sequence. - **Parameters** - **target** - **Description** A list of 6 target joint angles in degrees. - **Type** None - **velocity** - **Description** Joint velocity in degrees per second - **Type** None - **acceleration** - **Description** Joint acceleration in degrees per second squared - **Type** None - **blend_radius** - **Description** Blend radius in millimeters for smooth transitions between moves - **Type** None - **Returns** - **Description** Self for method chaining - **Type** None ****append_movel**** - **Description** Append a linear (Cartesian) move to the sequence. - **Parameters** - **target** - **Description** Target Cartesian pose [x, y, z, rx, ry, rz] in mm and degrees - **Type** None - **velocity** - **Description** Linear velocity in millimeters per second - **Type** None - **acceleration** - **Description** Linear acceleration in millimeters per second squared - **Type** None - **blend_radius** - **Description** Blend radius in millimeters for smooth transitions between moves - **Type** None - **reference_frame** - **Description** Optional reference frame for the target pose. If None, uses robot base frame. - **Type** None - **Returns** - **Description** Self for method chaining - **Type** None ****execute_async_on_exit**** - **Description** Mark this sequence for asynchronous execution when used as a context manager. - **Returns** - **Description** Self for method chaining - **Type** None ## **RobotOperationalState** **Description**: An enumeration. - **UNKNOWN**= 0 - **IDLE**= 1 - **RUNNING**= 2 - **JOGGING**= 3 - **FREEDRIVE**= 4 - **STOPPING**= 5 - **NON_OPERATIONAL**= 6 ## **RobotSafetyState** **Description**: An enumeration. - **UNKNOWN**= 0 - **NORMAL**= 1 - **EMERGENCY_STOP**= 2 - **REDUCED_SPEED**= 3 - **RECOVERABLE_FAULT**= 4 ## GenericJointConstraint A representation of a generic joint constraint. To be used within the compute_inverse_kinematics method of a robot. ****joint_index**** - **Description** The 1-based index of the robot joint - **Type** int ****max_position**** - **Description** The maximum position a joint can reach - **Type** float ****min_position**** - **Description** The mininum position a joint can reach - **Type** float ## DigitalInput A software representation of an DigitalInput. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance. DigitalInput peripherals can be connected to the controller via the following devices: - IO Module - Push Button Module - Conveyor Motor ****configuration**** - **Description** The configuration of the DigitalInput. - **Type** [DigitalInputConfiguration](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitalinputconfiguration) ****state**** - **Description** The state of the DigitalInput. - **Type** [DigitalInputState](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitalinputstate) ```python from machinelogic import Machine machine = Machine() # Get input by friendly name # Input peripherals can be connected to the controller via the following devices: #  - IO Module #  - Push Button Module #  - Conveyor Motor my_input = machine.get_input("Input") if my_input.state.value:    print(f"{my_input.configuration.name} is HIGH") else:    print(f"{my_input.configuration.name} is LOW") ``` ****on_state_change**** - **Description** Adds a change listener to execute when the DigitalInput state changes. - **Parameters** - **callback** - **Description** The callback to be called when the DigitalInput state changes. The first argument is the new value and the second argument is the DigitalInput itself. - **Type** Callable[[bool, [DigitalInput](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitalinput)], None] ```python import time from machinelogic import Machine machine = Machine() # We are assuming here that New DigitalInput is in the MachineLogic configuration my_input = machine.get_input("Input") # this "callback" function will be called every time the digital input value changes. def on_input_state_change(value, digital_input):    if value:        print("input value is now HIGH")    else:        print("input value is now LOW") my_input.on_state_change(on_input_state_change) while True:    # ...    time.sleep(1) ``` ## DigitalInputState Representation of the current state of an DigitalInput/DigitalOutput instance. ****value**** - **Description** The current value of the IO pin. True means high, while False means low. This is different from active/inactive, which depends on the active_high configuration. - **Type** bool ## DigitalInputConfiguration Representation of the configuration of an DigitalInput/DigitalOutput. This configuration is established by the configuration page in MachineLogic. ****active_high**** - **Description** The value that needs to be set to consider the DigitalInput/DigitalOutput as active. - **Type** bool ****controller_id**** - **Description** The MachineMotion controller id of the DigitalInput/DigitalOutput. - **Type** str ****controller_port**** - **Description** The MachineMotion controller port of the DigitalInput/DigitalOutput. - **Type** int ****device_id**** - **Description** The device number of the DigitalInput/DigitalOutput. - **Type** int ****name**** - **Description** The name of the DigitalInput/DigitalOutput. - **Type** str ****pin**** - **Description** The pin number of the DigitalInput/DigitalOutput. - **Type** typing.Union[int, typing.Literal['A', 'B']] ****uuid**** - **Description** The unique ID of the DigitalInput/DigitalOutput. - **Type** str ## DigitalOutput A software representation of an Output. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance. ****configuration**** - **Description** The configuration of the Output. - **Type** [DigitalOutputConfiguration](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitaloutputconfiguration) ****write**** - **Description** Writes the value into the Output, with True being high and False being low. - **Parameters** - **value** - **Description** The value to write to the Output. - **Type** bool - **Raises** - **Type** [DigitalOutputException](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#digitaloutputexception) - **Description** If we fail to write the value to the Output. ```python from machinelogic import Machine machine = Machine() my_output = machine.get_output("Output") my_output.write(True)  # Write "true" to the Output my_output.write(False)  # Write "false" to the Output ``` ## DigitalOutputConfiguration Representation of the configuration of an DigitalInput/DigitalOutput. This configuration is established by the configuration page in MachineLogic. ****active_high**** - **Description** The value that needs to be set to consider the DigitalInput/DigitalOutput as active. - **Type** bool ****controller_id**** - **Description** The MachineMotion controller id of the DigitalInput/DigitalOutput. - **Type** str ****controller_port**** - **Description** The MachineMotion controller port of the DigitalInput/DigitalOutput. - **Type** int ****device_id**** - **Description** The device number of the DigitalInput/DigitalOutput. - **Type** int ****name**** - **Description** The name of the DigitalInput/DigitalOutput. - **Type** str ****pin**** - **Description** The pin number of the DigitalInput/DigitalOutput. - **Type** typing.Union[int, typing.Literal['A', 'B']] ****uuid**** - **Description** The unique ID of the DigitalInput/DigitalOutput. - **Type** str ## Pneumatic A software representation of a Pneumatic. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance: E.g.: ```python machine = Machine() my_pneumatic = machine.get_pneumatic("Pneumatic") ``` In this example, "Pneumatic" is the friendly name assigned to a Pneumatic in the MachineLogic configuration page. ****configuration**** - **Description** The configuration of the actuator. - **Type** [PneumaticConfiguration](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#pneumaticconfiguration) ****state**** - **Description** The state of the actuator. - **Type** typing.Literal['pushed', 'pulled', 'transition', 'unknown'] ****idle_async**** - **Description** Idles the Pneumatic. - **Raises** - **Type** PneumaticException - **Description** If the idle was unsuccessful. ****pull_async**** - **Description** Pulls the Pneumatic. - **Raises** - **Type** PneumaticException - **Description** If the pull was unsuccessful. ****push_async**** - **Description** Pushes the Pneumatic. - **Raises** - **Type** PneumaticException - **Description** If the push was unsuccessful. ## PneumaticConfiguration Representation of a Pneumatic configuration. ****controller_id**** - **Description** The MachineMotion controller id. - **Type** str ****controller_port**** - **Description** The MachineMotion controller port of the io module that controls the pneumatic axis. - **Type** int ****device_id**** - **Description** The device id of the io module that controls the pneumatic axis. - **Type** int ****input_pin_pull**** - **Description** The optional pull in pin. - **Type** typing.Optional[int] ****input_pin_push**** - **Description** The optional push in pin. - **Type** typing.Optional[int] ****name**** - **Description** The name of the Pneumatic. - **Type** str ****output_pin_pull**** - **Description** The pull out pin of the axis. - **Type** int ****output_pin_push**** - **Description** The push out pin of the axis. - **Type** int ****uuid**** - **Description** The ID of the Pneumatic. - **Type** str ## ACMotor A software representation of an AC Motor. It is not recommended that you construct this object yourself. Rather, you should query it from a Machine instance: E.g.: ```python machine = Machine() my_ac_motor = machine.get_ac_motor("AC Motor") ``` In this example, "AC Motor" is the friendly name assigned to an AC Motor in the MachineLogic configuration page. ****configuration**** - **Description** The configuration of the ACMotor. - **Type** [ACMotorConfiguration](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#acmotorconfiguration) ****move_forward**** - **Description** Begins moving the AC Motor forward. - **Raises** - **Type** ACMotorException - **Description** If the move was unsuccessful. ```python from time import sleep from machinelogic import Machine machine = Machine() my_ac_motor = machine.get_ac_motor("AC Motor") my_ac_motor.move_forward() sleep(10) my_ac_motor.stop() ``` ****move_reverse**** - **Description** Begins moving the AC Motor in reverse. - **Raises** - **Type** ACMotorException - **Description** If the move was unsuccessful. ```python import time from machinelogic import Machine machine = Machine() my_ac_motor = machine.get_ac_motor("AC Motor") # Move the AC motor in reverse my_ac_motor.move_reverse() # The AC motor will stop moving if the program terminates time.sleep(10) ``` ****stop**** - **Description** Stops the movement of the AC Motor. - **Raises** - **Type** ACMotorException - **Description** If the stop was unsuccessful. ```python import time from machinelogic import Machine machine = Machine() my_ac_motor = machine.get_ac_motor("AC Motor") # Move the AC Motor forwards my_ac_motor.move_forward() # Do something here time.sleep(10) my_ac_motor.stop() ``` ## ACMotorConfiguration Representation of a ACMotor configuration. ****controller_id**** - **Description** The MachineMotion controller id - **Type** str ****controller_port**** - **Description** The MachineMotion controller port of the io module that controls the ac_motor. - **Type** int ****device_id**** - **Description** The device id of the io module of the ac_motor. - **Type** int ****name**** - **Description** The name of the Pneumatic. - **Type** str ****output_pin_direction**** - **Description** The push out pin of the axis. - **Type** typing.Optional[int] ****output_pin_move**** - **Description** The pull out pin of the axis. - **Type** int ****uuid**** - **Description** The ID of the Pneumatic. - **Type** str ## Scene A software representation of the scene containing assets that describe and define reference frames and targets for robots. Only a single instance of this object should exist in your program. ****get_calibration_frame**** - **Description** Gets a calibration frame from scene assets by name - **Parameters** - **name** - **Description** Friendly name of the calibration frame asset - **Type** str - **Returns** - **Description** The found calibration frame - **Type** [CalibrationFrame](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#calibrationframe) - **Raises** - **Type** SceneException - **Description** If the scene asset is not found ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a calibration frame defined # in Scene Assets called "New Calibration Frame" calibration_frame = scene.get_calibration_frame("New Calibration Frame") default_value = calibration_frame.get_default_value() print(default_value) ``` ****get_cartesian_target**** - **Description** Gets a cartesian target from scene assets by name - **Parameters** - **name** - **Description** Friendly name of the cartesian target asset - **Type** str - **Returns** - **Description** The found cartesian target - **Type** [CartesianTarget](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#cartesiantarget) - **Raises** - **Type** SceneException - **Description** If the scene asset is not found ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a cartesian target defined # in Scene Assets called "New Cartesian Target" cartesian_target = scene.get_cartesian_target("New Cartesian Target") # Use the cartesian target instance to get the position relative to its parent reference frame. # Note: see the get_position example in the CartesianTarget class documentation for # more details on the get_position method. default_position = cartesian_target.get_position() print(default_position) ``` ****get_joint_target**** - **Description** Gets a joint target from scene assets by name - **Parameters** - **name** - **Description** Friendly name of the joint target asset - **Type** str - **Returns** - **Description** The found joint target - **Type** [JointTarget](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#jointtarget) - **Raises** - **Type** SceneException - **Description** If the scene asset is not found ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a joint target defined # in Scene Assets called "New Joint Target" joint_target = scene.get_joint_target("New Joint Target") joint_angles = joint_target.get_joint_angles() print(joint_angles) ``` ****get_reference_frame**** - **Description** Gets a reference frame from scene assets by name - **Parameters** - **name** - **Description** Friendly name of the reference frame asset - **Type** str - **Returns** - **Description** The found reference frame - **Type** [ReferenceFrame](https://docs.vention.io/technicaldocumentation/docs/vention-python-api#referenceframe) - **Raises** - **Type** SceneException - **Description** If the scene asset is not found ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a reference frame defined # in Scene Assets called "New Reference Frame" reference_frame = scene.get_reference_frame("New Reference Frame") # Use the reference frame instance to get its position relative to its parent reference frame. # Note: see the get_position example in the ReferenceFrame class documentation for # more details on the get_position method. default_position = reference_frame.get_position() print(default_position) ``` ## CalibrationFrame A calibration frame, as defined in the scene assets pane, is represented in software. It is measured in millimeters and degrees, with angles given as extrinsic Euler angles in XYZ order. ****get_calibrated_value**** - **Description** Gets the calibration frame's calibrated values. - **Returns** - **Description** The calibrated value of the calibration frame in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **Raises** - **Type** SceneException - **Description** If failed to get the calibrated value ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a calibration frame defined # in Scene Assets called "New Calibration Frame" calibration_frame = scene.get_calibration_frame("New Calibration Frame") calibrated_value = calibration_frame.get_calibrated_value() print(calibrated_value) ``` ****get_default_value**** - **Description** Gets the calibration frame's default values. - **Returns** - **Description** The nominal value of the calibration frame in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **Raises** - **Type** SceneException - **Description** If failed to get the default value ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a calibration frame defined # in Scene Assets called "New Calibration Frame" calibration_frame = scene.get_calibration_frame("New Calibration Frame") default_value = calibration_frame.get_default_value() print(default_value) ``` ****set_calibrated_value**** - **Description** Sets the calibration frame's calibrated values. - **Parameters** - **frame** - **Description** The calibrated values of the Calibration Frame in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesionPose - **Raises** - **Type** SceneException - **Description** If failed to set the calibrated value ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a calibration frame defined # in Scene Assets called "New Calibration Frame" calibration_frame = scene.get_calibration_frame("New Calibration Frame") # CartesianPose in mm and degrees, where the angles are # extrinsic Euler angles in XYZ order. calibrated_cartesian_pose = [100, 100, 50, 90, 90, 0] calibration_frame.set_calibrated_value(calibrated_cartesian_pose) ``` ## ReferenceFrame A reference frame, as defined in the scene assets pane, is represented in software. It is measured in millimeters and degrees, with angles given as extrinsic Euler angles in XYZ order. ****get_position**** - **Description** Gets the reference frame's position. If the reference frame underwhich the position is requested is calibrated, - **Parameters** - **relative_to** - **Description** The reference frame's position relative to the robot base or its parent reference frame. Defaults to "parent". - **Type** Literal["robot_base", "parent"] - **Returns** - **Description** The position of the reference frame in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **Raises** - **Type** SceneException - **Description** If failed to get the position ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a reference frame defined # in Scene Assets called "New Reference Frame" reference_frame = scene.get_reference_frame("New Reference Frame") # You can specify the relative_to parameter to get the position # relative its "parent" frame or the "robot_base" frame. Default is "parent". reference_frame_wrt_parent = reference_frame.get_position(relative_to="parent") print(reference_frame_wrt_parent) reference_frame_wrt_robot_base = reference_frame.get_position(relative_to="robot_base") print(reference_frame_wrt_robot_base) ``` ## CartesianTarget A cartesian target, as defined in the scene assets pane, is represented in software. It is measured in millimeters and degrees, with angles given as extrinsic Euler angles in XYZ order. ****get_position**** - **Description** Gets the cartesian target's pose values. If the reference frame underwich the position is requested is calibrated, - **Parameters** - **relative_to** - **Description** The reference frame to which the position is relative. Defaults to "parent". - **Type** Literal["robot_base", "parent"] - **Returns** - **Description** The pose of the cartesian target in mm and degrees, where the angles are extrinsic Euler angles in XYZ order. - **Type** CartesianPose - **Raises** - **Type** SceneException - **Description** If failed to get the default value ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a cartesian target defined # in Scene Assets called "New Cartesian Target" cartesian_target = scene.get_cartesian_target("New Cartesian Target") # You can specify the relative_to parameter to get the position # relative its "parent" frame or the "robot_base" frame. Default is "parent". cartesian_target_wrt_parent = cartesian_target.get_position(relative_to="parent") print(cartesian_target_wrt_parent) cartesian_target_wrt_robot_base = cartesian_target.get_position(    relative_to="robot_base" ) print(cartesian_target_wrt_robot_base) # Important: In order to move to the position obtained from the Cartesian Target, you must use the # value obtained from the position relative to the robot_base: my_robot = machine.get_robot("Robot") my_robot.movel(cartesian_target_wrt_robot_base) ``` ## JointTarget A joint target is a representation of a target position for a robot's joints. It is defined by the joint angles in degrees. ****get_joint_angles**** - **Description** Gets the joint target's default values. - **Returns** - **Description** The nominal value of the joint target in degrees. - **Type** JointAnglesDegrees [j1_deg, j2_deg, j3_deg, j4_deg, j5_deg, j6_deg] - **Raises** - **Type** SceneException - **Description** If failed to get the default value ```python from machinelogic import Machine machine = Machine() scene = machine.get_scene() # Assuming we have a joint target defined # in Scene Assets called "New Joint Target" joint_target = scene.get_joint_target("New Joint Target") joint_angles = joint_target.get_joint_angles() print(joint_angles) ``` ## ActuatorException An exception thrown by an Actuator Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## MachineException An exception thrown by the Machine Args: ```python Exception (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## RobotException An exception thrown by a Robot Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## MachineMotionException An exeption thrown by a MachineMotion Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## DigitalInputException An exception thrown by an INput Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## DigitalOutputException An exception thrown by an Output Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## ActuatorGroupException An exception thrown by an ActuatorGroup Args: ```python VentionException (VentionException): Super class ``` ****with_traceback**** - **Description** Exception.with_traceback(tb) -- ## Related - [MachineLogic Python Programming Guide](/machinelogic-python-programming-guide.md)