Warning

You are reading the documentation for an older Pickit release (3.0). Documentation for the latest release (3.4) can be found here.

Siemens Pickit interface

This article gives an overview of the prgram blocks provided by Pickit. Both the communication function block (required) and robot commands function (optional) are covered in this article.

The communication function block

This section describes the Pickit communication Function Block (FB) in detail. Using the block in OB1 gives a clear overview of the imputs and outputs, as shown below.

The block inputs, ouputs, their corresponding datatype and default values are summarized in the two tables below. The default values can be overwritten in the data block. The robot_to_pickit_data, socket_params and pickit_to_robot_data are structures containing different data fields and are elaborated in detail in the subsections below.

Inputs
Input	Datatype	Default value	Comment
robot_to_pickit_data	Struct		Structure containing the data being sent from the robot to the Pickit system.
socket_params	Struct		Structure containing the TCP/IP V4 connection parameters.
enable	Bool	`true`	Bit that enables the block for commication, this bit has to remain high during runtime.
request	Bool	`false`	Bit that initiates a communcation request on a rising edge signal.
clear	Bool	`false`	Bit that clears the pickit_to_robot_data outputs on a rising edge signal.
reset	Bool	`false`	Bit that resets the block on a rising edge signal. Established connections will be terminated.

Similarly, an overview of the block outputs and their datatypes.

Outputs
Output	Datatype	Comment
pickit_to_robot_data	Struct	Structure containing the data being received from Pickit.
pickit_connected	Bool	Bit that states if a connection with the Pickit is successfully established.
pickit_success	Bool	Bit that states if the previous request had a succesful response.
pickit_mode	SInt	Integer that holds the Pickit mode.
done	Bool	Communication job finished successfully. The bit remains high until a new job is triggered.
busy	Bool	Active communication job. This bit will either move to done or busy.
error	Bool	This bit is set to high when a fatal block error occured.
status	Byte	This byte gives concrete information on block status and fatal block errors/faults.

The different status output values and their meaning are summarized below. All of the status variables marked as error are considered fatal, i.e. leading to block fault and subsequently terminating the connection. These error types require a block reset by the reset input or a memory reset MRES of the CPU (cold start).

Function block status output overview
status	error	Description
`16#00`	0	No active connection.
`16#10`	0	The connection is successfully established.
`16#11`	1	The established connection is lost.
`16#12`	1	The received data is invalid.
`16#1A`	1	The command input number is undefined.
`16#1B`	1	Pickit is not in robot mode.
`16#1C`	0	Pickit is not in calibration mode.
`16#1D`	1	Pickit returned a failure status number.
`16#40`	1	Timeout error, cannot establish a connection.
`16#41`	1	Timeout error, the connection was established but the initial handshake failed.
`16#42`	1	Timeout error, the connection was established but there was no data received as a response to the send request.

The communication is internally set up with the TSEND_C and TRCV_C standard function blocks. For detailed status information on the connection itself, these blocks can be monitored inside the Pickit data block. Detailed information can be found in the Siemens S7-1200 Programmable controller System Manual.

Robot to Pickit data

The robot_to_pickit_data structure contains all parameters that make up the send message of 48 bytes. Detailed information about the message structure can be found in the socket communication article.

robot_to_pickit_data
robot_to_pickit_data	Datatype	Default value	Comment
RobotPose.X	Real	`0.0`	Registers containing the robot pose X translation in m.
RobotPose.Y	Real	`0.0`	Registers containing the robot pose Y translation in m.
RobotPose.Z	Real	`0.0`	Registers containing the robot pose Z translation in m.
RobotPose.A	Real	`0.0`	Registers containing the robot pose A rotation.
RobotPose.B	Real	`0.0`	Registers containing the robot pose B rotation.
RobotPose.C	Real	`0.0`	Registers containing the robot pose C rotation.
RobotPose.D	Real	`0.0`	Registers containing the robot pose D rotation.
Payload.SetupId	DInt	`1`	ID of the setup configuration when requesting `rc_pickit_configure()`.
Payload.ProductId	DInt	`1`	ID of the product configuration when requesting `rc_pickit_configure()`.
Payload.DetectionRetries	DInt	`0`	Maximum number of detection retries when requesting `rc_pickit_look_for_objects_with_retries()`.
Command	DInt	`0`	Pickit robot command number.
MetaData.RobotType	DInt	`5`	Orientation convention dependent on robot brand. The default value corresponds to KUKA.
MetaData.InterfaceVersion	DInt	`11`	Pickit socket interface version `1.1`.

