COLLIB MANUAL

KUKA NAVIGATION
+COLLISION
DETECTION
+IKPY

Gabrielle Desiree Cardoso de Souza

January, 2020
Introduction
This document aims to explain how to use COLLIB to detect collision of the robot with
obstacles in application which Inverse Kinematics is necessary. To calculate forward
and inverse kinematics, obtain information from an URDF file and plot the robot chain a
library called IKPy was used. For more information about IKPy, please access
Phylliade/ikpy: An Inverse Kinematics library aiming performance and modularity.

It is a compilation of all the information necessary to make the whole system work and
includes topics about IKPy, COLLIB, SIM PRO, Office Lite, EthernetKRL and WorkVisual.

1
Background
COLLIB was developed to a task that uses a vision system to identify parts in a box and
provides its coordinates in space, so a KUKA KR8 Robot has to pick the piece. But the
robot needs a pose to realize the movement, so it is necessary to calculate the joint
angles through Inverse Kinematics. After obtaining the pose via IKPY, it was necessary
to check for collision between the box and robot and then send the information in a
XML file via Ethernet.

ColLib is available at Testbed - CIIRC Repository.

Python Programming | IKPy and COLLIB

After importing IKPy and COLLIB,the first step was to simulate the environment in a way
that was simple but enough to give visualization of the situation, that means plot box
and robot and understand the geometry of the problem.

To build the situation with 3D Matplotlib was used. The robot’s chain was plotted using
IKPy functions:

From URDF file: Creates a chain from a URDF file. The only argument necessary is the
path to the file.

Usage: Chain= ikpy.chain.Chain.from_urdf_file(path)

Arguments:

➔ Path{string}path of the URDF file

Example:

chain = ikpy.chain.Chain.from_urdf_file("kr8r1620.xacro")

Chain.Plot: Plots the robot’s chain when receiving the joint angles and the axles.

Usage: chain.plot(IK, ax)

Arguments:

2
 ➔ Pose{numpy.ndarray}array of the joints’ angles
➔ ax{3D axes} axes of the 3D space

*It is also possible to create a chain manually. For more information, please check :
Home · Phylliade/ikpy Wiki

It is necessary to give some information about the box or other obstacle that may not
collide with the robot. In this example the robot can’t collide with the box’s sides and
with the floor, but it can access what is inside the box. Two COLLIB’s functions are
responsible for creating and plotting it.

Create Box: needs a tuple of coordinates of the new box and its height, width and
length. Usually, the coordinates are of the point that is closer from the origin, the height
is the dimension in the Z direction, width, in Y direction and length in the X direction, as
is possible to see in the image above.

It is important to use meters as measure unit, as IKPy also uses it to plot chains,
following the URDF file default.

Usage: Box = ColLib.create_Box(xorigin, yorigin, zorigin, height, width, length)

3
Arguments:

➔ xorigin {float} x coordinate of the box origin

➔ yorigin {float} y coordinate of the box origin
➔ xorigin {float} z coordinate of the box origin
➔ height{float} box’s height (size in the z axle direction)
➔ width{float} box’s width (size in the y axle direction)
➔ length{float} box’s length (size in the x axle direction)

Draw box: once the box is created, this command can be used to draw the box in space.
It is necessary to provide as argument the same 3D axle used to plot the chain, so box
and robot can be plotted in the same figure.

Usage: draw_box(box):

Arguments:

➔ box {Box} box previously created

➔ ax {axle} same 3D axles used to plot the chain

Now that the box and the robot are already and plotted, one just has to give the target
coordinate to the program, and then it will calculate the inverse kinematics using IKPy.

IKPy uses the method inverse_kinematics to return the pose.

Inverse Kinematics: basically, the function needs the target coordinates framed on a
homogenous matrix. So, once the user inputs the target, it is necessary to create an eye
matrix and attribute the target to the fourth column of this matrix.

Usage: IK= chain.inverse_kinematics(t_frame, initial_position*)

Arguments:

➔ T_frame {4x4 matrix} a homogeneous matrix - Transformation matrix

➔ Initial_position {array} Optional - list of joints

Important: IKPy’s inverse kinematics uses an optimization algorithm that minimizes

the squared distance. If an initial position is not given, it assumes that all joint angles
are zero, the initial position is used as initial guess for the algorithm, so it tends to find
solutions near the floor, and favors collisions. For best performance, an initial position

4
may be used, it can be the home position, or somewhere near the box, or, if you want
to plan a whole path using IK, the initial position will be the previous position.

In this Notebook some IK issues are explained.

