Integration Guide Hyundai Robotics BPS 1.11

This guide describes how to integrate HD Hyundai Robotics robots (Hi6 and Hi7 controllers) with Bin Picking Studio (BPS). It is based on the HD Hyundai Robotics manual “Bin Picking Studio Integration Guide (v1.11.0)”.

Note

This guide describes the Robot module for Bin Picking Studio 1.11. It uses an older version of the communication interface. The supported versions of all Robot modules are listed in the Robot module support matrix. For the general concept of the communication, see the Robot communication overview.

1. Overview

1.1 BPS Robot Module

The BPS Robot module makes the integration between Photoneo Bin Picking Studio and HD Hyundai Robotics (HDR) robots easy. It provides:

• a dedicated user interface on the teach pendant (T/P) for real-time position streaming and data monitoring,

• dedicated commands that make it easy to create operation programs.

The figure below shows the terms used in this guide.

1.2 System Overview

The system has these components:

• Hardware: robot manipulator and robot controller, vision controller and scanner.

• Installation type: Hand-Eye (scanner mounted on the robot) or Extrinsic (scanner mounted in the cell).

• Communication between robot and vision: two Ethernet TCP/IP socket channels:

  1. Action Server (BPS) - request-response method. The robot controller exchanges data with BPS once, when it is needed.

  2. Robot State Server (robot) - streaming method. The robot controller sends the robot position data to BPS in real time.

1.3 Hardware Components

Item	Description and requirements
Robot manipulator	The robot model must be registered in BPS. Unregistered models can be added after consultation.
Robot controller	Hi6-N, Hi6-T, Hi7-N or Hi7-T. Controller software V60.32-00 or higher. The dedicated BPS Robot module is required.
3D scanner	PhoXi, MotionCam, etc.
Vision controller	Software: PhoXi Control and Bin Picking Studio.
Calibration board	For Hand-Eye installation.
Calibration ball	For Extrinsic installation.

1.4 Software Components

The software part of the Robot module has two parts: the BPS Robot module (plugin app) and the robot JOB programs.

BPS Robot module (plugin app)

The plugin app is required for the integration with Bin Picking Studio. It contains:

1. the Robot State Server setting UI,

2. the monitoring UI,

3. the HRScript (robot language) commands for BPS.

Item	Description
BPS State Server UI	UI to set and run the Robot State Server.
BPS monitoring UI	UI to monitor the connection and the data transmission.

The plugin app adds these BPS commands to HRScript:

Command	Description
connect	Connect to the BPS Action Server.
close	Disconnect from the BPS Action Server.
init	Register the start and end pose for path planning.
req_scan	Trigger a new scan and localization.
recv_scan	Receive the response of req_scan.
get_traj	Get the path planning result.
pick_failed	Notify BPS of a gripper grasp failure.
get_obj_pos	Get the position data of the localized object.
get_status	Get the status of the localization.
capture	Trigger a new scan without localization.
reuse_scan	Request localization with the last scan data.
change_bbox	Change the bounding box.
add_calib	Add the current position as a calibration point.
start_calib	Start the automatic calibration.
stop_calib	Stop the automatic calibration.
save_calib	Save the result of the automatic calibration.
change_sol	Change the deployed solution.
start_sol	Deploy a solution.
stop_sol	Stop the currently deployed solution.
get_run_sol	Get the ID of the deployed solution.
comm_check	Check the connection.

Robot JOB programs

The robot JOB programs required for the BPS integration are of two types:

1. module programs, which contain the functions,

2. operation sample programs.

Module programs

JOB program name	Function name	Description
bps_module_operation	bps_set_param	Declares and sets the global parameters for BPS.
bps_module_operation	bps_traj_run	Performs the bin picking operation based on the path planning data.
bps_module_gripper_cmds	bps_grip_cmd#	Performs the gripper operation based on the gripper command codes.

Sample programs

JOB program name	Description
bps_sample_calib	Semi-automatic calibration sample program for bin picking.
bps_sample_basic	Basic sample program for bin picking.
bps_sample_multigrip	Sample program for an operation with multiple gripping point IDs.
bps_sample_multi_vs	Sample program for multiple vision systems.
bps_sample_multi_sol_main	Main program of the multiple solution example.
bps_sample_multi_sol_sub	Sub-program of the multiple solution example.

Note

