TCP is a communication method in which PickWiz acts as the TCP server and the robot acts as the TCP client. When PickWiz communicates with the robot, it does not actively control the robot side. Instead, the robot side sends TCP commands to PickWiz, and PickWiz returns response data after receiving the commands. Therefore, when TCP communication is used, users need to write a program on the robot side to communicate with PickWiz.

Before configuring robot communication, please first refer to Project Operation Guide to create a new Project, then click Robot Configuration Panel on the main interface to enter the Add Robot interface.

1. Add Robot

（1）Enter the Add Robot interface and click +Add Robot

（2）Select TCP Server as the communication method, click Next, and enter the Robot Configuration interface

2. Configure the Robot

On the Robot Configuration interface, you can configure robot information, basic communication settings, and custom communication messages.

2.1 Robot Information Configuration

Configuration Item	Description
Communication Method	The communication protocol established between PickWiz and the robot. This cannot be modified
Configuration Name	The name of the robot configuration. Chinese and English characters, numbers, and symbols are supported
Configuration ID	The unique identifier of the robot configuration. It can be modified and supports numbers only
Brand	The robot brand. If the robot side is connected to a PLC, select Other Device for the brand
Model	The robot model. If the robot side is connected to a PLC, select Other Device for the model
Model File	When Other Device is selected for brand and model, you need to upload the model of that device. The model file format is urdf
Axis Count	The number of robotic arm axes. Three-axis, four-axis, and six-axis are supported
Rotation Expression	Describes the robot pose in three-dimensional space. Currently, Euler Angles and rotation vector are supported, and the Euler angle order can be modified.

2.2 Basic Communication Configuration

Configuration Item		Description
Communication Address	Host IP	The host IP address. In TCP communication mode, the default is 0.0.0.0
	Port Number	The specified port on the host to which the robot connects. The default port is 8887 and usually does not need to be modified
Read/Write Format	Euler Angle Unit	The unit of Euler Angles. Degree and radian are supported, with degree as the default.
	Length Unit	The length unit used by the robot, including Robot Pose, workpiece dimensions, etc. The default is mm
	Pose Type	The representation of Robot Pose. The default is Tool Pose. Tool Pose refers to the pose of the robot end Tool; Joint Motion refers to the pose of each robot joint, and the combination of all joint poses determines the pose of the robotic arm or end Tool. When Other Device is selected for the robot brand and model, only Tool Pose can be selected as the default pose type
	Delimiter	The delimiter is used to separate data. For example, a pose has 6 values, namely xyzabc, and the delimiter is used to distinguish these 6 values, such as x,y,z,a,b,c (no delimiter is added at the end of the data). The delimiter can be any character except escape characters such as \n, \r, and \t.
	End-of-message Special Characters	Some robotic arms may require special characters at the end of each message they receive or send, such as \n\r. You can enter these special characters here. The software appends these special characters to the end of each message it sends, and when receiving each message from the robotic arm, it attempts to remove the end special characters (if any).
	Command Length Limit	Some robotic arms can only receive or send a specified number of bytes in one message, so you can set the number of bytes for one message here
	Reserved Decimal Places	How many decimal places to retain for floating-point data in robot commands. Numbers only are supported, and the default is 1

2.3 Custom Communication Message Configuration

General Command Rules

3. TCP Command Description

3.1 Calibration Communication Messages

• Commands Sent from the Robot to PickWiz

  • p: pose information of the robot end Tool

  • $(p): outputs the pose information of the robot end Tool, 6 data values

• Commands Sent from PickWiz to the Robot

  • getRobotPose: obtains the robot coordinates

Examples

1. PickWiz sends the request getRobotPose to the robot, and the robot returns the robot coordinates p,${p} to PickWiz.

   

   

2. PickWiz sends the request (getRobotPose) to the robot, and the robot returns the robot coordinates p,${p} to PickWiz

   

   

3. PickWiz sends the request getRobotPose to the robot, and the robot returns the robot coordinates p,${p}\n to PickWiz.

   When the custom characters are not included in the robot coordinates returned by the robot to PickWiz, PickWiz cannot match this command. Only when the custom characters are included in the returned robot coordinates can the software match this command.

   

   

   

   Or enter \n in End-of-message Special Characters, and the software will automatically determine and parse it.

3.2 Vision Computation Communication Messages

