KUKA Pickit interface

This article documents the interface of the KUKA Pickit integration. For installation instructions, please refer to the KUKA installation and setup article.

Attention

If you are looking for the API functions of the old integration based on the KUKA Connect KRC module, go to the 4.0 documentation.

Pickit communication functions

Below you find an overview of the API-functions defined by Pickit that are responsible for communication between the KUKA robot controller and a Pickit system. You can call these functions from your KRL robot program (.src files), for example to trigger a detection, get the results, or check the communication status. This API, specific to the KUKA KR C4-5 integration, is based on the generic Pickit interface.

All of the functions wait for the Pickit reply before returning, except Pickit_look_for_object(), Pickit_process_image(), Pickit_next_object() and Pickit_detect_with_retr(), which return immediately and whose results are collected with Pickit_get_results(). These non-blocking functions are useful for improving cycle time by running the detection in masked time.

A function that returns a value has to be used in an expression, such as IF Pickit_is_running() THEN or WAIT FOR Pickit_get_results(). The functions documented as returning (none) are called as a bare statement.

Note

When a Pickit function fails unexpectedly, a descriptive message is shown on the smartPAD and the program stops at a HALT. Pressing Start resumes the program after the failed call. To handle such a failure from the robot program instead, see Communication status functions.

System functions

Pickit_is_running()

Check if Pickit is set to Robot mode.

Returns

(BOOL) – True if Pickit is in Robot mode.

Pickit_set_robot_mode()

Request Pickit to enable Robot mode, which only works as long as there are no unsaved changes in Pickit. If there are, save or discard them in the Pickit web interface first, or from the robot program with Pickit_save_setup() and Pickit_save_product().

The same restriction applies to the pop-up that appears when a detection is triggered while Pickit is in Idle mode: accepting it enables Robot mode only when Pickit has no unsaved changes.

Returns

(BOOL) – True if Pickit switched to Robot mode.

Pickit_shutdown()

Cleanly shut down the Pickit processor. This cannot be undone from the robot program: Pickit needs to be physically powered on again.

Returns

(none)

Detection functions

Note

Object poses communicated by Pickit have their Z-axis pointing upwards, this is automatically flipped 180 degrees by the integration to match the default downwards Z-axis of the KUKA flange/TCP.

If you have a custom flange/TCP, make sure the Z-axis is pointing downwards as well. Alternatively, if you have the Z-axis pointing upwards, you must undo the 180 degree flip by changing one line in the KUKA integration source code:

In R1\TP\Pickit\pickit_protocol.dat, change C 180 to C 0 in the following line:

GLOBAL FRAME pickit_x_rot={X 0,Y 0,Z 0,A 0,B 0,C 180}

There are two ways to trigger a detection:

In both cases, the results are collected afterwards with Pickit_get_results(). For example:

Pickit_look_for_object()
WAIT FOR Pickit_get_results()
IF Pickit_object_found() THEN
   F_Pick = Pickit_get_pose()
ENDIF

Pickit_get_results() combines Pickit_has_response() and Pickit_gppd(), which can also be called separately.

See the KUKA simple pick and place example for a complete pick-and-place program using Pickit.

Pickit_capture_image()

Trigger Pickit to capture a camera image. Follow up with Pickit_process_image() to trigger object detection. This command blocks the robot movements. This function is suitable if the camera is robot-mounted.

Returns

(none)

Pickit_process_image()

Trigger an object detection on the image that was captured via Pickit_capture_image(). This command is non-blocking. The robot can move while Pickit is processing the image. This function is suitable if the camera is robot-mounted. Collect the results with Pickit_get_results() (or Pickit_has_response()) before issuing any other Pickit command.

Returns

(none)

Pickit_look_for_object()

Trigger a Pickit object detection using the currently active setup and product Configuration. This single request combines Pickit_capture_image() and Pickit_process_image(). This command is non-blocking. The robot can move while Pickit is detecting objects, including during the image capture, which is why this function is suitable if the camera is fixed. Collect the results with Pickit_get_results() (or Pickit_has_response()) before issuing any other Pickit command.

Returns

(none)

Pickit_next_object()

Request the next detected object if multiple objects were found. Collect the results with Pickit_get_results() (or Pickit_has_response()) before issuing any other Pickit command.

Returns

(none)