On the controller, the JOB files have a number prefix: 0100_bps_sample_calib.job, 0110_bps_sample_basic.job, 0120_bps_sample_gripping_id.job, 0130_bps_sample_multi_vs.job, 0140_bps_sample_multi_sol_main.job, 0141_bps_sample_multi_sol_sub.job, 9000_bps_module_operation.job and 9001_bps_module_gripper_cmds.job (see 2.2 Robot Module Upload). The multiple gripping point sample is the file 0120_bps_sample_gripping_id.job.

2. Robot Controller Setup

2.1 Network Setup

Ethernet cable connection

Connect a LAN port of the robot controller (LAN1 or LAN2) to the LAN port “Robot” of the vision controller with an Ethernet cable.

Robot controller IP setting

1. On the T/P, go to [System] > [2: Control parameter] > [9: Network] > [1: Environment setting].

2. Click the tab of the LAN port that is connected with the cable ([LAN# (Public)]).

3. Enter the IP address and the subnet mask. Click [Apply] to save the settings.

4. Reboot the robot controller to apply the settings. You can also reboot later, after you upload the Robot module (see 2.2 Robot Module Upload).

Note

In a typical local network, the first three numbers of the IP address are the same on the vision controller and on the robot controller. Only the last number is different. For example, vision controller 192.168.1.1 and robot controller 192.168.1.150, both with subnet mask 255.255.255.0.

2.2 Robot Module Upload

Prepare the Robot module files

Copy the bps folder that you received from HD Hyundai Robotics or Photoneo to a USB drive formatted with FAT32.

Upload the module to the controller

1. Insert the USB drive into the T/P.

2. On the T/P, go to [Service] > [5: File manager].

3. Copy the bps folder from the USB drive and paste it to /MAIN/apps/ on the controller.

Move the robot JOB programs

1. Go to /MAIN/apps/bps/jobs.

2. Copy all JOB programs.

3. Paste them to /MAIN/project/jobs/.

4. Reboot the robot controller.

Warning

You must reboot the robot controller. The plugin app works correctly only after the reboot.

2.3 Robot State Server Setup

Robot State Server parameter setting

1. On the T/P, go to [System] > [4: Application parameter] > [Photoneo BPS State Server setting].

2. Enter the State Server(Robot) IP address. This is the IP address of the robot controller LAN port that is connected to the vision controller.

3. Enter the State Server port number. The default value is 11004.

4. Optional: if your process needs a signal that shows the vision connection, assign a digital output (DO) number in Connection output signal.

5. Click [OK].

Robot State Server connection monitoring

1. Split the T/P screen to create a monitoring window.

2. Click [panel layout] and then [Select].

3. Select [Photoneo BPS monitoring].

4. Check the parameters and the connection status.

3. Operation Program Creation

Note

All flowcharts and samples in this chapter are for reference only. Modify them for your application and factory conditions.

In the flowcharts, a blue box is a BPS function, a green box is a BPS command and a white box is a part that you define. In the flowcharts and in some texts of the manual, the trajectory function is shown as bps_run_traj. The function name in the JOB programs is bps_traj_run.

3.1 Function Editing

Global parameter setting

Set the user parameters in the function bps_set_param (program bps_module_operation.job). Edit lines 23 to 27 (user setting).

bps_module_operation.job

#---------------------------------------------------------------
def bps_set_param

global vision_id, sol_id, bbox_id, mode
global start_pos, end_pos
global res={Res:-1}
global Robot={Tool_no:0,Spd:[10,10],Accu:[1,1]}
global BPS_cur={traject_no:0,traject_size:0,waypoint_no:0,step_speed:0}
global BPS_info=[]

#***** User setting *****
Robot.Tool_no=1
Robot.Spd[0]=100 # CNT
Robot.Spd[1]=20 # FINE
Robot.Accu[0]=5 # CNT
Robot.Accu[1]=1 # FINE
#**************************
end

Line	Description
15	Declares the variables for vision system ID, solution ID, bounding box ID and vision type.
16	Declares the start and end pose variables.
17	Declares the return variable.
18	Declares the robot data variable.
19	Declares the bin picking monitoring variable.
20	Declares the bin picking data list variable.
23	User setting: robot tool number for bin picking.
24	User setting: step speed (%) for trajectory (CNT) motion.
25	User setting: step speed (%) for trajectory (FINE) motion (pick approach).
26	User setting: accuracy level for trajectory (CNT) motion.
27	User setting: accuracy level for trajectory (FINE) motion (pick approach).

Gripper operation

Define the gripper operation for each gripper command in the functions bps_grip_cmd# (program bps_module_gripper_cmds.job). The function bps_traj_run calls these functions during the trajectory, based on the gripper commands in the path planning data. You can also call them from your own programs.

bps_module_gripper_cmds.job

#---------------------------------------------------------------
def bps_grip_cmd1

#<< Input the operation of Gripper Command #1 >>

end

#---------------------------------------------------------------
def bps_grip_cmd2

#<< Input the operation of Gripper Command #2 >>

end

• Line 15: define the operation of gripper command 1 (Attach). Example: gripper open DO off, grip DO on, check the grip sensor DI.

• Line 26: define the operation of gripper command 2 (Detach). Example: grip DO off, gripper open DO on, check the open sensor DI.

• If necessary, define the gripper commands 3, 4 and 5 in the same way.

3.2 Calibration Program

Do the semi-automatic calibration during the initial setup.

• Use the TCP (0,0,0,0,0,0,”tool”).

• Record 9 different poses. The vision system must detect the calibration ball or board in each pose. Example: inside the field of view (FOV) of the scanner - 4 upper corners, the center and 4 lower corners.

• Each pose must have distinct and varied joint angles.

• At each point, wait until the robot is stable and then send add_calib (9 times).

For more information about calibration, see Calibration.

Calibration program example

bps_sample_calib.job

#Set parameters
call bps_set_param
var time=2.0

#Connect to server
res=bps.connect("192.168.1.1",11003,10)
if res.Res!=0 then *Error

#<< Record the Calibration Point #1(T0) >>

delay time
res=bps.add_calib()
if res.Res!=0 then *Error

#<< Record the Calibration Point #2(T0) >>

delay time
res=bps.add_calib()
if res.Res!=0 then *Error

Lines 28 to 63 (omitted here) repeat lines 16 to 21 for the calibration points 3 to 8.

#<< Record the Calibration Point #9(T0) >>

delay time
res=bps.add_calib()
if res.Res!=0 then *Error

#---------------------------------------------------------------
*Exit
bps.close()
end

*Error
print("Error code: "+str(res.Res))
stop
goto *Exit

Line	Description
9	Sets the required global variables.
10	User setting: stabilization time (s) after each movement.
13	Connects to the Action Server. User setting: server IP address, port and timeout.
14	If an error occurs (result code is not 0), jumps to the error branch.
16, 22, 64	User setting: record the calibration pose (step) 1, 2 … 9.
18, 24, 66	Waits for the stabilization time.
19, 25, 67	Adds the current position as a calibration point.
20, 26, 68	If an error occurs, jumps to the error branch.
71 - 73	End branch: disconnects the action client.
75 - 78	Error branch: shows the error code on the T/P and goes to the end.

3.3 Basic Bin Picking Operation Program

This is the most basic structure. It shows a repeated bin picking cycle for one model of workpiece.

1. Set the variables and send init (set the start and end poses).

2. First cycle: scan at the home position and get the path data.

3. Call bps_traj_run to do the bin picking motion (from the start pose to the end pose).

4. At the end pose, request the next scan.

5. Do the placing operation.

6. Check the result, get the new path data and repeat.

Basic bin picking program example

bps_sample_basic.job

#Set parameters
call bps_set_param
vision_id=1
mode="static"
start_pos=Pose(0,0,0,0,0,0,"joint")
end_pos=Pose(0,0,0,0,0,0,"joint")

#Connect to server
res=bps.connect("192.168.1.1",11003,10)
if res.Res!=0 then *Error

#Initialization
res=bps.init(vision_id,start_pos,end_pos)
if res.Res!=0 then *Error

*Home
#<< Record the home position step >>

#1st Scan request
bps.req_scan(vision_id,mode)

*Loop
#Receive Scan
res=bps.recv_scan()
if res.Res!=0 then *Error

#Traject
res=bps.get_traj(vision_id)
if res.Res!=0 then *Error
var traj=res

#Trajectory operation
call bps_traj_run, Robot,traj
res.Res=result()
if res.Res!=0 then *Error

#----- Place -----
#2nd or later Scan request
bps.req_scan(vision_id,mode)

#<< Input placing sequence >>


goto *Loop

#---------------------------------------------------------------
*Exit
bps.close()
end

*Error
print("Error code: "+str(res.Res))
stop
goto *Exit

Line	Description
8	Sets the required global variables.
9	User setting: vision system ID.
10	User setting: vision type ("static": Extrinsic, "hand": Hand-Eye).
11	User setting: start pose for path planning (outside the FOV for Extrinsic).
12	User setting: end pose for path planning (outside the FOV for Extrinsic).
15 - 16	Connects to the Action Server (user setting: server IP address, port and timeout). On error, jumps to the error branch.
19 - 20	Registers the start and end pose for path planning. On error, jumps to the error branch.
23	User setting: record the home position as a step (outside the FOV for Extrinsic).
26	Requests a scan (first cycle: at the home position).
28	Start of the loop.
30 - 31	Checks the result of the previous scan. On error, jumps to the error branch.
34 - 36	Gets the path planning data and stores it in a user variable. On error, jumps to the error branch.
39	Runs the path planning motion. The parameters are the Robot variable from bps_set_param and the result of get_traj.
40 - 41	Stores the result of the function. On error, jumps to the error branch.
45	Requests the next scan (after the first cycle: at the end position). For Hand-Eye, wait until the robot is fully stopped before the scan.
47	User setting: insert or call a program that places the object.
50	Jumps back to the loop to repeat the bin picking cycle.
53 - 55	End branch: disconnects the action client.
57 - 60	Error branch: shows the error code on the T/P and goes to the end.

3.4 Advanced: Multi Gripping Point

This example shows a bin picking cycle for a model that has more than one gripping point.

• The operation is the same as the basic operation up to bps_traj_run.

• After the bin picking motion, the program checks the gripping point ID.

• The program places the object based on the gripping point.

Note

Depending on your process, you can skip req_scan and return to the home position.

Multi gripping point program example

Lines 7 to 41 are the same as in the basic example (bps_sample_gripping_id.job). The additional lines are:

bps_sample_gripping_id.job

#----- Place -----
var grip_id=BPS_info[1]
switch grip_id
case 1
  #2nd or later Scan request
  bps.req_scan(vision_id,mode)

  #<< Insert placing sequence for Gripping ID #1 >>

  goto *Loop
case 2

  #<< Insert placing sequence for Gripping ID #2 >>

  break
default
  print("Gripper ID error")
  stop
end_switch
goto *Home

#---------------------------------------------------------------
*Exit
bps.close()
end

*Error

The error branch is the same as in the basic example.

Line	Description
44	Stores the gripping point ID in a user variable.
45	Selects the placing program based on the gripping point ID.
46 - 48	Case 1 (gripping point ID 1): requests the next scan (at the end position; for Hand-Eye, wait until the robot is fully stopped).
50	User setting: insert or call a program that places the object for gripping point ID 1. Example: normal placing.
52	Jumps back to the loop to repeat the bin picking cycle.
53 - 57	Case 2 (gripping point ID 2): user setting: insert or call a program that places the object for gripping point ID 2 (example: drop it into the bin box). Then leave the switch statement.
58 - 61	Other cases: shows a gripping point ID error on the T/P and stops.
62	Goes to the home position.
65 - 67	End branch: disconnects the action client.

3.5 Advanced: Multi Vision System

In this example, more than one workpiece model is registered, each as a separate vision system ID. When the bin picking of one model (bin) is complete, the program switches to the next model.

1. Set the global parameters, connect to BPS and set the vision system ID.

2. Send init (set the start and end poses).

3. Scan and check the condition for a vision system ID change (for example, error 202, no object found).

4. If there is no change, get the path data.

5. Call bps_traj_run to do the bin picking motion (from the start pose to the end pose).

Multi vision system program example

bps_sample_multi_vs.job

#Set parameters
call bps_set_param

#Connect to server
res=bps.connect("192.168.1.1",11003,10)
if res.Res!=0 then *Error

#----- Set Vision System -----
*Set_vs
mode="static"
vision_id=fb1.diw1
start_pos=Pose(0,0,0,0,0,0,"joint")
end_pos=Pose(0,0,0,0,0,0,"joint")

#Initialization
res=bps.init(vision_id,start_pos,end_pos)
if res.Res!=0 then *Error

*Home
#<< Record the home position step >>

#1st Scan request
bps.req_scan(vision_id,mode)

*Loop
#Receive Scan
res=bps.recv_scan()
if res.Res!=0 then *Error

#Traject
res=bps.get_traj(vision_id)
if res.Res==202 then *Set_vs
if res.Res!=0 then *Error
var traj=res

#Trajectory operation
call bps_traj_run, Robot,traj
res.Res=result()
if res.Res!=0 then *Error

#----- Place -----
#2nd or later Scan request
bps.req_scan(vision_id,mode)

#<< Insert placing sequence based on Vision ID >>

goto *Loop

#---------------------------------------------------------------
*Exit
bps.close()
end

*Error
print("Error code: "+str(res.Res))
stop
goto *Exit

The differences from the basic example are:

Line	Description
15	Branch point for the vision system (VS) setting.
16	User setting: vision type ("static": Extrinsic, "hand": Hand-Eye).
17	User setting: vision system ID. In this example, the ID comes from fieldbus data from a higher-level controller (fb1.diw1).
18 - 19	User setting: start and end pose for path planning (outside the FOV for Extrinsic).
38	If the condition for a vision system ID change is met (example: error 202, no object found), jumps to the VS setting.
51	User setting: insert or call a program that places the object based on the vision system ID.

3.6 Advanced: Multi Solution

This example shows a bin picking operation with more than one BPS solution.

• Prepare a main program and one sub-program for each solution. The sub-programs can reuse the basic and advanced examples above.

• Main program: set the parameters and connect to BPS.

• Main program: check the solution status, then deploy or change the solution.

• Sub-program: run the bin picking cycle until an error occurs.

• When the sub-program ends, the main program checks the condition for a solution change (for example, error 202, no object found).

• If the condition is true, the main program changes the solution with change_sol. If not, the main program handles the error.

Main program example

bps_sample_multi_sol_main.job

#Set parameters
call bps_set_param
var code, cur_sol

#connect to server
res=bps.connect("192.168.1.1",11003,10)
if res.Res!=0 then *Error

*Set_sol
sol_id=fb1.diw0

#Get current runnind solution
res=bps.get_run_sol()
code=res.Res

switch code
case 453
  res=bps.start_sol(sol_id)
  if res.Res!=0 then *Error
  break

case 0
  cur_sol=res.info
  if cur_sol!=sol_id
    res=bps.change_sol(sol_id)
    if res.Res!=0 then *Error
  endif
  break

default
  goto *Error
end_switch

#<< Call sub program for each solution ID >>
call 141

#Condition check
if res.Res==202 then *Set_sol
if res.Res!=0 then *Error

#---------------------------------------------------------------

The end and error branches are the same as in the basic example.

Line	Description
9	Declares the user variables.
12 - 13	Connects to the Action Server (user setting: server IP address, port and timeout). On error, jumps to the error branch.
15	Branch point for the solution ID setting.
16	User setting: solution ID. In this example, the ID comes from fieldbus data from a higher-level controller (fb1.diw0).
19 - 20	Gets the currently deployed solution and stores the result code.
22	Selects the case based on the result code.
23 - 26	No solution is deployed (error 453): deploys the selected solution. On error, jumps to the error branch.
28 - 34	A solution is deployed: stores its ID. If it is different from the target solution, changes the solution. On error, jumps to the error branch.
36 - 38	Other cases (error): jumps to the error branch.
40 - 41	User setting: call the sub-program for the solution ID (here JOB 141, 0141_bps_sample_multi_sol_sub.job).
44	If the condition for a solution change is met (example: error 202, no object found), jumps to the solution ID setting.
45	On other errors, jumps to the error branch.

Sub-program example

bps_sample_multi_sol_sub.job

#Set parameters
vision_id=1
mode="static"
start_pos=Pose(0,0,0,0,0,0,"joint")
end_pos=Pose(0,0,0,0,0,0,"joint")

#Initialization
res=bps.init(vision_id,start_pos,end_pos)
if res.Res!=0 then *Exit

*Home
#<< Record the home position step >>

#1st Scan request
bps.req_scan(vision_id,mode)

*Loop
#Receive Scan
res=bps.recv_scan()
if res.Res!=0 then *Exit

#Traject
res=bps.get_traj(vision_id)
if res.Res!=0 then *Exit
var traj=res

#Trajectory operation
call bps_traj_run, Robot,traj
res.Res=result()
if res.Res!=0 then *Exit

#----- Place -----
#2nd or later Scan request
bps.req_scan(vision_id,mode)

#<< Insert placing sequence >>

goto *Loop

#---------------------------------------------------------------
*Exit
end

The sub-program is the basic example with these differences:

• Lines 7 to 11 set the parameters for this bin picking sub-program (vision system ID, vision type, start and end pose).

• Line 12: there is no connect. The main program opens the connection.

• On error, the sub-program jumps to *Exit (lines 15, 26, 30 and 36). It has no error handling, because the main program handles the errors.

• Lines 47 to 48: the sub-program ends without closing the connection.

4. Robot Module

This chapter describes the BPS commands and functions of the Robot module. For the meaning of each request on the BPS side, see Action requests.

4.1 General Information

Command format

Use this syntax to call a BPS command in a robot JOB program and store the result:

ReturnVariable = bps.Command(Arg1, Arg2, ...)

Item	Description
ReturnVariable	Variable that stores the return values of the command. You define the name and the scope (local or global). Declare the variable before you use it, to avoid errors.
Command	BPS command. See sections 4.2 to 4.6.
Arg#	Input parameters of the command. The number of parameters depends on the command. See sections 4.2 to 4.6.

Command input on the T/P

1. Click [cmd.input] on the T/P. This creates an assignment statement.

2. Enter the return variable on the left side.

3. Put the cursor on the right side, then select [functions] > [bps].

4. Select the command and press Enter.

5. Edit the parameters and press Enter.

Function format

Use the call command to call a function of the module program. Use result() to get the return value.

call Function Arg1, Arg2, ...
ReturnVariable = result()

Item	Description
Function	Name of the function in the module program.
Arg#	Input parameters of the function. The number of parameters depends on the function. See section 4.7.
ReturnVariable	Variable that stores the return value of the function. You define the name and the scope (local or global). Declare the variable before you use it, to avoid errors.

Return variable format

The return values of a BPS command are stored in an object variable:

ReturnVariable = {"Res" : ResultCode, "msgs" : MessageList, "info" : InfoData, "pose" : Position }

To read a key, use ReturnVariable.KeyName. Examples: err_code = res.Res, print(res.info).

Item	Key	Description
ResultCode	Res	Result of the command. See the result codes below.
MessageList	msgs	BPS response messages, stored as an array. See “Message format” below.
InfoData	info	Optional key (only some commands). Stores the “info” messages: more than one value is stored as an array ([Info1, Info2, ...]), one value is stored as a single value (Info).
Position	pose	Optional key (only some commands). Stores the value of the “pose” message.

Result codes

Code	Meaning
0	Completed normally.
-1	In process.
-2	Timeout.
-3	Connection lost.
-4	Processing error.
-5	Parameter error.
-6	Received byte error.
> 0	Error code from BPS. See Error codes. Examples used in this guide: 202 No object found, 453 Deployment is not running.

Message format

A BPS response contains one or more messages. Each message is stored as an object in the msgs key (array) of the return variable:

ReturnVariable.msgs = [Message1, Message2, Message3, ... ]
Message# = {"Type": type code, "data": Value }

Type code	Data type	Contents	Description of data
0	Array	Trajectory waypoint list, trajectory (CNT)	Two-dimensional array with the waypoints of the trajectory: [waypoint1, waypoint2, waypoint3, ...], where waypoint# = [j1, j2, j3, j4, j5, j6, "joint"].
1	Array	Trajectory waypoint list, trajectory (FINE)	Same as type 0.
2	Integer	Gripper command code	Gripper command value (1, 2, 3, 4 or 5).
3	Integer	Error code	Error code value (0: OK).
4	Array / Numeric	Info data	Info data. One value is stored as a number, more values as an array.
5	Array	Object pose	Object position data: [x, y, z, rx, ry, rz, "robot"].

The key Type (Integer) stores the message type code (0, 1, 2, 3, 4 or 5). The key data stores the data for this type.

4.2 Setting Commands

4.2.1 connect

Connects to the request-response server (BPS Action Server). The timeout applies to the connection and to all requests (-1: no timeout).

Syntax: ReturnVariable = bps.connect(t, n1, n2)

Arguments

Argument	Type	Contents	Description
t	String	Server IP address	IP address of the server (BPS Action Server).
n1	Integer	Server port number	Port number of the server.
n2	Integer	Timeout (s)	Connection and response timeout.

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).

4.2.2 close

Closes the current request-response client socket.

Syntax: ReturnVariable = bps.close()

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).

