Siemens PLC Snap7 Functions

You are currently viewing the documentation for the latest version (2.1.0). To access a different version, click the "Switch version" button located in the upper-right corner of the page.

■ If you are not sure which version of the product you are currently using, please feel free to contact Mech-Mind Technical Support.

This topic introduces the Standard Interface functions that are based on the Snap7 protocol (also known as the S7 protocol) of Siemens PLCs.

Register Instructions

The register information for each variable used during S7 communication between the PLC and the vision system is shown in the table below.

Name Data type Offset Description

ToCamera

Struct

0.0

PLC output, that is, from the PLC to the vision system

Command Trigger

Bool

0.0

Trigger signal

Command

Int

2.0

Function code

Pose Type

Int

4.0

Pose type

Pose Number

Int

6.0

Expected number of vision points or waypoints

Vision Project No.

Int

8.0

Mech-Vision project ID

Recipe No.

Int

10.0

Parameter recipe ID

Joint Position

Array[0..5] of Real

12.0

Joint positions

Flange Pose

Array[0..5] of Real

36.0

Flange pose

Branch Name

Int

60.0

Branch by Msg Step ID

Branch Exit Port

Int

62.0

Number of the exit port of the Branch by Msg Step

Index Name

Int

64.0

Step ID of the index-type Step

Index Counter

Int

66.0

Value of the Current Index parameter of the index-type Step

External Input Box Dimension

Array[0..2] of Real

68.0

Object dimensions (length, width, height) to be input to the Mech-Vision project

External Input Pose

Array[0..5] of Real

80.0

External robot TCP to be input to the Mech-Viz project

Robot Move Status

Int

104.0

Robot motion status

Depalletize Tool Section Count

Int

106.0

Number of vacuum gripper sections

FromCamera

Struct

108.0

PLC input, that is, from the vision system to the PLC

Reserved

Array[0..42] of Int

108.0

Reserved field

Trigger Acknowledge

Bool

194.0

Trigger confirmation

Notify

Int

196.0

Message from the Notify Step

Heartbeat

Bool

198.0

Heartbeat value

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Number of Pose Sent

Int

204.0

Number of vision points or waypoints

Index of Vision Picking Point

Int

206.0

Position of “Vision Move” in planned path

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all waypoints or vision points obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all waypoints or vision points obtained this time

Target Tool ID

Array[0..39] of Int

1248.0

Tool IDs of all waypoints obtained this time

Digital Output

Array[0..63] of Int

1328.0

64 DO signals returned by the vision system

Custom Vision Output

Array[0..39, 0..9] of Real

1456.0

Custom data of all waypoints or vision points obtained this time

Target IsVisualMove

Array[0..39] of Int

3056.0

Whether the waypoint is a waypoint of the “Vision Move” Step

Target Move Type

Array[0..39] of Int

3136.0

Robot motion type

Speed Percentage

Array[0..39] of Int

3216.0

Velocity at this waypoint

VisualMove Planning Result

Array[0..39, 0..39] of Real

3296.0

Vision Move data

Function 101: Trigger Mech-Vision Project

Description

This function triggers the Mech-Vision project to run. When the Mech-Vision project is running, the vision system triggers the camera to capture images and then process the returned images with algorithms to produce a series of vision points or waypoints.

  • Vision point: An object recognized by Mech-Vision. A vision point has information including the object pose, label, dimensions, and custom data.

  • Waypoint: Each point that the robot reaches when moving along the planned path. A waypoint has information including the robot pose, label, and motion type.

Calling Sequence

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 101

Vision Project No.

Int

8.0

Mech-Vision project ID

Pose Number

Int

6.0

Expected number of vision points or waypoints

Pose Type

Int

4.0

Robot pose type

Joint Position and Flange Pose

Array[0..5] of Real

12.0 and 36.0

Robot pose. Joint Position indicates joint positions of the robot, and Flange Pose indicates the flange pose of the robot

Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

Pose Number

This parameter indicates the number of vision points or waypoints expected to be returned by the Mech-Vision project.

If the Mech-Vision project has a Path Planning Step, this parameter indicates the expected number of waypoints. Otherwise, it indicates the expected number of vision points.
  • 0: Obtain all vision points or waypoints from the Mech-Vision project.

  • A positive integer: Obtain the specific number of vision points or waypoints from the Mech-Vision project.

    • If the total amount of vision points or waypoints output by the Mech-Vision project is smaller than the parameter value, this function will obtain the number of all vision points or waypoints.

    • If the total amount of vision points or waypoints output by the Mech-Vision project is larger than or equal to the parameter value, this function will obtain the number of vision points or waypoints as specified by this parameter.

