ModBus Communication Configuration
About 2568 wordsAbout 9 min
ModBus is a communication method in which PickWiz acts as the client and the robot acts as the server. When communicating with the robot, PickWiz actively controls it by sending commands. The robot executes the commands and returns data.

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

2. Configure ModBus Communication
For general settings such as robot name, brand, model, number of axes, and rotation representation, see the Robot Configuration Guide. This page focuses on ModBus communication parameters and fields.
2.1 Basic Communication Settings

| Setting | Description | |
|---|---|---|
| Communication address | Host IP | Host IP address. The default for ModBus communication is 127.0.0.1. |
| Port number | The specified port through which the robot connects to the host. The default is 502 and generally does not need to be changed. | |
| Slave ID | A unique identifier for the robot that lets PickWiz identify and distinguish each robot. Only numbers are supported. The default is 1 and can be changed. | |
| Byte order | The byte order used for communication between PickWiz and the robot over ModBus. Options are ABCD/BADC/CDAB/DCBA; the default is ABCD. | |
| Read/write format | Euler angle unit | Unit for Euler angles. Options are degrees and 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 refers to the pose of the robot's end-effector; joint angles describe the positions of the robot's individual joints, which together 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 as the pose type. | |
| 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 Message Configuration

3. ModBus Command Reference
3.1 Communication Assurance Fields
Communication assurance fields monitor communication status and ensure that commands are executed uniquely and correctly.

| Field | Description |
|---|---|
| Heartbeat | Monitors communication status. When the robot/PLC is connected to PickWiz, PickWiz writes 1 to the corresponding address block. When communication between the robot/PLC and PickWiz is lost (PickWiz has not written 1 for an extended period), the robot/PLC writes 0 to that address block. |
| Trigger flag | Indicates whether the robot/PLC has triggered a command. When it triggers a command, the robot/PLC writes 1 to the trigger flag address block, and PickWiz reads the data from that block. After the robot/PLC receives confirmation that PickWiz received the command (the command acknowledgment flag is 1), it writes 0 to the trigger flag address block to prevent triggering the command a second time. After PickWiz executes the command, it returns the vision detection result to the robot/PLC and reads the trigger flag address block. If it reads 0, the robot/PLC can read the returned vision detection result. |
| Command acknowledgment flag | Indicates whether PickWiz received the command. After the robot/PLC triggers a command and PickWiz reads it, PickWiz writes 1 to the command acknowledgment flag address block to notify the robot/PLC that the command was received. After executing the command and confirming that the robot/PLC has reset the trigger flag (written 0), PickWiz also resets the command acknowledgment flag (writes 0). This tells the robot/PLC that execution is complete and the process has ended. The robot then reads the returned vision detection result and performs the task. |
| Execution command | Specifies the command to execute. When the robot/PLC needs to execute a command, it writes 100/101 to the execution command address block. PickWiz reads this block to determine which command the robot/PLC requires. 100 is the image capture command; 101 is the clear cache command (used when capturing once and picking multiple times). |

3.2 Calibration Communication Message

Command sent from the robot to PickWiz
Used during eye-hand calibration and when image capture is triggered in an eye-in-hand setup so that PickWiz can obtain the robot's current pose in real time.
If Tool Pose is selected as the Pose Type in the basic communication settings, send the current pose of the robot's end-effector to PickWiz (6 data values).
If Joint Angles is selected as the Pose Type in the basic communication settings, send the joint pose (6 data values). It is used to calculate the pick-point joint pose closest to this reference joint pose.
During eye-hand calibration or when image capture is triggered in an eye-in-hand setup, the robot writes its current pose to this address block, and PickWiz reads the pose from the block.
The robot pose consists of 6 data values, so storage space for 6 values must be reserved in the address block.
3.3 Vision Calculation Communication Message
When the Execution Command value is 100, vision calculation can be performed and the following message fields apply. Select a checkbox to display its corresponding address input field below, then enter an address block. When the robot triggers the image capture command, it writes data to the corresponding address block, and PickWiz reads that data.

