KUKA example user frame program

This article describes the KUKA user frame program commonly used in surface treatment and dispensing applications. More information about the logic of this program can be found in the robot-independent part location program.

Note

This program requires that Pickit is installed and set up with your robot. For installation instructions, please refer to the KUKA installation and setup article.

User frames in KUKA

In KUKA, a user frame can be defined using the BASE coordinate system.

The BASE coordinate system is a Cartesian system that represents the position of a known workpiece. It is always defined relative to the WORLD coordinate system, and by default BASE[0] is identical to the WORLD coordinate system.

In the KUKA controller, the user can define up to 32 different BASE coordinate systems, from BASE[1] to BASE[32]. Changing the user frame allows to translate the entire robot trajectory without the need to apply the translation to each point separately. This is particularly useful in surface treatment and dispensing applications, where the robot’s trajectory is based on the location of a user frame.

In this example program, the user frame is defined based on a pick point sent from Pickit (updated based on a detection).

Attention

The examples contained in the Pickit application files contain hard-coded robot poses that should be adapted to every new robot. For the user frame programs, you must reteach the XDetect, XTeachP1, XTeachP2, … poses. Also choose the correct #TOOL and #BASE, and fill in the correct setup and product IDs in Pickit_configure(). When executing such programs for the first time, please do so in manual mode and at low speed to check for potential collisions.

Teaching

The program PickitGuidanceTeaching.src is shown below. This program follows the generic trajectory teaching logic.

  • Before running this program, touch-up the desired trajectory points TeachP1, TeachP2, TeachP3 on the workpiece. Make sure the workpiece does not move until you run this program once.

  • Start the program.

  • Check if Pickit is in Robot mode.

  • If so, the robot moves to the detect pose and a detection is triggered.

  • If an object is found, BASE_DATA[32] is updated based on the object pose. Then the robot will move to the poses previously taught TeachP1, TeachP2, TeachP3 and will save them w.r.t the user frame BASE_DATA[32]. The saved poses are called F_Point1, F_Point2, F_point3.

  • End of the program.

This program can be found in R1 > Program > Pickit > PickitGuidanceTeaching.

DEF PickitGuidanceTeaching( )