Pickit expects to receive the robot pose continuously. For that reason does the block send the robot_to_pickit_data.RobotPose input values each 100 ms, also referred to as the heartbeat. This implies the robot pose must be sent to the PLC from the robot controller in a real-time data stream.

The convention in which the orientation part of the pose is expressed depends on the robot brand being used. This convention is specified in the MetaData.RobotType input. The supported brands and their corresponding convention can be found in the socket communication article under Meta Data.

Each request from the PLC contains a command number. This number has to be filled in inside the robot_to_pickit_data.Command variable. An overview of all possible Pickit commands can be found in the list below. More information on the exact meaning of each command can be found in socket communication article.

Request command constants

RC_PICKIT_NO_COMMAND                    = -1
RC_PICKIT_CHECK_MODE                    = 0
RC_PICKIT_FIND_CALIB_PLATE              = 10
RC_PICKIT_LOOK_FOR_OBJECTS              = 20
RC_PICKIT_LOOK_FOR_OBJECTS_WITH_RETRIES = 21
RC_PICKIT_CAPTURE_IMAGE                 = 22
RC_PICKIT_PROCESS_IMAGE                 = 23
RC_PICKIT_NEXT_OBJECT                   = 30
RC_PICKIT_CONFIGURE                     = 40
RC_PICKIT_SAVE_SCENE                    = 50
RC_PICKIT_BUILD_BACKGROUND              = 60
RC_PICKIT_GET_PICK_POINT_DATA           = 70

Warning

Sending undefined command numbers will lead to block fault, which is considered a fatal error and terminating the connection.

On startup the connection is automatically being established. To confirm there is a connection, an initial rc_pickit_check_mode() command is sent for verification. This initial handhake sets the pickit_mode output. During runtime, this output is only reliable when consiquently requesting the rc_pickit_check_mode() command. The possible values for this parameter are listed below.

The Pickit mode output values

UNDEFINED                               = -1
ROBOT MODE                              = 0
CALIBRATION MODE                        = 1
IDLE                                    = 2

Certain command numbers require Pickit to be in the correct mode. The rc_pickit_find_calib_plate() command requires calibration mode. The commands from rc_pickit_look_for_objects() and up require robot mode.

Warning

When Pickit is not set to the correct mode, the communication block faults and terminates the connection.

Socket parameters

The socket_params structure contains all parameters to set up the TCP/IP V4 connection. The tabel below gives an overview of all the parameters that have to be filled in.

socket_params
socket_params	Datatype	Default value	Comment
ConnectionId	Word	`16#0001`	Connection identifier in TIA. When having multiple connections, use the next free id.
RemoteAddress[0]	USInt	`169`	First octet of the Pickit IP address.
RemoteAddress[1]	USInt	`254`	Second octet of the Pickit IP address.
RemoteAddress[2]	USInt	`5`	Third octet of the Pickit IP address.
RemoteAddress[3]	USInt	`182`	Fourth octet of the Pickit IP address.
RemotePort[0]	USInt	`16#13`	First octet of the Pickit port number (fixed `5001`).
RemotePort[1]	USInt	`16#89`	Second octet of the Pickit port number (fixed `5001`).
Timeout	IEC time	`T#4s`	Communication timeout value.
Heartbeat	IEC time	`T#100ms`	Specifies the time between each `rc_pickit_no_command()`, default 100 ms.

The default value for the connection identifier within TIA Portal is set to 1. However with multiple connections, this number might already be in use. The ids that are still free to use can be found in device proporties under Device settings.

The socket_params.Timeout input specifies the timeframe the PLC has for receiving messages back from Pickit. When this timeframe is exceeded, the block faults.

The socket_params.Heartbeat input specifies the timestamp Pickit will receive the robot pose update. This information is necessary for the visualisation of the robot pose within the Pickit UI. Setting this value to T#0s will not update the robot pose and Pickit might appear to not be connected.

Pickit to robot data

The pickit_to_robot_data structure contains all the output parameters that make up the receive message of 64 bytes. Detailed information of the receive message can be found in the socket communication article.

