TCP Server Communication Configuration
About 3873 wordsAbout 13 min
In TCP communication, PickWiz acts as the TCP server and the robot acts as the TCP client. PickWiz does not actively control the robot. Instead, the robot sends TCP commands to PickWiz, and PickWiz returns response data after receiving them. To use TCP communication, you must write a program on the robot that communicates with PickWiz.

Before you begin, follow the Robot Configuration Guide to prepare the task, network, and robot communication program, then open the Add Robot screen.
1. Select TCP Server Communication
Click + Add Robot, select TCP Server as the communication method, then click Next to open the Robot Configuration screen.

2. Configure TCP Server Communication
For common settings such as robot name, brand, model, number of axes, and rotation expression, see the Robot Configuration Guide. This page focuses on TCP server communication parameters and messages.
2.1 Basic Communication Settings

| Setting | Description | |
|---|---|---|
| Communication Address | Host IP | Host IP address. The default for TCP communication is 0.0.0.0. |
| Port Number | The designated host port to which the robot connects. The default port is 8887 and generally does not need to be changed. | |
| Read/Write Format | Euler Angle Unit | Unit for Euler angles: degrees or radians. The default is degrees. |
| Length Unit | The length unit used by the robot, including for robot poses and target dimensions. The default is mm. | |
| Pose Type | How the robot pose is represented. The default is Tool Pose. Tool Pose is the pose of the robot's end-effector. Joint Angles are the poses of the robot's individual joints; together, they determine the pose of the robot arm or end-effector. When Other Device is selected for the robot brand and model, Tool Pose is the only available pose type. | |
| Delimiter | Separates data values. For example, pose contains six values, xyzabc; a delimiter distinguishes them as x,y,z,a,b,c (with no delimiter after the last value). Any character except the escape characters \n, \r, and \t can be entered as the delimiter. | |
| Special Trailing Characters | Some robot arms require special characters, such as \n\r, at the end of each message they receive or send. Enter those characters here. The software appends them to every outgoing message and attempts to remove them, if present, from every message received from the robot arm. | |
| Command Length Limit | Some robot arms can receive or send only a specified number of bytes per message. Set the number of bytes per message here. | |
| Decimal Places | Number of decimal places retained for floating-point values in robot commands. Only numeric values are supported. The default is 1. | |
2.2 Custom Communication Message Configuration

General Command Rules
3. TCP Command Reference

3.1 Calibration Communication Messages

Commands Sent from the Robot to PickWiz
p: Pose information for the robot's end-effector
$(p): Outputs the robot's end-effector pose information as six values
Commands Sent from PickWiz to the Robot
- getRobotPose: Gets the robot's coordinates
Examples
PickWiz sends the request getRobotPose to the robot, and the robot returns its coordinates as p,${p} to PickWiz.


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


PickWiz sends the request getRobotPose to the robot, and the robot returns its coordinates as ‘p,${p}\n’ to PickWiz.
If the coordinates returned by the robot do not contain the custom character, PickWiz cannot match the command. The software can match it only when the returned coordinates contain the custom character.



Alternatively, enter “\n” under Special Trailing Characters; the software will detect and parse it automatically.
3.2 Vision Calculation Communication Messages

3.2.1 Commands Sent from the Robot to PickWiz

Placeholder Reference
Placeholders are symbols or markers used in programming. During communication, they are replaced with actual content or data.
| Placeholder | Description |
|---|---|
| p | Robot tool pose, six values. When Pose Type is Tool Pose, the robot returns its current end-effector pose to PickWiz. |
| j | Robot reference joint pose, six values. When Pose Type is Joint Angles, the robot must send the Reference Joint Pose, which is used to calculate the pick point joint pose closest to that reference joint pose. |
| ps | Target dimensions. When incoming targets have different dimensions, the robot must adjust its picking strategy accordingly. The number and meaning of dimension values sent by the robot depend on the scene: one value for a circular face (radius); two for a cylinder (radius\height); three for a carton (length\width\height); and two for a quadrilateral (width\length). |
| p_tol | Target dimension tolerance. When incoming targets have different dimensions, the robot must adjust its picking strategy accordingly. The number and meaning of tolerance values sent by the robot depend on the scene: one value for a circular face (radius tolerance); two for a cylinder (radius\height tolerances); and two for a quadrilateral (width\length tolerances). |
| pid | Target ID, used by the robot to switch automatically between targets to pick. |
| wid | Task ID, used by the robot to switch tasks automatically. |
| calib_id | Calibration ID, used by the robot to switch eye-hand calibration configuration files automatically. |
| ee_id | End-effector ID, used by the robot to switch end-effectors automatically while performing a task. |
| roi_id | ROI ID, used by the robot to switch ROIs automatically. |
| vp_id | Vision parameter ID, used by the robot to switch vision parameters automatically. |
| so_id | Scene Object ID, used by the robot to switch scene objects automatically. |
| co | Image capture and calculation type, used to switch capture methods according to on-site requirements. 0: Capture a new image and perform vision calculation; 1: Perform vision calculation using the cached image (the previously captured image); 2: Capture an image only; 3: Capture an image for “random-pose automatic sampling”; 4: Perform real-time vision drift correction; 5: Perform vision calculation using historical data; 6: Shut down the industrial PC. |
Vision Detection Send Command
Configure the command text sent from the robot to PickWiz. The default is d,p,{wid}.
d: Command identifier, which prevents confusion between commands. For example, the identifier sent during calibration communication is p.
$(p): Robot end-effector pose information, six values
$(wid): Task ID, one value, used by the robot to switch tasks
Examples
Set the outgoing command to d,${p}. The robot sends only pose information to PickWiz, triggering the workflow.


