TCP Client Communication Configuration
About 3819 wordsAbout 13 min
In TCP client communication, PickWiz acts as the client and the robot acts as the server. PickWiz actively controls the robot by sending commands. The robot executes each command it receives and returns data.

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

2. Configure TCP Client Communication
For general settings such as the robot name, brand, model, number of axes, and rotation expression, see the Robot Configuration Guide. This page focuses on TCP client 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 | 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 describe the positions of the robot's joints; together, these joint positions determine the pose of the robot arm or end-effector. When Other Device is selected for the robot brand and model, only tool pose can be selected. | |
| Delimiter | Separates data values. For example, pose contains six values, xyzabc. A delimiter distinguishes them, as in x,y,z,a,b,c (with no delimiter at the end). You can enter any character except escape characters such as \n, \r, and \t. | |
| Special trailing characters | Some robot arms require special characters, such as \n\r, at the end of every 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 data in robot commands. Only numbers are supported. The default is 1. | |
2.2 Custom Communication Messages

General command rules
- Messages sent to the robot arm use UTF-8 encoding.
- Commands define the communication protocol between the software and the robot arm. Define a distinct command for each operation. A command consists of command tokens and custom characters.
- Command tokens are provided in shell-variable form: $ {command token}. A command token marks a placeholder that is replaced with actual data when a message is sent. For example,
${p}is replaced with0,0,0,0,0,0(the delimiter can be customized). - Custom characters can be any characters except escape characters such as \n, \r, and \t. They can appear anywhere in a command.
- A command can consist entirely of custom characters, with no command token, or contain only a single command token. However, commands for different operations must remain distinguishable (that is, each communication protocol message must be unique). Otherwise, neither the software nor the robot arm can determine which function to perform when a message is received.
- How the software determines what a message means: when it receives a message, the software replaces the command tokens in every user-configured command, turning each complete command into a regular expression. It then matches the message against those regular expressions. A successful match identifies the operation represented by the message. If none match, either a command is configured incorrectly or the robot arm sent incorrect data.
3. TCP Command Descriptions

3.1 Calibration Communication Messages

PickWiz sends the robot a
getRobotPoserequest to obtain the robot coordinates.The robot returns its coordinates to PickWiz.
p: Pose information for the robot's end-effector
$(p): Outputs the robot's end-effector pose information as six values
Example 1
PickWiz sends the robot a getRobotPose request, and the robot returns its coordinates as p,${p}.


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


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



3.2 Vision Computation Communication Messages

(1) Commands Sent from the Robot to PickWiz

- Placeholders
A placeholder is a symbol or marker used in programming that is replaced with specific content during communication.
| Placeholder | Description |
|---|---|
| p | Robot tool pose, six values. When Pose Type is Tool Pose, the robot sends the current pose of its end-effector 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 multiple sizes, the robot must adjust its picking strategy automatically according to their dimensions. The number of dimension values sent by the robot and what they represent depend on the scene: a circle scene uses one value for radius; a cylinder scene uses two values for radius\height; a carton scene uses three values for length\width\height; and a quadrilateral scene uses two values for width\length. |
| p_tol | Target dimension tolerance. When incoming targets have multiple sizes, the robot must adjust its picking strategy automatically according to their dimensions. The number of tolerance values sent by the robot and what they represent depend on the scene: a circle scene uses one value for radius tolerance; a cylinder scene uses two values for radius\height tolerance; and a quadrilateral scene uses two values for width\length tolerance. |
| 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 | Vision computation rule 0: Capture a new image and perform vision computation; 1: Compute using the previous image data; 2: Capture an image only; 3: Capture an image for “Random Pose Automatic Sampling”; 4: Perform real-time vision drift correction; 5: Perform vision computation using historical data; 6: Shut down the industrial PC. |
- Send Command Information (robot to PickWiz)
Configure the content of commands the robot sends to PickWiz.
d: Command identifier
$(p): Robot end-effector pose information, six values
$(wid): Task ID, one value, used by the robot to switch tasks
Example 1
Set Send Command Information to d,${ps}. The robot sends only pose information to PickWiz, triggering the process.


Example 2
Set Send Command Information 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 process.


Example 3
Set Send Command Information to d,${p},${wid}. The robot sends pose information and a Task ID to PickWiz, automatically switching between the detection processes for Tasks 1, 2, 4, and 5.





- Clear Cache
Clear Cache: Under Capture Once, Pick Multiple, clears the remaining cached instances so that a new image is captured the next time the detection process is triggered.
Picking logic:
- Capture Once, Pick Once: Vision captures an image and performs computation once, sends the result to the robot, and discards any additional results. The robot performs the corresponding pick action, and the sequence repeats.
- Capture Once, Pick Multiple: Vision captures an image and performs computation once, sends a computed result to the robot, and saves additional vision results. The robot performs the corresponding pick action. The next time the robot sends a capture and compute command, the software first checks whether a saved vision result meets the requirements. If it does, the software returns that result directly to the robot without capturing another image or computing again. The sequence then repeats.
Example
When Capture Once, Pick Multiple is not selected, PickWiz captures an image and performs computation every time the robot triggers the detection process.

