Saturday, January 10, 2015

Robot Programming using Kuka | prc

This post provides general information on setting up a Grasshopper definition for using Kuka|prc with the Agelis Workcell in the Taubman College Fab Lab.

KUKA|prc is a set of Grasshopper components that provide Procedural Robot Control (thus the name prc) for KUKA robots. These components are very straightforward to use and it's actually quite easy to program the robots using them.


Before we begin discussing KUKA|prc it's important to clarify some terminology that will be used in this topic.

  • Work Cell: All the equipment needed to perform the robotic process (robot, table, fixtures, etc.)
  • Work Envelope: All the space the robot can reach.
  • Degrees of Freedom: The number of movable motions in the robot. To be considered a robot there needs to be a minimum of 4 degrees of freedom. The Kuka Agelis robots have 6 degrees of freedom. 
  • Payload: The amount of weight a robot can handle at full arm extension and moving at full speed.
  • End Effector: The tool that does the work of the robot. Examples: Welding gun, paint gun, gripper, etc.
  • EOAT: End Of Arm Tooling. This is everything bolted to the end of the tool plate. An example is a transformer bolted to the tool plate but not actually the end effector. The transformer only supports the operation of the end effector.
  • Manipulator: The robot arm (everything except the EOAT).
  • TCP: Tool Center Point. This is the point (coordinates) that we program in relation to.
  • Positioning Axes: The first three axes of the robot (1, 2, 3). Base / Shoulder / Elbow = Positioning Axes
  • Orientation Axes: The other joints (4, 5, 6). These joints are always rotary. Pitch / Roll / Yaw = Orientation Axes.

Rhino File Setup

When you work with the robots using KUKA|prc your units in Rhino must be configured for the Metric system using millimeters. The easiest way to do this is to use the pull-down menus and select File > New... then from the dialog presented chose "Small Objects - Millimeters" as your template.

The KUKA|prc User Interface

When installed KUKA|prc has a user interface (UI) much like other Grasshopper plug-ins. The UI consists of the palettes in the KUKA|prc menu.

There are four palettes which organize the components. These are:
  • 01 | Core: The main Core component is here (discussed below). There are also the components for the motion types (linear, spline, etc.). 
  • 02 | Toolpath: Approach and Retract components are here (these determine how the robot should move after a toolpath has completed). There are also components for dividing up curves and surfaces and generating robotic motion based on that division. 
  • 03 | Virtual Robot: The various KUKA robots are here. We'll mostly be using the KUKA 
  • 04 | Virtual Tools: The tools (end effectors) are here. We'll mostly be using the Agelis KR6 R900 component.. 
  • 05 | Utility: The components dealing with input and outputs are stored here. These will be discussed in detail later. 


The component you always use in every definition is called the Core. It is what generates the KUKA Robot Language (KRL) code that runs on the robot. It also provides the graphical simulation of the robot motion inside Rhino. Everything else gets wired into this component.

The Core component takes five inputs. These are:
  • SLIDER - This is a numeric value. Attach a default slider with values from 0.00 to 1.00 to control the simulation. 
  • COMMAND - This is the output of one of the KUKA|prc Command components. For example a Linear motion command could be wired into this socket. 
  • COLLISION - This is an optional Mesh which represents the collision geometry, e.g. the workcell.
  • DEFAULT TOOL - This is the tool (end effector) to use. It gets wired from one of the Tool components available in the Virtual Tools panel. Usually you'll use the KUKA|prc Custom Tool option and wire in a Mesh component will show the tool geometry in the simulation.  
  • ROBOT - This is the robot to use. The code will be generated for this robot and the simulation will graphically depict this robot. You'll wire in one of the robots from the Virtual Robot panel. For the Agelis Workcell you'll use the Agelis KR6 R900 component.  

The right-click context menu for the Core component gives you access to its settings. Choose KUKA|prc Settings from the menu:

The settings are organized in a floating dialog with a hierarchy of options on the left side. You click on an option in the list and settings for it appear on the right side. These settings will be covered in more detail later.

Basic Wiring Setup

