TCP Server Communication Configuration
About 3795 wordsAbout 13 min
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
PickWiz sends the request getRobotPose to the robot, and the robot returns the robot coordinates p,${p} to PickWiz.


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


PickWiz sends the request getRobotPose to the robot, and the robot returns the robot coordinates
p,${p}\nto 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
\nin 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
Set the send command information to d,${p} so that the robot sends only pose information to PickWiz to trigger the process


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


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 ofVision 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
100for success and0for 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.
