This page contains a detailed description of the action requests that can be sent from the robot controller as well as response-receiving procedures to the asynchronous requests.
1 Bin picking action requests
Note: Most bin picking requests are bound to a specific vision system - the ID of the vision system is a required parameter for these requests. The exception is the Change scene state request which requires the ID of the scene state.
1.1 Initialization request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.0.0
Required parameters
start joints pose, end joint pose, vision system ID
Description
Initializes a vision system; joint values of the start pose and end pose defined in the robotic controller are transferred to the vision controller to be used as the start and end points of the bin picking routine for the requested vision system.
It blocks the execution of the robotic program for a negligible amount of time.
Usage
Typically it is sent only once at the beginning of the robotic program when deployment is already running. Then it is sent only if:
- change of the start/end pose is necessary
- deployment was stopped and started
- localization memory needs to be cleared (if the localization memory clearing parameter is turned on)
1.2 Scan request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.0.0
Required parameters
vision system ID
Description
The sensor associated with the requested vision system triggers a new scan (full/fast). Immediately after the scan completion, the localization starts reporting found objects, and path planning proceeds with calculating trajectories for them.
Completion of scanning can take up to several seconds and its result is sent when the operation has finished. In order not to block the execution of the robotic program during this time, the response from the vision controller is received in a separate dedicated procedure Wait for scan completion which must be always sent after a scan request.
Usage
Hand-eye vision system
Typically it is sent in each cycle as soon as the robot completes a pick (bin picking routine) and it is still above the bin (single bin application). This maximizes the time the Bin Picking Studio has for localization and path planning before the robot is ready to pick another object.
Scan request is then immediately followed by the procedure Wait for scan completion in order to block the execution of the robotic program until the scanning operation has finished (the robot must stay still during scan execution).
Extrinsic vision systems
Typically it is sent in each cycle as soon as the robot completes a pick (bin picking routine) and clears the scanning volume. This maximizes the time the Bin Picking Studio has for localization and path planning before the robot is ready to pick another object.
Scan request is then followed by the procedure Wait for scan completion that receives the result of the scanning operation.
1.3 Trajectory request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.0.0
Required parameters
vision system ID
(timeout - set in the solution settings)
Description
Requests a bin picking trajectory along with other bin picking data (gripper commands, grasping data) to be sent to the robotic controller.
The most suitable object at the time the request is received by the vision controller, based on the configured priority settings, from the objects with successfully computed trajectories, is chosen. If no such object exists yet, the first object to have successfully computed trajectory is chosen or an error is sent to the robotic controller.
Trajectory request does not block the execution of the robotic program as the bin picking trajectory sent from the vision controller is received by a separate dedicated procedure Receive trajectory which must be always sent after a trajectory request.
Usage
Normally it is sent only once in each cycle after a scan request for the same vision system. Sending a trajectory request for a different vision system than the one for which the last scan request was sent will result in an error.
It is a good practice to send the trajectory request just before the execution of the bin picking routine (when the robot reaches/is on the way to the start pose) in order to have as many candidates for picking to choose from as possible.
The trajectory is then received by procedure Receive trajectory. If successful, the bin picking routine can be executed afterward.
Trajectory request will respond with trajectory as long as there are picked objects with successfully finished path planning (green). However, it is highly dangerous and thus not recommended to send the trajectory request multiple times in a row. It should always be preceded by a scan request because during the execution of the previous trajectory (bin picking routine) the objects in the bin might have moved. That can result, in the best-case scenario, in an unsuccessful pick, or, in the worst case, in a collision.
1.4 Pick-failed request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.2.0
Required parameters
vision system ID
Description
Informs the vision controller about a failed pick. It increments the pick-failed counter of the object for which the last trajectory/object pose was returned. When the object is again the best candidate for picking based on the configured priority settings, it will not be chosen for picking until all objects with successfully planned trajectories and lower pick-failed counters (at the moment the trajectory request is received) have been picked.
For the pick-failed feature to work the pick-failed thresholds must be set up correctly - the object needs to be considered the same (have the same ID) when it moves a little between scans to maintain the pick-failed counter.
It blocks the execution of the robotic program for a negligible amount of time.
Usage
To be able to use this request the robot/cell needs to be equipped with a sensor that is able to recognize that.
When such a situation occurs, the request is sent.
1.5 Change scene state request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.7.0
Required parameters
scene state ID
Description
Requests change of the active scene state.
It blocks the execution of the robotic program until the requested scene state is loaded successfully or an error occurs.
Usage
The request is used when the collision objects in the robotic cell change in such a way it must be reflected in the virtual environment for the collision checking feature to work correctly.
1.6 Get vision system status request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.8.0
Required parameters
vision system ID
Description
Requests the current status of a vision system. Data provided in the response are:
It blocks the execution of the robotic program for a negligible amount of time.
Usage
The request is used whenever there’s a need to get status of a vision system.
Returned data
error code, number of localized objects, number of ready objects, state of the processing
1.7 Trigger scan request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.9.0
Required parameters
vision system ID
TCP (based on usage)
Description
The sensor associated with the requested vision system triggers a new scan.
This request is specific for Hand-eye MultiView approach where it preceeds the usage of the basic Scan request.
Completion of scanning can take up to several seconds and its result is sent when the operation has finished. In order not to block the execution of the robotic program during this time, the response from the vision controller is received in a separate dedicated procedure Wait for scan completion which must be always sent after the Trigger scan request.
Usage
Hand-eye MultiView approach requires the scans of the scene to be acquired from multiple viewpoints. This request is sent in every one of these viewpoints (robot poses). The basic Scan request is used at the end of the scene capturing to create the final virtual scan of the scene and start the localization and path planning pipeline.
1.8 Localize on the last scan request
Required running process
Deployment
Introduced in the Communication interface version
BPS 1.9.0
Required parameters
vision system ID
Description
This is a variant of the basic Scan request. If a scan from the sensor associated with this vision system is available, upon this request, the localization starts reporting found objects, and path planning proceeds with calculating trajectories for them.
The scan to be used did not have to be acquired by the same vision system.
Usage
The request is used the same way as the basic Scan request with the exception that no scanning is actually executed. Instead, the last scan acquired from the associated sensor is used.
2 Locator action requests
2.1 Scan request
Required running process
Deployment
Introduced in the Communication interface version
LS 1.0.0
Required parameters
vision system ID
TCP (only for hand-eye vision system)
Description
The sensor associated with the requested vision system triggers a new scan (full/fast). Immediately after the scan completion, the localization starts reporting found objects, and path planning proceeds with calculating trajectories for them.
For hand-eye vision systems, the request must transfer the TCP to the vision controller. The same TCP and coordinate frame must be used as was during calibration in the Add calibration point request.
Completion of scanning can take up to several seconds and its result is sent when the operation has finished. In order not to block the execution of the robotic program during this time, the response from the vision controller is received in a separate dedicated procedure Wait for scan completion which must be always sent after a scan request.
Usage
Hand-eye vision system
Typically it is sent every time it is required to localize new objects. Apart from the vision system ID, also the TCP must be specified. The robotic arm must be in the scanning position - the sensor must see the scene.
Scan request is immediately followed by the procedure Wait for scan completion in order to block the execution of the robotic program until the scanning operation has finished (the robot must stay still during scan execution).
Extrinsic vision systems
Typically it is sent every time it is required to localize new objects. The TCP must be omitted.
Scan request is followed by the procedure Wait for scan completion that receives the result of the scanning operation.
2.2 Get objects request
Required running process
Deployment
Introduced in the Communication interface version
LS 1.0.0
Required parameters
vision system ID
number of requested objects
(timeout - set in the solution settings)
Description
Requests an object pose to be sent to the robotic controller (or multiple).
The most suitable object according to the sorting criteria is chosen. If multiple objects are requested, these are also sorted.
In case the timeout is set to some positive value and multiple objects were requested, the objects are chosen at the time the response is sent to the robotic controller.
If no suitable object is found, an error is sent to the robotic controller.
If the timeout is set to 0, it blocks the execution of the robotic program for a negligible amount of time (returns immediately).
If the timeout is set to some positive value, it blocks the execution of the robotic program until the requested number of objects is found or the timeout is reached.
Usage
It is sent when a new object pose is required.
Returned data
error code, object poses, number of returned objects
Error codes
No error (0),
Service error (1),
Communication error (3),
Bad data (4),
Timeout (5),
Vision system not found (500),
Empty scene (501),
No object found, Detection running (502),
No object found, Detection stopped (503),
All objects rejected, Detection running (504),
All objects rejected, Detection stopped (505)
2.3 Get vision system status request
Required running process
Deployment
Introduced in the Communication interface version
LS 1.1.0
Required parameters
vision system ID
Description
Requests the current status of a vision system. Data provided in the response are:
It blocks the execution of the robotic program for a negligible amount of time.
Usage
The request is used whenever there’s a need to get status of a vision system.
Returned data
error code, number of localized objects, number of ready objects, state of the processing
2.4 Trigger scan request
Required running process
Deployment
Introduced in the Communication interface version
LS 1.2.0
Required parameters
vision system ID
TCP (based on usage)
Description
The sensor associated with the requested vision system triggers a new scan.
This request is specific for Hand-eye MultiView approach where it preceeds the usage of the basic Scan request.
Completion of scanning can take up to several seconds and its result is sent when the operation has finished. In order not to block the execution of the robotic program during this time, the response from the vision controller is received in a separate dedicated procedure Wait for scan completion which must be always sent after the Trigger scan request.
Usage
Hand-eye MultiView approach requires the scans of the scene to be acquired from multiple viewpoints. This request is sent in every one of these viewpoints (robot poses). The basic Scan request is used at the end of the scene capturing to create the final virtual scan of the scene and start the localization and path planning pipeline.
2.5 Localize on the last scan request
Required running process
Deployment
Introduced in the Communication interface version
LS 1.2.0
Required parameters
vision system ID
Description
This is a variant of the basic Scan request. If a scan from the sensor associated with this vision system is available, upon this request, the localization starts reporting found objects, and path planning proceeds with calculating trajectories for them.
The scan to be used did not have to be acquired by the same vision system.
Usage
The request is used the same way as the basic Scan request with the exception that no scanning is actually executed. Instead, the last scan acquired from the associated sensor is used.
3 Calibration action requests
3.1 Add calibration point request
Required running process
Calibration
Introduced in the Communication interface version
BPS 1.6.0
LS 1.0.0
Required parameters
- - - (BPS)
TCP (LS)
Description
The sensor associated with the requested vision system triggers a scan. Based on the calibration type (extrinsic/hand-eye) the calibration tool (ball/pattern) is localized and a new calibration point is added.
Locator Studio The request transfers the TCP to the vision controller. In the scan request, the same TCP and coordinate frame as during the calibration must be used.
It blocks the execution of the robotic program until the calibration point is added successfully or an error occurs.
Usage
The request is sent when the robot reaches a calibration pose. The robot must be completely still in order to achieve optimal scan quality.
3.2 Start automatic calibration request
Required running process
Calibration
Introduced in the Communication interface version
BPS 1.8.0
LS 1.1.0
Required parameters
solution ID
vision system ID
Description
Requests starting of the automatic calibration procedure for the given solution and its vision system.
It blocks the execution of the robotic program until the calibration process is started successfully or an error occurs.
Usage
The request is sent when there is a need to recalibrate a vision system. The automatic calibration must be enabled for that vision system and no other process can be running at the time in order for the request to be successful.
3.3 Save automatic calibration result request
Required running process
Calibration
Introduced in the Communication interface version
BPS 1.8.0
LS 1.1.0
Required parameters
- - -
Description
Requests saving of the result of the automatic calibration procedure.
It blocks the execution of the robotic program for a negligible amount of time.
Usage
The request is sent after all calibration points have been added successfully to save the result of the automatic calibration procedure.
Returned data
error code, calibration accuracy, calibration matrix (as a cartesian pose)
3.4 Stop automatic calibration request
Required running process
Calibration
Introduced in the Communication interface version
BPS 1.8.0
LS 1.1.0
Required parameters
- - -
Description
Requests stopping of the automatic calibration procedure.
It blocks the execution of the robotic program until the calibration process is stoppped successfully or an error occurs.
Usage
The request is sent to stop the automatic calibration procedure.
4 Solution action requests
4.1 Change solution request
Required running process
—
Introduced in the Communication interface version
BPS 1.3.0
LS 1.0.0
Required parameters
solution ID
Description
Requests termination of currently deployed solution and deployment of the solution with the provided ID.
A solution must be already running in deployment for the request to be successful. Other than that, the requested solution must be ready for deployment (flag Ready) and the brand of the robot must match the brand of the robot that had sent the request.
It blocks the execution of the robotic program until the deployment of the requested solution is finished, an error occurs, or the timeout (180 seconds) is reached.
Warning: Always make sure the requested solution has the correct robot model selected!
Usage
The request is used during the deployment of a solution when there’s a need to change the deployed solution for another one.
4.2 Start solution request
Required running process
—
Introduced in the Communication interface version
BPS 1.6.0
LS 1.0.0
Required parameters
solution ID
Description
Requests deployment of the solution with the provided ID.
No solution can be running in deployment for the request to be successful, the requested solution must be ready for deployment (flag Ready) and the brand of the robot must match the brand of the robot that sent the request.
It blocks the execution of the robotic program until the deployment of the requested solution is finished, an error occurs, or the timeout (180 seconds) is reached.
Warning: Always make sure the requested solution has the correct robot model selected!
Usage
The request is used when a solution needs to be deployed and there is no other solution currently running in deployment.
Error codes
No error (0),
Service error (1),
Communication error (3),
Bad data (4),
Timeout (5),
Bin picking in simulation mode (8),
Invalid solution ID (450),
Another solution running (451),
Deployment not started (452),
Solution is not complete (455),
Invalid robot brand (457),
Solution already running (458),
Solution access unauthorized (459)
4.3 Stop solution request
Required running process
—
Introduced in the Communication interface version
BPS 1.6.0
LS 1.0.0
Description
Requests termination of the currently deployed solution.
It blocks the execution of the robotic program until the deployment is terminated. In case of an error, it blocks for a negligible amount of time.
Usage
The request is used when a solution is currently running in deployment and it needs to be terminated.
4.4 Get running solution request
Required running process
—
Introduced in the Communication interface version
BPS 1.6.0
LS 1.0.0
Description
Requests the ID of the currently running solution to be sent to the robotic controller.
A solution must be running in deployment for the request to be successful.
It blocks the execution of the robotic program for a negligible amount of time.
Usage
The request is used when there’s a solution running in deployment and it needs to be identified.
Returned data
error code, solution ID
4.5 Get available solutions request
Note:
This action request is not supported in the robot modules for the Locator Studio
This action request is deprecated in the robot modules for the Bin Picking Studio based on the Communication interface version 1.8.0 and will be removed in the next version of the Communication interface** **
Required running process
—
Introduced in the Communication interface version
BPS 1.6.0
Description
Requests the list of IDs of available solutions to be sent to the robotic controller.
For a solution to be considered available it must be ready for deployment (flag Ready). The brand of robot selected in a solution does not need to match the brand of the robot that had sent the request.
It blocks the execution of the robotic program for a negligible amount of time.
Usage
The request is used when there is a need to obtain the list of all available solutions.
Returned data
error code, solution ID list
5 Response receiving procedures
5.1 Wait for scan completion
Corresponding asynchronous request
Required running process
Deployment
Description
Receives a response from the vision controller which contains the result of the scanning operation. The response is sent from a vision controller after the scanning operation has finished.
It must always be executed after the scan request.
It blocks the execution of the robotic program until the scanning operation has finished and the response is received.
Usage
Hand-eye vision system
The procedure is executed immediately after the scan request in order to block the execution of the robotic program until the scanning operation has finished (the robot must stay still during scan execution).
Extrinsic vision systems
The procedure is usually executed when (or before) the robot is ready to move back into the scanning volume to ensure the scanning has already finished or before another request needs to be sent. This way of usage in robotic programs minimizes the time of the blocking of the execution of the robotic program by scanning operation (usually there’s no blocking).
5.2 Receive trajectory
Corresponding asynchronous request
Required running process
Deployment
Description
Receives a response from the vision controller which contains the bin picking trajectory and other related data in case of success, error code in case of a failure.
It must always be executed after the trajectory request (not immediately, but before any other request is sent). In case of failure, the procedure for execution of the bin picking routine will also fail.
It blocks the execution of the robotic program until the response is received. Successful response (bin picking trajectory with other data) is sent from the vision controller as soon as the first object has a successfully computed trajectory. When there are multiple objects with successfully computed trajectories at the time the trajectory request is received, then the most suitable one is chosen based on the configured priority settings.
In case of an error, the response is sent from the vision controller:
Immediately
when there is no point cloud (usually when bounding box is used) -> error No object found
when the empty scene feature is enabled and the scene is evaluated as empty -> error Empty scene
when localization had already finished and no object was found -> error No object found
when localization had already finished and path planning for all objects has already finished unsuccessfully -> error Path planning failed
When localization timeout is reached
if it is reached before the trajectory request timeout and no object was found -> error No object found
if it is reached before the trajectory request timeout and path planning for all found objects has finished unsuccessfully before the localization timeout is reached -> error Path planning failed
When path planning for all objects has finished unsuccessfully
When the trajectory request timeout is reached (preceded with the warning “Choosing object to pick timeout” in the Deployment console)
and localization is still running but no object was found yet -> error No object found
and path planning is still running but no object has successfully computed trajectory yet -> error Path planning failed
Usage
Typically it is executed just before the execution of the bin picking routine (during the robot’s motion to the start pose or in it) immediately or shortly after sending the trajectory request.
Returned data
error code, bin picking trajectory, gripper commands, tool point invariance, gripping point ID, gripping point invariance