Pickit_detect_with_retr(LZ_Retries)

Repeatedly trigger a Pickit object capture and detection (similar to Pickit_look_for_object()) as long as nothing is found and the ROI is not empty, up to a maximum number of detections. Collect the results with Pickit_get_results() (or Pickit_has_response()) before issuing any other Pickit command.

Parameters

LZ_Retries (INT) – Maximum total number of detections.

Returns

(none)

Pickit_get_results()

Combination of Pickit_has_response() and, when an object was found, Pickit_gppd(). This is the most compact and therefore recommended way of collecting the detection results: it updates all output values, so no follow-up call is needed.

Returns

(BOOL) – True once Pickit has replied, or the request definitively failed. All Pickit output values are updated in the background.

Pickit_has_response()

Returns true and updates results, if the Pickit detection is finished. Usually used inside a Wait command. It should always be the next Pickit function after a Pickit_look_for_object(), Pickit_next_object(), Pickit_detect_with_retr() or Pickit_process_image() request. Follow it with Pickit_gppd() to also get the pick point ID and offset.

Returns

(BOOL) – True once Pickit has replied, or the request definitively failed. All Pickit output values are updated in the background, except the pick point IDs and offset.

Pickit_gppd()

Get pick point data: request the pick point ID and pick point offset of the last requested object. This updates Pickit_object_pick_id(), Pickit_object_ref_id() and Pickit_get_offset(). It is not needed after Pickit_get_results(), which already performs this request.

Returns

(none)

Configuration functions

Pickit_configure(LZ_Setup, LZ_Product)

Load the specified setup and product Configuration on Pickit.

Parameters

  • LZ_Setup (INT) – ID of the desired setup configuration.

  • LZ_Product (INT) – ID of the desired product configuration.

Returns

(none)

Pickit_set_cylinder(LZ_Length, LZ_Diameter)

Set the dimensions of a Teach cylinder model. This leaves the product file with unsaved changes, which can be stored by calling Pickit_save_product(). Note that while there are unsaved changes, Pickit_set_robot_mode() cannot enable Robot mode.

Parameters

  • LZ_Length (INT) – Cylinder length [mm].

  • LZ_Diameter (INT) – Cylinder diameter [mm].

Returns

(none)

Pickit_save_setup()

Save the currently active setup file.

Returns

(none)

Pickit_save_product()

Save the currently active product file.

Returns

(none)

Pickit_build_bkg_cloud()

Build the background cloud used by one of the Advanced filters.

Returns

(none)

Calibration functions

Pickit_configure_calib(LZ_Method, LZ_Mount, LZ_Tf)

Configure the next robot-camera calibration. Learn more about the arguments here.

Unlike the other Pickit functions, this one does not queue behind a request that is still running. If one is, nothing is sent to Pickit, the smartPAD shows Pickit: busy with another command. Collect the pending result first, and Pickit_get_comm_error() returns -18: PICKIT_COMM_BUSY. Collect the pending result with Pickit_get_results() before calling this function.

Parameters

  • LZ_Method (INT) –

    Calibration method:

    • Single pose: PICKIT_CALIB_SINGLE_POSE or 0

    • Multi pose: PICKIT_CALIB_MULTI_POSE or 1

    • Manual: PICKIT_CALIB_MANUAL or 2

    • Default: PICKIT_CALIB_DEFAULT or 3 to use the settings from the web interface and ignore the other two arguments.

  • LZ_Mount (INT) –

    Camera mount:

    • PICKIT_CAM_FIXED or 0

    • PICKIT_CAM_ON_ROBOT or 1

  • LZ_Tf (FRAME) –

    Depends on LZ_Method:

    • For PICKIT_CALIB_SINGLE_POSE (0), the helper transformation.

    • For PICKIT_CALIB_MANUAL (2), the full calibration transform. The pose must be expressed in robot base frame for fixed camera, robot flange frame for robot-mounted camera.

    • Unused by the other methods, ignore or pass a zero frame.

Returns

(none)

Pickit_do_calibration()

Trigger a detection of the robot-camera calibration plate. This locates the plate, it does not compute the calibration.

Returns

(none)

Pickit_compute_calib()

Compute the robot-camera calibration from the collected calibration plate detections. On success, the Calibration results are updated.

Returns

(none)