Pose Type and Joint Position/Flange Pose

  • The robot pose type specifies the type of the pose of the real robot to be input to the Mech-Vision project. The value range is from 0 to 3.

  • The value of the robot pose is decided by that of the robot pose type.

The following table explains the relationship between the two parameters.

Robot pose type Robot pose Description Applicable Scenarios

0

0,0,0,0,0,0

The command does not send the robot pose data to the Mech-Vision project.

If the “Path Planning” Step is used in the Mech-Vision project, the start point of the planned path will be the Home point set in the path planning tool.

This setting should be used if the camera is mounted in eye to hand mode and the project does not require images to be captured beforehand.

1

Robot’s current JPs and flange pose

The robot joint positions and flange pose must be input to the Mech-Vision project.

This setting should be used when the camera is mounted in eye in hand mode.

This setting is recommended for most scenarios except those involving gantry robots.

2

Robot’s current flange pose

The robot flange pose must be input to the Mech-Vision project.

This setting is recommended for scenarios involving gantry robots.

3

User-defined joint positions

This command sends custom joint positions to the Mech-Vision project.

This joint positions will be sent to the Path Planning Step in the Mech-Vision project as the start point, where the robot will move from this start point to the first waypoint of the planned path.

This setting should be used if the camera is mounted in eye to hand mode and the project requires images to be captured beforehand.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 1102 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 102: Get Vision Result

Description

This function obtains vision result, namely, a series of vision points, from Mech-Vision. The object pose of the vision point (namely, the output of the poses port of the Output Step) will be automatically converted to the robot’s TCP by the vision system. The process is as follows.

get tcp
  1. Convert the object pose from the form of quaternions to Euler angles.

  2. Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.

    convert tcp

Calling Sequence

This function should be called after Function 101: Trigger Mech-Vision Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 102

Vision Project No.

Int

8.0

Mech-Vision project ID

Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Number of Pose Sent

Int

204.0

Number of vision points

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all vision points obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all vision points obtained this time

Status Code

Status code 1100 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Status of Pose Sent

This parameter indicates the data transmission status. 1 indicates that the data obtained from the vision system is new data. After the PLC reads the new data, please reset this register.

Number of Pose Sent

This parameter indicates the number of obtained vision points. By default, the vision system sends no more than 20 vision points at a time. Therefore, the maximum default value of this parameter is 20.

Target Pose

This parameter indicates the poses of all vision points obtained, with the pose type being TCP.

The vision system automatically converts the object poses of vision points (i.e., data from the "poses" port of the "Output" step) into the corresponding TCPs.
get tcp
  1. Convert the object pose from the form of quaternions to Euler angles.

  2. Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.

    convert tcp

Target Label

This parameter indicates the labels (i.e., data from the "labels" port of the "Output" step) of all obtained vision points.

  • A label must be a integer-formatted string. If the data is not an integer-formatted string, add a Label Mapping Step before the Output Step to transform the output of the labels port to an integer-formatted string.

  • If the “Output” Step does not have a “labels” port, the Target Label value is 0.

Function 103: Switch Mech-Vision Parameter Recipe

Description

This function triggers Mech-Vision to switch the parameter recipe used by the project. The image below shows how to manually switch the parameter recipe for a Mech-Vision project. For details about parameter recipes, see the parameter recipe guide.

set recipe

Calling Sequence

This function should be called BEFORE Function 101: Trigger Mech-Vision Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 103

Vision Project No.

Int

8.0

Mech-Vision project ID

Recipe No.

Int

10.0

Parameter recipe ID

Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

Recipe No.

The ID of the parameter recipe in the Mech-Vision project. The ID is a positive integer, from 1 to 99. For details on how to check the parameter recipe ID, see View the Parameter Recipe ID.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 1107 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 105: Get Planned Path from Mech-Vision

Description

This function obtains the path planned by the Mech-Vision project as a series of waypoints. The path is planned by the path planning tool, which you may enter by clicking Config wizard as shown in the image below. For details about Path Planning, see Path Planning.

Set the Port Type parameter of the “Output” Step in Mech-Vision to “Predefined (robot path)”.
get plan path step

Calling Sequence

This function should be called after Function 101: Trigger Mech-Vision Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 105

Vision Project No.

Int

8.0

Mech-Vision project ID

Pose Type

Int

4.0

Waypoint pose type

Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

Pose Type

This parameter specifies the type of waypoint poses to be obtained.

  • 1: Robot’s Joint positions (JPs)

  • 2: Tool pose of the robot

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Number of Pose Sent

Int

204.0

Number of waypoints

Index of Vision Picking Point

Int

206.0

Position of “Vision Move” in planned path

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all waypoints obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all waypoints obtained this time

Target Tool ID

Array[0..39] of Int

1248.0

Tool IDs of all waypoints obtained this time

Status Code

Status code 1103 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Status of Pose Sent