3.2.1 Commands Sent from the Robot to PickWiz

Placeholder Reference

Placeholders are symbols or markers used in programming. During actual communication, placeholders are replaced with specific content/data.

Placeholder	Description
p	Robot Tool Pose. For 6 data values, when Pose Type is Tool Pose, the robot returns the current pose of the robot end Tool to PickWiz
j	The robot reference joint pose. For 6 data values, when Pose Type is Joint Motion, the robot needs to send Reference Joint Pose to calculate the Pick Point joint pose closest to the reference joint pose
ps	The incoming workpieces may have multiple sizes, so the robot needs to automatically adjust the grasping strategy based on different sizes. In different scenarios, the number of workpiece dimension values passed from the robot side and the corresponding workpiece information differ. For the circular surface scenario, 1 value is passed, representing the radius; for the cylinder scenario, 2 values are passed, representing radius\height; for the carton scenario, 3 values are passed, representing length\width\height; for the quadrilateral scenario, 2 values are passed, representing width\length.
p_tol	The incoming workpieces may have multiple sizes, so the robot needs to automatically adjust the grasping strategy based on different sizes. In different scenarios, the number of workpiece dimension tolerance values passed from the robot side and the corresponding workpiece information differ. For the circular surface scenario, 1 value is passed, representing the radius tolerance; for the cylinder scenario, 2 values are passed, representing radius\height tolerances; for the quadrilateral scenario, 2 values are passed, representing width\length tolerances.
pid	Workpiece ID, used by the robot to automatically switch the workpiece to pick
wid	task ID, used by the robot to automatically switch tasks
calib_id	Calibration ID, used by the robot to automatically switch eye-hand calibration configuration files
ee_id	Tool ID, used by the robot to automatically switch the end Tool during task execution
roi_id	The ID of the ROI, used by the robot to automatically switch the ROI
vp_id	Vision Parameter ID, used by the robot to automatically switch vision parameters
so_id	Scene Object ID, used by the robot to automatically switch the Scene Object
co	Photo computation type, used to switch different photo-taking methods. Configure it according to on-site usage. 0: retake a photo, acquire an image, and perform vision computation 1: use the cached image (the last acquired image) for vision computation 2: only take a photo and acquire the image 3: take a photo for random pose automatic sampling 4: real-time correction of vision drift 5: use historical data for vision computation 6: IPC shutdown

Vision Inspection Send Command

Configure the command character text box to define the content of the command sent from the robot to PickWiz. The default is:d,${p},${wid}.

• d: command identifier, used to avoid confusion caused by duplicated commands. For example, in calibration communication, the send command identifier is p.

• $(p): pose information of the robot end Tool, 6 data values

• $(wid): task ID, 1 value, used by the robot to switch tasks

Examples

1. Set the send command information to d,${p} so that the robot sends only pose information to PickWiz to trigger the process

   

   

2. Set the send command information to d,${ps}. In the single-sack depalletizing scenario, when the robot sends workpiece dimensions to PickWiz, an error is reported indicating that it applies only to cartons, circles, cylinders, and quadrilaterals. In the single-carton depalletizing scenario, the robot sends the carton length, width, and height to PickWiz to trigger the inspection process

   

   

3. Set the send command information to d,${p},${wid} so that the robot sends pose information and the task ID to PickWiz, automatically switching the inspection flows of tasks 1, 2, 4, and 5

   

   

   

   

   

Clear Cache

Only for the one shot, multiple picks scenario, clear the current remaining instance cache so that a new photo will be taken the next time the inspection process is triggered.

Prerequisite information:
You need to understand the usage logic of Vision Computation Configuration - Picking Logic:

• One shot, one pick: the vision system takes one photo and performs one computation, sends the result to the robot after computation, discards any excess results, the robot performs the related picking action, and then the process repeats.
• One shot, multiple picks: the vision system takes one photo and performs one computation, sends the result to the robot after computation, saves the excess vision results, the robot performs the related picking action, and the next time the robot sends a photo computation command, the system first checks whether the saved vision results meet the requirements. If they do, the system does not execute the photo-taking + computation logic and instead returns the result directly to the robot, then repeats.

Examples

When One shot, multiple picks is not selected, PickWiz must perform photo-taking and computation every time the robot triggers the inspection process