4.3 Bin Picking Operation Commands

All commands in this section return these keys (some commands return more keys, see the command):

Common return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
msgs	Array	Response message list	List of the received messages.

4.3.1 init

Requests the initialization of path planning in the vision system and sets the start and end poses (waypoints) for path planning. For robots with external axes, get_traj uses the external axis values of the start pose. See Initialization request.

Syntax: ReturnVariable = bps.init(n, p1, p2)

Arguments

Argument	Type	Contents	Description
n	Integer	Vision system ID	BPS vision system ID.
p1	Pose	Start pose	Start position of path planning (crd: joint).
p2	Pose	End pose	End position of path planning (crd: joint).

Return variable: Res, msgs.

4.3.2 req_scan

Triggers a new scan and starts the localization. Run init once before you use this command. For Hand-Eye vision systems, use this command only when the robot is fully stopped. See Scan request.

Syntax: ReturnVariable = bps.req_scan(n, t)

Arguments

Argument	Type	Contents	Description
n	Integer	Vision system ID	BPS vision system ID.
t	String	Installation type	Vision installation type: Extrinsic ("static") or Hand-Eye ("hand"). All values other than "hand" are handled as Extrinsic.

Return variable: Res, msgs.

4.3.3 recv_scan

Receives the result of the last scan request. Use this command as the next command after req_scan.