This parameter indicates the data transmission status. 1 indicates that the data obtained from the vision system is new data. After the PLC reads the new data, please reset this register.

Number of Pose Sent

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 20 waypoints at a time. Therefore, the maximum default value of this parameter is 20.

BEFORE calling Function 105: Get Planned Path from Mech-Vision, set the expected number of vision points or waypoints parameter of Function 101: Trigger Mech-Vision Project to 0 to minimize the times of calling Function 105: Get Planned Path from Mech-Vision. If the expected number of vision points or waypoints parameter of Function 101: Trigger Mech-Vision Project is set to 1, only one waypoint will be obtained each time you call Function 105: Get Planned Path from Mech-Vision. You will need to call Function 105 for several times to obtain all waypoints.

Index of Vision Picking Point

This parameter indicates the position of the Vision Move waypoint corresponding to the “Vision Move” Step of the path planning tool in the entire path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of waypoints “Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, Fixed-Point Move_3” in sequence, the position of the Vision Move waypoint is 3.

In the scenario where the robot needs to send this function multiple times to receive the entire path, this parameter has slightly different interpretations in the responses. In the first response, it indicates the position of the Vision Move waypoint in the entire path, while in subsequent responses, this parameter indicates the position of the Vision Move waypoint among the remaining waypoints.

Target Pose

This parameter indicates the poses of all waypoints obtained this time. The pose type can be TCP or joint positions. The pose type is decided by the Pose Type parameter in the function sent by the robot.

Target Label

This parameter indicates the labels (i.e., data from the "labels" port of the "Output" step) of all obtained waypoints.

  • A label must be a integer-formatted string. If the data is not an integer-formatted string, add a Label Mapping Step before the Output Step to transform the output of the labels port to an integer-formatted string.

  • If the “Output” Step does not have a “labels” port, the Target Label value is 0.

Target Tool ID

This parameter indicates the tool IDs of all waypoints obtained this time. Tool IDs are set in the path planning tool.

Function 110: Get Custom Data from Mech-Vision

Description

This function obtains data from the custom port(s) of the “Output” Step in Mech-Vision. Select the Output Step and click Open the editor to enter the settings window of custom ports. The Customized Keys panel displays custom port names, such as customeData1 and customeData2 in the image below.

  1. Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.

  2. Port Type of the Output Step in Mech-Vision must be Custom, and the poses port is required.

custom data

Calling Sequence

This function should be called after Function 101: Trigger Mech-Vision Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 110

Vision Project No.

Int

8.0

Mech-Vision project ID

Mech-Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all vision points obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all vision points obtained this time

Custom Vision Output

Array[0..39, 0..9] of Real

1456.0

Custom data of all vision points obtained this time

Status Code

Status code 1100 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Status of Pose Sent

This parameter indicates the data transmission status. 1 indicates that the data obtained from the vision system is new data. After the PLC reads the new data, please reset this register.

Target Pose

This parameter indicates the poses of all vision points obtained, with the pose type being TCP.

The vision system automatically converts the object poses of vision points (i.e., data from the "poses" port of the "Output" step) into the corresponding TCPs.
get tcp
  1. Convert the object pose from the form of quaternions to Euler angles.

  2. Rotate the object’s pose around the X-axis by 180° to orient its Z-axis downward.

    convert tcp

Target Label

This parameter indicates the labels (i.e., data from the "labels" port of the "Output" step) of all obtained vision points.

  • A label must be a integer-formatted string. If the data is not an integer-formatted string, add a Label Mapping Step before the Output Step to transform the output of the labels port to an integer-formatted string.

  • If the “Output” Step does not have a “labels” port, the Target Label value is 0.

Custom Vision Output

Custom data of all vision points obtained this time. For example, data output from ports of the “Output” Step is presented in the following table. The elements in custom data of the first vision point are [0, 0, 1] and [0, 0]; and the elements in custom data of the second vision point are [1, 0, 0] and [1, 1].

Port name

poses

labels

customData1

customData2

Output port data

[

[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]

]

[

"0",
"1"

]

[

[0, 0, 1],
[1, 0, 0]

]

[

[0, 0],
[1, 1]

]

First vision point

[0, 0, 0, 1, 0, 0, 0]

0

[0, 0, 1]

[0, 0]

Second vision point

[0, 0, 0, 1, 0, 0, 0]

1

[1, 0, 0]

[1, 1]

The custom output data is arranged in alphabetical order of the names of custom ports.

Function 201: Trigger Mech-Viz Project

Description

This function starts the Mech-Viz project to run. Mech-Viz plans the robot’s motion path based on the vision result output by Mech-Vision.

Right-click the project name in the “Resources” panel in Mech-Viz and select Autoload Project.

Calling Sequence

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 201

Pose Type

Int

4.0