When One shot, multiple picks is selected in Vision Computation Configuration, PickWiz can implement one photo-taking/computation cycle with multiple picks. As shown below, 5 instances are recognized. The first pick is triggered by PickWiz, and the next 4 picks are triggered by the robot. During those 4 picks, the robot sends pose information to PickWiz to trigger the inspection process, and PickWiz does not perform photo-taking and computation. Instead, it directly returns the Picking Pose.

The 1st pick is triggered by the client, and the 2nd and 3rd picks are triggered by the robot. The robot sends pose information to PickWiz to trigger the inspection process, and PickWiz does not perform photo-taking and computation but directly returns the Picking Pose. Then enter the co command to clear the cache, and PickWiz starts photo-taking and computation again for the 4th pick

3.3 Commands Sent from PickWiz to the Robot

Placeholder Reference

Placeholders are symbols or markers used in programming. During actual communication, placeholders are replaced with specific content.

Placeholder	Meaning
s	Vision status code, 1 value. The default success value is 100, and other exceptions are 0. Custom configuration is supported
entity	Returned instance type, 1 value, where 1 indicates a pallet and 0 indicates a workpiece
ln	Remaining instance count, 1 value. In the one shot, multiple picks picking logic, this returns the current remaining cached instance count
rn	Returned instance count, 1 value. Returns the number of instances identified by instance segmentation 2D recognition. This value is less than or equal to the Sent Instance Count. If there are multiple instances, the Grasp-related Information Length increases with the returned instance count
tn	Total detected instances, 1 value. The number of detected instances before instance filtering
vn	Valid instance count, 1 value. The number of detected instances after instance filtering
info	Grasp-related information
cid	Workpiece type
sr	Calibration sampling result, which is used by the automatic sampling calibration command. Different calibration sampling results correspond to different signal values. 0: the sample count reaches the minimum quantity 1: successfully added a new sample 11: failed to add a new sample 12: automatic sampling ended and the sample list has been executed 13: failed to generate a sampling pose 14: calibration sampling page was not opened 15: system error
cp	Next sampling pose, used by the automatic sampling calibration command. It indicates the moving position for the robot to collect the next calibration sample
<SPLIT>	Special separator. When using it, you do not need to add ${}; directly add this identifier to the command, and the data will be forcibly split at this position. Note: this function is mutually exclusive with the function of splitting data by character count, and this function has a higher priority.

Vision Inspection Send Command

Configure the content of the command sent from PickWiz to the robot. The default is ${rn},$

Automatic Calibration Sampling Send Command

When the eye-hand calibration method is random pose automatic sampling, this command must be configured. Otherwise, the robot cannot communicate with PickWiz

Grasp-related Information

The lengths of the grasp-related information described below are for a single Pick Point. If there are multiple Pick Points, the length is the number of values x the number of Pick Points

• Universal information for all scenarios

  Field	Description
  Picked Workpiece ID	1 value; indicates the current workpiece sequence number
  Pick Point Pose	6 values; indicates the pose data of the Pick Point
  Pick Point Index	1 value; indicates the current Pick Point sequence number
  Additional Information	1 value; indicates the custom additional information of the current workpiece
  Forward Point	Only applicable when the pose type is Joint Motion. The length is 1 + the number of Waypoints; the format is (number of Waypoints, joint Waypoint poses from the pre-pick point to the Pick Point)
  Retreat Point	Only applicable when the pose type is Joint Motion. The length is 1 + the number of Waypoints; the format is (number of Waypoints, joint Waypoint poses from the Pick Point to the retreat pick point)

• Specific scene information

  • Carton/sack depalletizing

    • Product Length: 1 value, the current product length (along the image x direction)

    • Product Width: 1 value, the current product width (along the image y direction)

    • Product Orientation: 1 value, the product orientation (0: horizontal along x, 1: vertical along y)

    • Upper-left Vertex Position of the Pallet: 3 values (x, y, z), indicating the position information of the upper-left vertex of the pallet in the current scene

    • Upper-right Vertex Position of the Pallet: 3 values (x, y, z), indicating the position information of the upper-right vertex of the pallet in the current scene

    • Lower-left Vertex Position of the Pallet: 3 values (x, y, z), indicating the position information of the lower-left vertex of the pallet in the current scene

    • Lower-right Vertex Position of the Pallet: 3 values (x, y, z), indicating the position information of the lower-right vertex of the pallet in the current scene

  • Carton depalletizing information:

    • Product Height: 1 value, the current product height

  • Ordered/Random disc picking:

    • Circular Surface Radius: 1 value, the current product circular surface radius

  • Ordered/Random cylinder picking:

    • Circular Surface Radius: 1 value, the current product circular surface radius

    • Cylinder Height: 1 value, the current product height

  • Random picking:

    • Workpiece Category: 1 value, the current workpiece category, used in scenarios where multiple workpiece types are recognized.

  • Ordered/Random quadrilateral picking:

    • Quadrilateral Length: 1 value, the current product length

    • Quadrilateral Width: 1 value, the current product width