Pickit_validate_calib(LZ_DistTol, LZ_AngTol)

Validate the current robot-camera calibration. The Calibration results hold the measured errors, also when these are out of tolerance.

Parameters

  • LZ_DistTol (REAL) – Distance tolerance [mm].

  • LZ_AngTol (REAL) – Angle tolerance [deg].

Returns

(BOOL) – True if the measured distance and angle errors are below the specified tolerances. False on communication failure, on a Pickit-reported failure, or on metadata decode failure. In case of False, the three Calibration results will be zeroed, and you can distinguish the failures using Pickit_get_comm_error().

Running a calibration from a robot program

For example, a calibration consists of the following sequence for a multi-pose calibration with a fixed camera:

Pickit_configure_calib(PICKIT_CALIB_MULTI_POSE, PICKIT_CAM_FIXED)
Pickit_do_calibration()   ; x10, once for each calibration pose
Pickit_compute_calib()

How many times Pickit_do_calibration() is called depends on the calibration method: not at all for manual, once for single pose, multiple times for multi pose. For manual, Pickit_compute_calib() is not called either.

The KUKA calibration program example implements exactly this sequence: it configures a multi-pose calibration for a fixed camera, calls Pickit_do_calibration() at ten taught poses, and computes the result.

Note

Two configurations are rejected by Pickit:

  • PICKIT_CALIB_SINGLE_POSE together with PICKIT_CAM_ON_ROBOT.

  • A 4 DOF robot that has not been calibrated once through the calibration wizard of the web interface.

Monitoring functions

Pickit_save_scene()

Save a snapshot in the robot snapshot folder with the latest detection results.

Returns

(none)

Pickit_save_scene_sub(LZ_Sub)

Save a snapshot in a subfolder of the robot snapshot folder.

Parameters

LZ_Sub (INT) – Number of the subfolder (1 to 255). Other values save the snapshot directly in the robot folder, like Pickit_save_scene().

Returns

(none)

Pickit helper functions

The following functions don’t communicate with Pickit, but use the results of previous commands. They can be used to make your robot program more readable. The return values of these functions get updated after using the Pickit functions Pickit_has_response() or Pickit_get_results(). See KUKA simple pick and place on how they are typically implemented in a robot program.

Pickit_object_found()
Returns

(BOOL) – True if a valid object was detected.

Pickit_roi_empty()
Returns

(BOOL) – True if the ROI is empty.

Pickit_no_image_captured()

Check if no image was captured by Pickit. If so, check the camera connection.

Returns

(BOOL) – True if no image was captured.

Pickit_license_invalid()

Check if the detection could not run because a Pickit license module is missing or expired. This is reported as a message on the smartPAD, but does not stop the program, so that it can act on it.

Returns

(BOOL) – True if a required license is missing or expired.

Pickit output functions

Detection results

The following functions are used to get the output values of detections (they do not communicate with Pickit directly). The output values are updated after using the Pickit functions Pickit_has_response() or Pickit_get_results().

Pickit_get_pose()
Returns

(FRAME) – Pick point expressed with respect to the robot base frame.

Pickit_object_pick_id()
Returns

(INT) – ID of the pick point that was selected for the previously sent object.

Pickit_object_ref_id()
Returns

(INT) – ID of the selected pick point’s reference pick point.

Pickit_get_offset()
Returns

(FRAME) – Pick point offset of the last requested object.

Pickit_object_type()

  • For a Teach detection, ID type of the detected object.

  • For a Flex/Pattern detection, the object type of the detected object. These are declared in `pickit_functions.dat` and also listed here

  • In a Bags detection, a value holding information about the bag pattern and the detected layer orientation.

Returns

(INT) – Object type

Pickit_object_model_id()

Alternative name for Pickit_object_type(), returns the same value. Used for Teach detection to avoid confusion.

Returns

(INT) – Model ID.

Pickit_object_dim_1()
Returns

(REAL) – Object dimension 1: length or diameter [mm].

Pickit_object_dim_2()
Returns

(REAL) – Object dimension 2: width or diameter [mm].

Pickit_object_dim_3()
Returns

(REAL) – Object dimension 3: height or diameter [mm].

Pickit_object_age()
Returns

(REAL) – Amount of time that has passed between the capturing of the camera image and the moment the object information is sent to the robot [s].

Pickit_remaining_objects()
Returns