Robot pose type

Joint Position and Flange Pose

Array[0..5] of Real

12.0 and 36.0

Robot pose. Joint Position indicates joint positions of the robot, and Flange Pose indicates the flange pose of the robot

Pose Type and Joint Position/Flange Pose

  • Robot pose type specifies the type of the pose of the real robot to be input to the Mech-Viz project. The value range is 0 to 2.

  • The value of the robot pose type parameter specifies what robot pose will be sent to the vision system.

The following table explains the relationship between the two parameters.

Robot pose type Robot pose Description Applicable scenario

0

0, 0, 0, 0, 0, 0

The robot will not send its pose to the Mech-Viz project. The simulated robot in Mech-Viz moves from the initial pose (JPs = [0, 0, 0, 0, 0, 0]) to the first waypoint.

The camera mounting mode is eye to hand.

1

Current joint positions and flange pose of the robot

The robot sends its current joint positions and flange pose to the Mech-Viz project. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.

This setting is recommended when the camera is mounted in eye in hand mode.

2

Specific joint positions of the robot

The robot sends the JPs of a teaching point, instead of the current JPs, to the Mech-Viz project. The Mech-Viz project uses the JPs to plan the next path in advance while the robot is not in the camera capture region, as shown below. The simulated robot in Mech-Viz moves from the input joint positions to the first waypoint.

This setting is recommended when the camera is mounted in eye to hand mode.

Why robot pose type 2 is recommended when the camera is mounted in eye to hand mode?

In eye to hand mode, the camera can perform image capturing for the next round of path planning before the robot returns to the image capture region and picking region, thus shortening the cycle time. The image below demonstrates how a robot works in the placing region.

If robot pose type is set to 1, the robot will send the current pose to Mech-Viz. It is possible that the real robot moves to other positions before reaching the first waypoint. However, the simulated robot moves directly to the first waypoint of the Mech-Viz project from the pose sent by the robot. Consequently, there may be a mismatch between the paths of the real robot and simulated robot. This mismatch can potentially lead to unpredicted safety hazards, especially if collision is detected in the path of the simulated robot.

On the other hand,if robot pose type is set to 2, the robot will send the taught image-capturing pose set on the robot side to Mech-Viz. Thus, the real robot can trigger the next round of path planning in Mech-Viz when the real robot is in the image-capturing region and the cycle time can be shortened.

In conclusion, robot pose type should be set to 2 for projects in eye to hand mode.

robot example

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 2103 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 202: Stop Mech-Viz Project

Description

This function stops the Mech-Viz project.

Calling Sequence

This function should be called after Function 201: Trigger Mech-Viz Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 202

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 2104 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 203: Set Exit Port for Branch by Msg in Mech-Viz

Description

This function sets the exit port for the Branch by Msg Step. When the next Step is a Branch by Msg Step, the Mech-Viz project will wait for this function to specify the exit port.

set branch

Calling Sequence

This function should be called after Function 201: Trigger Mech-Viz Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 203

Branch Name

Int

60.0

Branch by Msg Step ID

Branch Exit Port

Int

62.0

Number of the exit port of the Branch by Msg Step

Branch Name

This parameter specifies the Step ID of the “Branch by Msg” Step. The value is a positive integer. The Step ID is displayed in the Step parameter panel. For example, the Step ID of the Step in the image above is 1.

Branch Exit Port

This parameter specifies the exit port of the “Branch by Msg” Step. The value is a positive integer. When the parameter value is set to “N”, the Mech-Viz project exits from the port with an ID of “N-1” of the “Branch by Msg” Step. Assume that you set Branch Name to 2 and Branch Exit Port to 1. When the Mech-Viz project execution reaches the Branch by Msg Step No.2 after the PLC sends this function to the vision system, the project will take exit port 0 of the Branch by Msg Step No.2.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 2105 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 204: Set Current Index for Mech-Viz

Description

This function sets the value of the Current Index parameter of index-type Steps. Index-type Steps are Steps that include the Index section, which include Move by Grid, Move by List, Custom Pallet Pattern, and Predefined Pallet Pattern.

set index

Calling Sequence

Index-type Steps are often preceded by a “Branch by Msg” Step. The robot should call functions in this order: Function 201: Trigger Mech-Viz Project, Function 204: Set Current Index for Mech-Viz, and Function 203: Set Exit Port for Branch by Msg in Mech-Viz. This is to ensure that Mech-Viz has enough time to set the Current Index value.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 204

Index Name

Int

64.0

Step ID of the index-type Step

Index Counter

Int

66.0

Value of the Current Index parameter of the index-type Step

Index Name

This parameter specifies the Step ID of the Index-type Step. The value is a positive integer. The Step ID is displayed in the Step parameter panel. For example, the Step ID of the Step in the image above is 3.