Select Capture Once, Pick Multiple in the vision computation settings so PickWiz can capture and compute once for multiple picks. In the following figure, five instances are identified. PickWiz triggers the first pick, and the robot triggers the remaining four. For those four picks, the robot sends pose information to PickWiz to trigger the detection process. PickWiz returns pick poses directly without capturing images or performing computation.


The client triggers the first pick. The robot triggers the second and third picks by sending pose information to PickWiz to start the detection process. PickWiz returns pick poses directly without capturing images or performing computation. A co command is then entered to clear the cache. PickWiz resumes image capture and computation for the fourth pick.

(2) Commands Sent from PickWiz to the Robot

- Placeholders
A placeholder is a symbol or marker used in programming that is replaced with specific content during communication.

| Placeholder | Meaning |
|---|---|
| s | Detection result signal: a one-value vision detection signal. By default, success is 100 and other errors are 0. These values can be customized. |
| entity | Returned instance type, one value: 1 for a pallet and 0 for a target. |
| ln | Number of remaining instances, one value. Under the Capture Once, Pick Multiple picking logic, returns the current number of remaining cached instances. |
| 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, the Pick-Related Information Length increases with the number of returned instances. |
| tn | Total number of detected instances, one value: the number of detected instances before 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, used by the automatic calibration sampling command. Different sampling results correspond to different signal values. 0: The minimum number of samples has been reached 1: New sample added successfully 11: Failed to add a new sample 12: Automatic sampling ended; all entries in the sample list have been processed 13: Failed to generate a sampling pose 14: The calibration sampling page is not open 15: System error |
| cp | Next sampling pose, used by the 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 its position. This function is mutually exclusive with splitting data by character count and has higher priority. |
- Vision Detection Send Command (PickWiz to robot)
Configure the content of commands PickWiz sends to the robot.
- 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.
- Pick-Related Information
The lengths below are for a single pick point. For multiple pick points, the length is the number of values × the number of pick points.
Information common to all scenes
| Field | Description |
|---|---|
| Picked target ID | One value; indicates the current target's sequence number. |
| Pick point pose | Six values; represents the pick point pose data. |
| Pick point index | One value; indicates the current pick point's sequence number. |
| Additional information | One value; represents custom additional information for the current target. |
| Approach points | Applies only when the pose type is Joint Angles. The length is 1 + the number of path points; the format is (number of path points, joint poses of path points from the pre-pick point to the pick point). |
| Retreat points | Applies only when the pose type is Joint Angles. The length is 1 + the number of path points; the format is (number of path points, joint poses of path points from the pick point to the retreat pick point). |
- Vision Status Codes
Vision status codes help with troubleshooting. The recommended codes are listed below.
Configure
¥{s}in Vision Detection Send Command.
- If vision status codes are not customized, the default is
100for success and0for all other errors.
| Error | 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 | Target dimension 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 dimension filter (Size Criteria) |
| Exception | 20000 | General exception; check the logs to confirm. |
| Insufficient video memory | 20001 | General exception; check the logs to confirm. |
| Invalid input (check algorithm parameters) | 20002 | General exception; check the logs to confirm. |
| Full detection | 20003 | Related to point cloud processing operator (full_detect_judgment) |
| Foreign object detection error | 20004 | Related to instance filtering operator (foreign_matter_judgement) |
- Capture Complete
Configure CaptureFinished under Capture Complete. After the camera finishes capturing an image, PickWiz sends the CaptureFinished command to the robot.


When a KINGFISHER camera is used, the “Capture Complete” signal changes to “Imaging Complete.” “Imaging Complete” means the camera has acquired the image and processed its data.

- When a KINGFISHER camera is used, the robot can be configured with an Image Acquisition Complete signal.
“Image Acquisition Complete” means the camera has obtained image data after capture but has not generated a point cloud or processed the image. It is commonly used when a robot needs to send a command signal before imaging is complete to trigger the next system or script operation. The robot does not need to wait for imaging to complete, which takes longer than image acquisition and can reduce the overall process time.

4. Verify the Connection
After completing TCP communication configuration, select the robot configuration for the current Task Scene on the Task Main Screen. Select the appropriate robot configuration in the robot configuration selector. PickWiz will attempt to establish communication with the robot over TCP.

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 the industrial PC is secure and that the robot system has loaded and is running the correct program. Then configure the robot again.

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