Syntax: ReturnVariable = bps.recv_scan()

Return variable: Res, msgs.

4.3.4 capture

Triggers a new scan without localization (for multiple scans). See Trigger scan request.

Syntax: ReturnVariable = bps.capture(n)

Argument: n (Integer) - BPS vision system ID.

Return variable: Res, msgs.

4.3.5 reuse_scan

Requests a localization with the last received scan data. See Localize on the last scan request.

Syntax: ReturnVariable = bps.reuse_scan(n)

Argument: n (Integer) - BPS vision system ID.

Return variable: Res, msgs.

4.3.6 get_traj

Gets a collision-free path to pick a localized object and extract it from the scene (bin, rack, etc.). Use this command after the scan. Use the return variable as a parameter of bps_traj_run. The trajectory info data is stored in the info key. See Trajectory request and Info data.

Syntax: ReturnVariable = bps.get_traj(n)

Argument: n (Integer) - BPS vision system ID.

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
info	Array	Received info data list	Trajectory info data: [Tool invariance ID, Gripping point ID, Gripping point invariance ID, Length, Width, Z rotation]. CAD picking: 3 values, AI picking: 6 values.
msgs	Array	Response message list	List of the received messages.

4.3.7 pick_failed

Notifies BPS that the pick failed, based on the gripper feedback. You can add this command to the grasp function bps_grip_cmd1. See Pick-failed request.