Index Counter

This parameter specifies the Current Index value for a Index-type Step. The value is a positive integer. When this parameter value is set to N, the current index of the corresponding Step is N-1. Assume that you set Index Name to 2 and Index Counter to 1. After the PLC sends this function to the vision system, the Current Index value of Index-type Step No.2 is 0.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 2106 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 205: Get Planned Path from Mech-Viz

Description

This function obtains the path planned by the Mech-Viz project as a series of waypoints.

Waypoint: Each point that the robot reaches when moving along the planned path. A waypoint has information including the robot pose, label, and motion type. Waypoints can be divided into two categories:

  • Vision Move waypoint: Waypoint corresponding to the Vision Move Step.

  • Non-Vision Move waypoints, which refer to the waypoints corresponding to move-type Steps other than the Vision Move Step.

Calling Sequence

This function should be called after Function 201: Trigger Mech-Viz Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 205

Pose Type

Int

4.0

Waypoint pose type

Pose Type

This parameter specifies the type of waypoint poses to be obtained.

  • 1: Robot’s Joint positions (JPs)

  • 2: Tool pose of the robot

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Number of Pose Sent

Int

204.0

Number of waypoints

Index of Vision Picking Point

Int

206.0

Position of “Vision Move” in planned path

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all waypoints obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all waypoints obtained this time

Target Tool ID

Array[0..39] of Int

1248.0

Tool IDs of all waypoints obtained this time

Status Code

Status code 2100 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Status of Pose Sent

This parameter indicates the data transmission status. 1 indicates that the data obtained from the vision system is new data. After the PLC reads the new data, please reset this register.

Number of Pose Sent

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 20 waypoints at a time. Therefore, the maximum default value of this parameter is 20.

Index of Vision Picking Point

This parameter specifies the position of the Vision Move waypoint (i.e., the waypoint corresponding to the “Vision Move” Step in the Mech-Viz project) in the planned path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of waypoints “Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, Fixed-Point Move_3” in sequence, the position of the Vision Move waypoint is 3.

In the scenario where the robot needs to send this function multiple times to receive the entire path, this parameter has slightly different interpretations in the responses. In the first response, it indicates the position of the Vision Move waypoint in the entire path, while in subsequent responses, this parameter indicates the position of the Vision Move waypoint among the remaining waypoints.

Target Pose

This parameter indicates the poses of all waypoints obtained this time. The pose type can be TCP or joint positions. The pose type is decided by the Pose Type parameter in the function sent by the robot.

Target Label

This parameter indicates the labels (i.e., data from the "labels" port of the "Output" step) of all obtained waypoints.

  • A label must be a integer-formatted string. If the data is not an integer-formatted string, add a Label Mapping Step before the Output Step to transform the output of the labels port to an integer-formatted string.

  • If the “Output” Step does not have a “labels” port, the Target Label value is 0.

Target Tool ID

This parameter indicates the tool IDs of all waypoints obtained this time. Tool IDs are set in the Mech-Viz project.

Function 206: Get Gripper DO List

Description

This function obtains the gripper DO list planned by Mech-Vision or Mech-Viz. Before using this function, you must perform the following configurations in Mech-Vision or Mech-Viz.

  • Configure the Mech-Vision project

    • In the Path Planning Step, click Config wizard. In Global configuration, enable Box depalletizing.

      vision move vis
    • In the Path Planning Step, click Config wizard, and then double-click the name of the robot tool. In the pop-up window, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure DO signals according to needs.

      sucker vis
  • Configure the Mech-Viz project

    • In the Vision Move Step of Mech-Viz, set Select Picking Method to Box depalletizing.

      vision move viz
    • In Mech-Viz, double-click the tool name, select Depalletizing vacuum gripper for Tool type, click Configure depalletizing vacuum gripper, and then configure the DO signals according to needs.

      sucker viz

Calling Sequence

This function must be called before the Function 105: Get Planned Path from Mech-Vision or Function 205: Get Planned Path from Mech-Viz function. This means that the PLC must obtain the planned path and then obtain gripper DO signals of the Vision Move waypoint.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 206

Vision Project No.

Int

8.0

Source of the gripper DO list

Depalletize Tool Section Count

Int

106.0

Number of vacuum gripper sections

Vision Project No.

This parameter specifies the source of the gripper DO list. Valid values:

  • 0: Get gripper DO list from Mech-Viz.

  • Positive integer: Get gripper DO list from Mech-Vision. The positive integer is the ID of the Mech-Vision project.

Depalletize Tool Section Count

This parameter indicates the number of vacuum gripper sections. For example, the number of gripper sections in the above image is 3.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Digital Output

Array[0..63] of Int

1328.0

64 DO signals returned by the vision system

Status Code