Set the outgoing command to d,${ps}. In a single-sack depalletizing scene, sending target dimensions from the robot to PickWiz causes an error stating that this applies only to cartons, circles, cylinders, and quadrilaterals. In a single-carton depalletizing scene, the robot sends the carton's length, width, and height to PickWiz, triggering the detection workflow.


Set the outgoing command to d,p,{wid}. The robot sends pose information and a task ID to PickWiz, automatically switching between the detection workflows for tasks 1, 2, 4, and 5.





Clear Cache
For Capture Once, Pick Multiple only, clear the remaining cached instances. A new image will be captured the next time the detection workflow is triggered.
Prerequisite:
Understand how “Vision Calculation Configuration - Picking Logic” works:
- Capture Once, Pick Once: Capture an image and calculate once, send the calculated result to the robot, and discard any additional results. The robot performs the corresponding pick, and the sequence repeats.
- Capture Once, Pick Multiple: Capture an image and calculate once, send the calculated result to the robot, and save additional vision results. The robot performs the corresponding pick. The next time the robot sends an image capture and calculation command, the system first checks whether the saved vision results meet the requirements. If they do, it returns a result directly to the robot without capturing an image or calculating again. The sequence then repeats.
Examples
When Capture Once, Pick Multiple is not selected, PickWiz captures an image and calculates every time the robot triggers the detection workflow.

When Capture Once, Pick Multiple is selected in Vision Calculation Configuration, PickWiz can capture and calculate once, then pick multiple times. In the example below, five instances are detected. PickWiz triggers the first pick, and the robot triggers the next four. For those four picks, the robot sends pose information to PickWiz to trigger the detection workflow. PickWiz returns the pick poses directly without capturing another image or calculating again.


The client triggers the first pick. The robot triggers the second and third picks by sending pose information to PickWiz, which returns pick poses directly without capturing another image or calculating again. Then the co command is entered to clear the cache. PickWiz captures an image and calculates again for the fourth pick.

3.3 Commands Sent from PickWiz to the Robot

Placeholder Reference
Placeholders are symbols or markers used in programming. During communication, they are replaced with actual content.