There is a common set of components used in nearly all definitions for use with the Agelis Workcell. Not surprisingly, these correspond to the inputs on the Core component. Here is a very typical setup:

  • SLIDER: The simulation Slider goes from 0.00 to 1.00. Dragging it moves the robot through all the motion specified by the Command input. It's often handy to drag the right edge of this slider to make it much wider than the default size. This gives you greater control when you scrub to watch the simulation. You may also want to increase the precision from a single decimal point to several.
  • COMMAND: The components which gets wired into the COMMAND slot of the Core is really the heart of your definition and will obviously depend on what you are intending the robot to do. In the example above a simple Linear Move component is wired in.
  • DEFAULT TOOL: We normally use custom tools with the Agelis Workcell. Therefore a Mesh component gets wired into the KUKA|prc Custom Tool component (labelled TOOL above). This gets wired into the DEFAULT TOOL slot of the Core. The Mesh component points to a mesh representation of the tool drawn in the Rhino file.
  • ROBOT: The robots we have in the Agelis Workcell are KUKA KR6 R900s. So that component is chosen form the Virtual Robots panel. It gets wired into the ROBOT slot of the Core.

Robot Position and Orientation

The workcell has two robots named Mitey and Titey. Depending on which one you are using you'll need to set up some parameters so your simulation functions correctly. These parameters specify the location and orientation of the robot within the workcell 3D model.


Mitey is the name of the robot mounted in the table. Its base is at 0,0,0. The robot is rotated about its vertical axis 180 degrees. That is, the cable connections are on the right side of the robot base as you face the front of the workcell.

To set up Mitey do the following:

Right-click on the Core component, chose Settings from the context menu, then select the Base Settings choice on the left side of the dialog. The dialog is shown below:

You specify the X, Y, and Z offsets in the Base X, Base Y, and Base Z fields of the dialog. Again, for Mitey these should all be 0. In order to rotate the robot around the vertical axis you specify 180 in the Base A field. You can see that the A axis corresponds to vertical in the diagram.
  • Base X: 0
  • Base Y: 0
  • Base Z: 0
  • Base A: 180
  • Base B: 0
  • Base C: 0
After you hit Apply Settings the robot position will be shown in the viewport. You can close the dialog with the [X] in the upper right corner.

The upper robot hanging from the fixture is named Titey. It has a different X, Y and Z offset values and rotations. Use the seeings below when your definition should run on Titey.

Note: These values are all in millimeters.

  • Base X: 1102.51
  • Base Y: 0
  • Base Z: 1125.66
  • Base A: 90
  • Base B: 180
  • Base C: 0

Code Output

The purpose of KUKA|prc is to generates the code which runs on the robot controller. This code is written in the Kuka Robot Language (KRL). You need to tell KUKA|prc what directory and file name to use for its code output. Once you've done this, as you make changes in the UI, the output will be re-written as necessary to keep the code up to date with the Grasshopper definition settings.

To set the output directory and file name follow these steps:

  • Right -click on the Core component. 
  • Choose Settings from the context menu. 
  • Select the Output settings on the left of the dialog. 

  • Check the Save File box. 
  • Click the Set Output Directory button and select a path from the Browse for Folder dialog presented. 
  • Enter the File Name you wish to use in the Project/File Name box. 
  • Press the Apply Settings button and close the dialog. 

That's all you need to do to generate code.

Note: If you check the Automatic File Numbering for Mass Customization check box KUKA|prc will generate a new file every time you change something inside Grasshopper. This can easily generate hundreds or even thousands of files - so be aware of that before you check it!

See the topic Taubman College Agelis Workcell Operating Procedure for details on how to get the code onto the robot and run it.

Start Position / End Position

The program needs to know where to begin before it runs. That is, where and how is the tool positioned before the motion starts. Also, where should the tool move to when the programmed motion completes.

You specify these values in the Settings of the Core. Bring up the settings dialog and choose the Advanced Settings section on the left.

Under the Start and End sections you enter the axis values for A1 through A6. This of course begs the questions "how do I know what values to use?".

You can read these directly from the robot pendant (smartPAD). That is, you jog the robot into the start position and read the values from the pendant. Enter the values into the dialog. Then do the same for the End values.

See the section Jogging the Robot in topic Taubman College Agelis Workcell Operating Procedure.

Motion Types

Note: The information in this section contains material excerpted from the KUKA documentation. 

KUKA|prc provides several motion types. These are:

PTP: Point to Point

You get this motion type by using the KUKA|prc PTP Movement component

The robot guides the TCP along the fastest path to the end point. The fastest path is generally not the shortest path and is thus not a straight line. As the motions of the robot axes are rotational, curved paths can be executed faster than straight paths. The exact path of the motion cannot be predicted.

LIN: Linear