If the function is executed successfully, the status code is 2102 (which means the gripper DO list is obtained from Mech-Viz) or 1106 (which means the gripper DO list is obtained from Mech-Vision). For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Digital Output

This parameter indicates the 64 DO signals returned by the vision system. The DO signals returned vary based on the deployed project.

  • Gripper DO signals planned by the Mech-Vision project

    • Under Global Configuration of the path planning tool, if Plan all vision results is disabled, this function returns 64 gripper DO signals that are planned in this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.

      plan all vis off

      For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these DO signals to ON.

      1st

      2nd

      3rd

      4th

      5th

      6th

      7th

      8th

      ...

      63rd

      64th

      1

      3

      5

      6

      -1

      -1

      -1

      -1

      ...

      -1

      -1

    • Under Global Configuration of the path planning tool, if Plan all vision results is enabled, Mech-Vision can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this function are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.

      plan all vis on

      For example, if the number of vacuum gripper sections is 4 and the function returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.

      First round of planning

      Second round of planning

      ...

      16th round of planning

      1st

      2nd

      3rd

      4th

      5th

      6th

      7th

      8th

      ...

      61st

      62nd

      63rd

      64th

      1

      3

      4

      -1

      1

      4

      -1

      -1

      ...

      -1

      -1

      -1

      -1

  • Gripper DO signals planned by the Mech-Viz project

    • If Reuse Vision Result is not selected for the Vision Move Step, this function returns 64 gripper DO signals that are planned during this round. Valid DO signals are non-negative integers ranging from 0 to 999. Invalid DO signals are -1, which serves as a placeholder.

      vision move off

      For example, valid DO signals in the table below are 1, 3, 5, and 6, which means that the robot will set the values of these DO signals to ON.

      1st

      2nd

      3rd

      4th

      5th

      6th

      7th

      8th

      ...

      63rd

      64th

      1

      3

      5

      6

      -1

      -1

      -1

      -1

      ...

      -1

      -1

    • If Reuse Vision Result is selected for the Vision Move Step and the Vision Move Step is used in a loop, Mech-Viz can perform multiple rounds of planning based on the same vision result. The 64 gripper DO signals returned by this function are obtained during all rounds of planning. In this case, you can use the number of vacuum gripper sections to differentiate the gripper DO signals obtained during each round of planning.

      vision move on

      For example, if the number of vacuum gripper sections is 4 and the function returns 64 DO signals in total, each 4 DO signals are multi-section vacuum gripper signals obtained during each round of planning.

      First round of planning

      Second round of planning

      ...

      16th round of planning

      1st

      2nd

      3rd

      4th

      5th

      6th

      7th

      8th

      ...

      61st

      62nd

      63rd

      64th

      1

      3

      4

      -1

      1

      4

      -1

      -1

      ...

      -1

      -1

      -1

      -1

Function 210: Get Vision Move Data or Custom Output Data

This function obtains Vision Move data from the Mech-Vision project, or the Vision Move data or custom data from the Mech-Viz project. One function call stores all data in robot memory.

For Mech-Viz 2.0, this function obtains only Vision Move data and does not obtain custom data.
  • Mech-Vision projects: Vision Move data refers to data output by the Vision Move Step in the path planning tool, which you may enter from the Path Planning Step. Vision Move data includes labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, and dimensions of workobject group.

  • Mech-Viz projects:

    • Vision Move data refers to data output by the Vision Move Step in Mech-Viz, including the labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, and dimensions of workobject group.

    • Custom data refers to data output by the custom port(s) of the Output Step in Mech-Vision and then forwarded by Mech-Viz.

      Select the Output Step and click Open the editor to enter the settings window of custom ports. The Customized Keys panel displays custom port names, such as customeData1 and customeData2 in the image below.

      1. Data output from Predefined Keys, such as poses, labels, sizes, offsets, is not custom data.

      2. Port Type of the Output Step in Mech-Vision must be Custom, and the poses port is required.

      custom data

Calling Sequence

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 210

Vision Project No.

Int

8.0

Source of the Vision Move data

Pose Type

Int

4.0

This parameter specifies the expected format of the returned data.

Vision Project No.

This parameter specifies the source of the Vision Move data. Valid values:

  • 0: Get Vision Move output from Mech-Viz.

  • Positive integer: Get Vision Move output from Mech-Vision. The positive integer is the Mech-Vision project ID.

Pose Type