(INT) – Number of remaining objects that can be sent to the robot using Pickit_next_object().

More detailed information about these outputs can be found here.

Calibration results

The following functions are used to get the results of a robot-camera calibration. Both Pickit_compute_calib() and Pickit_validate_calib() update them, with a different meaning, so read them right after the call.

Pickit_get_calib_pose()
Returns

(FRAME) – After Pickit_compute_calib(), the computed calibration transform (robot_T_camera). After Pickit_validate_calib(), the calibration error.

Pickit_calib_err_dist()
Returns

(REAL) – Distance calibration error [mm].

Pickit_calib_err_angle()
Returns

(REAL) – Angle calibration error [deg].

More detailed information about these outputs can be found here.

Using pick offset in a robot program

When using multiple pick points or flexible pick orientations, it can be useful to adjust the drop-off point with the pick offset (Pickit_get_offset()) to get a consistent drop-off position regardless of the pick point used. See also Smart placing examples.

The following lines of code show how to correct the fixed drop-off point XDrop with the pick offset in a KUKA robot program:

drop_offset = Pickit_get_offset()
XDrop_corrected = XDrop:drop_offset
PTP XDrop_corrected

Communication status functions

The following functions don’t communicate with Pickit either. They report the state of the communication, to allow a robot program to process a failure, instead of stopping at a HALT, as mentioned in the note at the beginning of this page.

Pickit_is_connected()

Check if the connection with Pickit is up. This says nothing about whether Pickit is making progress on a request.

Returns

(BOOL) – True if the connection is up.

Pickit_get_comm_error()

Get the outcome of the last Pickit function call that communicated with Pickit, as one of the following constants:

  • 0: PICKIT_COMM_OK: the call completed.

  • -10: PICKIT_COMM_TIMEOUT: Pickit did not reply in time.

  • -11: PICKIT_COMM_DESYNC: the Pickit reply could not be matched to the request (byte stream is desynced), and the connection is reestablished.

  • -12: PICKIT_COMM_NO_CONN: the connection was not up when the call was made.

  • -13: PICKIT_COMM_METADATA: Echoed convention/protocol metadata did not match.

  • -14: PICKIT_COMM_SEND_FAIL: the request could not be sent.

  • -15: PICKIT_COMM_NO_ENGINE: PickitSps() is not running, check the SPS file settings.

  • -16: PICKIT_COMM_IDLE: Pickit is not in Robot mode.

  • -17: PICKIT_COMM_PICK_INVAL: the pick point data is no longer valid, run a new detection.

  • -18: PICKIT_COMM_BUSY: another Pickit request was still running, collect its result first. Only Pickit_configure_calib() reports this.

Returns

(INT) – Communication status of the last call.

Pickit_comm_is_ok()
Returns

(BOOL) – True if Pickit_get_comm_error() returns 0: PICKIT_COMM_OK.

Pickit_get_robot_mode()

Get the Pickit mode reported by the last Pickit_is_running() call, without sending a new request.

Returns

(INT) – 0 for Robot mode, 1 for Idle mode, or -1 after any (re)connection or if Pickit_is_running() has not been called yet.

Pickit_pick_data_valid()

Check if the pick point ID and offset come from the current detection on the current connection. Call this before moving the robot to a pick point.

Returns

(BOOL) – True if the pick point data is valid.

Checking the outcome of a function call

Most communication functions return nothing, and report a failure as a message on the smartPAD followed by a HALT. For some of the blocking functions, you might wish to branch on the faulty outcome instead of stopping the program (for example for Pickit_compute_calib(), Pickit_validate_calib(), Pickit_configure_calib(), Pickit_do_calibration(), Pickit_configure(), or Pickit_capture_image()).

For example, if you don’t want the program to stop when Pickit_capture_image() fails, you can use the following code snippet:

Pickit_capture_image()
IF Pickit_comm_is_ok() AND (CON_PI_P2R_DATA.Status == PICKIT_IMAGE_CAPTURED) THEN
  Pickit_process_image()
ELSE
  ; handle the failure
ENDIF

Pickit_comm_is_ok() checks whether the communication was successful; checking the Pickit status tells you the outcome of the function call (success or failure). Substitute the relevant status of the function that was called. The available statuses are declared in the pickit_protocol.dat interface file, and are documented here.