;FOLD INI;%{PE}
;FOLD BASISTECH INI
    GLOBAL INTERRUPT DECL 3 WHEN $STOPMESS==TRUE DO IR_STOPM ( )
    INTERRUPT ON 3
    BAS (#INITMOV,0 )
;ENDFOLD (BASISTECH INI)
;FOLD USER INI
    ;Make your modifications here
;ENDFOLD (USER INI)
;ENDFOLD (INI)

;Copyright (c) 2026, Pick-it NV
;Provided as an example program. You may copy and modify this file
;for use with Pickit products.

;***********************************************************************
; Before running this program, touch-up the desired trajectory
; points TeachP1, TeachP2, TeachP3 on the workpiece.
; Make sure the workpiece does not move until you run this program once.
;***********************************************************************

;Set the tool, make sure the TCP is defined correctly
BAS(#TOOL,1)
BAS(#BASE,0)

PTP XHOME

IF NOT Pickit_is_running() THEN
    IF Pickit_comm_is_ok() THEN
        PickitMessages(#info, 1)
    ENDIF
    HALT
ENDIF

;Fill in correct setup and product id
Pickit_configure(18,14)

;Go to the detect position

PTP XDetect

;Wait until the robot reaches the position
WAIT SEC 0.0

;Trigger the detection (up to 5 detection attempts in total)
Pickit_detect_with_retr(5)
WAIT FOR Pickit_get_results()

IF Pickit_object_found() THEN
F_ObjectDetected=Pickit_get_pose()

;Save the detection result as the Base n32, we will use it to teach the trajectory.
BASE_DATA[32]=F_ObjectDetected
$BASE=BASE_DATA[32]
BAS(#BASE,32)

;*********************************************************************************
; Move to every point of the trajectory
; Then save the points as frames: F_Point1, F_Point2, F_point3
; To add more trajectory points, define more frames in the corresponding .DAT file
;*********************************************************************************

PTP XTeachP1

WAIT SEC 0.0

$BASE=BASE_DATA[32]
F_Point1.X      = $POS_ACT.X
F_Point1.Y      = $POS_ACT.Y
F_Point1.Z      = $POS_ACT.Z
F_Point1.A      = $POS_ACT.A
F_Point1.B      = $POS_ACT.B
F_Point1.C      = $POS_ACT.C


PTP XTeachP2

WAIT SEC 0.0

$BASE=BASE_DATA[32]
F_Point2.X      = $POS_ACT.X
F_Point2.Y      = $POS_ACT.Y
F_Point2.Z      = $POS_ACT.Z
F_Point2.A      = $POS_ACT.A
F_Point2.B      = $POS_ACT.B
F_Point2.C      = $POS_ACT.C

PTP XTeachP3

WAIT SEC 0.0

$BASE=BASE_DATA[32]
F_Point3.X      = $POS_ACT.X
F_Point3.Y      = $POS_ACT.Y
F_Point3.Z      = $POS_ACT.Z
F_Point3.A      = $POS_ACT.A
F_Point3.B      = $POS_ACT.B
F_Point3.C      = $POS_ACT.C

MsgNotify("Teaching of trajectory points successful")
HALT


ELSE ;No object found, or the exchange failed: stop
    IF Pickit_comm_is_ok() THEN
        IF Pickit_roi_empty() THEN
            PickitMessages(#info, 3)
        ELSE
            PickitMessages(#info, 4)
        ENDIF
    ENDIF
    HALT

ENDIF


END

See KUKA Pickit interface for more information about the Pickit macros available.

Execution

The program PickitGuidanceExecution.src is shown below. This program follows the generic trajectory execution logic.

  • First check if Pickit is in Robot mode.

  • If so, the robot moves to its detect pose and a detection is triggered.

  • If an object is found, BASE_DATA[30] is updated based on the new object pose.

  • The robot follows the trajectory and goes back to the second step.

  • If the ROI is empty or no object is found, the program stops.

This program can be found in R1 > Program > Pickit > PickitGuidanceExecution.

DEF PickitGuidanceExecution( )

;FOLD INI;%{PE}
;FOLD BASISTECH INI
    GLOBAL INTERRUPT DECL 3 WHEN $STOPMESS==TRUE DO IR_STOPM ( )
    INTERRUPT ON 3
    BAS (#INITMOV,0 )
;ENDFOLD (BASISTECH INI)

;FOLD USER INI
    ;Make your modifications here
;ENDFOLD (USER INI)

;ENDFOLD (INI)

;Copyright (c) 2026, Pick-it NV
;Provided as an example program. You may copy and modify this file
;for use with Pickit products.

PTP XHOME

IF NOT Pickit_is_running() THEN
    IF Pickit_comm_is_ok() THEN
        PickitMessages(#info, 1)
    ENDIF
    HALT
ENDIF

;Fill in correct setup and product id
Pickit_configure(18,14)

;Set the tool, make sure the TCP is defined correctly
BAS(#TOOL,1)
BAS(#BASE,0)

;Go to the detect position

PTP XDetect

;Wait until the robot reaches the position
WAIT SEC 0.0

;Trigger the first detection
Pickit_detect_with_retr(5)
WAIT FOR Pickit_get_results()

LOOP
IF Pickit_object_found() THEN

    ;Change the base frame based on the new position of the workpiece
    F_ObjectDetected=Pickit_get_pose()
    BASE_DATA[30]=F_ObjectDetected
    BAS(#BASE,30)

    ;Conservative LIN motion parameters for following the trajectory
    BAS(#VEL_CP,0.5)
    BAS(#ACC_CP,1.0)

    ;Follow the trajectory taught in the PickitGuidanceTeaching routine
    ;They are declared as global in the PickitGuidanceTeaching.dat file
    LIN F_Point1
    LIN F_Point2
    LIN F_Point3

    ;Set again to the world base frame
    BAS(#BASE,0)

ENDIF

PTP XDetect
WAIT SEC 0.0

Pickit_detect_with_retr(5)
WAIT FOR Pickit_get_results()

IF NOT Pickit_object_found() THEN
    IF NOT Pickit_comm_is_ok() THEN
        ;Communication failed. Program is HALTED and a message is
        ;automatically shown naming the root cause (message cases 23-32)
        EXIT
    ENDIF
    IF Pickit_roi_empty() THEN
        PickitMessages(#info, 3)
        EXIT
    ELSE
        PickitMessages(#info, 4)
        EXIT
    ENDIF
ENDIF

ENDLOOP
END

Note

These two programs use three trajectory poses as an example, but more poses can be added if needed. If a trajectory pose is added, make sure that the teaching and execution programs are modified accordingly.

Note

The listings above are a simplified rendition of the shipped programs: the KUKA inline form folds around the motion instructions are collapsed into a single PTP line each. Always start from the programs shipped with your Pickit installation files and adapt them to your application.

See KUKA Pickit interface for more information about the Pickit macros available.

Set correct input arguments

The commands Pickit_configure and Pickit_detect_with_retr need input arguments. See Pickit communication functions for more information about these arguments.

Define the user frame

Make sure that User Frames BASE_DATA[30] and BASE_DATA[32] can be used before running the example program. Note that teaching the user frames is not necessary since they will take the value of the object pose when running the programs.

Define fixed points

In this program, 2 fixed points are used. These points need to be defined depending on the application.

  • HOME: Where the robot will start the program.

  • Detect: Where to perform object detection from.

There are also 3 poses to be defined relative to the workpiece: TeachP1, TeachP2 and TeachP3. These 3 poses then are used as F_Point1, F_Point2 and F_Point3 in the execution program.

Trajectory motion parameters

The trajectory is followed with conservative Cartesian velocity and acceleration, set in the execution program with BAS(#VEL_CP,0.5) and BAS(#ACC_CP,1.0). Note that #VEL_CP is expressed in m/s and #ACC_CP in m/s². In surface treatment and dispensing applications these are process parameters, so adapt both to your application.

Collision recovery

The two programs above do not implement collision detection or recovery. If you wish to add these, refer to the Collision recovery section in the bin picking example.

Execute the user frame program

Attention

Before running the robot program for the first time, make sure that:

  • There exists a valid robot-camera calibration.

  • The Tool Center Point (TCP) has been correctly specified.

  • The robot speed is set to a low value, so unexpected behavior can be identified early enough to prevent the robot from colliding with people or the environment.

  • Pickit is in robot mode, which is enabled in the Pickit web interface.

Now you can run the program.