| Placeholder | Meaning |
|---|---|
| s | Vision status code, one value. By default, success returns 100 and other errors return 0. This can be configured. |
| entity | Returned instance type, one value: 1 for a pallet and 0 for a target. |
| ln | Number of remaining instances, one value. With Capture Once, Pick Multiple picking logic, returns the number of instances currently remaining in the cache. |
| rn | Number of returned instances, one value. Returns the number of instances identified by 2D instance segmentation. This value is less than or equal to Number of Instances to Send. If multiple instances are returned, Pick-Related Information Length increases with the number of returned instances. |
| tn | Total number of detected instances, one value: the number of detected instances that have not been removed by instance filtering. |
| vn | Number of valid instances, one value: the number of detected instances after instance filtering. |
| info | Pick-related information. |
| cid | Target type. |
| sr | Calibration sampling result for an automatic calibration sampling command. Different results correspond to different signal values. 0: Minimum number of samples reached; 1: New sample added successfully; 11: Failed to add new sample; 12: Automatic sampling finished and the sample list has been completed; 13: Failed to generate a sampling pose; 14: Calibration sampling page has not been opened; 15: System error. |
| cp | Next sampling pose for an automatic calibration sampling command: the position to which the robot moves to collect the next calibration sample. |
| <SPLIT> | Special delimiter. Add this marker directly to the command without ${}. Data is forcibly split at this position. This feature is mutually exclusive with splitting data by character count and takes precedence over it. |
Vision Detection Send Command
Configure the command sent from PickWiz to the robot. The default is rn,{info}.
Automatic Calibration Sampling Send Command
When the eye-hand calibration method is “Random-Pose Automatic Sampling,” this command must be set; otherwise, the robot cannot communicate with PickWiz.
Pick-Related Information
The lengths below are for a single pick point. For multiple pick points, multiply the length by the number of pick points.
Information Common to All Scenes
Field Description Picked Target ID One value; identifies the current target's sequence number. Pick Point Pose Six values; represents the pick point pose. Pick Point Index One value; identifies the current pick point's sequence number. Additional Information One value; custom additional information for the current target. Approach Points Applies only when the pose type is Joint Angles. Length: 1 + number of path points. Format: (number of path points, joint path point poses from the pre-pick point to the pick point). Retreat Points Applies only when the pose type is Joint Angles. Length: 1 + number of path points. Format: (number of path points, joint path point poses from the pick point to the retreat pick point). Scene-Specific Information
Carton/Sack Depalletizing
Product Length: One value; current product length (along the image x direction).
Product Width: One value; current product width (along the image y direction).
Product Orientation: One value; product orientation (0: horizontal along x; 1: vertical along y).
Pallet Upper-Left Vertex Position: Three values (x, y, z); position of the pallet's upper-left vertex in the current scene.
Pallet Upper-Right Vertex Position: Three values (x, y, z); position of the pallet's upper-right vertex in the current scene.
Pallet Lower-Left Vertex Position: Three values (x, y, z); position of the pallet's lower-left vertex in the current scene.
Pallet Lower-Right Vertex Position: Three values (x, y, z); position of the pallet's lower-right vertex in the current scene.
Carton Depalletizing Information:
- Product Height: One value; current product height.
Ordered/Random Picking of Circular Discs:
- Circular Face Radius: One value; radius of the current product's circular face.
Ordered/Random Picking of Cylinders:
Circular Face Radius: One value; radius of the current product's circular face.
Cylinder Height: One value; current product height.
Random Picking:
- Target Category: One value; current target category. Used in scenes that identify multiple types of targets.
Ordered/Random Picking of Quadrilaterals:
Quadrilateral Length: One value; current product length.
Quadrilateral Width: One value; current product width.
Vision Status Codes
Vision status codes help with troubleshooting. The recommended codes are listed below:
Configure ${s} in the Vision Detection Send Command.
- If vision status codes are not configured, success returns
100by default, and all other errors return0by default.
| Status | Default Value | Related Node |
|---|---|---|
| Success | 100 | |
| Bottom plate detected | 301 | Foreground processing (Foreground Builder) |
| Container not detected | 4000 | Container detection (Container Builder) |
| Instance not detected | 5000 | Instance segmentation (Instance Builder) |
| Pose not detected | 6000 | Pose estimation (Pose Builder) |
| Pick point not detected | 7000 | Pick point generation (Grasp Builder) |
| Path not detected | 8000 | Robot trajectory generator (Trajectory Builder) |
| Instance dimensions not detected | 9000 | Target size generator (Size Builder) |
| Empty ROI | 1101 | Valid point filter (ValidPoints Criteria) |
| No valid instances | 12000 | Instance filter (Instance Criteria) |
| No valid target poses | 13000 | Pose filter (Pose Criteria) |
| No valid pick points | 14000 | Pick point filter (Grasp Criteria) |
| All detection results are unpickable due to collisions | 15000 | Collision detection filter (Collision Criteria) |
| No instances with valid dimensions | 17000 | Target size filter (Size Criteria) |
| Error | 20000 | General error; check the logs. |
| Out of video memory | 20001 | General error; check the logs. |
| Invalid input (check algorithm parameters) | 20002 | General error; check the logs. |
| Full detection | 20003 | Point cloud processing operator (full_detect_judgment) |
| Foreign object detection error | 20004 | Instance filtering operator (foreign_matter_judgement) |
Imaging Complete
“Imaging Complete” means the camera has acquired an image and the image data has been processed.

Image Acquisition Complete
“Image Acquisition Complete” means image data has been obtained after the camera takes a picture, but a point cloud has not been generated and image processing has not been performed. It is commonly used when a robot sends a command signal before imaging is complete to trigger the system or a script to perform the next step. The robot does not need to wait for imaging to finish, which takes longer than image acquisition; this can reduce the overall workflow time.

Example
Set the command to CaptureFinished under Image Acquisition Complete / Imaging Complete. When camera image acquisition or imaging is complete, PickWiz sends the CaptureFinished command to the robot, which can trigger the next operation.



4. Verify the Connection
After configuring TCP communication, select a robot configuration for the current task scene on the task Main Screen. Select the corresponding configuration in the robot configuration selector. PickWiz will attempt to establish communication with the robot using the TCP protocol.

If the connection succeeds, the robot communication status in the lower-left corner of the Main Screen displays "Connected".

If the connection fails, the robot communication status displays "Disconnected". Check that the network cable between the robot and industrial PC is securely connected and that the program loaded and running on the robot system is correct, then configure the robot again.

When PickWiz is the server and multiple robot clients attempt to connect, the log reports rejected connection requests from clients other than the one already connected, as shown below.

For instructions on editing, copying, deleting, and selecting robot configurations for a task, see the Robot Configuration Guide.
5. Related Documents
Return to communication method selection and the common configuration workflow
Configure the number of instances and pick points in vision results
Extend processing logic when TCP messages are received and sent