You get this motion type by using the KUKA|prc PTP Movement component. 

The robot guides the TCP at a defined velocity along a straight path to the end point. This path is predictable.

CIRC: Circular

You get this motion type by using the KUKA|prc PTP Movement component. 

The robot guides the TCP at a defined velocity along a circular path to the end point. The circular path is defined by a start point, auxiliary point and end point.

SPLINE: Smooth Spline 

You get this motion type by using the KUKA|prc Spline Movement component. 

The robot will move along the positions in a smooth spline movement.

Using the Movement Components

The three movement components mentioned above all use the same parameters. 

*** In Progress... 

Sunday, December 21, 2014

Taubman College Agelis Workcell Operating Procedure

by Mark Meier

This post is an overview of the procedure for operating the Agelis robotics workcell in the Taubman College Fab Lab.

The Agelis Workcell

This Agelis workcell is used for teaching introductory robotics at Taubman College. It consists of a fixture for holding the robots, a worktable with removable panels, and two industrial robots: Kuka model KR 6 R900 SIXX (KR AGILUS). The robots are named Mitey and Titey. Mitey is mounted below the table. Titey is mounted above the table.

Each robot consists of the following components:
  • Manipulator: The robot arm and the associated electrical hookups. 
  • Robot Controller: The computer hardware located below the table. 
  • SmartPAD: The hand hand device for interacting with the robot. 
  • Connecting Cables: The cables connecting the manipulator to the controller. 
  • Software: The software consists of KUKA System Software and Windows XPe. 


Any discussion of working with the robots begins with safety. Safe operation of the robots relies on several things:
  • Awareness of the environment the robot is moving within: Make sure the path is clear of computers, building materials, and especially people(!) before jogging the robot or running programs. If you are only working with one robot, move the other one well out of the way. The work envelopes overlap so if you are not paying attention it's easy to have them collide. 
  • Simulation of the robot path prior to running programs: It is essential you software simulate the path the robot will move through prior to running the code on the robot itself. 
  • Start your program slowly: When you first run a program make sure to turn the speed of the program way down (say 10% to start with). After you verify that the path is clear of obstruction and there are no collisions with the table, the other robot, or your classmates, you can speed it up. 

Turning the Robots On and Off

Normally the robots are left running. That is the controller stays booted up and running. When you are done using them you can simply put the stylus back in the teach pendant, put the pendant into the holder, and that's it.

If you find a robot has been turned off  simply click the power switch on its controller (there is one for each robot). The robot will boot up in under a minute.

Workcell Coordinate System

The two robots in the workcell use the same coordinate system with the axes directions as shown below. It is important to understand this coordinate system when jogging and when designing programs for the robot:

The X axis is parallel to the front face of the table, with positive X values increasing to the right. 
The Y axis is from front to back, with positive Y values increasing toward the wall. 
The Z axis is vertical, with positive Z values increasing toward the ceiling. 

See the section below for the origin location. 

Units, Origin and a 3D Model for Simulation

When you work with robot toolpath programming software such as Kuka|prc or Super Matter Tools, you should use the Metric system in your Rhino files. Configure your file to use "Small Objects - Millimeters" as your template (choose File > New from the pull-down menus, then select the template). 

(See Common Metric Conversions for access to conversion values between Imperial and Metric). 

There is a 3D model of the workcell you can use inside your projects. If you use Super Matter Tools it can be automatically inserted from the interface. Choose DualKR6R900SIXX_UofM from the Work Cell drop-down. Then click the Import WorkCell Geometry button. 

If you use Kuka|prc then you can get it from my Google Drive and insert it into your model: AgelisWorkcellModel

The origin of the 3D model of the workcell is directly beneath Mitey, at 38.04mm below the top of the aluminum rails of the table surface. ***TODO: This is not correct - and the mesh model is not correct - it needs to be measured at the robot by touching the toolplate to the rails and reading Z ***


You interact with the robot through its teach pendant. Kuka refers to this as its SmartPAD. These are hand held devices with a number of push button keys, knobs and a display.

The display is a touch screen so you can use your fingers. However, the buttons are small and it is usually easier to use the stylus stored in the back of the pendant case.

Below are the main buttons used on the controller. These diagrams and notes are excerpted from the Kuka User Guide.