This parameter specifies the expected format of the returned data. The value range is 1 to 4.

  • When Vision Project No. is 0, the value range of Pose Type is from 1 to 4. Detailed description is in the table below.

    Value of Pose Type Format of returned data (Explained below)

    1

    Pose (joint positions), motion type, tool ID, velocity, element 1 in custom output data, … element N in custom output data

    2

    Pose (TCP), motion type, tool ID, velocity, element 1 in custom output data, … element N in custom output data

    3

    Pose (joint positions), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom output data, … element N in custom output data

    4

    Pose (TCP), motion type, tool ID, velocity, Mech-Viz Vision Move data, element 1 in custom output data, … element N in custom output data

  • When Vision Project No. is a positive integer, the value range of Pose Type is from 1 to 2. Detailed description is in the table below.

    Value of Pose Type Format of returned data (Explained below)

    1

    Pose (joint positions), motion type, tool ID, velocity, Mech-Vision Vision Move data

    2

    Pose (TCP), motion type, tool ID, velocity, Mech-Vision Vision Move data

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status of Pose Sent

Bool

202.0

Data transmission status

Number of Pose Sent

Int

204.0

Number of waypoints

Index of Vision Picking Point

Int

206.0

Position of “Vision Move” in planned path

Target Pose

Array[0..39, 0..5] of Real

208.0

Poses of all waypoints obtained this time

Target Label

Array[0..39] of Int

1168.0

Labels of all waypoints obtained this time

Speed Percentage

Array[0..39] of Int

3216.0

Velocity at this waypoint

Custom Vision Output

Array[0..39, 0..9] of Real

1456.0

Custom data of all waypoints obtained this time

Target IsVisualMove

Array[0..39] of Int

3056.0

Whether the waypoint is a waypoint of the “Vision Move” Step

Target Move Type

Array[0..39] of Int

3136.0

Robot motion type

Target Tool ID

Array[0..39] of Int

1248.0

Tool IDs of all waypoints obtained this time

VisualMove Planning Result

Array[0..39, 0..39] of Real

3296.0

Vision Move data

Status Code

If the function is successfully executed, the status code is 2100 (which means that the Vision Move data or custom data is obtained from the Mech-Viz project) or 1103 (which means that Vision Move data is obtained from the Mech-Vision project). For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Status of Pose Sent

This parameter indicates the data transmission status. 1 indicates that the data obtained from the vision system is new data. After the PLC reads the new data, please reset this register.

Number of Pose Sent

This parameter indicates the number of obtained waypoints. By default, the vision system sends no more than 20 waypoints at a time. Therefore, the maximum default value of this parameter is 20.

Index of Vision Picking Point

This parameter specifies the position of the Vision Move waypoint (i.e., the waypoint corresponding to the “Vision Move” Step in the Mech-Viz project) in the planned path. If the path does not contain a “Vision Move” waypoint, the value of this parameter is 0.

If the planned path consists of waypoints “Fixed-Point Move_1, Fixed-Point Move_2, Vision Move, Fixed-Point Move_3” in sequence, the position of the Vision Move waypoint is 3.

In the scenario where the robot needs to send this function multiple times to receive the entire path, this parameter has slightly different interpretations in the responses. In the first response, it indicates the position of the Vision Move waypoint in the entire path, while in subsequent responses, this parameter indicates the position of the Vision Move waypoint among the remaining waypoints.

Target Pose

This parameter indicates the poses of all waypoints obtained this time. The pose type can be TCP or joint positions. The pose type is decided by the Pose Type parameter in the function sent by the robot.

Target Label

This parameter indicates the labels (i.e., data from the "labels" port of the "Output" step) of all obtained waypoints.

  • A label must be a integer-formatted string. If the data is not an integer-formatted string, add a Label Mapping Step before the Output Step to transform the output of the labels port to an integer-formatted string.

  • If the “Output” Step does not have a “labels” port, the Target Label value is 0.

Speed Percentage

The meaning of velocity varies based on the project type.

  • For Mech-Vision projects, velocity indicates the Simulation Speed value in the path planning tool, in the form of percentage.

  • For Mech-Viz projects, velocity, represented in percentage, indicates the velocity set for a move-type Step multiplied by the global velocity set in Mech-Viz.

Custom Vision Output

This parameter indicates the custom data of all waypoints obtained this time. For example, data output from ports of the “Output” Step is presented in the following table. The elements in custom data of the first waypoint are [0, 0, 1] and [0, 0]; and the elements in custom data of the second waypoint are [1, 0, 0] and [1, 1].

Port name

poses

labels

customData1

customData2

Output port data

[

[0, 0, 0, 1, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0]

]

[

"0",
"1"

]

[

[0, 0, 1],
[1, 0, 0]

]

[

[0, 0],
[1, 1]

]

First waypoint

[0, 0, 0, 1, 0, 0, 0]

0

[0, 0, 1]

[0, 0]

Second waypoint

[0, 0, 0, 1, 0, 0, 0]

1

[1, 0, 0]

[1, 1]

Target IsVisualMove