Once we already have the robot pose calculated, and it is necessary to check if this
pose is possible in the real world or if its cause collisions or is out of the robot bounds.

To do such verifications, first we have to check if the target was reached. So, it is
necessary to compare the target coordinates with the coordinates reached by the pose
calculated by inverse kinematics. If the objective has not been reached, it means that
the robot's limits do not allow it.

To do that forward kinematics from IKPy is used, it receives the pose calculated by
inverse kinematics and calculates the end effector final coordinates.

Forward Kinematics: calculates the cartesian coordinates of the end effector based on
the joint angles position.

Usage: FK = chain.forward_kinematics(pose)

Arguments:

➔ pose {array} list of joint angles

Forward Kinematics returns a 4x4 transformation Matrix, to compare with the target
coordinates, it is necessary to extract it from the matrix using a ColLib function:

EndEffector_Coordinates: is a simple function that extracts the coordinates of the end

effector of the transformation matrix.

Usage: EE_Coordinates = ColLib.EndEffector_Coordinates(FK)

Arguments:

➔ FK {4x4 matrix} a homogeneous matrix - Transformation matrix

In case that the goal is achieved, it means that the robot may move to that position, but
some barrier may be in the way, resulting in a collision. Once the Inverse kinematic was

5
calculated, the program must look for collisions and only move, if the way is free for the
robot. For this propose COLLIB is used:

Check Collision: this method receives the box (or other object that the robot must avoid)
and the coordinates of all joints in the space (see Robot_Pose). The information of the
box and joint. In pairs, the joint coordinates describes a line, the function checkPlan
checks if this line intercepts a semi plan (box’s side). Check Collision does the
verification for all the joints and all box’s sides.

The function Check Plan (described below), called by Check Collision, also plots things
in the figure if there is a collision, so it is necessary to give as argument the 3D axle
previously used.

Usage: checkCollision(box, pose,ax)

Arguments:

➔ box {Box} box previously created - possible obstacle in the robot way
➔ JointCoordinates - Matrix of x,y,z of joints’ coordinates in space - The return of the function
Robot_pose.
➔ ax {axle} same 3D axles used to plot the chain

Robot Pose: Given a chain and a pose (joints’ angle), returns the X,Y and Z coordinates
of each joint in space. This method was based on IKPy plot chain.

Usage: Robot_Pose(chain, pose,axle)

Arguments:

➔ Chain- The robot’s chain

➔ Pose - list of joints’ angles

Check Plan: Checks if there is intersection between a semi plan and a line described by
two points. Using the box vertices, the program identifies whether the semi plan has y or
x coordinate constant. A plan can be intercepted by a line just in a point, using the
straight line equation, it is calculated the coordinates of this point. After, it is only
necessary to check whether the coordinates are between the four vertices of the box
size, if yes, the robot will collide with the obstacle. Each collision is represented as a
yellow point in the box.

Usage: checkPlan(x, y, z, x_, y_, z_, h, x0, y0, z0, x1, y1, z1, axle)

6
Arguments:

➔ x, y , z -tuple of coordinates of a box’s vertices

➔ x_,y_ , z_ -tuple of coordinates of the other box’s vertices
➔ h - the height of the box. Used to obtain the other two vertices
➔ x0, y0, z0 - joint’s coordinates - first tupla
➔ x1, y1, z1 - joint’s coordinates of the child’s joint
➔ ax {axle} same 3D axles used to plot the chain

The last step is to plot the chain using IKPy’s chain.plot and display the other elements
and send the XML file to the robot.

Ethernet Communication
The Ethernet connection is configured via an XML file, it uses Ethernet KRL as described
in the Topic Ethernet KRL + OfficeLite bellow. There was a previously created Ethernet
KRL Server, this python application was commented on and it is available in the
repository Hanz KRL .Inside the same folder are a DataStructures Datastructures file
and some examples.

This communication is important because the application needs some information of

the robot and so the robot needs information of the application.

The application will need to receive the robot's actual position to use as initial_position
parameter to calculate inverse kinematics properly. After calculation and collision check
the robot needs to know whether it is supposed to move, and which angle it should
move each servo motor, or to be stopped and display an error message because if it
realizes the movement a collision will happen.

Ethernet KRL server does all the communication and sends and receives the xml files,
DataStructure has all the data structures and conversions between python and xml.
RemoteControl_ has the functions that will be used in the movement, here will be the
interface between KUKA NAVIGATION and the ethernet communication.

To use IKPY’s inverse kinematics, a new data class was created in the file
Datastructures_. The previous class, called Axes, only worked with 6 arguments, the 6
joint’s angles, but using IKPY inverse kinematics there were only a list of the joint angles
in one single variable. So the class Pose was created.