(1) Commands sent from the robot to PickWiz
| Field | Description |
|---|---|
| Joint pose | Reference joint pose of the robot, consisting of 6 data values. When Pose Type is Joint Angles, enter the Reference Joint Pose to calculate the pick-point joint pose closest to it. |
| 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 the target information each value represents depend on the scene. For a circular surface, 1 value represents the radius; for a cylinder, 2 values represent radius\height; for a carton, 3 values represent length\width\height; for a quadrilateral, 2 values represent width\length. |
| Target dimension tolerance | When incoming targets have multiple sizes, the robot must adjust its picking strategy automatically according to their dimensions. The number of target dimension tolerance values sent by the robot and the target information each value represents depend on the scene. For a circular surface, 1 value represents the radius tolerance; for a cylinder, 2 values represent the radius\height tolerances; for a quadrilateral, 2 values represent the width\length tolerances. |
| Target ID | Target ID, used by the robot to switch automatically between targets to pick. |
| Task ID | Task ID, used by the robot to switch tasks automatically. |
| Calibration ID | Calibration ID, used by the robot to switch eye-hand calibration configuration files automatically. |
| End-effector ID | End-effector ID, used by the robot to switch end-effectors automatically when performing a task. |
| ROI ID | ROI ID, used by the robot to switch ROIs automatically. |
| Vision parameter ID | Vision parameter ID, used by the robot to switch vision parameters automatically. |
| Scene Object ID | Scene Object ID, used by the robot to switch Scene Objects automatically. |
| Image capture calculation type | Image capture calculation type: 0: capture a new image and perform vision calculation; 1: perform vision calculation using the cached image (the image captured previously); 2: capture an image only; 3: capture an image for “automatic sampling with random poses”; 4: correct vision drift in real time; 5: perform vision calculation using historical data; 6: shut down the industrial PC. |
(2) Commands sent from PickWiz to the robot
- Vision detection information
| Field | Description |
|---|---|
| Image capture completion signal | A 1-value signal indicating that image capture is complete. The robot/PLC must reset it after receiving it. |
| Detection result signal | A 1-value vision detection signal. By default, success returns 100 and other errors return 0; this can be configured. |
| Returned instance type | A 1-value instance type. 0 represents a target and 1 represents a pallet. Picking information differs by instance type. |
| Remaining instance count | A 1-value count of the cached instances remaining when using the capture-once, pick-multiple-times logic. |
| Returned instance count | A 1-value count of instances identified by 2D instance segmentation. This value is less than or equal to Number of Instances to Send. If there are multiple instances, Picking Information Length increases with the returned instance count. |
| Total detected instances | A 1-value count of detected instances before instance filtering. |
| Valid instance count | A 1-value count of detected instances after instance filtering. |
| Target type | The type ID that can be returned when multiple target types are recognized. |
- Automatic Calibration Sampling Command
When the eye-hand calibration method is “Automatic Sampling with Random Poses,” this command must be configured; otherwise, the robot cannot communicate with PickWiz.
| Field | Description |
|---|---|
| Calibration sampling result: Different results correspond to different signal values | 0: Minimum sample count reached 1: New sample added successfully 11: Failed to add a new sample 12: Automatic sampling ended; the sample list has been completed 13: Failed to generate a sampling pose 14: Not on the calibration sampling page 15: System error |
| Next sampling pose | The position to which the robot moves to acquire the next calibration sample. |
- Picking Information
The picking information 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 |
|---|---|
| Target category | / |
| Picked target ID | 1 value; indicates the sequence number of the current target. |
| Pick-point pose | 6 values; represent the pose data of the pick point. |
| Pick-point index | 1 value; indicates the sequence number of the current pick point. |
| Additional information | 1 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 the 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 the path points from the pick point to the retreat pick point). |
- Vision Status Codes
Vision status codes are used for troubleshooting. The complete list follows.
Under Commands Sent from PickWiz to the Robot – Vision Detection Information, select “Vision Status Code” and configure the address block and communication data type.
If the vision status code is not configured, the default return value 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 size detected | 9000 | Target size generator (Size Builder) |
| Empty ROI | 1101 | Invalid 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 cannot be picked due to collisions | 15000 | Collision detection filter (Collision Criteria) |
| No instances with valid dimensions | 17000 | Target size filter (Size Criteria) |
| Exception | 20000 | General exception; check the logs to confirm. |
| Insufficient GPU 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 | Point cloud processing operator (full_detect_judgment) |
| Foreign object detection error | 20004 | Instance filtering operator (foreign_matter_judgement) |
4. Verify the Connection
After configuring ModBus communication, select the robot configuration for the current task scene on the task Main Screen. In the robot configuration selector, choose the corresponding configuration. PickWiz will attempt to establish communication with the robot over ModBus.

If the connection succeeds, the robot communication connection status in the lower-left corner of the main screen displays “Connected.”

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

For instructions on editing, copying, deleting, and selecting a robot configuration for a task, 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
Learn about the placeholder processing hooks available for ModBus