Vision Status Code

The vision status codes are used for troubleshooting. The recommended status codes are shown in the table below:

¥{s} must be configured in Vision Inspection Send Command

• If the vision status code is not custom-configured, the default value is 100 for success and 0 for all other exceptions

Error Content	Default Value	Related Node
Success	100
Bottom plate detected	301	Foreground Processing(Foreground Builder)
No container detected	4000	Container Detection(Container Builder)
No instance detected	5000	Instance Segmentation(Instance Builder)
No pose detected	6000	Pose Estimation(Pose Builder)
No Pick Point detected	7000	Pick Point Generation(Grasp Builder)
No Path detected	8000	Robot Trajectory Generator(Trajectory Builder)
No instance dimensions detected	9000	Workpiece Dimensions Generator(Size Builder)
Empty ROI	1101	Invalid Point Filter(ValidPoints Criteria)
No valid instance	12000	Instance Filtering(Instance Criteria)
No valid workpiece pose	13000	Pose Filtering(Pose Criteria)
No valid Pick Point	14000	Pick Point Filtering(Grasp Criteria)
All detection results are unpickable due to collisions	15000	Collision Detection Filtering(Collision Criteria)
No instance with valid dimensions	17000	Workpiece Dimensions Filtering(Size Criteria)
Exception	20000	General exception error. Please check the logs for confirmation
Insufficient video memory	20001	General exception error. Please check the logs for confirmation
Invalid input (please check algorithm parameters)	20002	General exception error. Please check the logs for confirmation
Full inspection	20003	Related to point cloud processing operator(full_detect_judgment)
Foreign matter detection exception	20004	Related to instance filtering operator(foreign_matter_judgement)

Imaging Complete

Imaging Complete indicates that camera image acquisition has been completed and the image data has been processed.

Image Acquisition Complete

Image Acquisition Complete indicates that the camera has obtained image data after taking a photo, but no point cloud has been generated and no image processing has been performed. It is commonly used when one robot sends a command signal before imaging is complete to trigger the system/script to perform the next step, without waiting for imaging completion (because imaging completion takes longer than image acquisition completion), which can reduce the overall process time to some extent.

Example

In Image Acquisition Complete / Imaging Complete, configure the command CaptureFinished. After the camera completes image acquisition / imaging, PickWiz sends the CaptureFinished command to the robot, which can trigger the next operation.

4. Edit, Copy, and Delete the Robot

（1）Edit Robot Configuration

On the Add Robot interface, left-click a robot configuration to edit the selected robot configuration.

（2）Copy Robot Configuration

On the Add Robot interface, right-click a robot configuration to copy the selected robot configuration.

（3）Delete Robot Configuration

On the Add Robot interface, right-click a robot configuration to delete the selected robot configuration.

5. Select a Robot Configuration

After completing the TCP communication configuration, you can select a robot configuration for the current task scene on the task main interface. Select the corresponding robot configuration in the robot configuration selection bar, and PickWiz will attempt to establish communication with the robot through the TCP communication protocol.

If the communication connection is successful, the robot communication connection status in the lower-left corner of the main interface will display "Connected".

If the communication connection fails, the robot communication connection status will display "Disconnected". Please check whether the network cable between the robot and the industrial PC is securely connected and whether the program loaded and running on the robot system is correct, then reconfigure the robot.

When PickWiz acts as the server and multiple robot clients connect, if clients other than the already connected client attempt to connect, the log displays a prompt indicating that the request was rejected, as shown below.

Previous pageTCP Client Communication Configuration

Next pageModBus Communication Configuration