7
Pose is the same as the class Axes but receives an array with a list of joints and split
into each axles angle. It also ignores the first position[0] due to the use with IKPy's
inverse kinematics. The list returned by IKPy has 7 angles, but the first one is not real, it
is just a programming artificial.

The new files are saved with an _ at the end and the old Hanz KRL files are with the
same name.

As the client is not working due to problems at the simulation, it was not possible to test
the whole communication, even though the xml is sent:

LESSONS LEARNED

KUKA OfficeLite
OfficeLite is a virtual machine of the robot controller, with which it is possible to do
some KRL programming and integrate with KUKA SIM PRO.

The installation is described step by step in the OfficeLite Manual, but here come some
issues that one can get through (and how to solve them!).

License

Some actions may make your license not available, if it happens you have to ask KUKA
to refresh it by mailing simulation@kuka-roboter.de and send a .kpf file by running
FingerprintCreator.exe, program that generates the *.kpf file and it is located C:\KRC\
UTIL\FLEXLM, in the VM.

Same examples of things that may cause problems with the license are:

8
 ● Erasing the .lck file. (VMWare failed to lock the file problem and solution is
described below)
● Opening a backup of the VM
● Having more than one VM on the Workstation’s library

VMWare failed to lock the file

This probably happens when you turn off the computer without shutting off the VM.
When you try to open the VM again, this error will appear. It is possible to reopen the
VM by erasing the .lck file, but it may cause problems with the license HOST ID, you will
have to contact KUKA and ask for a new .lic file.

To solve this problem copy and paste all the files in the folder where the VM is located
and save somewhere else as backup. After this, locate the .lck file, open it using
notepad or other text editor, click and save as, use the same name and put .vmdk at the
end. Then erase the .lck file and try to run the VM again.

More information about this issue can be found in Investigating hosted virtual machine
lock files (1003857).

Error while powering on: Could not get vmci driver version: The handle is invalid. You
have an incorrect version of driver 'vmci.sys'. Try reinstalling VMware Player. Module
'DevicePowerOn' power on failed. Failed to start the virtual machine.

This is a problem probably due to an update, and prevents you from starting the virtual
machine. It can be easily solved by running VMWare setup and clicking in the option
restore the program. After doing that, the VM will open normally.

Ethernet KRL + OfficeLite

The Ethernet Connection is configured via an XML file. The configuration file must be
defined for each connection in the directory C:\KRC\ROBOTER\Config\User\Common\
EthernetKRL of the robot controller. The configuration is read in when initializing a
connection. More information about Ethernet KRL and its configuration, installation and
programming can be found at EthernetKRL Manual.

9
Ethernet KRL needs a KLI (KUKA Line Interface), but Office Lite doesn’t have it. So to use
OfficeLite and Ethernet KRL it is necessary to install KRC Router and follow this
procedure.

If the IP address that appears in the EthernetKRL-Server.exe is different from the

desired one, change the Network interface card index and press play again, repeat it
until find the correct IP address. In my case was number 2.

SIMPRO
KUKA.SIM PRO is a software used for simulation and offline programming. There it is
possible to draw and import elements to create a scenario similar to the real one, and
the program the robot and export or import a KRL Program.

Here is KUKA.SIM Manual.

Connecting SIMPRO and OfficeLite

It is simple to connect SIMPRO and OfficeLite following the tutorial Video Tutorial, but if
after clicking in CONNECT, it stays for a long time with the message “connecting”, you
are supposed to check the firewall of windows(HOST-PC, not VM). If you disable the
public network firewall, the connection you will succeed.

To be sure that the problem is the firewall block, try to ping the VM from the host PC, if
you are able to do it, the problem probably is the firewall.

If VRC Manager is not installed, follow the instructions to do it available on the section
3.6 of OfficeLite Manual

*According to KUKA specialist, it is not possible to connect SIMPRO with Office Lite if
you have WorkVisual installed.

UNSOLVED
At this point it was not possible to use SIMPRO, OfficeLite and Ethernet KRL together.
After installing KUKA router, OfficeLite is showing drivers inconstancy problems.

10
11
KUKA advised us to try to solve this by using WorkVisual, but during the deployment
step both OfficeLite and WorkVisual asked for an user input and after unknown error.

12
There is a Tutorial about how to use WoV and Office lite, this was the procedure
followed and the errors took place . The log errors were sent and KUKA is analyzing the
problem.

WorkVisual can be downloaded here. More information about it at WoV Manual.

13