Syntax: ReturnVariable = bps.pick_failed(n)

Argument: n (Integer) - BPS vision system ID.

Return variable: Res, msgs.

4.3.8 get_status

Gets the current status of a vision system during localization. Use this command after the scan. See Get vision system status request.

Syntax: ReturnVariable = bps.get_status(n)

Argument: n (Integer) - BPS vision system ID.

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
info	Array	Status info list	Current state of the localization: [number of localized objects, number of planned objects, processing status (0 or 1)].
msgs	Array	Response message list	List of the received messages.

4.3.9 change_bbox

Changes the bounding box for the localization of the vision system. See Change bounding box request.

Syntax: ReturnVariable = bps.change_bbox(n1, n2)

Arguments

Argument	Type	Contents	Description
n1	Integer	Vision system ID	BPS vision system ID.
n2	Integer	Bounding box ID	ID of the target bounding box.

Return variable: Res, msgs.

4.3.10 get_obj_pos

Gets the raw Cartesian pose of the localized object. Use this command after the scan. See Object pose request.

Note

This is the raw position of the object. It does not depend on the grip pose.

Syntax: ReturnVariable = bps.get_obj_pos(n)

Argument: n (Integer) - BPS vision system ID.

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
msgs	Array	Response message list	List of the received messages.
pose	Array	Object position data	Position of the localized object: [x, y, z, rx, ry, rz, "robot"].