pickit_to_robot_data
pickit_to_robot_data	Datatype	Comment
RobotPose.X	Real	Object translation X in m.
RobotPose.Y	Real	Object translation Y in m.
RobotPose.Z	Real	Object translation Z in m.
RobotPose.A	Real	Object rotation A.
RobotPose.B	Real	Object rotation B.
RobotPose.C	Real	Object rotation C.
RobotPose.D	Real	Object rotation D.
Payload.SelectedPickPointID	UDInt	ID of the pick point that was selected for the given object.
Payload.ReferencePickPointID	UDInt	ID of the selected pick point’s reference pick point.
PickPointOffset.X	Real	Pick point offset translation X in m.
PickPointOffset.Y	Real	Pick point offset translation Y in m.
PickPointOffset.Z	Real	Pick point offset translation Z in m.
PickPointOffset.A	Real	Pick point offset rotation A.
PickPointOffset.B	Real	Pick point offset rotation B.
PickPointOffset.C	Real	Pick point offset rotation C.
PickPointOffset.D	Real	Pick point offset rotation D.
Payload.ObjectType	UDInt	For a Teach detection, this field contains the model ID of the current object. For a Flex/Pattern detection, this field contains the object type.
Payload.ObjectDimensions.Length	Real	Object length (SQUARE, RECTANGLE, ELLIPSE, CYLINDER, POINTCLOUD, BLOB) or diameter (CIRCLE, SPHERE) in meters.
Payload.ObjectDimensions.Width	Real	Object width (RECTANGLE, ELLIPSE, POINTCLOUD, BLOB) or diameter (CYLINDER) in meters.
Payload.ObjectDimensions.Height	Real	Object height (POINTCLOUD, BLOB) in meters.
Payload.ObjectAge	Real	The duration (in seconds) elapsed between the capturing of the camera image and the moment the object information is sent to the robot.
Payload.ObjectsRemaining	UDInt	If this field is non-zero, it contains the number of remaining objects that can be retrieved via consecutive RC_PICKIT_NEXT_OBJECT requests.
Status	DInt	The Pickit response status number.
MetaData.RobotType	DInt	The confirmed orientation convention dependent on robot brand.
MetaData.InterfaceVersion	DInt	The confirmed Pickit socket interface version.

The pickit_to_robot_data.ObjectPose holds the object pose expressed to robot base frame. The orientation convention is determined by the robot_to_pickit_data.MetaData.RobotType parameter in the input section.

The robot_to_pickit_data.PickPointOffset contains the offset transformation w.r.t. the reference pick point set inside the Pickit system. To obtain both the object pose and the pick point offset you need to subsequently request a rc_pickit_find_objects() and rc_pickit_get_pick_point_data() in correct order.

Note

The orientation of the object pose is expressed in compliance with the Pickit Objects view. More specifically, the object pose z-axis points outwards from the model. Dependent on your TCP configurtion on the robot side, it will be necessary to apply an additional 180 degrees rotation around the object x-axis. This to ensure the robot approaches the object correctly.

Warning

The object pose from Pickit is not validated on reachability. It is strongly advised to validate this position on the robot controller before moving to the position. The supported robot brands by Pickit have these validations built into the robot interface. When using any of these brands, contact support for more information.

The response message from Pickit contains a status number, found in the pickit_to_robot_data.Status output. The possible constants are shown in the list below.

Response status constants

PICKIT_UNKNOWN_COMMAND                  = -99
PICKIT_ROBOT_MODE                       =   0
PICKIT_IDLE_MODE                        =   1
PICKIT_CALIBRATION_MODE                 =   2
PICKIT_FIND_CALIB_PLATE_OK              =  10
PICKIT_FIND_CALIB_PLATE_FAILED          =  11
PICKIT_OBJECT_FOUND                     =  20
PICKIT_NO_OBJECTS                       =  21
PICKIT_NO_IMAGE_CAPTURED                =  22
PICKIT_EMPTY_ROI                        =  23
PICKIT_IMAGE_CAPTURED                   =  26
PICKIT_CONFIG_OK                        =  40
PICKIT_CONFIG_FAILED                    =  41
PICKIT_SAVE_SNAPSHOT_OK                 =  50
PICKIT_SAVE_SNAPSHOT_FAILED             =  51
PICKIT_BUILD_BKG_CLOUD_OK               =  60
PICKIT_BUILD_BKG_CLOUD_FAILED           =  61
PICKIT_GET_PICK_POINT_DATA_OK           =  70
PICKIT_GET_PICK_POINT_DATA_FAILED       =  71

The robot commands function

This section describes the Pickit robot commands function in detail. The use of this block is optional.

This function calculates the Pickit command number from separate command inputs. The inputs for the block are all Booleans that can be linked to user-defined memory. The output is a double integer DInt containing the command number. This output is intented to be linked directly to the robot_to_pickit_data.Command input parameter as shown in the image.

Warning

Note that if two or more inputs are set to True, the block outputs an undefined command number which results in block fault. Therefore it is mandatory to set only one input each time.