This parameter indicates whether the waypoint is a Vision Move waypoint. 0 indicates that it is not a Vision Move waypoint, and 1 indicates that it is a Vision Move waypoint. Only Vision Move waypoint carries Vision Move data or custom data.

Target Move Type

This parameter indicates the motion type of the robot. Valid values: 1 and 2.

  • 1: Joint motion (MOVEJ)

  • 2: Linear motion (MOVEL)

Target Tool ID

This parameter indicates the tool IDs of all waypoints obtained this time.

  • For Mech-Vision projects, tool IDs are set in the path planning tool.

  • For Mech-Viz projects, tool IDs are set in the Mech-Viz project.

VisualMove Planning Result

Data output by the Vision Move Step in Mech-Vision or Mech-Viz, including labels of picked workobjects, number of picked workobjects, number of workobjects to be picked this time, edge or corner ID of vacuum gripper, TCP offset, orientation of workobject group, orientation of workobject, and dimensions of workobject group.

Name Description Number of Elements

Labels of picked workobjects

A label consists of 10 integers. The default value is ten 0s.

10

Number of picked workobjects

The total number of picked workobjects.

1

The number of workobjects to be picked this time.

The number of workobjects to be picked this time.

1

Edge or corner ID of vacuum gripper

The ID of the edge or corner used to pick workobjects this time.

1

TCP offset

The XYZ offset between the center of the workobject group and the tool pose center.

3

Orientation of workobject group

The relative position between the workobject group and the length of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.

1

Orientation of workobject

The relative position between the length of a workobject and that of the vacuum gripper. The value is 0 or 1, where 0 stands for parallel and 1 for vertical.

1

Dimensions of workobject group

The length, width, and height of the workobject group to be picked this time.

3

Function 501: Input Object Dimensions to Mech-Vision Project

Description

This function dynamically inputs object dimensions into the Mech-Vision project. The object dimensions are the values of the Box Size Settings parameters in the “Read Object Dimensions” Step.

read object dimensions

Calling Sequence

This function should be called BEFORE Function 101: Trigger Mech-Vision Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 501

Vision Project No.

Int

8.0

Mech-Vision project ID

External Input Box Dimension

Array[0..2] of Real

68.0

Object dimensions (length, width, height) to be input to the Mech-Vision project

Vision Project No.

You can check the ID of a Mech-Vision project in the “Project List” panel. The number before the name of a project is its ID.

External Input Box Dimension

This parameter indicates the object dimensions, in mm, to be input to the Mech-Vision project. These values are read by the “Read Object Dimensions” Step and set for the parameters Length on X-axis, Length on Y-axis and Length on Z-axis.

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 1108 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

Function 601: Get Message from Notify Step

Description

When the Mech-Vision project or Mech-Viz project is executing the Notify Step, the vision system returns the message predefined in the Notify Step.

Before sending this function, complete the following settings for the Notify Step.

  • For a Notify Step in the Mech-Vision project:

    1. Connect the “Notify” Step to the right side of another Step. The “Output” Step is taken as an example in the image below.

      notify 1
    2. Select Trigger Control Flow Given Output in the parameter panel of the “Output” Step.

      notify 5
    3. In the parameter panel of the “Notify” Step, enter Standard Interface Notify (a required value) for the Service Name. Enter a positive integer for Message, for example, 1001.

      notify 2
  • For a “Notify” Step in the Mech-Viz project:

    1. Connect the “Notify” Step to a proper Step in the workflow.

      notify 3
    2. In the parameter panel of the “Notify” Step, select Standard Interface. Enter a positive integer for Message, for example, 1000.

      notify 4

Calling Sequence

This function should be called immediately AFTER Function 101: Trigger Mech-Vision Project or Function 201: Trigger Mech-Viz Project.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 601

Output Parameters

Name Data type Offset Description

Notify

Int

196.0

Message from the Notify Step

Notify

Value in the Message text box of the “Notify” Step.

When the Notify Step is executed in the Mech-Vision or Mech-Viz project, the message remains in the buffer of the vision system for only one second. Therefore, you should consider the timing of calling this function to ensure successful message retrieval. Additionally, after receiving the message, the PLC should clear the data in the register.

Function 901: Get Software Status

Description

This function checks if the Mech-Vision project is ready.

Input Parameters

Name Data type Offset Description

Command

Int

2.0

Function code is 901

Output Parameters

Name Data type Offset Description

Status Code

Int

200.0

Status code

Status Code

Status code 1101 is returned for a successful function execution. For a failed command execution, the specific error code is returned. For details, refer to Status Codes and Troubleshooting.

We Value Your Privacy

We use cookies to provide you with the best possible experience on our website. By continuing to use the site, you acknowledge that you agree to the use of cookies. If you decline, a single cookie will be used to ensure you're not tracked or remembered when you visit this website.