4.4 Calibration Commands

4.4.1 add_calib

Adds the current robot position as a new calibration point. Use this command only when the robot is fully stopped. See Add calibration point request.

Syntax: ReturnVariable = bps.add_calib()

Return variable: Res (Integer, execution result, 0: completed), msgs (Array, list of the received messages).

4.4.2 start_calib

Starts the automatic calibration. See Start automatic calibration request.

Syntax: ReturnVariable = bps.start_calib(n1, n2)

Arguments

Argument	Type	Contents	Description
n1	Integer	Solution ID	BPS solution ID.
n2	Integer	Vision system ID	BPS vision system ID.

Return variable: Res, msgs.

4.4.3 save_calib

Saves and returns the result of the automatic calibration. Use this command after start_calib. See Save automatic calibration result request.

Syntax: ReturnVariable = bps.save_calib(n1, n2)

Arguments

Argument	Type	Contents	Description
n1	Integer	Solution ID	BPS solution ID.
n2	Integer	Vision system ID	BPS vision system ID.

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
info	Integer	Calibration accuracy	Calibration accuracy (error).
msgs	Array	Response message list	List of the received messages.
pose	Array	Camera position	Calibrated camera position: [x, y, z, rx, ry, rz, "robot"].

4.4.4 stop_calib

Stops the automatic calibration. Use this command after start_calib. See Stop automatic calibration request.