The most important controls are highlighted in bold below: 
  1. Button for disconnecting the teach pendant. 
  2. Keyswitch for calling the connection manager. The switch can only be turned if the key is inserted.
  3. EMERGENCY STOP button. Stops the robot in hazardous situations. The EMERGENCY STOP button locks itself in place when it is pressed.
  4. Space Mouse: For moving the robot manually.
  5. Jog keys: For moving the robot manually.
  6. Key for setting the program override
  7. Key for setting the jog override
  8. Main menu key: Shows the menu items on the smartHMI
  9. Status keys. The status keys are used primarily for setting parameters in technology packages. Their exact function depends on the technology packages installed.
  10. Start key: The Start key is used to start a program.
  11. Start backwards key: The Start backwards key is used to start a program backwards. The program is executed step by step.
  12. STOP key: The STOP key is used to stop a program that is running.
  13. Keyboard key. Displays the keyboard. It is generally not necessary to press this key to display the keyboard, as the pendant detects when keyboard input is required and displays the keyboard automatically.

Note: These pendants cost about $9,000 each so please be careful in handling them. When done place them back in the storage bracket. And make sure to store the stylus in the case.

Push up on the foam to lift the bottom of the pendant over the lower rail, and twist it into place.

Logging In

Before you can fully operate the robots you'll need to log in. This lets you copy files and execute programs on the robot. To do so follow these steps:

Press the Main Menu key on the bottom right edge of the pendant (it's also available in the upper left corner of the display):

Choose Configuration > User Group.

Press the Log on button at the bottom of the screen:

From the Select a user section choose Expert. Then using the virtual keyboard enter the password which is kuka. Don't tell anyone the password - it is top secret... hardy, har, har. Then press the Enter key as shown.

As long as you continue to use the teach pendant you'll remain logged on. After about 5 minutes of inactivity you'll be logged off automatically. If you find you can't perform certain operations (for example loading programs) you likely need to log back in again.

Online Help

Even though you have access to the magnificent user guide you are now reading you may require more information. You can easily access the documentation for the robot using the following steps:

Press the Main Menu key on the bottom right edge of the pendant:

Choose Help > Documentation > System Software from the touch screen:

Choose the category you'd like to view, for example Operation.

Use the buttons at the bottom of the display to move through the pages. There is a lot of good information contained in the online help. 

Jogging the Robot

Manually moving the robot is referred to as Jogging. There are two ways of jogging the robot:
  • Cartesian Jogging: The Tool Center Point (TCP) is jogged in the positive or negative direction along the axes of a coordinate system.
  • Axis-specific Jogging: Each axis (A1 through A6) can be moved individually in a positive and negative direction.
I find it most convienient to use the jog keys on the right hand side of the pendant (rather than the 3D mouse which is not as intuitive and is not covered in this discussion):

To jog using World Coordinates click the on screen icon just above the axes labels. A pop up menu appears to let you choose mode. Click on the World icon:

The labels change to X, Y, Z, A, B and C.

Press and hold any one of the Enabling Switches located on the back of the pendant (labelled 1, 3 and 5 in the following illustration). The display labels turn green to indicate they are active. Then press the corresponding jog keys on the right side of the pendant to move in either the + or - direction for that axes.

Jogging in this mode will keep the orientation of the tool the same. Only the position will change.

To work in Axes mode select Axes from the pop-up menu. The labels now read A1, A2, A3, A4, A5 and A6. Axis A1 is the base of the manipulator and axis A6 is the wrist. Axes A1, A2 and A3 are referred to as Positioning Axes. Axes A4, A5, and A6 are referred to as Orientation Axes.

Press and hold any one of the Enabling Switches. The labels turn green to indicate they are active. Then press the corresponding jog keys to rotate in either the + or - direction of that joint.

If you are in a tight situation and not sure which way to move (+ or -), refer to the manipulator itself. Each joint is labelled on the arm along with arrows which show you the + and - directions.

Copying Program Files to the Controller

To get your program from your computer to the robot controller you'll need a USB flash drive. Note that USB 1.0 and 2.0 drives are compatible. USB 3.0 drives are not.

Plug your drive into any of the the USB slots on the controller as shown below:

You copy programs from the USB to the controller using the Navigator file manager. If the Navigator is not showing, make sure to cancel the currently running program.

Click on the R at the top of the display and choose Cancel program from the menu.

If necessary press the Main Menu key to clear the main menu from the display. You should now see the Navigator display:

The plugged in USB Disk will be shown at the bottom of the folders list. The robot program files folder is at the top of the list (KRC:\)

Open the USB DISK (E:\) folder, navigate to the file you wish to copy. Note: You need to fully open folders on the left panel of the Navigator. You can't double-click them on the right panel as you can in Windows Explorer.

With the file you wish to copy selected, press the Edit button on the lower right of the display. From the menu presented choose Copy. These items are highlighted below in red.

Navigate to the folder to store your program. Files are stored in a subfolder of robot root:
KRC:\ (this is the one with the orange robot icon at the top of the list)

For my students in ARCH409 and ARCH509 create a folder for your group beneath this folder:

So you'd have:
R1\Program\SRC\409\group name

To Paste the file follow these steps:

Select the destination folder on the left. Click on the right side of the explorer in the file list for that folder. Click the Edit button at the bottom of the screen and choose Paste. 

In the example below the file is being pasted into the meier folder. 

You need to Select the program to make it available to run. 

Select the file on the right side of the Navigator. Press the Select button. The program's KRL code will appear and you can now run it. 

Important Note: Files in the system must be uniquely named. This is not just in one directory as you’d expect. It is across ALL directories. This means two things:
  • When choosing a filename use something to make it unique. For example don’t use something like "Project1". Everyone in the class could name it Project1. Better to use something like your group name followed the project name and number. 
  • When you are finished with a project, delete the files from the controller. Simply select the file in the Explorer and choose Edit > Delete. This will keep it from getting cluttered in the future. 

Controlling the Program Execution

After you've selected the program to run the KRL code will appear in the display.

Set the program playback speed slow at first. You can do this by pressing the + or - keys next to the playback icon. You'll see the current speed at the top of the display:

Hold one of the Enabling Switches and press the Play key on the left of the pendant.

To Pause the running program simply release the Enabling Switch.

To Resume a paused program hold one of the enabling switches and press the Play key.

To Restart the running program from the beginning choose Reset program from the menu as shown below:

Installing the Grippers

It's a common operation with the robots to grip parts. To do this the pneumatic gripper tools are used. Each user is responsible for creating their own gripper fingers. The fingers are the part that is screwed to the gripper tool making it uniquly suited to the parts you wish to grab.

Custom fingers can be easily 3D printed in ABS plastic for about $10-$15 for a pair.

The grippers fingers are screwed to the gripper assembly using M3 screws, two screws per finger. This lets you slide the fingers back and forth and adjust the width of the part that's gripped. In the example pictured below the screws are 8mm in length.

It is sometimes useful to add double sided foam tape to the gripper fingers. This gives them a bit of cushion during the grip. Keep the outside face of the tape covered so it is not sticky.

The entire gripper tool is screwed to the toolplate using four M6 screws.

The gripper is operated by air pressure. The air hoses connect to the robot arm as shown below. Simply press them into the holes shown. To release them you need to press on the blue ring surrounding the hole, then when pressed in (it doesn't move much at all) pull the hose free.

You turn the air pressure on from the wall valve. Note: The air is supplied to both robots so you'll need to install the grippers on both robots even if you are not using them. If not using the second robot just place the gripper on the table and plug in the air hoses. No need to fully screw on the tool.

Manually Clamping or Releasing the Grippers

Normally the gripper is operated under program control. However sometimes you’ll need to clamp and unclamp them manually. Follow this procedure to do so:

From the Main Menu select Display > Input/output > Digital I/O:

From the dialog presented click on items 1 (gripper_close) or 4 (gripper_open) and click the Value button to toggle it's state. If it appears in red the value is True. Note: You need to enable only one of those items at a time. So turn one off before turning the other one on. 

Installing a Tool

When you want to add a custom tool you'll have to add data about it to the Tool table stored by the robot. You'll also have to let the robot know which tool is in use.

To configure a tool follow these steps:

From the Main Menu choose Start-up > Calibrate > Tool > Numeric input:

Here you can begin to enter the data about the tool; its number and name. Then press Next. 

Then you enter the distance and angular offset from the tool plate origin:
*** more detail here including diagram. 

Verify the data you entered is correct and then press Save. 

You can now choose the tool from the Tool/base status indicator. After clicking the tool number the following menu will appear:

Select the tool you wish to use from the drop-down. This should correspond to the tool number specified in your program code.

Table of Tool Numbers

We have some standard tool numbers we use in the lab. *** TODO: Not yet... *** Here they are:

  1. Pen Tool
  2. Maze Tool
  3. Gripper Tool
  4. Brush Tool