Syntax: ReturnVariable = bps.stop_calib()

Return variable: Res, msgs.

4.5 Solution Commands

All solution commands return Res (Integer, execution result, 0: completed) and msgs (Array, list of the received messages). get_run_sol also returns info.

4.5.1 change_sol

Changes the deployed solution. Use this command only when a solution is deployed. See Change solution request.

Syntax: ReturnVariable = bps.change_sol(n)

Argument: n (Integer) - ID of the solution to deploy.

4.5.2 start_sol

Deploys a solution. See Start solution request.

Syntax: ReturnVariable = bps.start_sol(n)

Argument: n (Integer) - ID of the solution to deploy.

4.5.3 stop_sol

Stops the currently deployed solution. See Stop solution request.

Syntax: ReturnVariable = bps.stop_sol()

4.5.4 get_run_sol

Gets the ID of the deployed solution. See Get running solution request.

Syntax: ReturnVariable = bps.get_run_sol()

Return variable

Key	Type	Contents	Description
Res	Integer	Execution result	Result of the command (0: completed).
info	Integer	Deployed solution ID	ID of the deployed solution.
msgs	Array	Response message list	List of the received messages.

4.6 Additional Commands

4.6.1 comm_check

Checks if the communication with the vision system is still active. You can use it for a simple connection check. See Communication check request.

Syntax: ReturnVariable = bps.comm_check()

Return variable: Res (Integer, execution result, 0: completed), msgs (Array, list of the received messages).

4.7 Functions

4.7.1 bps_set_param

Declares and sets the global variables required for the Bin Picking Studio integration.

Syntax: call bps_set_param

Variables for the sample programs

Name	Key	Type	Contents
vision_id		Integer	Vision system ID for the sample programs.
sol_id		Integer	Solution ID for the sample programs.
bbox_id		Integer	Bounding box ID for the sample programs.
mode		String	Vision installation type for the sample programs: "static" or "hand".
start_pos		Pose	Start pose of path planning for the sample programs (joint coordinates only): Pose(j1, j2, j3, j4, j5, j6, "joint").
end_pos		Pose	End pose of path planning for the sample programs (joint coordinates only): Pose(j1, j2, j3, j4, j5, j6, "joint").
res	Res	Object / Integer	Stores the command return values in the sample programs. The key structure depends on the command.

Variables for the bin picking function

Name	Key	Type	Contents
Robot	Tool_no	Object / Integer	Robot tool number.
Robot	Spd	Object / Array	Step speed (%) for each trajectory type (CNT/FINE): [CNT trajectory speed (%), FINE trajectory speed (%)].
Robot	Accu	Object / Array	Accuracy level for each trajectory type (CNT/FINE): [CNT trajectory accuracy, FINE trajectory accuracy].
BPS_cur	traject_no	Object / Integer	Index of the current trajectory while bps_traj_run runs.
BPS_cur	traject_size	Object / Integer	Number of waypoints in the current trajectory while bps_traj_run runs.
BPS_cur	waypoint_no	Object / Integer	Number of the current waypoint while bps_traj_run runs.
BPS_cur	step_speed	Object / Integer	Step speed of the current trajectory while bps_traj_run runs.
BPS_info		Array	Information about the object that the robot currently handles in bps_traj_run: [Tool invariance ID, Gripping point ID, Gripping point invariance ID].

4.7.2 bps_grip_cmd#

Runs the operation for the gripper command. Define the operation of each function in the program bps_module_gripper_cmds.job before you use it (see section 3.1).

call bps_grip_cmd1  # Attach
call bps_grip_cmd2  # Detach
call bps_grip_cmd3  # User1
call bps_grip_cmd4  # User2
call bps_grip_cmd5  # User3

4.7.3 bps_traj_run

Runs the bin picking motion based on the robot parameters and the path planning (trajectory) data. To run the trajectory waypoint by waypoint, add a stop command inside the move loop.

Syntax:

call bps_traj_run, Robot,obj
UserVariable = result()

UserVariable is the variable for the function result.

Arguments

Argument	Type	Contents	Description
Robot	Object	Robot data	Use the Robot variable from bps_set_param. It contains the tool number and the step speed and accuracy for each trajectory type.
obj	Object	Path planning data	Use the result variable of get_traj without changes. It contains all path data: waypoints, gripper commands and info data.

Return value

Name	Type	Contents	Description
err_code	Integer	Execution result	Result of the function. 0: completed, -5: parameter error.