Katana4D Manual

Version: 4.3.5
Datum: 11.12.07

© Copyright Neuronics AG
This document – and/or parts of it – may only be published, copied and/or made available to third parties with the
express permission of the publisher.
Table of Contents
Introduction................................................................................................................................ 5
Installation................................................................................................................................ 5
Fonts in this manual................................................................................................................. 5

1 Quick-Start............................................................................................................ 6
1.1 First steps............................................................................................................................ 7
1.1.1 Set up wizard.................................................................................................................. 7
1.1.2 Login............................................................................................................................... 8
1.2 Creating Pick&Place-Applications using the wizard........................................................ 9
1.2.1 Picking up the objects................................................................................................... 11
1.2.2 Positioning of the objects.............................................................................................. 13
1.2.3 Intermediate points....................................................................................................... 14
1.2.4 Creating an application................................................................................................. 16
1.3 Pick&Place-Application (single points)........................................................................... 17
1.3.1 Defining the positions in the Katana4D project............................................................. 17
1.3.2 Programing the actions................................................................................................. 21
1.4 Hand Control....................................................................................................................... 27

2 Software Description......................................................................................... 28
2.1 Overview............................................................................................................................ 29
2.1.1 Start / Login.................................................................................................................. 29
2.1.2 User management........................................................................................................ 30
2.1.2.1 Users.................................................................................................................................. 30
2.1.2.2 Groups................................................................................................................................ 31
2.1.3 Configuration................................................................................................................ 32
2.1.3.1 Change the language......................................................................................................... 32
2.1.3.2 The tab Configuration......................................................................................................... 32
2.1.4 Structure....................................................................................................................... 34
2.1.4.1 Projects / Programs............................................................................................................ 34
2.1.4.2 Applications........................................................................................................................ 34
2.1.5 Main calibration............................................................................................................. 35
2.1.5.1 Motors Navigation............................................................................................................... 35
2.1.5.2 Space Navigation................................................................................................................ 35
2.1.5.3 Tool-Navigation................................................................................................................... 36
2.1.5.4 Additional commands......................................................................................................... 36
2.1.5.5 Main calibration................................................................................................................... 36
2.2 Katana................................................................................................................................ 37
2.2.1 General configuration Katana....................................................................................... 37
2.2.2 Gripper.......................................................................................................................... 38
2.2.2.1 Universal gripper................................................................................................................. 38
2.2.2.2 Other grippers..................................................................................................................... 38
2.2.3 Sensors........................................................................................................................ 39
2.2.3.1 Current Measure................................................................................................................. 39
2.2.3.2 Color sensor....................................................................................................................... 39
2.2.4 Parameters................................................................................................................... 40

2/187
 2.2.4.1 Katana Parameters............................................................................................................. 40
2.2.4.2 Controller Parameters......................................................................................................... 41
2.2.4.3 Main Calibration Parameters.............................................................................................. 41
2.2.5 Firmware....................................................................................................................... 42
2.2.5.1 Firmware Versions.............................................................................................................. 42
2.2.5.2 Firmware Update................................................................................................................ 43
2.3 Applications....................................................................................................................... 44
2.3.1 Structure of applications............................................................................................... 44
2.3.2 Creating an application................................................................................................. 45
2.3.3 Helper functions............................................................................................................ 46
2.4 Projects.............................................................................................................................. 47
2.4.1 General......................................................................................................................... 48
2.4.2 Grid............................................................................................................................... 49
2.4.2.1 General definitions.............................................................................................................. 49
2.4.2.2 Extended Grid..................................................................................................................... 50
2.4.2.3 Deleting points of the grid................................................................................................... 50
2.4.2.4 Teach grid points and compute grid coordinates................................................................ 52
2.4.2.5 Special orientations............................................................................................................ 52
2.4.3 Points............................................................................................................................ 54
2.4.4 Path functions............................................................................................................... 56
2.4.4.1 Overview............................................................................................................................. 56
2.4.4.2 Paths.................................................................................................................................. 57
2.4.5 Trajectories................................................................................................................... 60
2.4.6 Object Recognition....................................................................................................... 63
2.4.6.1 Objects............................................................................................................................... 65
2.4.6.2 Training Set........................................................................................................................ 66
2.4.6.2.1 Training Samples........................................................................................................ 68
2.4.6.2.2 The Neural Network.................................................................................................... 70
2.4.6.2.2.1 Training................................................................................................................................ 71
2.4.6.2.2.2 Configuration........................................................................................................................ 73
2.4.6.3 Object recognition within a user Program........................................................................... 75
2.4.6.4 NN Assistant....................................................................................................................... 76
2.4.7 Project functions in the main window............................................................................ 81
2.5 Programs............................................................................................................................ 83
2.5.1 General......................................................................................................................... 84
2.5.2 Structure of the programs............................................................................................. 85
2.5.3 Stopping programs....................................................................................................... 86
2.5.4 Katana4D Script............................................................................................................ 87
2.5.4.1 Comments in Katana4D...................................................................................................... 88
2.5.4.2 Katana commands.............................................................................................................. 89
2.5.4.3 4D programming language................................................................................................. 90
2.5.4.4 User variables..................................................................................................................... 91
2.5.5 Start script and End script............................................................................................. 93
2.5.6 Sequences.................................................................................................................... 94
2.5.7 User methods............................................................................................................... 97
2.5.7.1 Locale User Methods.......................................................................................................... 98
2.5.7.2 Global User Methods.......................................................................................................... 99
2.5.7.3 Event driven methods....................................................................................................... 101
2.5.8 Options....................................................................................................................... 103
2.5.9 Program functions in the main window....................................................................... 106
2.6 Interfaces......................................................................................................................... 108
2.6.1 National Instruments Digital I/O Card.......................................................................... 109
2.6.2 Connector-Box............................................................................................................ 112

3/187
 2.6.3 File communication..................................................................................................... 114
2.6.4 Serial communication.................................................................................................. 115
2.6.5 TCP/IP........................................................................................................................ 116
2.6.6 ModBus TCP.............................................................................................................. 117
2.6.7 Web-Services............................................................................................................. 118
2.6.8 Siemens S7 – Plugin.................................................................................................. 119
2.6.9 Cognex Camera.......................................................................................................... 121

3 Command description..................................................................................... 122

3.1 Action Commands........................................................................................................... 123
Path functions....................................................................................................................... 123
3.1.1 General Action commands.......................................................................................... 124
3.1.2 Approaching positions in space.................................................................................. 127
3.1.3 Approaching Points in a grid....................................................................................... 132
3.1.4 Approaching points in space....................................................................................... 134
3.1.5 Moving along paths..................................................................................................... 139
3.1.6 Moving along a trajectory............................................................................................ 140
3.1.7 Project Control............................................................................................................ 141
Points............................................................................................................................................. 141
Grids.............................................................................................................................................. 143
3.2 State checkings............................................................................................................... 146
3.3 Katana Settings............................................................................................................... 152
3.4 Interfaces......................................................................................................................... 155
3.4.1 National Instruments IO Card..................................................................................... 156
3.4.2 Katana Connector-Box................................................................................................ 158
3.4.3 File communication..................................................................................................... 159
3.4.4 Serial communication.................................................................................................. 161
3.4.5 TCP/IP........................................................................................................................ 162
3.4.6 ModBus TCP.............................................................................................................. 165
3.4.7 Siemens S7 - Plugin................................................................................................... 168
3.4.8 Cognex Camera.......................................................................................................... 177
3.4.9 Katana 1.2.................................................................................................................. 179
3.5 Program flow control....................................................................................................... 180
3.6 Neural Network Functions.............................................................................................. 186

4/187
Introduction

Introduction
We congratulate you on your choice to use Katana, Neuronics small and flexible robot.
This quickstart manual briefs you about the startup of your Katana robot using the control software
Katana4D.
We recommend you read this manual carefully and step by step. You will see quickly, how easy it
is to set up and program Katana.
We wish you both, fun and success!
Neuronics AG

Installation
To install the software, insert the CD into your CD-ROM/DVD-ROM drive and wait until the
autostart menu appears on the screen. Click „Installieren“ and follow the instructions on the screen.

Note
If the autostart menu doesn't automatically appear, open “My Computer” and double click the CD-
ROM/DVD-ROM drive you inserted the installation CD into. Execute the file “setup.exe” by double
clicking it. This starts the installation.

Fonts in this manual

In this manual the following elements are always presented in the same font:
• input fields and check boxes
• buttons
• Tabs and Windows
• Regular Text
• 'Text to be entered into forms'

5/187
1 Quick-Start

1 Quick-Start

6/187
1 Quick-Start

1.1 First steps

1.1.1 Set up wizard

When you first start Katana4D, the set up wizard is opened. This wizard helps you to set up your
software.
First you have to choose whether you want the program to automatically recognize the Com ports.
It is recommended to do so. In case the automatic recognition does not work correctly or takes too
long, you should deactivate it.
Connect the robot to the computer now and continue the dialog.
As soon as a Katana was recognized, the next page is opened. On that page the type of Katana
has to be selected and the tool at motor 6 (turner or gripper, respectivele) can be set. In the text
field Name the Katana can be given a name.
E.g. the type of a Katana with 6 motors, HarmonicDrive, gripper and safety padding is KatHD300s-
6M180.
On the last page, the password for the administrator can be set. For security reasons, the
password has to be repeated in the second text field.

7/187
1 Quick-Start

1.1.2 Login
After the setup, the start screen is opened.

Choose 'Katana administrator' in the 'Katana' menu to log in as administrator.

At this point a main calibration of the connected robot is necessary. To do so click main calibration
(this takes about 1 min.)

8/187
1 Quick-Start

1.2 Creating Pick&Place-Applications using the wizard

In this example of a pick&place application we want to define two grids. One of them is used for
picking up objects, the other one is used to place them. Both grids consists of 3 points (i.e. 3 x 1 or
1 x 3). The robot will pick up the first object from the first point in the first grid an place it at the first
point of the second grid. It will repeat this with objects at the other two points. We assume that
there is an obstacle between the two grids and therefor an intermediate point is defined to avoid
the obstacle.

Graphical representation of the task:

Intermediate point

M4

M6 M5 M3 M2 Target grid
1 row / 3 objects
1 row / 3 objects
1 2 3
1 2 3
M1
A B
A B

• • •
To conduct this example, prepare a table, and place the robot its middle in such a way that there is
enough space for one grid on each side of the robot. Also define the objects to be used and the
points for picking up and placing.
• Click new project in the tab labeled projects & programs.

• In the text field name, enter 'ExampleProject1.'

9/187
1 Quick-Start

• Activate the check box Use wizard.

At this point, the initial form of the wizard appears:

The wizard consists of several pages. The blue arrow buttons can be used to navigate between the
different pages. To switch between the different text fields, use the tabulator key on your keyboard.
The wizard is self-explanatory, i.e. the user is guided through the wizard step by step, so that even
an inexperienced user can create an executable program without additional help.
• Enter a short description of the project into the text field Description of the project. E.g.
'PickAndPlace application with grid'.
• Complete the next two text fields with your personal data, e.g 'companyXYZ' and
'PersonXYZ'.
• In the next field the Katana to be used can be chosen. Don't modify this field.
• The section “Gripper” allow to define the encoder values for the gripper in open and closed
position, respectively.

• Click the button to go to the next page.

10/187
1 Quick-Start

1.2.1 Picking up the objects

The second page defines how and where the objects are picked up.

• Since we want the robot to pick up objects at more than one point, please check the
checkbox Multiple Position
• As soon as you do so, the expanded view for defining the grid appears.

• Enter '1' into the field How many rows? and '3' into the field Number of objects per row.
Press Enter.
You can now see points A and B:

To store the grid, the outermost points have to be taught by hand. The intermediate points
are then computed automatically.
• Press Refresh grid Image on the right.

11/187
1 Quick-Start

Here you can clearly see the points on the grid. You can also see that the corner points A and B
are internally called point 1 and point 3.

Teaching the grid:

• Turn off the robot by clicking All motors off.
• Close the gripper so that the robot securely grips the object. To do so, you have to open the
hand control and close the gripper either by clicking Close gripper or by using the slider.
Close the hand control by clicking End. For more details on the hand control, see chapter
„1.4 hand control“.
• Move the robot by hand to the first pick up point (Point A), whilst keeping the aperture of the
gripper the same.
• Click All motors on so you can let go of the robot.
• If necessary, correct the position with the hand control. (hand control). For more details on
the hand control, see chapter „1.4 hand control“.
• Teach point A by clicking Teach A. The X, Y, Z – coordinates appear in their respective
fields.
• Repeat the last 6 instructions for point B.
When you're done teaching the corner points, the X, Y, Z coordinates of the corner points are
displayed:

The points of the grid are now stored.

At the bottom of the window two fields additional fields are located. The first one determines the
height above the objects, the robot moves to, before it moves directly down towards the object to
grip it. The second field determines the height above the objects the robot moves to after gripping
the object but before doing any further movements. The default value is 20mm.
• Don't modify either field.

• Click the button to go to the next page.

12/187
1 Quick-Start

1.2.2 Positioning of the objects

Teaching the target grid is exactly the same as before. The only difference is, that the gripper must
be open during the teaching, so that the robot can let go of the objects correctly.
• Using the hand control, open the gripper wide enough for the robot to let go of the object
and move away from it. For more details on the hand control, see chapter „1.4 hand
control“.
• Repeat the steps in 'Picking up the objects', except the part about opening the gripper.

• Again, click the button to go to the next page.

13/187
1 Quick-Start

1.2.3 Intermediate points

You can choose between linear and non-linear movements to approach the intermediate points.
• Select the option 'Linear Movements' (if not already selected).
• Since we want to have intermediate points, also select the next checkbox, which
determines that there are intermediate points.
• At this point you can decide whether the intermediate points, that will be created, shall be
visited on the way there and/or the way back.
• Click Create new Between Point now.
When you do so, a row is inserted into the table. In this row, our intermediate point will be stored.
The default name of the point is 'Z1'.
• Click the name and change it to 'intermediatePoint1'.

• To teach the intermediate point, turn off the motors by clicking turn off motors, move the
robot to the desired position (approximately in the middle between the two grids) and then
turn the motors back on by clicking All motors on If necessary, the position can be
corrected using the hand control.
• Click the row in the table. You can now see three symbols on the right side of the table.

14/187
1 Quick-Start

Click to save the intermediate point.

• Click the button to go to the last page.

• On the last page, the velocity of the robot can be set using the slider. Set the slider to slow.

• By clicking the Confirm button, the wizard is closed and the program is created. Clicking
Cancel will result in the project not being saved and all the changes you made being lost.
The pick-and-place application is now complete. The wizard added a project 'Example1' and a
program 'Example1_AutoProg' in the tab Projects & Programs. The project contains the two
grids and the intermediate point, whereas the program contains the actions as a script.
The program can be executed by the administrator by clicking Execute. Try out the program now
and correct it where necessary.

If you set the number of repetitions to '1', only one object will be moved. '3' will result in all three
objects being moved. If '0' is entered, the program will loop until either the shift-key is pressed or
the program is terminated by clicking End.

In the next chapter you will learn how to allow a regular user to execute the program.

15/187
1 Quick-Start

1.2.4 Creating an application

• Click New application in the tab Application.
• Enter 'Pick & place with wizard' into the field name.
• Select the newly created application and click Add Program.

All projects and their respective programs appear.

• Chose the previously created program 'Example1_AutoProg' and click OK.

The program was assigned to the application.

• Log out (Click End in the upper right corner).

• Log in as User.

The programs you made available to the user are shown.

The whole example is now executable by regular users.

• Execute the program as a user by clicking Execute.

Enjoy your program!

16/187
1 Quick-Start

1.3 Pick&Place-Application (single points)

In this second example we want to create a simple Pick&Place-application, in which the robot
moves from a pick up position to a put down position via an intermediate point. We will use to
single points instead of a grid. The application will be created without the wizard.

Graphical representation of the task:

intermediate position

M4

M6 M5 M3 M2

M1

start position target position

The following steps must be taken to implement a solution in Katana4D:

• Defining the positions in a project.
• Programming the actions as a script in a program.
• Making the program available to the user in an application.

1.3.1 Defining the positions in the Katana4D project

• Open the tab Projects & Programs.
• Open a new project by clicking New Project
• Enter 'Example2' into the field name.
• Confirm the form by clicking OK.
The start form of the newly created project appears:

17/187
1 Quick-Start

• Enter a short an description of the project (e.g. 'Pick & Place application with single points
and without wizard.' ) into the field Description.
• Also complete the fields Author and Company according to your particulars.
• Open the tab Points.

The list of points is a table in which each row represents a certain positions of the robot with its
corresponding space coordinates and encoder values.
Will will successively store 3 points (pick up point, target point and intermediate point, to avoid an
obstacle in the middle).
• Create a new point by clicking New.

18/187
1 Quick-Start

The window Point is opened:

• Enter the name of the pick up point ('pickUpPos') into the field Name.
• Turn off the robot by clicking All Motors off . Attention: Hold robot before using this
command!
• Move the robot by hand to the point you want it to pick the object up. Block the motors by
clicking All Motors on.
• In the hand control (Hand Control) the position can be corrected if necessary. For more
details on the hand control, see chapter “1.4 hand control”.

The position of the gripper while teaching the point (i.e. whether it's open or closed) doesn't matter.
We will take care of this while programming the actions.
• Store the position by clicking Get Current Values.
• Close the window by clicking Confirm.
The newly created point was added to the table.

19/187
1 Quick-Start

To edit the point, the following actions are available:

Open the window Point to modify it.

Move the robot to the point (linear movement if selected).

Store the current position in the selected row. (Caution, this will override the former data!)
Delete point (Caution!)

The last three symbols are only displayed when clicking a row.
• Create the target point „TargetPos“ and the intermediate point „IntermPos“ in the same
way.

Before closing the project, all positions should be tested by moving the robot there, using the green
arrow button.
• Close the project by clicking Confirm.

The needed points are now created. All that is left to do is programming a script containing the
actions of the robot.

20/187
1 Quick-Start

1.3.2 Programing the actions

• In the tab Projects & Programs, select the Project 'Example2' you just created and click
New Program
• Enter 'Pick&Place' into the field Name.

The program contains three different types of scripts which are executed automatically: The
startscript, the sequences and the endscript. The startscript is executed at the beginning of the
program execution. After that the individual sequences are executed one after the other. You can
decide how many times the sequences are executed. At the end of the program, the endscript is
executed. There is an additional kind of scripts called user methods. User methods are not
executed automatically and we will not go into details about them in this example.
Any number of commands can be added to a script. A list of commands that can be used can be
found below each script.
There are different kinds of of command. e.g. movement commands('Action Command') or
communication commands ('Interfaces'). Right now we are mostly interested in the action
commands. More details can be found in chapter 'command description'.
Enough general information, let's start programming:
Almost every action command needs to be passed the velocity, the acceleration and the tolerance
of the movement. For that reason, those two variables are declared in the startscript by default:

21/187
1 Quick-Start

Two velocities are defined, the velocity for regular movements ('Velocity') and the velocity for linear
movements ('LinVelocity'). The tolerance (in encoders) defines how accurate a point is approached
before the next command is executed.
The character string “:=“ (colon, equal sign) assigns a value to a variable.
We will now modify the velocity and acceleration and define two additional values setting the
aperture of the gripper by adding two variable definitions to the startscript:

The character “`“ starts a comment that will be ignored by Katana4D.

The values to assign to the variables must be found out by the administrator using the hand
control.
• Open the hand control using hand control, then open the gripper (motor 6) in small steps
until the robot can move to an pick up the object. More details on the hand control can be
found in chapter “1.4 hand control”.
• Write down the encoder value of the gripper (motor 6) and close the hand control. Now
change the value of the variable “GrOpen” from 12000 to the value you wrote down.
• Repeat the last two steps for the encoder values of the closed gripper. The gripper must be
able to pick up the object with the noted encoder values. Assign the value to the variable
“GrClosed” (instead of 7500).

22/187
1 Quick-Start

The variable definition in the startscript is done now. We will now program the individual
movements to the points.
• Create a new sequence by clicking New in the tab Sequence.

As mentioned above, a sequence can contain any number of commands. Therefor the whole
program could be implemented in one sequence, but we want to split the program into several
sequences to keep it more understandable.
• Enter 'Move to pick up position and close gripper' into the field Name.
• Enter '1' into the field Order.
• Double click the command 'MoveToPointDelta' at 'Action commands'  'Run up Space-
Points'.

• Select the point 'pickUpPos' from the list and click OK.

The command 'MoveToPointDelta' is inserted into the script. This command lets the robot move to
the specified point with the specified offsets and the passed movement parameters Velocity,
Acceleration and Tolerance (You already specified the movement parameters in the startscript).

23/187
1 Quick-Start

This means that the robot does not go directly to the point. Instead it goes to the position +30mm
in the Z Direction (this means up) from the specified point. This is used so that the robot can then
move to the point linearly.
• Enter the values '0', '0' and '30' for 'DeltaX', 'DeltaY' and 'DeltaZ'.
• Double click the command 'MoveToPointLin' at 'Action commands'  'Run up space points'
and select the point 'pickUpPos'.

The pick up point is reached. Now it's time to close the gripper.
• Double click 'MoveMotAndWait' at 'Action commands'  'General commands'.
• Replace 'MotorNumber' by '6' and 'TargetPosition' by the variable name 'GrClosed'.

At this point the robot grabbed the object and it should now linearly move up 30mm, so that it can
move on problem-free.
• Double click 'MoveToPointLinDelta' at 'Action commands'  'Run up Space-Point', select
'pickUpPoint' and replace 'DeltaX', 'DeltaY' and 'DeltaZ' by '0'; '0' and '30'.
This is how the sequence, with some additional comments should look like:

• Close the sequence by clicking Confirm

The newly created sequence appears in the table. Since moving to the target position is very
similar, we can copy the sequence and modify it.

• Copy the sequence you created using the copy function . You will have to click the row
for the symbol to appear.
• Open the copied sequence using >> .
• Enter 'Move to target position and open gripper' into the field Name.
• Enter '3' into the field Order.

24/187
1 Quick-Start

• In the script, replace 'GrClose' by 'GrOpen' an all occurrences of 'pickUpPos' by 'targetPos'.

The sequence should now look as follows:

Ablagepunkt versetzt anfahren

öffnen

• Close the sequence by clicking Confirm.

The robot moves to the pick up position, picks up the object, moves to the target position and lets
go of the object. Since there is an obstacle in the middle, we have to move to the intermediate
point between the two sequences and at the end.
• Create a new sequence with Name 'Move to intermediate position', Order '2' and the
following script:

• Copy this sequence and change the Order to '4'.

t
The last step will complete the program.
• Save the program by clicking Confirm.

The program you just created appears in the list in the tab Projects & Programs. The
administrator can execute the program at this point. You should do this to test your program.
Additionally, we want a regular user to be able to execute the program. To do so, we have to
create an application. You learned how to do that in the paragraph 'Creating an application' in the
first example.

25/187
1 Quick-Start

• Create a new application called 'Pick & Place with single points' and add the program 'Pick
& Place' to the application.
• Change to user mode.

Enjoy your program!

26/187
1 Quick-Start

1.4 Hand Control

In hand control mode you can operate the robot very easily. You can do so using either Motors
Navigation, Space Navigation or Tool Navigation.
When using Motors Navigation, each axis is controlled individually. In Space Navigation the
robot can be moved in the base coordinate frame and the Tool Navigation moves it relative to the
TCP- (Tool Center Point) frame, which allows you to accurately position the robot.
A detailed description of the hand control can be found in paragraph 2.1.5 in the software
description.

27/187
2 Software Description

2 Software Description

28/187
2 Software Description

2.1 Overview

2.1.1 Start / Login

When starting the software, the following window is opened:
To log in, open the menu 'Katana' and select 'Login, or press 'Ctrl+X'. In the window that is opened,

you have to enter you username and password. When first started, the software automatically
offers the users 'User' and 'Administrator'. The administrator has all right, the user only has limited
right (for more information see section 'User management').
You can log in as those two user directly using 'Katana'  'Katana User' (Ctrl+U) or 'Katana' 
'Katana Administrator' (Ctrl+A)

29/187
2 Software Description

2.1.2 User management

If your logged in as Administrator, you manage the other users in the tab User management.
Per default there are the two users 'User' and 'Administrator' and two groups with the same names.

2.1.2.1 Users
You can create a new user by clicking New User.
Below the list of users you can edit the settings that concern the user directly.
• The name can be changed via the field Name.
• The password can be set in the field Password. You can also specify whether the user
should be able to change his password. If you activate that option, the user can change
his/her password via 'Katana'  'Change Password'.
• Finally the user has to be added to a group, which defines his rights.

Except for 'User' and 'Administrator', you can delete users using Delete User.

30/187
2 Software Description

2.1.2.2 Groups
Users are added to a group which defines what right the user has. Each user that belongs to a
group, has the same rights as the rest of the group. The following rights can be granted:
Recht Description
View Settings Page The tab Settings is available.
View NI-I/O Card Page The tab NI-Card is available (if a NI-card is available)
Use Hand Control Hand control can be used.
User Management Users and groups can be managed, rights can be given
and passwords can be changed.
View Project Page The tab Projects & Programs is available.
Create Project Projects can be created.
Edit Project Projects can be edited.
Delete Project Projects can be deleted.
Import Project Projects can be imported.
Export Project Projects can be exported.
Duplicate Project Projects can be duplicated.
Neuronal Network The user can use the neuronal networks. This right is only
available if the neuronal networks are enabled..
Execute Program Programs can be executed (In tab 'Projects & Programs')
Create Program Programs can be created.
Edit Program Programs can be edited.
Delete Program Programs can be deleted.
Import Program Programs can be imported.
Export Program Programs can be exported.
Duplicate Program Programs can be duplicated.
View Katana Page The tab Katana is available.
Create Katana An additional Katana can be created.
Delete Katana Katanas can be deleted.
Edit Katana Katanas can be edited.
Execute Application Applications can be executed.
Delete Application Applications can be deleted.
Create Application Applications can be created.

Note
Be careful when changing user privileges. If the administrator gets denied access to the user
management, it can't be undone!
All changes to user privileges will not take effect until the next login.

31/187
2 Software Description

2.1.3 Configuration

2.1.3.1 Change the language

The language of Katana4D can be changed using 'Katana'  'Change Language' (Ctrl+L) on the
start screen. A dialog that lets you choose the language will be opened. For the change to take
effect, it's necessary to restart Katana4D.
Note
To get to the start screen, click End.

2.1.3.2 The tab Configuration

Working mode
The working mode determines whether there is a Katana connected to the computer or not.
If set to Online, Katana4D tries to establish a connection to the Katana. Otherwise the specific
settings for the selected Katana are loaded, but no connection is made.
This option only specifies whether the user interface (e.g. The hand control) communicates with
the robot. You can still execute a program that uses the robot if it is set to offline.

Optimization
With this setting you can optimize the speed of your programs. If you only execute one program at
at time, select One Program, if you have multiple programs running at the same time (e.g. One
program that moves the robot and one program that monitors the I/Os of a SPS), select more than
one Program.

Import, Export, delete

This setting determines what happens to the contained programs, when a project is imported,
exported or deleted. The option Incl. Programs will cause the programs to be included in the
export/import/delte. Without Programs on the other hand excludes the programs from those
actions. (If a project is deleted without its programs, the programs are move to 'Without Project').
The third option, Ask me, will make Katana4D ask you what to do for each import/export/delete.

32/187
2 Software Description

Automatic check for new Firmware versions

If this option is activated, Katana4D will check the current firmware version of the robot each time it
connects to it, and tell you if it is out of date.

Automatic recognition of the available COM-ports

This setting determines whether the Com-ports are recognized automatically or if the user has to
do it manually. Automatic recognition may result in long delays on certain computers.
If No is selected, a list, in which the ports can be defined, appears below the radio buttons.

Datafile
Katana4D stores all your data (e.g. Katana settings, projects, programs, etc.) in one file. This file is
called 'Datafile' and has the file extension .4DD (4th dimension data file). The standard data file,
'Katana4D.4DD' can be found in the the directory 'Database' in the installation directory of
Katana4D. If you want to back up all your programs, it's sufficient to back up that file (about 2 MB),
because you can find everything else on the installation CD of Katana4D. To back up or share
individual projects, Katana4D has an export/import function in the tab Projects & Programs.
If you want to load a different Datafile, click Load existing datafile, and choose the desired .4DD
file.
If you want to create a new datafile click Create new datafile. You can then specify a name an
directory for the new datafile. If an empty datafile is loaded, the set up wizard will be run the next
time Katana4D is started.

33/187
2 Software Description

2.1.4 Structure

2.1.4.1 Projects / Programs

A project contains a number of definitions that are used in a program. Programs are part of a
project. A program accesses the Katana, that is assigned to the project and the values (e.g. Points,
grids) that are stored in the project.

2.1.4.2 Applications

Anwendung 1 Anwendung 2

Programm 1 Programm 1

Programm 2 Programm 3

An application is an independent layer to which programs can be added. When an application is

executed, all contained programs are run.

34/187
2 Software Description

2.1.5 Main calibration

2.1.5.1 Motors Navigation

By clicking the arrows, the corresponding motor moves to the left/right, (resp. up/down), according
to the set step size and the direction that was clicked.. (ENC = Encoder, DEG = degree). The
target position of the motors can also be entered directly into the corresponding fields. (Press All
motors to target position to move the robot to the entered position). Please be careful when
doing so.
When 'DEG' is selected, the motor angles, instead of the encoder values, can be set.
Hints
- Choose between 50 and 5000 Encoder values for the step size.
- Consider carefully whether Katana can really move to where you tell it to go, and if there are no
obstacles (or the ground!) in the way.

2.1.5.2 Space Navigation

Katana can also be controlled in a three dimensional Cartesian coordinate system. The origin of
the coordinate system is in the middle of joint number two, the Z-axis is the plumb line. To
unambiguously control Katana, the three angles phi, theta and psi are necessary. They define the
orientation of the gripper relative to the position in space. The units are in mm, resp. degrees. In
the fields on the right ('step size') the desired displacement/rotation can be entered. All motors to
target position move the robot to the entered position/orientation.
If 'Linear Movements' is selected, the robot move to the position linearly.

35/187
2 Software Description

2.1.5.3 Tool-Navigation
In the area 'Tool navigation', the robot can be moved relative to the tool coordinate system. The Z-
axis is along the tool, the Y-axis along the fingers.
The velocity and linear/non-linear settings of the space navigation are used.

2.1.5.4 Additional commands

All Motors off To move the robot by hand, you can turn off the motors with this button.
CAUTION: Hold on to the robot before turning off the motors!
All Motors ont Turns the motors back on. The robot will remain in the position you're holding
it at.
Open gripper Opens the gripper (If motor 6 is a gripper).
Close gripper Closes the gripper (If motor 6 is a gripper).
Main calibration Performs a main calibration. See section 'main calibration' for more details.
Read now Refreshes the motor and space position by reading them from the robot.

2.1.5.5 Main calibration

Each time the robot was cut off from electricity, the motors have to be recalibrated. This is done by
clicking Main Calibration. Main calibration means, that all motors are slowly moved to their
respective mechanical stops and in, that position, the encoders are set to their default values.
Use this function after a power outage, if the robot hit an obstacle or if a position can, for some
reason, not be reached accurately.

36/187
2 Software Description

2.2 Katana
In the tab Katana all you can find all setting of the robot. In the list on the left there is an entry for
each Katana profile you entered. For each Katana there are several configuration pages that will
be explained in the following sections.
The button New Katana lets you create a new Katana profile. Even if you only have one robot, it
can be helpful to have more than one profile, with different parameters, for it. This way you don't
have to change the parameters all the time, instead it's sufficient to just switch between profiles.
Press Print to print the selected robot profile.

2.2.1 General configuration Katana

The field Name shows the name of the profile. In the drop down menu below it, the type of Katana
has to be selected. It's very important, that this selection is correct, because a wrong selection
might result in unpredictable movements.
In the 'Katana Communication' part, the COM-port the robot is connected to can be selected. Only
the COM-ports, that windows recognized and are not currently in use, are shown. If the Katana is
connected over TCP/IP, you have to select this option and set the IP address and the port.
Collision Detection determines whether the robot stops when a collision is detected. For safety
reasons, it's recommended to always activate this option.
Below the collision detection you have to chose whether motor 6 of your robot is a gripper or a
turner. If there is no motor 6, 'gripper' has to be selected.
The field Strong Motor1 shows you, whether a strong or regular motor was used for motor 1.

37/187
2 Software Description

2.2.2 Gripper

2.2.2.1 Universal gripper

The standard finger is equipped with four infrared and 2 force sensors. Additionally, another
infrared sensor directly at the gripper is available.
If Read Gripper Sensor values is clicked, the current sensor values are written into the
corresponding fields. If Start is clicked, the sensor values are read continuously until Stop is
clicked.
The field Length of Gripper shows the length of the installed gripper.
In addition there you can also open or close the gripper by clicking Open gripper / Close Gripper.

2.2.2.2 Other grippers

Pendulum gripper
This type of gripper has an additional degree of freedom. Due to gravity, the chops are always
vertical. This lets the robot pick up objects independently of the orientation of the arm.

Vacuum gripper
The vacuum gripper is a gripper that is operated hydraulically This gripper doesn't need a motor.

38/187
2 Software Description

2.2.3 Sensors

In this window you can see all the values that are provided by the sensorboard.
If Read Gripper Sensor values is clicked, the current sensor values are written into the
corresponding fields. If Start is clicked, the sensor values are read continuously until Stop is
clicked.

2.2.3.1 Current Measure

Read Motors Current [mA]: The current in the individual joints are measured and displayed. The
range of the values is 0 to 255. These values are multiples of the actual current in the joints. Using
these, the maximum load of a joint can be measured.

2.2.3.2 Color sensor

The color sensor recognizes the color of an object. Before using it, the sensor has to be calibrated,
i.e. put a black piece of paper in front of the sensor and click Set black. Repeat with a white piece
of paper and Set white. Press Save to save the calibration values.

39/187
2 Software Description

2.2.4 Parameters

2.2.4.1 Katana Parameters

On the Katana Parameters page, the parameters of the robot are set. Only change these values if
you know what you are doing. More details on these values can be found in the Katana manual.
The button Load Standard values resets these values to their default value.

Set X-Axis
This function sets the positive X – Axis to the current position of the robot.

Define Origin
The origin of the base coordinate system that was described earlier can be moved. Move the robot
to any point in space and click Get current values.
You can now see the coordinates of the position in the three fields. Reset sets them back to the
last values that were stored, Reset to 0 sets them to zero and Confirm stores the values in the
X,Y,Z fields as the new origin.
Note
The values in the X,Y,Z fields are offsets relative to the default origin.

40/187
2 Software Description

2.2.4.2 Controller Parameters

Controller parameters are parameters that are stored on each motor controller of the robot.

A detailed description of these parameters can be found in the Katana manual.

2.2.4.3 Main Calibration Parameters

If the check box manual main calibration is activated, the main calibration is done by hand. This
means, that each joint is moved to its respective mechanical stop and the encoder values are then
read.

'Direction' specifies what direction the main calibration is performed at. If motor 6 is a gripper it
might be useful, if the gripper is opened instead of closed.
'Velocity' and 'Force' are the values the robot approaches the mechanical stops the second time to
set the encoder values.
Using the parameter 'Correction', the values can be corrected if they are not as desired.

41/187
2 Software Description

2.2.5 Firmware

By clicking Send command you can send a command in the field Send Katana Command directly
to the firmware on the robot. The commands that are displayed in the list below it can be written
into the Send Katana Command field directly by double clicking them.
The field Answer displays the answer received from the robot.

Example
The simplest command to test the connection to the robot is 'Z'. If the robot is connected and
received the command it will send back a lower case z'. The second row of the answer field shows
you the ASCII Code of the answer. In this case it is '122'.

A description of all commands can be found in the Katana manual.

2.2.5.1 Firmware Versions

Read Firmware: The firmware version (operation system for each individual joint). The master
board 'main' controls the individual slaves, 'motor 1' to 'motor 6' and has its own firmware. Normally
all slaves have the same firmware version, but in some special cases (e.g. if there is a strong
motor 1) that the versions don't match.
Sending commands directly to the robot and reading the firmware version helps the administrator
to identify communication problems. Our support team can help you quicker, if you know what
firmware version your robot is running.

42/187
2 Software Description

2.2.5.2 Firmware Update

You can update the firmware directly from Katana4D. Master, motors and the sensorboard can be
updated by clicking Update Firmware. After the update you have to perform a main calibration.
If there is an old firmware version on the robot, you will be notified about this at connection time. At
that point you will also be able to update directly.

43/187
2 Software Description

2.3 Applications
An application is an independent layer to which you can add programs that were created in
projects.

2.3.1 Structure of applications

An application consists of several programs. You can add as many programs to an application as
you want, but they all have to be in different projects. This restriction applies, because you cannot
have two programs, that use the same Katana, at the same time.

44/187
2 Software Description

2.3.2 Creating an application

To create a new application click New Application. After a name was entered, the application
appears in the list.
To add a program to an application, select the application and
click Add Program.

Select the program to be added and click OK.

To delete a program, select the program in the list and click Delete program.

You can move the order of the programs in a an application by using the buttons < and > . The
order the programs appear in is the order in which they are started by the application. I.e. a
program that does the initialization must be at the beginning of the list. etc.
You can also move the programs by Drag & Drop.

Delete Application deletes the whole application.

An application is always executed as a whole. When you click Execute, all programs in the
application are started according to their order in the application. I.e when the last program is
started, all programs run in parallel and the button Execute is replaced by Stop (which stops all
programs). It is not possible to run more than one application at a time.

45/187
2 Software Description

2.3.3 Helper functions

On the right side of the application window, the current Katana is selected. If you have more than
one Katana, you can select a different one in the drop down menu in the upper right corner.
In the bottom part the following functions are available:
Main calibration Performs a main calibration for the selected robot.
Move by hand The robot turns off all motor so you can move it by hand. At the end, all
motors are turned back on, so you can let go of the robot.
Open gripper Opens the gripper. (Only available if motor 6 is a gripper.)
Close gripper Closes the gripper. (Only available if motor 6 is a gripper.)

46/187
2 Software Description

2.4 Projects
A project contains a lot of information that can be used in its programs.

You can create a new program using the button New Project.

The first thing to do for a project is assign it a name. The name cannot be changed afterwards.

There are two ways of creating a project:

• Using the wizard (see chapter 'Katana4D wizard') or
• manually
The wizard is appropriate for beginners or for presentation since it enables you to create an
executable program very quickly. For more complex programs each part of the program has to be
modified manually.
A project consists of the following tabs:
• General
• Grids
• Points
• Paths
• Object recognition
In the following chapters each tab will be explained in detail.

47/187
2 Software Description

2.4.1 General

The fields Description, company and Author roughly describe the project so that the programmer
knows what the program is doing when he/she looks at it later. Filling out these fields is not
mandatory but strongly recommended. In the drop down menu Katana the robot to be used in this
project can be selected.

48/187
2 Software Description

2.4.2 Grid

2.4.2.1 General definitions

In a project points can be stored. These points can be independent from each other or arranged so
that they form a grid. If the distances between the point are equal and all points are on one plane,
the grid function can be used.
A project can contain as many grids as you want. Click New to create a new grid.

The name of the new grid can be entered into the field Grid-Name. The name has to be unique so
the grid can be used unambiguously in programs. You cannot change the name at a later point.
If you do need to change the name of a grid, copy the grid, assign the desired name to the new
grid and delete the old one.

49/187
2 Software Description

The grid is computed from 4 corner points (A, B, C and D) and the entered number of rows an
columns. The intermediate points are assigned a number between 1 and [number of columns X
number of rows]. By clicking Refresh Grid Image a graphical representation of the grid can be
displayed.
The image on the right helps the user to visualize the grid. It does not affect the functionality of
the grid. The numbers assigned to the points can be changed by activating the check box Inverse
Numbering.
Activating Complete with intermediate grid will result in additional points being added in between
the original points. The numbers assigned to the points will change accordingly.

The image has to be refreshed manually by

clicking Refresh Grid Image.

2.4.2.2 Extended Grid

If the desired grid is bigger than the one that results from the taught corner points (e.g. A circle
instead of a square) or the corner points cannot be taught, because there are no points at the
corners you will have to use the extended grid.

When you activate the check box extended grid The fields Number of Rows and Number of
Columns, of the extended grid appears..

The corners of the Teaching grid are taught, the corners of the Extended grid are computed. To
see the extended grid points, click Delete Points.

2.4.2.3 Deleting points of the grid

If not all points of the grid can be used, the respective points have to be deleted. Click Delete
Points to open the Delete Points window.

50/187
2 Software Description

On the image on the left, the points of the grid appear in black. In the field Delete points the
points to be deleted can be entered. Use semicolons to separate individual points and hyphens to
delete a range of points. To make sure you are deleting the correct points, you can hide and show
points first. To do so use the field Test Points and the buttons Hide Points and Show Points.

Example
“1-3;6“ is entered into the field Delete points.
The points 1,2,3 and 6 are deleted. Deleted points are shown in white.

51/187
2 Software Description

Click Refresh Grid to see the changes you made.

Click Confirm to store the changes you made and close the window.

2.4.2.4 Teach grid points and compute grid coordinates

Up till now we defined the grid but the actual points weren't created yet. Before the intermediate
points can be computed, the corner points have to be taught. Move the robot by hand to point A,
if necessary, correct the position using hand control. Since each point in space can be approached
with different orientations, the orientation of the gripper has to be stored as well. Click Teach
Angles to do so. This orientation will be used for all points. Repeat the teaching (except for storing
the angles!) with points B, C and D.
When you're done teaching, click Calculate Grid Coordinates to find the other points of the grid
and insert them into the list.

For testing you can move the robot to the individual points using Go to Point (Enter the number of
the point on the right). If the point is not accurate, it can be corrected by either entering values into
the fields X .. psi or moving the robot to the correct position using hand control and then clicking on
the 'Save' symbol on the right of the point in the list (Click onto the point in the list for the symbol to
appear). Show all shows all points of the list, because moving the robot to a point hides the points
in the list.

The grid is now created. Click Confirm to store the grid and close the window. The grid will then
appear in the list of grids. Click >> to edit the grid.

2.4.2.5 Special orientations

For some types of Katana there are additional ways to approach the points in the grid. The
orientation stays the same, but the position.
Katana6M_180 / Katana6Ms_180
adjust psi :
To keep the angle you specified before, motor 5 does not move when approaching points in the
grid., Activate adjust psi for motor five to move so that the gripper is always aligned in space in the

52/187
2 Software Description

same way.
Katana6M_90 / Katana6Ms_90
other run up angle :

For this type of robot you can have it move to the points in different orientations for each point. This
might be necessary, if not all points can be reached in a certain orientation.
activate other run up angle and click Edit:
Select the position you want to be at when approaching the points. Katana4D will compute the
corresponding orientation. The robot might not accurately go to the point you specified because of
mechanical constraints.

53/187
2 Software Description

2.4.3 Points

If the points you want to approach aren't in a grid, they are stored in the tab Points.
You can add as many points as you want, but each point in a project must have a unique name.
If If you click New , the window Point appears.

The field Name is mandatory. Move the robot to the desired position and, if necessary, correct it
using hand. Then click Get Current values to get the current encoder values and space
coordinates.
Click Confirm to store the point and close the window. The newly created point now appears in the
list.

Small changes can be entered directly into the fields X..Psi.

54/187
2 Software Description

When clicking a row in the list, the following buttons appear:

Opens the window Point to modify the point.

Moves the robot to the point (linear movement if specified).

Changes the values of the point to the current position of the robot (Caution!)
Delete Point (Caution!)

You can move the robot to the individual points for testing. The actions, i.e. the order in which the
robot should move to the individual points and what it should do there , is defined in the programs.

You can print the list by clicking Print.

You might change the Katana parameters (Main window -> Katana -> Parameter -> Katana) after
the point are taught. To make sure that you don't have to reteach the points, there are the two
functions Recalculate XYZ and Recalculate Enc.

Recalculate XYZ recalculates the space coordinates. Use this if you changed the Katana
parameters Angles at mechanical stop or Length.

Recalculate Enc recalculates the encoder values. Use this if you changed Encoder per 360° or
Start value.

55/187
2 Software Description

2.4.4 Path functions

2.4.4.1 Overview
Functions Graph Orientation of gripper Comment
Non linear Movements The orientation of the Often the robot will move
MoveToPos gripper is only defined at up and down in Z-
MoveToPosEnc
Ende the start and at the end. direction. Use linear
MoveToPosDeg movements if this is not
MoveDelta appropriate.
MoveRadial
MoveInToolDirection
MoveToGridPoint
MoveToGridPointDelta
MoveToPoint
MoveToPointDelta Start
MoveToPointEnc
Linear Movement The orientation of the The movement of the TCP
MoveToPosLin gripper is defined at the (Tool Center Point) is
MoveDeltaLin
Ende start and at the end. linear. If it is not possible
MoveDeltaLinUntil Between those two to reach one of the
MoveRadialLin points it changes intermediate points (incl.
MoveRadialLinUntil linearly. gripper orientation) that
MoveinToolDirectionLin Katana computed, an error
MoveToGridPointLin message will appear. In
MoveToGridPoinLinDelta this case, try a non linear
MoveToPointLin movement.
MoveToPointLinDelta Start
Paths Ende The orientation of the The robot stores a lot of
MoveAlongPath gripper is depends on points, incl. Gripper
how the path was orientation, while the path
Start taught. is recorded.

Blend- Motion Radiu The orientation of the In a blend motion, the

s
MoveLinMultipleBlend Punkt gripper is not changed robot doesn't move to the
during the movement. points accurately but,
instead, it moves by them
with the specified radius.

Circles The orientation of the You specify a start point

MoveToPointArc gripper is computed and end point and an
Z from the three points. intermediate point. The
The gripper changes its robot will move in a
orientation proportional circular motion from start
to how far along the to end via the intermediate
path it is. point.
Start Ende

56/187
2 Software Description

2.4.4.2 Paths

The path functions let you record a path while moving the robot by hand. When you're done
recording you can have the robot repeat the recorded path as often as you want. You can also
import a path from a text file.
Click New to create a new path.

The name of the path is specified at the beginning and cannot be changed later. If you specify a
start point, the robot will move to the start point before moving along the path you recorded.
(Caution, if you don't specify a start point, the motion will be started from wherever the robot is at
that moment) If you specify an end point, it will move to that point when done with the path.

57/187
2 Software Description

To specify the start or end point, activate the corresponding check box and either use the current
position by clicking Create or choose a point from the points list by clicking >>. If you create a new
point, it will be added to the list of points in the tab Points.

The start and end point also contain a position for motor 6. Using Adjust movement of motor 6,
when motor 6 should start moving towards the end position and when it should reach that position.
Those points in time are defined as percentages of the whole path.

Recording a path, step by step:

Enter the name into the field Name .
• If desired, select the start and/or stop point using >> or Create.
• Record Path
• The robot moves, after an alert, to the start point (if defined).
• After another alert, the motors are turned off and you can move it along the desired path.
• The CTRL key stops the recording and turns the motors back on. If an end point is defined,
the robot moves there.
When you're done recording, all intermediate points are shown in the list at the bottom. You can

58/187
2 Software Description

see the Encoder values and the point in time (Milliseconds after start) it was recorded at.

When you click a row in the table, the three known buttons Move to point, Store Position and
Delete Point appear.

In most cases, the recorded path is not optimal because when moving the robot by hand you make
a lot of little breaks that you don't want in the final motion. By clicking Optimize points you can
delete all points whose encoder values are closer to the previous point than the value specified in
the field Encoder-Difference. This value is different for each application. You will have to do some
testing to find the optimal number.

Import path:
It is also possible to import a path from a text file. Activate the radio button Import Path and then
click Import Path to select a file.
The text file can be generated using Export path.

Click Confirm to store the path and close the window. The path now appears in the list.

Repeat the path exactly as it was recorded.

Move along the path backwards. (Only available if an end point is defined).

59/187
2 Software Description

2.4.5 Trajectories

A trajectory is a path that consists of linear and circular (arcus) paths. These parts are connected
to each other and then executed without breaks in between.

A trajectory can consist of any number of paths.

Click New to create a new trajectory. The Trajectory window is opened.

60/187
2 Software Description

Click New to add a new part. A window to create the new part is opened.

Choose a type (linear/circular) and define the necessary points (start/end for linear, start/help/end
for circular paths).

To use an existing point, click >> to open a list with all available points. Otherwise click Create to
use the robots current position.

The starting point of a new part has to be the same as the end point of the part before it!

The velocity can be set for each part individually. If the difference between the velocities of two
neighboring parts is too big the robot might not move smoothly though.

Click Confirm to close the window and store the newly created part.

In the list on the left, a window, the window to edit a part can be opened using the >> button.

When a part in the list is selected, it can be deleted by clicking the button next to it. When
deleting a part, make sure the start and end point of the now neighboring parts are the same.

61/187
2 Software Description

Hint
When the robot moves along a trajectory that consists of more than one part, sharp corners are

smoothed, so that the desired velocity can be maintained. In the following graph you can see the
ideal path in blue and the real path in red. If the corner points have to be approached accurately,
trajectories cannot be used and the individual parts have to be programed individually.

Click Confirm to close the window and store the newly crated trajectory in the list of trajectories.

Move along the trajectory the way it was created

Move along the trajectory backwards.

Hint
Like grids, points and paths, trajectories are defined in a project, but they are used in programs.

62/187
2 Software Description

2.4.6 Object Recognition

The object recognition is based on neural networks. They are used as „learning machines“ in
Katana4D. Neural nets can be regarded as functions, which enable to allocate input data to a
desired output (e.g. a certain action) by training.
In the „Object“ section of the projects, these technology is used to identify a grasped object by the
sensor values and to typically place it correctly, according to the object classification.

The collection of the data (training samples) is done in a Training Set. In the background a three
dimensional network is generated:
1. Input Layer: Number of elements equals the number of sensors selected for the recognition
process.
2. Hidden layer: Is important especially at difficult learning problems, because this
intermediate layer allows nonlinear relations between input and output elements.
3. Output Layer: Represents the objects in the correct order (as sorted in the object table).
The training results in an adaptation of the connections between input and output (indirectly trough
the hidden layer) so that the sensor stimulation during grasping automatically activates that output
element which belongs to the respective object (the element shows a value close to 1). The other
output elements are maintained close to 0. The big advantage compared to a complete explicit
programming of all cases is:
• the sensor data have not to be analyzed in order to build the correct relations
• an unlimited number of objects can be trained
• different sensor modalities can be mixed
• training works even if the same object results in different sensor values in repetitive tasks
(e.g. because it is not grasped identically every time).
• Learning is easily obtained in a dialog with the user.

63/187
2 Software Description

64/187
2 Software Description

2.4.6.1 Objects
With New a new object is created in the object list. The standard name is „Object“, it can be
changed directly in the row. The order is important, because it directly relates to the according
output element of the trained network, and thus relates to the respective object grasped and the
according action of the robot.

All objects which are used in a training set of a project have to exist in the object list. On the other
hand, the training set has not to include all objects.

65/187
2 Software Description

2.4.6.2 Training Set

An unlimited number of training sets can be created. With New a training set windows appears
which allows to define the new training set.

The training sets carry an unique ID number, Field Number It is generated automatically and can't
be changed. The Name field Name is optional but useful to recognize it later in the training set list.
Project shows, to which project the training set is related. In the field Description thins training set
can be described more concretely, e.g., which objects should be recognized by which sensors. As
input for the object recognition, signals of the infrared and force sensors can be used as well the
position encoder values of the gripper's opening angle. By clicking on the field Sensor
Combination a list appears which allows to select a combination of the sensors for training of the
actual list of objects.

66/187
2 Software Description

• 1 All: All sensors including the position encoder

• 2 IR All: Sensors 0-1, 4-5, 8-9, 11, 12-13
• 3 Force All: Sensors 6-7,14-15
• 4 All inside: Sensors 0-1, 6-7, 8-9, 14-15
• 5 All outside: Sensors 4-5, 12-13
• 6 Select: The sensors can be selected individually
• 7 Encoder: only the position encoder
• 8 Force + Encoder: all force sensors plus the position encoder
• 9 IR + Encoder: All infrared sensors plus the position encoder

A Training set includes a neural network and a set of training samples, which serve as input for the
neural network.

67/187
2 Software Description

2.4.6.2.1 Training Samples

Before the neural network can be trained, training samples have to be collected. That means in the
case of object recognition with Katana, to gasp an object with the gripper and to give feedback to
the program about the current object.
Training samples can be logged in two ways:
• - directly in the window TrainingSet by Create New Training Sample or
• with the NN-Assistant within the program script (which includes the command „NN-Start“)
In the capture „NN Assistant“ the use of neural networks in the program script is explained.
After choosing Create New Training Sample the Hand Control appears in a new window. Hold the
object between the two fingers. Then close the gripper. Close the Hand Control window. Then you
can choose the correct object from a list which is automatically prompted.

Thereafter, a new trainings sample record is created and appears in the Training Sample list with
in the Training Set window.

To each training sample, has an identification number. Date and time are stored together with the
object name and the sample data (starting with the position encoder value, followed by the sensor
values in the order of the sensor numbers).
For each object to be recognized, at least one example has to be recorded. Objects which are
difficult to distinguish may need more examples than easy ones (here already one example per
object may be sufficient).
Important:
In order to obtain good training results, the sensors have to be activated correctly and in a way
which allows the neural net to categorize correctly.
• Force sensors: The object should press the gripper always at about the same positions
inside the fingers
• Opening angle (= position encoder): Be sure that the gripper is closed sufficiently in the
program script before staring the training sample
• IR-Sensors:make sure that the light conditions are similar for all training examples.
Although the visible light is filtered to a high amount, strong light surces (like spot lights at
exhibitions) can influence the infrared sensors. When the Katana station is moved from one

68/187
2 Software Description

place to another, a new training set might eventually be necessary for the new environment
conditions.
If the same object is trained more than one time, all objects should be presented once, and then a
second presentation is added. This is better than repeating the same object directly several times.
However, it is also possible to mix the training sample later by using Mix Samples. The new mix is
visible in the sample list; mix until the objects are well distributed. Sort samples allows to sort the
samples by the object names (notice: bad mix for learning!).
Export stores all training examples on the hard disk, while Import allows to load training samples
from the hard disk (to exchange samples between different Katana4D databases or between
different training sets of the same database).
Training samples can be removed by the delete button on the right side of the activated record.
Before the neural network can start learning, the training data has to be „normalized“, that is to be
transformed into values between -1 and 1 for the input layer. This is done when choosing the
button Create NN Training patterns. Notice that before doing so, a neural network has to be
created. This is done automatically, if not done manually with the New button in the Neural
Network dialog in the lower part of the Training Set window.

69/187
2 Software Description

2.4.6.2.2 The Neural Network

The neural network dialog is divided into two registers; Training and Configuration. By training,
the neural network learns to recall the desired objects. The windows also allows to observe the
training progress. The Configuration section allows a user with knowhow in the neural network
technology to check and modify the elements and connection of an individual network. This is,
however, not necessary for standard object recognition tasks.

70/187
2 Software Description

2.4.6.2.2.1 Training

Training can be done directly during runtime of a program (see NN-Assistant) or in this Training
window. A diagram shows the learning progress (which can be observed as a continuous reduction
of the error).
After using the button Learn in Steps the samples (the maximum equals the number of samples in
the training set) and the number of epochs (repetition of all chosen samples) can be set by chosen.
A Backpropagation network typically needs 1000 learning steps or more to categorize sufficiently.
If, e.g. 3 objects have to be trained and each was grasped two times during sample collection,
these are 6 samples. At 1000 epochs this equals 6000 learning steps to be performed by the
network. The Log Rate allows to set the number of points in the diagram for plotting the error
diagram. For easy tasks it is recommended to choose a low number, such as 20, so that the
progress during the first phase of learning (when the error decrease is mostly pronounced) is
visible.

The learning progress, indicated by the Square error (between desired and real output), is
continuously updated.
The learning process can be canceled by pressing the ALT (Windows) or Control (Mac) key.

71/187
2 Software Description

If the neural network is to be reset before learning, the button Set back NN can be used. The
weights (connection strengths between the elements of the multilayer network) are reset to a value
close to 0.
The learning rate influences the learning speed. 0.1 is a convenient value for most cases. For
difficult objects, this value may be reduced down to 0.01.
Square Error: The smaller the error, the better the network has learned Note that a square error of
about 0.05 to 0.01 is sufficient for a good categorization. Smaller values (e.g. 0.000000001) show
an even better learning result for the trained patterns, but may result in a worse performance with
additional examples (test patterns) because the generalization ability of the network decreases
when learning is too perfect.
Pattern:
The patterns in the list at the lower part of the window are use for training. They correspond with
the samples in the Training Set, but the values are normalised for the network.
After training, the network can directly be tested:
Using the Test Pattern command, a pattern is presented to the network. The ID number of the
input pattern can be chosen in the following dialog box. The winning output element is then shown
in the dialog box together with the object name.
Test Gripper Object does the same, but instead of a stored training pattern it is a real new input
which is presented to the neural network. As mentioned already, the conditions should be
comparable with those during the training phase: lightening conditions, position of grasping in the
fingers, and closing behavior of the fingers. If Katana4D is used in an offline mode, the user can
enter the values manually on the keyboard.

72/187
2 Software Description

2.4.6.2.2.2 Configuration

The neuronal elements (artificial neurons) and their activity are shown in the list Elements. The list
Connections thereafter shows the connection strengths („weights“) between the elements.
In the top part of the window, network structure and parameters are listed.
Network Type:
The network type „Backpropagation“ belongs to the „supervised“ networks. That means that,
during training, the desired output is presented to the network simultaneously with the respective
input. During learning, the network tries to correct the connection strengths such that the input
leads automatically to the correct activation of the output elements. In practical applications, the
object which was grasped is chosen from a list when the network decision was incorrect
(otherwise the user confirms that the decision was correct).
Connection Type:
A nonlinear function for the connection between the elements (transfer function) is necessary for
the general case, where objects are not linearly separable. The connection type sigmoidal fulfills
this need and allows a relatively simple calculation of the error of the network for each pattern
presented. The correction of the weights between the elements is based on the size of the error of
each output element.
In the second row in the upper part of the window, the number (#) of elements of the network
layers (Input, Hidden Layer1, Hidden Lyer2, Output Layer) are shown. The number of input
elements corresponds to the number of sensors used in the Training Set (see field „Sensor
Combination“ in the Training Set window). The number of output elements corresponds with the
number of objects defined in the project. The Bias element is used as a threshold function. The
parameter „Momentum“ causes (significantly when chosen relatively high, typically 0.9), that the

73/187
2 Software Description

last learning pattern influences the learning at the next training pattern, because the last
corrections of the weights are added to the calculated corrections in the actual correction process.
This leads to a more continuous learning progress. The „Gain“ parameter influences the inclination
of the sigmoid transfer function. This value may need a change (different from 0.5) only if the
learning progress does not show up which is seldom the case. The parameters 3-5 are not used
for the actual network type. They could be used, e.g. to change the learning rate dynamically
during in the course of the learning progress.

74/187
2 Software Description

2.4.6.3 Object recognition within a user Program

In order to use the „learning machine“ for the object recognition in a user program, this functionality
has to be included in the user script. Fortunately, this is quite easy.
If more than one Training Set has been created in the project, one of them has to be activated by
the „Default“ Checkbox.

In a program, only one (the default) training is used normally.

In the Katana command list, there are two commands available for the object recognition:
OR_Start and OR_Winner.
First, a normal script for the Katana movements has to be written, e.g. a pick & place application.
The Katana robot moves to the pick up position and grasps an object. After picking up the object,
the object recognition function is started with OR_Start. The object is then tried to be recognized
correctly. The recognized object is called „Winner“. The Variable OR_Winner contains the order
number of the winning object.
The winning objects usually influences the action of the robot, e.g. as follows:

75/187
2 Software Description

2.4.6.4 NN Assistant
In the previous chapter it is explained how the neural network learns from the training samples in
the project and how this function can be used in a program. By using the NN Assistant, it is easier
to record training samples and to let the neural network learn. This assistant helps the user by
means of a „question&answer game“ step by step for a complete object recognition procedure
including learning.
Three things are needed:
– In the project, all objects have to be created and an order number has to be given for each of
them
– Like described in the previous section, a Katana4D program script has to be written
– The command OR_Start() has to be used with the parameter value 1: OR_Start(1). This means
that the dialog is active. If OR_Start is sent without parameter or as OR_Start(2), no dialog will
appear.
To change from the learning to the recognition mode, only one parameter has to be changed in the
program: OR_Start(1) is changed to OR_Start(2).
The question&answer game starts as soon as an object has been grasped (if the command
OR_Start(1) is put at the correct place in the script). The dialog starts with the question „Do you
like to use the assistant for the Neural Network (NN)?”.

– Yes: The NN Assistant is available during the whole program execution.

– No: Training samples can be registered nevertheless. Only the learning functions are not used.

76/187
2 Software Description

The following question is prompted:

– Yes: All training examples in the default Training Set are deleted.

– No: The existing training samples are left in the table, and the new ones are added.

Afterwards, the grasped object is categorized. If the neural network has not learned yet, the object
winning output element is at random, and usually always the same object wins. Even if the
recognition is correct, it was chance level. The result is shown and the feedback whether correct or
incorrect can be given in the next dialog box.

– Yes: The object was recognized correctly.

– No: The object identification was incorrect. Therefore, a list of all objects defined in the project
will be shown, so that the user can indicate the correct one.

The correct object is chosen by a double click on the respective line. Next, the question appears

77/187
2 Software Description

whether the training sample should be stored.

– Yes: A new training sample is created in the default training set.

– No: The training sample will be skipped.

This recognize & store procedure will continue until the program is terminated (either by reaching
the chosen number of repetitions or when the Shift key is pressed to stop the program).
At the end, the NN Assistant prompts a dialog which allows to choose the number of training
samples and learning epochs.

– Reset NN: The connection strengths of the neural network are initialized, which means that the
network „forgets“ the previous learning.

– Continue learning: The learning is continued without initialization of the connection weights.

The number of recorded training samples are shown. A lower number will reduce the training

78/187
2 Software Description

samples used for the training accordingly.

In this field, the number of epochs are entered. This means how many times the whole set of
training samples is presented to the neural network during learning.

79/187
2 Software Description

During the learning phase, a window shows the current square error together with the epoch
number and the total epochs to be passed.

Now, learning has been finished. The result can be tested directly by setting the dialog parameter
off: NNstart(2) and starting the program again. It is also possible to have a look in the object tab of
the project, where all training samples should be listed in the default Training Set, and where the
learned neural network can be tested as well.

80/187
2 Software Description

2.4.7 Project functions in the main window

• Edit
The window to edit the project is opened. If the check boy Use Wizard is activated, the
wizard is used to edit the program. This is especially useful if the program was created
using the wizard.
• Duplicate
The project including all definitions is copied with a new name.
• Delete
The project is, after you confirm the alert, deleted permanently from the database.
Depending on the database settings (tab Configuration) the contained programs are
deleted or moved.
• Print
A window, in which you can select what to print, is opened.

When 'Programs' is selected, the additional

options in the frame below it are used for each
program in the project.

81/187
2 Software Description

• Export
The project with all its definitions is saved to disk. A new folder with the same name as the
project is created in the location you specify. Definitions are saved in *.4IE files, the main
window has the file extension .pj. If the programs are exported as well, folders for the
projects are created.

• Import Project
An exported project is imported back into Katana4D. If there already is a project with the
same name, you can decide whether you want to overwrite it or import the project with a
different name.

82/187
2 Software Description

2.5 Programs
In a program a sequence of movements of the robot are stored in terms of a script using Katana4D
commands and the definitions (Points, Grids, etc.) of the project the program is part of.

When you click New Program, the window Program is opened.

A program is part of a project. When you create a new program, the project that is selected in the
list is set as the parent project. This can be changed easily though.
You can also create a project that is not part of a program. To do so you have to either select
'Whiteout Project' in the list before creating the program or chose the empty entry when changing
the parent project of the program. Since Katanas are associated with a project, programs with no
parent project cannot use commands that use the robot.

83/187
2 Software Description

2.5.1 General

When you create a new program, the window Program is opened. Each program gets an unique
number. You can change this number though, by clicking Change and entering a new number.

If you enter a number that is already in use, Katana4D will

display an error message.

The field Name is mandatory. The name should identify the program. It appears next to the
program number in the main window. Author and Description should also be completed and the
parent project has to be selected in the drop down menu (Selecting the empty entry will result in
the program not having a parent project).

84/187
2 Software Description

2.5.2 Structure of the programs

A program consists of several scripts:
• Start script
• Sequences
• End script
• Methods
The start script is executed at the beginning of the program. After the start script the sequences
are executed as many times as specified. Finally, the end script is executed. Unlike the other
scripts, the user methods are not executed automatically, but only when they are called from one
of the other scripts.

85/187
2 Software Description

2.5.3 Stopping programs

There are six ways to stop a program:
• The program is automatically shut down when it is finished. In this case, the end script is
always executed.
• Pressing the SHIFT key stops the program. The end script is only executed if the option
Always execute end script in the tab Options is activated.
• If the Katana variables 'NotAus' or 'SaveAbort' are set to TRUE in a script or 'ExitProgram'
is called, the program is aborted.
NotAus:=TRUE: The robot is stopped immediately and the program is aborted.
SaveAbort:=TRUE: The current movement is finished and the program is aborted.
ExitProgram(1): Abort program 1
If a communication error occurs (e.g. If you unplug the serial cable or turn off the robot) the
program is aborted. In this case the end script is not executed.
• If the collision detection detects a collision Katana4D asks you whether you want to abort
the program.
• Clicking the End button, which appears when you execute a program, aborts the program.

86/187
2 Software Description

2.5.4 Katana4D Script

In Katana4D 'Script' describes a field with several lines of commands. Each line can contain a
command or be empty.
A command is one of the following:
• a comment
• a command from the list of commands (see 'Description of commands')
• a variable assignment
• a single row command of the 4D programming language.

87/187
2 Software Description

2.5.4.1 Comments in Katana4D

Comments are use to describe your code. A Comment starts with the „ ` “ character and lasts the
rest of the line. Comments are meant to make programs clearer to the programmer and are
completely ignored by the program.

88/187
2 Software Description

2.5.4.2 Katana commands

Below each script there is a list of katana commands.
There are 6 main categories:
• Action Commands
• State Checkings
• Katana Settings
• Interfaces
• Program Flow control
• Neuronal Network

Clicking the +sign opens the corresponding category. To add a command to the script, double click
it. A command may have several parameters. Details on the commands and parameters can be
found in the section “command description”. More commands are added to the program
successively.

89/187
2 Software Description

2.5.4.3 4D programming language

4th Dimension (4D) is the programming language Katana4D was written in. In the scripts all single
line commands of 4th Dimension can be used, but usually only the Katana commands are needed.
More details on 4th Dimension can be found in the document 4D_Language.pdf (~2000 pages).

90/187
2 Software Description

2.5.4.4 User variables

In Katana4D, a value can be assigned to and read from a variable.
To use them, open the appropriate category in the list “User variables” (bottom right) by clicking the
plus sign. The desired variable can then be added to the script by double clicking it. Use “:=” (colon
equal sign) to assign a value to the variable. Once the variable is assigned a value, it can be used
anywhere in the script. You can assign a new value by using “:=” again.
Katana4D will report a syntax error, if you are trying to use a variable without assigning a value to it
beforehand.
Example
VarInt1 := 1000
MoveMot(2;VarInt1) `Moves motor 2 to the position 1000

Variables are especially useful if a value is used several times and might be changed afterwards. If
the value is explicitly used each time (instead of using the variable), the value has to be changed
on every line it is being used, instead of just having to change it once on the line where the value is
being assigned to the variable.

Integer Only integers can be assigned to these variables. This means no decimal
(VarInt1-10) places are accepted. The range is – 231 to +231.

Example: VarInt1:=54
Number VarReal1 – 10 can store integers as well as number with decimal places. The
(VarReal1-10) range is – 231 to +231 with no more than 15 decimal places

Example. VarReal1:=54.587
Strings String variables can hold up to 255 characters. To assign a value, surround it
(VarStr1-10) by double quotes.

Example: VarStr1:=“abc-123-*%$“
Text variables These are the same as Strings, but they can hold up to 32'000 characters.
(VarText1-10)
Booleans These variables can only hold the two values True or False.
(VarBool1-10)
Example: VarBool1:=False
Files These variables can hold files. The files are being assigned to the variables
(VarFile1-10) using the command Open document (document; dataType).

Example: VarFile1:=Open document(“C:\test”; ”TXT”)

Katana Variables SaveAbort:=TRUE
(Boolean) stops the program and executes the user method “OnSaveAbort” if specified.

NOTAUS:=TRUE
Emergency stop
stops the program and the robot immediately and an alert, informing the user
that a emergency stop occurred, is being displayed.

<>SaveAbortAll and <>NotAusAll

are being used if more than one Katana is being used and all of them have to
be stopped.

91/187
2 Software Description

Interprocess-Variables It is possible to have Katana4D execute more than one program at the same
time. The communication between the individual programs can be done using
the interfaces or by using interprocess variables. The second way of
communicating is safer and faster. An interprocess variable can be use and
changed in every program.
To identify a variable as an interprocess variable, prefix its name with “<>”
Example: <>VarInt1:=4

92/187
2 Software Description

2.5.5 Start script and End script

The start script and end script look exactly the same. As said before, they are being executed at
the beginning and the end of the program.
The start script is usually used to initialize variables. It's also useful to move the robot to a certain
position before the sequences are started.

Examples
VarInt1:=7400 `Variable initialization: The encoder value for the open gripper.
MoveToPoint(“StartPosition“;150;1;100) `Moves the robot to the point „StartPosition“
...

In addition to the described Katana variables, the four more variables Velocity, Acceleration,
LinVelocity and Tolerance are predefined in the start script, because they are needed for most
action commands.
The end script is best used if the robot has to be moved to a safe position before the program
terminates. Of course this script can contain any kind of commands as well.

93/187
2 Software Description

2.5.6 Sequences

A program can contain any number of sequences. These sequences are scripts that are executed
sequentially between the start and the end script. It's recommended to separate the program into
several small sequences to make the program easier to understand. In additoin, separating the
program makes it easier to find error in the code, since the sequences can be turned on/off
individually and the order they are executed in can be changed.

New opens the window Sequence.

The sequence can be given a name in the field Name and a description of the sequence can be
added in the field Description. The name does not have to be a single word. When the sequence is
saved the name will appear in the list of sequences.
Since the sequences are executed automatically, their order has to be defined. (Field Order). The
sequence is only executed if the check box Execute is activated.

94/187
2 Software Description

The script of a sequence is no different from the start or end script. On the right you can see the list
of user variables and at the bottom the list of Katana commands is displayed. Since the points that
are stored in the corresponding project are used quite often, there is a direct link to the tab Points
of the window Projects. For the same reason there is the button Edit marked user method, which
opens the marked user method (see chapter “User methods”) if it exist.

Example
MoveToPos (X;Y;Z;Phi;Theta;Psi;150;1;100) `Moves the robot to the position X, Y, Z

When you confirm the sequence, the window is closed and the newly crated sequence appears in
the list of sequences.

95/187
2 Software Description

>> lets you edit the sequence and the two symbols on the right (only appear when you click the
row) delete or duplicate the sequence.

96/187
2 Software Description

2.5.7 User methods

User methods are scripts that are not executed automatically. They have to be started by the user
or by an occurring event.
User methods can be compared to functions that perform a specific task. They can be called in any
script by using RunUserMethod(“NameOfUserMethod“) or by using NameOfUserMethod
directly.

97/187
2 Software Description

2.5.7.1 Locale User Methods

Local user methods are created in a program and are only visible (and usable) inside that program.

98/187
2 Software Description

2.5.7.2 Global User Methods

Global user methods are created within a program but they are visible (in the list “Globale user
Methods”) and can be called by any program in Katana4D.
Local user methods have a higher priority than global ones. I.e. If there is a global and a local user
method with the same name, the local one is executed.
It's recommended to only make user methods global if they are used by other programs.

How to create a new user method (global or local):

Depending on what kind of user method you want to create, click the button New above the list
„local user methods“ or „global user methods“
The window Local User Methods is opened. This window looks very similar to the sequences
window, except that the fields for the order and the check box specifying whether the method
should be executed are missing.
After confirming the user method, the window is closed and the newly created user method
appears in the list.

99/187
2 Software Description

A user method can be edited by double clicking it. To delete or duplicate it, mark the method and
click the appropriate button. When a method is duplicated, the new method has the name of the
old one, followed by a “2”. This name can be changed though.

100/187
2 Software Description

2.5.7.3 Event driven methods

An event driven user method can be created or edited by double clicking it. When existing, the
symbol on its left is activated. When an even driven method is deleted, the symbol is deactivated
again.

OnStartMoving Is executed right before a MoveMot.. command is executed. (NOT before

MoveMot.. commands!)
OnMove Is executed until the end of the movement (NOT for MoveMot.. commands!)
OnEndMoving Is executed when the robot reached its target position. (NOT for MoveMot..
commands)
OnShiftDownStop Is executed after the program was stopped by the pressing the shift key.
OnCommunicationError Is executed if the program is stopped because of a communication error.
OnMotorCollision Is executed when a collision is reported by a motor. (If the collision alert is
turned on, this method is only executed if the alert is answered with „Yes“).
OnSaveAbort Is executed after the variable SaveAbort or <>SaveAbortAll is set to TRUE.
OnExecuteLine Is executed before any regular command is executed (Helpful for emergency
stop queries)
OnStartKatana4D Is executed when Katana4D is started.
OnLoginKatana4D Is executed when the user logs in.
OnLogoutKatana4D Is executed when the user logs out (i.e. When the start window is closed)

An event driven user method is almost the same as a regular user method except that you're not
allowed to change its name. If you do chnage the name, Katana4D treats it as a regular user
method.
After OnShiftDownStop, OnCommunicationError, OnMotorCollision and OnSaveAbort the program
is stopped. If the option always execute endscript is activated (default), the end script is executed
AFTER the event driven user method.
The global user methods can be saved to or loade from the harddisk with the Export and Import

101/187
2 Software Description

buttons. When exporting, the file „Globale Benutzermethoden.4IE“ is created. Local user methods
can't be exported in this window. They can be exported with the whole program though.
Print prints a list of the user methods.

The global user methods 'OnStartKatana4D', 'OnLoginKatana4D' and 'OnLogout Katana4D' can't
use a robot. If it is necessary to use a robot on startup, this can be moved to a program which can
be called from 'OnLoginKatana4D' by using the command 'RunProgram(Nr)'. A program can only
use a robot, if this robot is associated with the programs project.

102/187
2 Software Description

2.5.8 Options

When executing a program a window asking for the number of repetitions of the sequences
appears.

The default value “0“ means, that the program is executed until the user presses the SHIFT button
or clicks End This standard value can be changed in the field Repetitions of the sequences.
Activating Execute automatically results in the program being started without asking the
user for the number of repetitions.

If the program is stopped by the SHIFT key or by setting the variable SaveAbort to True, the end
script is only executed if Always execute endscript is activated.

If you don't want the user to be able to stop the program with the SHIFT key, activate Don't cancel
the program on pressing the shift key.
When Execute sequences individually, the individual sequences can be called individually.

103/187
2 Software Description

If Don't show a message when the robot has a collision is activated, the program is stopped
without an alert, if a collision occurs. This only makes sense, if you display your own alert in the
event driven user method 'OnMotorCollision' or Katana4D is controlled remotely.

Activating Check repositioning of joints will result in an alert being displayed if one of the joints has
to be repositioned. You can then decide, whether you want the program to continue or not.

Repositioning of joints 2,3 and 4 Repositioning of joint 1

To have Katana4D check whether a main calibration is necessary before running the program,
activate Check if main calibration is necessary. If this is activated and the main calibration is
necessary, a confirmation dialog is displayed to the user and, when confirmed, the main calibration
is performed.
If you don't want the confirmation dialog to be displayed, activate Execute automatically to have
Katana4D automatically perform a main calibration if necessary.

If Show messages during program progress is activated, all commands that are sent to Katana are
displayed on the screen.

Katana4D maintains a log in the background per default. Each time a program is executed, a file
called “log_ProgramNr” (e.g “log_6”) is created in the subdirectory 'Log' of the installation folder of
Katana4D. The following information is saved there:
• Date and Time at program start
• Program Number
• Number of repetitions entered at the beginning.
• All script commands that are executed.
• The actual number of repetitions, if the program was stopped prematurely.
• Error Messages (Reason for termination of program)

104/187
2 Software Description

If Advanced Log is activated, the robot position before and after all action commands is stored as
well. This makes the program slower, since reading the position takes about 20 ms. Therefore you
should only use this option for testing and debugging.
At this point of the tab, you can also specify the maximum size of the log file. This size is only for
this particular program. For each program a new file is created.
Reserved memory defines how much space is available to the program. The default value is
64'000. If Katana4D tells you that your program ran out of memory (stack, Stapelspeicher), this
value has to be increased.
You can search for a certain piece of code using Search. All scripts of the program are searched
and in the list below the button Katana4D displays in what program and what script the piece of
code was found.

If Search only in this program is not activated, all programs are searched for the desired piece of
code.

Click Confirm to close the window and store the newly created program in the list of programs.

105/187
2 Software Description

2.5.9 Program functions in the main window

The following functions are available:

• Execute
The program that is selected in the list is executed. (See chapter. “Stopping Programs“ for
termination conditions). When the program is started, the Execute button disappears and
the End button appears a little further to the right.
The program can be edited while it's running. The changes are applied in the next iteration
of the sequences. The project the program belongs to can only be read but not edited.
Other programs, which don't use a Katana that is already in use, can be started while a
program is already running. To do so, select the program you want to run in the list and
click Execute.
When a program is stopped, the Execute button reappears at its original position.

• Edit
The program window is opened so you can edit the program.

• Duplicate
The program is copied. The copy gets a new name and a new number.

• Delete
When confirmed, the program is deleted from the database for good.

106/187
2 Software Description

• Print
A dialog letting you decide what to print is displayed. When the desired items are selected,
click E OK to print them.

These options only apply to the selected

program.

• Export
The program and all its scripts (start script, end script, sequences and local user methods)
are stored to the hard disk. The user can select the directory to store them in. In that
directory, a new folder is created. In that folder 3 files are stored.

• Import program
The program and all its scripts are loaded from the hard disk into the database of
Katana4D. If there exists a program with the same number, the user has to decide whether
the old program should be overwritten or the new program given a new number. Select the
file ending with “.4pg” belonging to your program.

107/187
2 Software Description

2.6 Interfaces

108/187
2 Software Description

2.6.1 National Instruments Digital I/O Card

Short description
Communication via the I/O channels of a national instruments card.

Diagram

Pros / Cons
+ Many digital I/O channels
+ short reading/writing time
+ Simple control of non intelligent systems (valves, light barriers)
― Additional card / box has to be attached to computer
Requirement
• NI 6514 (PCI), NI DAQPad-6015 (USB) oder NI USB-6501

Technical Description

The most popular solution is based on a PCI-card with 32 digital I/O channels that can be supplied
externally by a maximum of 30V (75 mA to 350 mA per output channel). With this card (NI6514)
access times of 8ms can be achieved.
If a laptop is used to control the robot, the NI DAQPad-6015 card (8 digital I/Os, 16 analog input
channels, 2 analog output channels) or NI DAQPad-6016 card(32 digital I/Os, 16 analog input
channels, 2 analog output channels) can be used. These are external boxes that are connected to
the laptop using USB.

109/187
2 Software Description

Description of the input and output channels

NI 6514 (PCI)
Input K4D Pin GND Output K4D Pin GND VCC
1 1 P0.0 1 26 P4.0
2 2 P0.1 2 27 P4.1
3 3 P0.2 3 28 P4.2
4 4 P0.3 4 29 P4.3
9,10,11,12 34 35,36,37
5 5 P0.4 5 30 P4.4
6 6 P0.5 6 31 P4.5
7 7 P0.6 7 32 P4.6
8 8 P0.7 8 33 P4.7
9 13 P2.0 9 38 P6.0
10 14 P2.1 10 39 P6.1
11 15 P2.2 11 40 P6.2
12 16 P2.3 12 41 P6.3
21,22,23,24 46 47,48,49
13 17 P2.4 13 42 P6.4
14 18 P2.5 14 43 P6.5
15 19 P2.6 15 44 P6.6
16 20 P2.7 16 45 P6.7
17 51 P1.0 17 76 P5.0
18 52 P1.1 18 77 P5.1
19 53 P1.2 19 78 P5.2
20 54 P1.3 20 79 P5.3
59,60,61,62 84 85,86,87
21 55 P1.4 21 80 P5.4
22 56 P1.5 22 81 P5.5
23 57 P1.6 23 82 P5.6
24 58 P1.7 24 83 P5.7
25 63 P3.0 25 88 P7.0
26 64 P3.1 26 89 P7.1
27 65 P3.2 27 90 P7.2
28 66 P3.3 28 91 P7.3
71,72,73,74 96 97,98,99
29 67 P3.4 29 92 P7.4
30 68 P3.5 30 93 P7.5
31 69 P3.6 31 94 P7.6
32 70 P3.7 32 95 P7.7

NI DAQPad-6015 (USB)
Input K4D Pin GND Output K4D Pin GND
1 33 P0.0 1 33 P0.0
35 35
2 34 P0.1 2 34 P0.1
3 36 P0.2 3 36 P0.2
4 37 P0.3 39 4 37 P0.3 39
5 38 P0.4 5 38 P0.4
6 40 P0.5 6 40 P0.5
7 41 P0.6 43 7 41 P0.6 43
8 42 P0.7 8 42 P0.7

110/187
2 Software Description

NI USB-6501
Input K4D Pin GND Output K4D Pin GND
1 17 P0.0 1 17 P0.0
2 18 P0.1 2 18 P0.1
3 19 P0.2 3 19 P0.2
4 20 P0.3 4 20 P0.3
25,26 25,26
5 21 P0.4 5 21 P0.4
6 22 P0.5 6 22 P0.5
7 23 P0.6 7 23 P0.6
8 24 P0.7 8 24 P0.7
9 27 P1.0 9 27 P1.0
10 28 P1.1 10 28 P1.1
32 32
11 29 P1.2 11 29 P1.2
12 30 P1.3 12 30 P1.3
13 6 P1.4 13 6 P1.4
14 5 P1.5 14 5 P1.5
1 1
15 4 P1.6 15 4 P1.6
16 3 P1.7 16 3 P1.7
17 16 P2.0 17 16 P2.0
18 15 P2.1 18 15 P2.1
19 14 P2.2 19 14 P2.2
20 13 P2.3 20 13 P2.3
7,8 7,8
21 12 P2.4 21 12 P2.4
22 11 P2.5 22 11 P2.5
23 10 P2.6 23 10 P2.6
24 9 P2.7 24 9 P2.7

Usage in Katana4D
If a NI card is found, a new tab appears in the main window.
In the left column all found cards are listed. For each card the device number and its type are
displayed. The card can be selected by clicking on it.
At the top the inputs can be read. Their values are refreshed by clicking Read now. Below the
inputs the output channels can be set. The commands for using the NI cards in a script are
described in chapter “Command description”.

Note
On request other NI cards can be used. Up till now only the cards mentioned above are usable.

For now only the digital channels of the QPad-6015 (USB) can be used.

111/187
2 Software Description

2.6.2 Connector-Box

112/187
2 Software Description

Short description
Communication via the digital I/Os of the Katana connector box.

Diagram

Pros / Cons
+ Directly mounted to Katana
+ Very fast reading/writing
+ Simple control of non intelligent systems (valves, light barriers)
― Only two digital I/Os
Requirements
• Connector-Box

Technical Description
• For projects that only require a small number of I/Os.
• Access times are below 5ms.
• The maximum external supply is 30V and 1A.
Description of the input and output channels
Input K4D Pin GND Output K4D Pin GND
1 2 1 1 7 8
2 4 3 2 10 11

Usage in Katana4D
If a ConnectorBox was found, a new entry that can be selected appears in the Katana list.
On the left side, the input channels can be read. Click Read now to refresh the values. On
the right side the output channels can be set. The commands for using the NI cards in a
script are described in chapter “Command description”.

113/187
2 Software Description

2.6.3 File communication

Short description
Communication via a text file.

Diagram

Pros / Cons
+ Simple to program
+ Can be used for a lot of different applications
+ No hardware requirements
+ Can be used in a network
― External system must be able to use files
― Access to files must be controlled.
Requirement
• external system that can handle files

Technical Description
Several computers/processes access a common text file. Any kind of numbers or characters can
be written to or read from that file.

Note
The files interface can also be used to communicate with a camera.

114/187
2 Software Description

2.6.4 Serial communication

Short Description
Communication via the serial port

Diagram

Pros / Cons
+ Simple to program
+ Can be used for a lot of different applications
+ Several external systems can be controlled.
― Read and write access times can not be ensured.
Requirement
• free COM-Port
• RS-232 cable
• external system with a serial interface.

Technical Description
Katana can send and receive numbers or characters via a serial port.

Note
The RS232 interface can also be used to communicate with a camera.

115/187
2 Software Description

2.6.5 TCP/IP

Short Description
Communication via the network protocol TCP/IP.

Diagram

Pros / Cons
+ Can be used for a lot of different applications
+ fast data transport
+ Several external systems can be controlled
Requirement
• free network connection
• external system that can handle TCP/IP

Technical Description
Katana4D can send and receive numbers or character

Note
The TCP/IP interface can also be used to communicate with a camera.

116/187
2 Software Description

2.6.6 ModBus TCP

Short Description
Communication via the standard protocol ModbusTCP.

Schema

Pros / Cons
+ can be used for numerous applications.
+ very fast data exchange (<5ms per K4D command poss., depending on remote device)
+ allows data exchange between I/O modules, SPS etc. of different brands (if
ModbusTCP is supported) and Katana4D
Requirements
• free network connection
• Device that can act as a ModbusTCP client

Technical Description
Katana4D can send and receive numbers (16-bit per address) or individual bits.

117/187
2 Software Description

2.6.7 Web-Services

Short Description
Communication via a network

Diagram

Pros / Cons
+ Katana4D commands are used
+ The external system does the controlling.
― Slow communication
Requirement
• external system that can handle Web-Services.
• Network connection

Technical Description
Katana4D has an integrated web server which is started automatically when the software is
started. The web server provides the enabled Katana4D commands to the external system as an
XML file via the SOAP protocol. The XML file is available at the the following address:
http://IP-Adresse:123/4DWSDL
External systems, i. e. Development environments (e.g. MS Visual Studio) that support Web-
Services can read the XML file and display the available Katana4D commands which can then be
called.

Note
Web-Services can not be used at the same time as Katana4D.

118/187
2 Software Description

2.6.8 Siemens S7 – Plugin

Short Description
Communication with a Siemens S7 3xx

Diagram

Pros / Cons
+ simple way to exchange information between Katana4D and a Siemens S7 3xx or 4xx
+ Any data of the Siemens S7 3xx or 4xx can be accessed.
― Long access time (~. 45 ms per command)
― Additional box has to be attached to the computer permanently.
Requirements
• Siemens S7 3xx or 4xx
• Siemens S7 PC Adapter USB (Product-Nr. 6ES7972-0CB20-0XA0)

Technical Description
The data of the SPS are exchanged via a standard Siemens programming adapter. The adapter is
connected to the USB port of the computer and the MPI interface of the SPS. Katana4D can access
all data of the SPS (I/Os, markers, database) via predefined commands.
Note
For save usage of the the USB adapter, drivers version 1.2 has to be installed.
With some additional programming by Neuronics AG a Siemens S7 2xx could be used as well.
It might be necessary to adjust the settings for the PG/PC interface in the „Settings“ window of MS
Windows.

119/187
2 Software Description

Select “S7ONLINE” as the entry point of the application. The Interface parameters must be „PC
Adapter (MPI)“.

In the settings for the PC Adapter, select „USB“ for the local connection.

120/187
2 Software Description

2.6.9 Cognex Camera

Short Description
Communication with a camera system by Cognex.

Diagram

Pros / Cons
+ Fast visual recognition of objects
― Additional software (Training!) required.
Requirements
• Cognex Camera
• Camera software „InSight“

Technical Description
There are special commands to communicate with the InSight software, which controls the
camera. See chapter „Command description“ for more information.

Note

To communicate with other camera systems, it's best use a serial connection or a text file.

121/187
3 Command description

3 Command description

122/187
3 Command description

3.1 Action Commands

Path functions
Functions Graph Orientation of gripper Comment
Non linear Movements The orientation of the Often the robot will move
MoveToPos gripper is only defined at up and down in Z-
MoveToPosEnc
Ende the start and at the end. direction. Use linear
MoveToPosDeg movements if this is not
MoveDelta appropriate.
MoveRadial
MoveInToolDirection
MoveToGridPoint
MoveToGridPointDelta
MoveToPoint
MoveToPointDelta Start
MoveToPointEnc
Linear Movement The orientation of the The movement of the TCP
MoveToPosLin gripper is defined at the (Tool Center Point) is
MoveDeltaLin
Ende start and at the end. linear. If it is not possible
MoveDeltaLinUntil Between those two to reach one of the
MoveRadialLin points it changes intermediate points (incl.
MoveRadialLinUntil linearly. gripper orientation) that
MoveinToolDirectionLin Katana computed, an error
MoveToGridPointLin message will appear. In
MoveToGridPoinLinDelta this case, try a non linear
MoveToPointLin movement.
MoveToPointLinDelta Start
Ende
Paths The orientation of the The robot stores a lot of
MoveAlongPath gripper is depends on points, incl. Gripper
how the path was orientation, while the path
Start taught. is recorded.

Blend- Motion Radiu The orientation of the In a blend motion, the

s
MoveLinMultipleBlend Punkt gripper is not changed robot doesn't move to the
during the movement. points accurately but,
instead, it moves by them
with the specified radius.

Circles The orientation of the You specify a start point

MoveToPointArc gripper is computed and end point and an
Z from the three points. intermediate point. The
The gripper changes its robot will move in a
orientation proportional circular motion from start
to how far along the to end via the intermediate
path it is. point.
Start Ende

123/187
3 Command description

3.1.1 General Action commands

MoveMot
MoveMot (MotorNumber; TargetPosition)

Parameter Type Description

MotorNumber Integer Motor Number (1-6)
TargetPosition Integer Encoder value of target positionder Zielposition

Description
This is the simplest and fastest Motor command. The specified motor move to the specified
position. The program continues as soon as the command was sent to the robot. Subsequent
commands to the same motor will be executed immediately whether the motor has reached its
target position or not.

Example
MoveMot (2; -15000)

Moves motor 2 to position -15000

MoveMotAndWait
MoveMotAndWait (MotorNumber; TargetPosition; Tolerance)

Parameter Type Description

MotorNumber Integer Motor Number (1-6)
TargetPosition Integer Encoder value of target position
Tolerance Integer Encoder value of the tolerance

Description
Like MoveMot this command moves the specified motor to the specified target position, but it
waits for the motor to reach the target position (with the specified tolerance) before executing
the subsequent command.

Example
MoveMotAndWait (6; 6500; 100)

The gripper is being closed until it is within 100 encoders of 6500.

124/187
3 Command description

WaitForMot
WaitForMot (MotorNumber; TargetPosition; Tolerance)

Parameter Type Description

MotorNumber Integer Motor Number (1-6)
TargetPosition Integer Encoder value of target position
Tolerace Integer Encoder value of tolerance

Description
This command doesn't move anything, but it waits for the specified motor to reach the target
position within the specified tolerance.

Example
MoveMot (1; 15000)
WaitForMot (1; 15000; 100)

The above example could also be implemented by just using MoveMotAndWait.

MotorOff
MotorOff (MotorNumber)

Parameter Type Description

MotorNumber Integer Motor Number (1-6)

Description
Turns off the specified motor. This can be useful if the robot should yield in a certain axis when
picking up an object. The motor is turned back on by any other action command.

MotorFreeze
MotorFreeze (MotorNumber)

Parameter Type Description

MotorNumber Integer Motor Number (1-6)

Description
This command freezes the specified motor at its current position. It makes the current position
the target position.

125/187
3 Command description

MoveHome
MoveHome

Description
This command performs a full main calibration. It has the same effect as pressing the main
calibration button in Katana4D, except that no alert is displayed on completion.

AllMotorsOff
AllMotorsOff

Description
This command turns off all motor. To turn them back on, use command 'FreezeAllMotors'.

FreezeAllMotors
FreezeAllMotors

Description
Freezes all motors. I.e. all motors stop in their current position. To unfreez them, use comand
'AllMotorsOff'.

OpenGripper
OpenGripper {(Velocity{; PWM})}

Parameter Type Description

Velocity Integer Velocity (0-180)
PWM Integer Force (30-127)

Description
Opens the gripper until the mechanical stop is reached. With the optional parameters 'Velocity'
and 'PWM' the velocity and force of the movement can be adjusted.

CloseGripper
CloseGripper{(Velocity{; PWM})}

Parameter Type Description

Velocityt Integer Velocity (0-180)
PWM Integer Force (30-127)

Description
Closes the gripper until the mechanical stop is reached.Schliesst den Greifer auf einen
Anschlag. With the optional parameters 'Velocity' and 'PWM' the velocity and force of the
movement can be adjusted.

126/187
3 Command description

3.1.2 Approaching positions in space

These commands move the robot to specified positions in space. To specify the position variables
or constant encoder/space coordinates can be used.

Example

Combination of variables and constant values:

MoveToPosEnc(UL1;UL2;17884;4588;UL6;UL6)

MoveToPos
MoveToPos (X; Y; Z; Phi; Theta; Psi {; Velocity; Acceleration; Tolerance})

Parameter Type Description

X Real space coordinate X
Y Real space coordinate Y
Z Real space coordinate Z
Phi Real Euler Angle Phi
Theta Real Euler- Angle Theta
Psi Real Euler Angle Psi
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command moves the robot to the desired positiont. The movement of the individual axis
are coordinated, so that all axis get to the target position at the same time. The passed velocity
is used for the motor that has to move the biggest distance.

MoveToPosLin
MoveToPosLin (x; y; z; phi; theta; psi {; LinVelocity})

Parameter Type Description

X Real space coordinate X
Y Real space coordinate Y
Z Real space coordinate Z
Phi Real Euler angle Phi
Theta Real Euler angle Theta
Psi Real Euler anglel Psi
LinVelocity Integer Velocity of TCP in space (0-300)

Description
This command linearly moves the robot to a position in space.

Hint
The variable MoreMultiple can be used for this command. For more information see the
description of 'MoveToPointLin'.

127/187
3 Command description

MoveToPosEnc
Syntax for 6M:
MoveToPosEnc(Motor1; Motor2; Motor3; Motor4; Motor5; Motor6{; Velocity; Acceleration;
Tolerance})

Syntax for 5M:

MoveToPosEnc(Motor1; Motor2; Motor3; Motor4; Motor5{; Velocity; Acceleration; Tolerance})

Parameter Type Description

Motor1 Integer Encoder value for Motor 1
Motor2 Integer Encoder value for Motor 2
Motor3 Integer Encoder value for Motor 3
Motor4 Integer Encoder value for Motor 4
Motor5 Integer Encoder value for Motor 5
Motor6 Integer Encoder value for Motor 6
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
Moves every motor to the specified encoder value. The velocity of the individual motors are
coordinated, so they all get to the target encoder value at the same time. The specified velocity
is used for the motor that has to move the biggest distance.

MoveToPosDeg
MoveToPosEnc(Angle1; Angle2; Angle3; Angle4; Angle5; Angle6{; Velocity; Acceleration;
Tolerance})

Parameter Type Description

Angle1 Real Winkel von Gelenk 1
Angle2 Real Winkel von Gelenk 2
Angle3 Real Winkel von Gelenk 3
Angle4 Real Winkel von Gelenk 4
Angle5 Real Winkel von Gelenk 5
Angle6 Real Winkel von Gelenk 6
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command does the same as “MoveToPosEnc“, except that the angles of the motors
instead of encoder values are passed.

MoveDelta
MoveDelta (DeltaX; DeltaY; DeltaZ{; Velocity; Acceleration; Tolerance})

Parameter Type Description

DeltaX Real offset in x direction (mm)

128/187
3 Command description

DeltaY Real offset in y direction (mm)

DeltaZ Real offset in z direction (mm)
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command moves the robot to a position relative to its current position. The orientation of
the gripper stays the same.

Example
MoveDelta(0;0;10)

Moves the robot 10mm in z direction

MoveDeltaLin
MoveDeltaLin (DeltaX; DeltaY; DeltaZ{; LinVelocity})

Parameter Type Description

DeltaX Real offset in x direction (mm)
DeltaY Real offset in y direction (mm)
DeltaZ Real offset in z direction (mm)
LinVelocity Integer Velocity of the TCP in space(0-300)

Description
This command does the same as “ MoveDelta“, except that the tcp is moved linearly.

Example
MoveDeltaLin(0;0;10)

Moves the robot 10mm in z direction.

Hint
The variable MoreMultiple can be used for this command. For more information see the
description for 'MoveToPointLin'.

MoveRadial
MoveRadial (Distanz {; Velocity; Acceleration; Tolerance})

Parameter Type Description

Distance Real Distance (mm)
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
Depending on whether Distance is positiv or negativ, the robot is move away from or towards
axis 1.

Example

129/187
3 Command description

MoveRadial (-30; 150; 1; 250)

Moves the robot 30mm toward the axis 1.

MoveRadialLin
MoveRadialLin (Distanz {; LinVelocity})

Parameter Type Description

Distance Real Distance (mm)
LinVelocity Integer Velocity of the TCP in space (0-300)

Description
This command does the same as “ MoveRadial“, except that the TCP is moved linearly.

Example
MoveRadialLin(50; LinVelocity )

Linearly moves the robot 50mm aways from axis 1.

Hint
The variable MoreMultiple can be used for this command. For more information see the
description for 'MoveToPointLin'.

MoveInToolDirection
MoveInToolDirection (Distance {; Velocity; Acceleration; Tolerance})

Parameter Type Description

Distance Real Distance in Tool direction (mm)
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
The robot moves the specified distance in the direction of the tool. According to ISO 9787, the
+Z axis is the direction the gripper points in. The orientation stays the same.

Example
MoveInToolDirection (-10; 30; 1; 250)

The robot moves 1 cm in tool in the direction of the gripper.

MoveInToolDirectionLin
MoveInToolDirectionLin (Distance {; LinVelocity})

Parameter Type Description

Distance Real Distance in Tool direction

130/187
3 Command description

LinVelocity Integer Velocity of TCP in space (0-300)

Description
This command does the same as „MoveInToolDirection“, except that the TCP is moved linearly.

Example
MoveInToolDirectionLin (-10; 30; 1; 250)

The robot is linearly moved 1cm in tool direction.

Hint
The variable MoreMultiple can be used for this command. For more information see the
description for 'MoveToPointLin'.

131/187
3 Command description

3.1.3 Approaching Points in a grid

The commands in this paragraph are used to approach points that were created in the tab Grid.

When double clicking one of these commands, a window displaying all available grids is displayed.
Mark the grid you want to use and click OK.

MoveToGridPoint
MoveToGridPoint (Name; Number{; Velocity; Acceleration; Tolerance})

Parameter Type Description

Name String Name of Grid
Number Integer Number of Point int grid
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command moves the robot to the specified point in the specified grid.
All other parameters are optional. If the specified point can't be found, an alert is displayed and
the program is terminated. Internally this command uses “MoveToPos”

Example
MoveToGridPoint(„Grid 1“;1;100;1;100)

The first point in grid „Grid1“ is approached.

MoveToGridPointDelta
MoveToGridPointDelta(Name;Number;DeltaX;DeltaY;DeltaZ{;Velocity;Acceleration; Tolerance})

Parameter Type Description

Name String Name of grid
Number Integer Number of point in gird.
DeltaX Real Offset in X direction
DeltaY Real Offset in Y direction
DeltaZ Real Offset in Z direction

132/187
3 Command description

Velocity Integer Velocity (0-180)

Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command does the same as „MoveToGridPoint“, except that you can enter an offset.

MoveToGridPointLin
MoveToGridPointLin (Name; Number{; LinVelocity})

Parameter Type Description

Name String Name of grid
Number Integer Number of point in grid
LinVelocity Integer Velocity of TCP in space (0-300)

Description
Linear movement to a point in a grid. Internally this command uses MoveToPosLin(…)

Hint
The variable MoreMultiple can be used for this command. See the description of'
MoveToPointLin' for more information.

MoveToGridPointLinDelta
MoveToGridPointLinDelta (Name; Number; DeltaX; DeltaY; DeltaZ{; LinVelocity})

Parameter Type Description

Name String Name of grid
Number Integer Number of point in grid
DeltaX Real Offset in X direction
DeltaY Real Offset in Y direction
DeltaZ Real Offset in Z direction
LinVelocity Integer Velocity of TCP in space (0-300)

Description
A linear movement to a point in a grid with offset (DeltaX, DeltaY, DeltaZ).

Hint
The variable MoreMultiple can be used for this command. See the description of'
MoveToPointLin' for more information.

133/187
3 Command description

3.1.4 Approaching points in space

The commands in this chapter use the points that were created in the project.
When double clicking one of these commands, a window displaying all available points is
displayed. Mark the point you want to use and click OK.

MoveToPoint
MoveToPoint (Name{; Velocity; Acceleration; Tolerance})

Parameter Type Description

Name String Name of point to approach
Velocity Integer Velocity to approach the point with (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This command moves the robot to a specified point. All other parameters are optional. If the
specified point is not found, an error message is displayed and the program is stopped.
Internally this command uses „MoveToPos(..).“

Example
MoveToPoint(“PunktAboveBolt“;80;1;100)

MoveToPointDelta
MoveToPointDelta (Name; DeltaX; DeltaY; DeltaZ{;Velocity; Acceleration; Tolerance})

Parameter Type Description

Name String Name of point to approach
DeltaX Real Offset in X direction
DeltaY Real Offset in Y direction
DeltaZ Real Offset in Z direction
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)

134/187
3 Command description

Tolerance Integer Tolerance (1-...)

Description
The specified point is approached with an offset of (DeltaX, DeltaY, DeltaZ). This command is
useful when followed with an linear movement to approach a point accurately.
+

Example
MoveToPointDelta(“PointAboveBolt“;0;0;30;80;1;100)

The robot moves to the point 30mm above the point „PointAboveBolt“.

MoveToPointEnc
MoveToPointEnc (Name{;Velocity; Acceleration; Tolerance})

Parameter Type Description

Name String Name of point to approach
Velocity Integer Velocity (0-180)
Acceleration Integer Acceleration (1-4)
Tolerance Integer Tolerance (1-...)

Description
This is the same as “MoveToPoint“, except that the encoder values instead of the point in space
is approached and motor 6 (the gripper) moves to the encoder values stored in the point instead
of keeping its current position. Internally, this command uses “MoveToPosEnc(…)“.

Example
MoveToPointEnc(„PointAboveBolt“;200;1;100)

MoveToPointLin
MoveToPointLin (Name{; LinVelocity}{; Percentage})

Parameter Type Description

Name String Name of point to approach
LinVelocity Integer Velocity of TCP in space (0-300)
Percentage Real Percentage of path (0-1)

Description
This command moves the robot linearly to the specified point. Percentage tells the command
how much of the path to the point it should move the robot (e.g. 1 = 100%; 0.5 = 50% of the
path). Internally the command uses “MovoToPosLin(…)“.

Example
MoveToPointLin(“PointAboveBolt“;80)

Hint
The system variable „MoreMultiple“ can be set to true before this command. This means that
the next linear movement is executed directly when this command is executed (The robot
doesn't stop between the two movements).

135/187
3 Command description

Approaching three points with this optimization would look as follows:

MoreMultiple:=True
MoveToPointLin (“IntermediatePoint“;120)
MoreMultiple:=True
MoveToPointLin (“BeforePickUP“;80)
MoveToPointLin (“PickUp“;60)

The commands 'MoveToPointLin (“IntermediatePoint“;120)' and 'MoveToPointLin

(“BeforePickUP“;80)' are completed after the command is sent (and while the robot is still
moving). 'MoveToPointLin (“PickUP“;60)' on the other hand waits for the movement to be
complete before completing, because 'MoreMultiple' is NOT set to true directly before it.
If you want to end a set of linear movements, don't set 'MoreMultiple' to TRUE before the last
command.
MoreMultiple can be used for all linear movements as well as for 'MoveLinMultipleBlend',
'MoveAlongPath', 'MoveToPointArc' und 'MoveTrajecory'.

MoveToPointLinDelta
MoveToPointLinDelta (Name; DeltaX; DeltaY; DeltaZ{; LinVelocity})

Parameter Type Description

Name String Name of point to approach
DeltaX Real Offset in X direction
DeltaY Real Offset in Y direction
DeltaZ Real Offset in Z direction
LinVelocity Integer Velocity of TCP in space (0-300)

Description
The specified point is approached with an offset of (DeltaX; DeltaY; DeltaZ).

Example
MoveToPointLinDelta(“PointAboveBolt“;0;0;-30;80)

Hint
The variable MoreMultiple can be used for this command. For more information see the
description of 'MoveToPointLin'.

136/187
3 Command description

MoveLinMultipleBlend
MoveLinMultipleBlend (BlendVelocity; Radius;Point1;Pointt2{;Point3}{;Point4}{;Point5}{; Point6})

Parameter Type Description

BlendVelocity Integer velocity (0-400)
Radius Integer Blending radius (0-50)
Point1 String Name of Point 1
Point2 String Name of Point 2
Point3 String Name of Point 3
Point4 String Name of Point 4
Point5 String Name of Point 5
Point6 String Name of Poitn 6

Description
With this command up to 6 points can be approached linearly without stopping. The blending
radius defines how close the path passes by the points. The smaller the number the closer to
the points the robot passes.

Example
MoveLinMultipleBlend (200;20;“Point1“;“Point2“;“Point3“)

Hint
The variable MoreMultiple can be used for this command. For more information see the
description of 'MoveToPointLin'.

137/187
3 Command description

MoveToPointArc
MoveToPointArc (Startpoint; Endpoint; Helppoint; LinVelocity{; NoStartpoint})

Parameter Type Description

Startpoint String Name of Startpoint
Endpoint String Name of Endpoint
Helppoint String Name of Helppoint
LinVelocity Integer Velocity of TCP in space (0-300)
NoStartpoint -1/1 with/without Startpointt

Description
This command move the robot along a circular path from the start point to the end point via the
help point. If you made sure that the robot is at the start point when this command is called, you
can set the 5th parameter to 1. If you don't do this, Katana will move to the start point even if it's
already there.

Beispiel
MoveToPointArc (“Start“;“Ende“;“Z“;200)

Hint
The variable MoreMultiple can be used for this command. This only works, if the robot is already
at the start position though. (I.e. If 'MoreMultiple' is set to true, the robot will NOT move the the
start point before moving along the circular path, even if the fifth parameter is set to -1).

For more information on 'MoreMultiple' see the description of 'MoveToPointLin'.

138/187
3 Command description

3.1.5 Moving along paths

MoveAlongPath
MoveAlongPath (Name; PathsVelocity{; Direction}{; NoStartpoint})

Parameter Type Description

Name String Name of path
PathsVelocity Integer Velocity in relation to recording
Direction -1/1 backwards/forward (compared to direction of recording)
NoStartpoint -1/1 with/without Startpoint

Description
This command moves the robot along a path that was stored in the project. The velocity
depends on how fast the robot was moved when the path was recorded (Original velocity is
100%) Good values for this are usually between 5 and 1000. The robot will not move smoothly if
the velocity is too high, so move to the limit carefully.
The third (and optional) parameter specifies what direction the path should be followed in..
If you make sure the robot is at the correct start point when this command is called, you can
pass '1' for the 4th parameter. In this case the robot will start the path from its current position
instead of moving to the start point first. This can optimize the speed of the program, because
the robot will try to move to the start point even if it's already there, if this optimization is omitted.

Example
MoveAlongPath("TestPath";400;-1;1)

The robot is moved backwards along the path 'TestPath' four times as fast the the path was
recorded, without moving to the start point (or, in this case, the end point) first.

Hint
The variable MoreMultiple can be used for this command. This only works, if the robot is already
at the start position though. (I.e. If 'MoreMultiple' is set to true, the robot will NOT move the the
start point before moving along the path, even if the fourth parameter is set to -1).

For more information on 'MoreMultiple' see the description of 'MoveToPointLin'.

139/187
3 Command description

3.1.6 Moving along a trajectory

MoveTrajectory
MoveTrajectory (Name{; Velocity{; Direction{; NoStartPoint}}})

Parameter Type Description

Name String Name of trajectory
Velocity Integer percentage of defined default velocity
Direction -1/1 backwards/forward
NoStartpoint -1/1 with/without start point

Description
This command move the robot along a specified. The velocity depends on the velocity that is
stored in the trajectory. 100% means the robot is moved with the same velocity as defined in the
trajectory (this is also the default value).
The third (and optional) parameter tells the robot whether it should move forward or backward
along the trajectory.
If you made sure the robot is at the starting point, you can pass 1 as the fourth parameter. If you
don't do this, the robot is first trying to reach the starting point, even if it's already there.

Example
MoveTrajectory("TC1")

Moves the robot along the trajectory „TC1“.

Hint
he variable MoreMultiple can be used for this command. This only works, if the robot is already
at the start position though. (I.e. If 'MoreMultiple' is set to true, the robot will NOT move the the
start point before moving along the path, even if the fourth parameter is set to -1).

For more information on 'MoreMultiple' see the description of 'MoveToPointLin'.

140/187
3 Command description

3.1.7 Project Control

Points

GetPoint
GetPoint (Name; ->X; ->Y; ->Z; ->Phi; ->Theta; ->Psi)

Parameter Type Description

Name String Name of point
->X Real X coordinate
->Y Real Y coordinate
->Z Real Z coordinate
->Phi Real angle Phi
->Theta Real angle Theta
->Psi Real angle Psi

Description
Reads the space coordinates and angles of the specified point.

Beispiel
GetPoint("Start";->X;->Y;->Z;->Phi;->Theta;->Psi)
SavePoint("Start_copy";X;Y;Z;Phi;Theta;Psi)

Reads the values of point „Starts“ and stores them in the point „Start_copy“.

GetPointEnc
GetPointEnc (Name; ->Enc1; ->Enc2; ->Enc3; ->Enc4; ->Enc5; ->Enc6)

Parameter Type Description

Name String Name of Point
->Enc1 Integer Encoder value of motor 1
->Enc2 Integer Encoder value of motor 2
->Enc3 Integer Encoder value of motor 3
->Enc4 Integer Encoder value of motor 4
->Enc5 Integer Encoder value of motor 5
->Enc6 Integer Encoder value of motor 6

Description
Reads the encoder values of the specified point.

Example
GetPointEnc("Start";->Enc1;->Enc2;->Enc3;->Enc4;->Enc5;->Enc6)
SavePointEnc("Start_copy2";Enc1+30000;Enc2;Enc3;Enc4;Enc5;Enc6)

Reads the values of point „Starts“ and stores them in the point „Start_copy“.

141/187
3 Command description

SavePoint
SavePoint (Name; X; Y; Z; Phi; Theta; Psi) -> Boolean

Parameter Type Description

Name String Name of point
X Real X coordinate
Y Real Y coordinate
Z Real Z coordinate
Phi Real angle Phi
Theta Real angle Theta
Psi Real angle Psi
return value Boolean was storing successful?

Description
This command stores a point in the point list of the project the program belongs to. If the point
already exists, the values are overwritten, if not a new point is created.
The encoder values corresponding to the coordinates and angles are computed and then
stored.
If this succeeded, the command returns true. If the point can't be reached by the robot, the point
is not stored and the command returns false.

Example
GetPoint("Start";->X;->Y;->Z;->Phi;->Theta;->Psi)
SavePoint("Start_copy";X;Y;Z;Phi;Theta;Psi)

Reads the values of point „Starts“ and stores them in the point „Start_copy“.

Hint
When calculating the encoder values, the first solution is used. This may result in the robot not
positioning itself as desired. In that case, „SavePointEnc“ has to be used.

SavePointEnc
SavePointEnc (Name; Enc1; Enc2; Enc3; Enc4; Enc5; Enc6) ->Boolean

Parameter Type Description

Name String Name of point
Enc1 Integer Encoder value of motor 1
Enc2 Integer Encoder value of motor 2
Enc3 Integer Encoder value of motor 3
Enc4 Integer Encoder value of motor 4
Enc5 Integer Encoder value of motor 5
Enc6 Integer Encoder value of motor 6
return value Boolean was storing successful?

Description
This command stores a point in the point list of the project the program belongs to. If the point
already exists, the values are overwritten, if not a new point is created.
The space coordinates and angles are computed and stored as well.
If this succeeded, the command returns true. If the point can't be reached by the robot, the point
is not stored and the command returns false.

142/187
3 Command description

Example
GetPointEnc("Start";->Enc1;->Enc2;->Enc3;->Enc4;->Enc5;->Enc6)
SavePointEnc("Start_copy2";Enc1+30000;Enc2;Enc3;Enc4;Enc5;Enc6)

Reads the values of point „Starts“ and stores them in the point „Start_copy“.

Grids

GetGridPoint
GetGridPoint (Name; Number; ->X; ->Y; ->Z; ->Phi; ->Theta; ->Psi)

Parameter Type Description

Name String Name of grid
Number Integer Number of point
->X Real X coordinate
->Y Real Y coordinate
->Z Real Z coordinate
->Phi Real angle Phi
->Theta Real angle Theta
->Psi Real angle Psi

Description
Returns the space coordinates and angles of a specified point in a specified grid in the project
the program belongs to.

Example
GetGridPoint("Grid1"; 1;->X;->Y;->Z;->Phi;->Theta;->Psi)
SaveGridPoint("Grid1"; 2;X;Y;Z;Phi;Theta;Psi)

Reads the values of point 1 in grid „Grid1“ and stores them in point 2.

GetGridPointEnc
GetGridPointEnc (Name; Number; ->Enc1; ->Enc2; ->Enc3; ->Enc4; ->Enc5; ->Enc6)

Parameter Type Description

Name String Name of grid
Number Integer Number of point
->Enc1 Integer Encoder value of motor 1
->Enc2 Integer Encoder value of motor 2
->Enc3 Integer Encoder value of motor 3
->Enc4 Integer Encoder value of motor 4
->Enc5 Integer Encoder value of motor 5
->Enc6 Integer Encoder value of motor 6

143/187
3 Command description

Description
Reads the encoder values of a specified grid point of the project the program belongs to.

Example
GetGridPointEnc("Grid1"; 1;->Enc1;->Enc2;->Enc3;->Enc4;->Enc5;->Enc6)
SaveGridPointEnc("Grid1"; 2;Enc1+30000;Enc2;Enc3;Enc4;Enc5;Enc6)

Reads the values of point 1 in grid „Grid1“ and stores them in point 2.

SaveGridPoint
SaveGridPoint (Name; Number; X; Y; Z; Phi; Theta; Psi) -> Boolean

Parameter Typ Description

Name String Name of grid
Number Integer Number of point
X Real X coordinate
Y Real Y coordinate
Z Real Z coordinate
Phi Real angle Phi
Theta Real angle Theta
Psi Real angle Psi
return value Boolean was storing successful?

Description
This command stores a specified point in a specified grid. Points can only be overwritten but not
created.
The encoder values corresponding to the coordinates and angles are computed and then
stored.
If this succeeded, the command returns true. If the point can't be reached by the robot, the point
is not stored and the command returns false.

Example
GetGridPoint("Grid1"; 1;->X;->Y;->Z;->Phi;->Theta;->Psi)
SaveGridPoint("Grid1"; 2;X;Y;Z;Phi;Theta;Psi)

Reads the values of point 1 in grid „Grid1“ and stores them in point 2.

Hint
When calculating the encoder values, the first solution is used. This may result in the robot not
positioning itself as desired. In that case, „SaveGridPointEnc“ has to be used.

SaveGridPointEnc
SavePointEnc (Name; Number, Enc1; Enc2; Enc3; Enc4; Enc5; Enc6) ->Boolean

Parameter Typ Description

Name String Name of grid
Number Integer Number of point
Enc1 Integer Encoder value motor 1
Enc2 Integer Encoder value motor 2

144/187
3 Command description

Enc3 Integer Encoder value of motor 3

Enc4 Integer Encoder value of motor 4
Enc5 Integer Encoder value of motor 5
Enc6 Integer Encoder value of motor 6
return value Boolean was storing successful?

Description
This command stores a specified point in a specified grid. Points can only be overwritten but not
created.
The space coordinates and angles are computed and stored as well.
If this succeeded, the command returns true. If the point can't be reached by the robot, the point
is not stored and the command returns false.

Example
GetGridPointEnc("Grid1"; 1;->Enc1;->Enc2;->Enc3;->Enc4;->Enc5;->Enc6)
SaveGridPointEnc("Grid1"; 2;Enc1+30000;Enc2;Enc3;Enc4;Enc5;Enc6)

Reads the values of point 1 in grid „Grid1“ and stores them in point 2.

145/187
3 Command description

3.2 State checkings

ReadCoordinates
ReadCoordinates (->X; ->Y; ->Z; ->Phi; ->Theta; ->Psi)

Parameter Type Description

X Real space coordinate X
Y Real space coordinate Y
Z Real space coordinate Z
Phi Real angle Phi
Theta Real angle Theta
Psi Real angle Psi

Description
Gets the current space coordinates and angles.

Example
ReadCoordinates(->X;->Y;->Z;->Phi;->Theta;->Psi)
MoveToPos (X; Y; Z; Phi; Theta; Psi+20; 100; 1; 100)

Reads the current position and moves to that position, but changes Psi by 20 degrees.

ReadMotorPos
ReadMotorPos (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer Encoder value of motor

Description
Returns the current encoder value of the specified motor.

Example
VarInt1 := ReadMotorPos (3)

The current encoder value of motor 3 is stored in VarInt1.

146/187
3 Command description

ReadEncoders
ReadEncoders (->Enc1; ->Enc2; ->Enc3; ->Enc4; ->Enc5; ->Enc6)

Parameter Type Description

Enc1 Integer Encoder value of motor 1
Enc2 Integer Encoder value of motor 2
Enc3 Integer Encoder value of motor 3
Enc4 Integer Encoder value of motor 4
Enc5 Integer Encoder value of motor 5
Enc6 Integer Encoder value of motor 6

Description
Returns the current values of all encoders.

Example
ReadCoordinates (->Enc1; ->Enc2; ->Enc3; ->Enc4; ->Enc5; ->Enc6)
MoveToPosEnc (Enc1; Enc2; Enc3; Enc4; Enc5; Enc6+100; 100; 1; 100)

Reads the current encoder values and moves to the same position except that motor 6 is
moved by 100 encoders.

ReadMotorStatus
ReadMotorStatus (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer Status of specified motor

Description
Returns the current status of the specified motor.

0 = off
8 = in desired position
24 = moving to desired position.
40 = stopped because of a collision.
88 = finished linear movement.
128 = invalid motor data (internal communication error)

ReadActualVel
ReadActualVel (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer Current velocity of specified motor.

147/187
3 Command description

Description
Returns the current velocity of the specified motor.

Example
VarInt1:= ReadActualVel (5)

The current velocity of motor 5 is stored in VarInt1.

ReadMaxVel
ReadMaxVel (MotorNumber {; ->VarInt2; ->VarInt3}) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
->VarInt2 Integer maximum positive velocity of motor.
->VarInt3 Integer maximum negative velocity of motor.
return value Integer maximum positive velocity of motor.

Description
Returns the maximum velocity of the specified motor. If you want to know the maximum velocity
in both directions, two output parameters (prefix name with '->') have to be passed to the
command. After the execution of the command, those two variables contain the two velocities.

Example
VarInt1 := ReadMaxVel (3)
The maximum positive velocity of motor 3 is stored in VarInt1.

ReadMaxVel (2; ->VarInt1; ->VarInt2)

The maximum velocity of motor 2 in both directions is stored in VarInt1 and VarInt2.

ReadActualPWM
ReadActualPWM (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer PWM of motor

Description
Returns current PWM of the specified motor.

Example
VarInt1:= ReadActualVel (2)

The current PWM of motor 2 is stored in VarInt1.

ReadMaxPWM
ReadMaxPWM (MotorNumber {; ->VarInt2; ->VarInt3}) -> Integer

148/187
3 Command description

Parameter Type Description

MotorNumber Integer Number of motor
->VarInt2 Integer maximum positive PWM of motor
->VarInt3 Integer maximum negative PWM of motor
return value Integer maximum positive PWM of motor

Description
Returns the maximum PWM of the specified motor. If you want to know the maximum PWM in
both directions, two output parameters (prefix name with '->') have to be passed to the
command. After the execution of the command, those two variables contain the two PWMs.

Example
VarInt1 := ReadMaxPWM (6)
Den maximale positive PWM des Motors 6 ermitteln.

ReadMaxPWM (5; ->VarInt1; ->VarInt2)

Den PWM-Wert in beide Richtungen des Motors 5 ermitteln.

ReadMaxAcc
ReadMaxAcc (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer maximum acceleration of specified motor

Description
Returns the maxim acceleration of the specified motor.

Example
VarInt1 := ReadMaxAcc (3)

The maximum acceleration of motor3 is stored in VarInt1.

ReadCollisionPosLimit
ReadCollisionPosLimit (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer Collision limit of specified motor.

Description
Returns the collision limit of the specified motor. This value describes how much force has to
act on the robot for it to report a collision.

Example
VarInt1 := ReadCollisionPosLimit (1)

The collision limit of motor 1 is stored in VarInt1.

149/187
3 Command description

ReadCollisionPosLimitLin
ReadCollisionPosLimitLin (MotorNumber) -> Integer

Parameter Type Description

MotorNumber Integer Number of motor
return value Integer Collision limit of specified motor

Description
Returns the collision limit of the specified motor for linear movements. This value describes how
much force has to act on the robot for it to report a collision.

Example
VarInt1 := ReadCollisionPosLimitLin (2)

The collision limit of motor 2 is stored in VarInt1.

ReadK
ReadK (MotorNumber; ->VarInt1; ->VarInt2; ->VarInt3)

Parameter Type Description

MotorNumber Integer Number of motor
->VarInt1 Integer Kspeed
->VarInt2 Integer Kpos
->VarInt3 Integer Ki

Description
This command stores the three motor controller constants (Kspeed, Kpos, Ki) of the specified
motor. After this command, those three values are stored in the the variables passed as
parameter 1 to 3. (You have to prefix the names of the variables with '->' to mark them as output
parameters).

Example
ReadK (3;->VarInt1; ->VarInt2; ->VarInt3)

The controller constants are stored in VarInt1, VarInt2 and VarInt3

150/187
3 Command description

ReadSensor
ReadSensor(Nr) -> Integer

Parameter Type Description

Nr Integer Number of sensor
return value Integer value of specified sensor (0-255)

Description
Returns the current value of the specified sensor.

Example
VarInt1 := ReadSensor (1)

The value of sensor 1 is stored in VarInt1.

ReadSensors
ReadSensors

Description
This command reads all 16 sensors and stores their values in the global variables: LiSe0,
LiSe1, LiSe2 ... LiSe15
Those variables are of type Integer and contain values between 0 and 255. The numbering of
the variables corresponds to the numbering of the sensors.

ReadSensorsUntil
ReadSensorsUntil (SensorNr1{; SensorNr2}{; SensorNr3}; SensorValue; Direction; Timeout)

Parameter Type Description

SensorNr1 Integer Number of first sensor
SensorNr2 Integer Nummer des Sensors
SensorNr3 Integer Nummer des Sensors
SensorValue Integer Wertvorgabe des Sensores (0-255)
Direction 0/1 überschreiten/unterschreiten
Timeout Integer Timeout in Millisekunden (0=unendlich)

Description
This command reads all sensors until one of the (at most) three specified sensors has a value
higher (if Direction = 0) or lower (if Direction = 1) than the specified value. If this occurs, or the
timeout is over, all sensors are read and the global sensor variables LiSe0 to LiSe15 are
updated. The parameters Sensor1, SensorValue, Direction and Timeout are mandatory.

Example
ReadSensorsUntil (3; 7; 200; 0; 5000)
Sensor 3 and 7 are read until one of them has a value higher than 200.

151/187
3 Command description

3.3 Katana Settings

SetK
SetK (MotorNumber; Kspeed; Kpos; Ki)

Parameter Type Description

MotorNumber Integer Number of motor
Kspeed Integer Kspeed
Kpos Integer Kpos
Ki Integer Ki

Description
Returns the controller constants “Kspeed“; “Kpos“ und “Ki“ for a specified motor.

SetPWM
SetPWM (MotorNumber; PWMPos; PWMNeg)

Parameter Type Description

MotorNumber Integer Number of motors
PWMPos Integer positive PMW value
PWMNeg Integer negative PMW value

Description
Sets the PWM limit (force) for the specified motor.

SetVel
SetVel (MotorNumber; VelocityPos; VelocityNeg)

Parameter Type Description

MotorNumber Integer Number of motor
VelocityPos Integer Forward velocity
VelocityNeg Integer Backward velocity

Description
Sets the forward (Pos) and backward (Pos) velocity of the specified motor

SetAcc
SetAcc (MotorNumber; Acceleration)

Parameter Type Description

MotorNumber Integer Number of motor
Acceleration Integer Acceleration

152/187
3 Command description

Description
Sets the acceleration of the specified motor.

SetCollisionPosLimit
SetCollisionPosLimit (MotorNumber; Limit)

Parameter Type Description

MotorNumber Integer Number of motor
Limit Integer Collision limit

Description
Sets the position depending collision limit for the specified motor.

SetCollisionPosLimitLin
SetCollisionPosLimitLin (MotorNumber; Limit)

Parameter Type Description

MotorNumber Integer Number of motor
Limit Integer Collision limit

Description
Sets the position depending collision limit for linear movements for the specified motor.

SetCollisionVelLimit
SetCollisionVelLimit (MotorNumber; Limit; LimitLin)

Parameter Type Description

MotorNumber Integer Number of motor
Limit Integer velocity dependent collision limit
LimitLin Integer velocity dependent collision limit for linear movements

Description
Sets the velocity dependent collision limit for the specified motor for regular and linear
movements.

SetCollisionDetection
SetCollisionDetection (true/false)

Parameter Type Description

true/false Boolean detect collisions?

Description
This command turns the collision detection on (true) or off (false).

153/187
3 Command description

SetKatanaAddress
SetKatanaAddress (KatanaAdresse)

Parameter Type Description

KatanaAddress Integer Address of Katana

Description
Sets the address of the Katana. This value can be between 24 and 32. There is a jumper on the
BaseBoard which can be used to change the address of the Katana.

SetComport
SetComport(ComNr)

Parameter Type Description

ComNr Integer Number of COM port

Description
This command opens the specified COM port with the Katana defaults (57600 Baud, Data Bits
8, Stop Bits 2, Parity None).
If you need other values for your COM port, you have to use the Katana command SET
CHANNEL. More information on that command can be found in the file “4D_Language.pdf”.

154/187
3 Command description

3.4 Interfaces

155/187
3 Command description

3.4.1 National Instruments IO Card

NI_ReadInput
NI_ReadInput(Inputnumber;{DeviceNr}) -> Integer

Parameter Type Description

Inputnumber Integer PIN-Number (1-32)
DeviceNr Integer Number of card
return value Integer state 0/1

Description
This command returns the state of the passed input channel(1-32). If the channel is activated 1
is returned, if not, zero is returned.
DeviceNr is the number of the card to read from. This parameter is optional. If it is not passed,
card number 1 is used.

Example
VarInt1 := NI_ReadInput(1)

NI_SetOutput
NI_SetOutput(Outputnumber;Value;{DeviceNr})

Parameter Type Description

Outputnumber Integer PIN-Number (1-32)
DeviceNr Integer Number of card
Value Integer state 0/1

Description
This command turns a specified output channel to one or zero, depending on what value is
passed to the command.
DeviceNr is the number of the card to write to. This parameter is optional. If it is not passed,
card number 1 is used.

Example
NI_SetOutput(1;0)

Output channel 1 is set to 'off' (0).

NI_ReadBank(BankNr)
NI_ReadBank(BankNr;{DeviceNr}) -> Integer

Parameter Type Description

BankNr Integer Bank Number

156/187
3 Command description

DeviceNr Integer Number of card

return value Integer State of the input channels of the specified bank

Description
NI_ReadBank() reads 8 bits in a row and returns the 8 bit number (between 0 and 255) that is
composed of those 8 bits. (NI_ReadBank(1) reads bits 0-8, NI_ReadBank(2) reads bits 9 – 16,
etc.) This makes it easy to communicate with other systems that are connected with this card.
DeviceNr is the number of the card to read from. This parameter is optional. If it is not passed,
card number 1 is used.

NI_SetBank
NI_SetBank(BankNr;Value;{DeviceNr})

Parameter Type Description

BankNr Integer Bank Number
DeviceNr Integer Number of card
Value Integer State to set the pins to

Description
This command sets the 8 bits of the specified output bank to the 8 bit value (between 0 and
255) passed to the command.
DeviceNr is the number of the card to write to. This parameter is optional. If it is not passed,
card number 1 is used.

157/187
3 Command description

3.4.2 Katana Connector-Box

ReadInput
ReadInput(Inputnumber) -> Integer

Parameter Type Description

Inputnumber Integer PIN-Number (1/2)
return value Integer State 0/1

Description
This command returns the value of the specified input channels (1 or 2). If the specified channel
is activated, 1 is returned, 0.

Example
VarInt1 := ReadInput(1)

SetOutput
SetOutput(Outputnumber;Value)

Parameter Type Description

Outputnumber Integer PIN-Number (1/2)
Value Integer state 0/1

Description
This command sets the specified output channel (1 or 2) either to active (value = 1) or inactive
(value = 0)

Example
SetOutput(1;0)

Output channel 1 is turned off.

158/187
3 Command description

3.4.3 File communication

WriteFile
WriteFile (FileName; Value) -> Boolean

Parameter Type Description

FileName String Path and Filename
Value String Text to write into the file
return value Boolean writing successful?

Description
Writes the passed text (Value) into the specified file (FileName). If there was an error, false is
returned. On success, the command returns true.

If an empty string is passed for the file name, a „Save As“ Dialog is opened.

Example
If (WriteFile("C:\test.txt";"Text in File"))
Alert(„Writing was successful“)
Else
Alert(„Writing failed“)
End If

Creates a file containing the text „Text in File“ and displays a message to the user whether
creating the file was successful.

AddToFile
AddToFile (FileName; Value{; CreateDocument}) -> Boolean

Parameter Type Description

FileName String Path and file name
Value String Text to add to file
CreateDocument Boolean should the file be created if it doesn't exist yet?
return value Boolean successful?

Description
Adds the specified text to the specified file. If no error occurred, the command returns true. If
there was an error, false is returned.

Example
AddToFile("C:\test.txt";char(13)+char(10)+"added Text")

Adds a new line and „added Text“ to the file „test.txt“.

159/187
3 Command description

ReadFile
ReadFile (FileName; DocumentPosition; NumChar{; StopChar}) -> String

Parameter Type Description

FileName String Path and file name
DocumentPosition LongInteger position in file to start reading from
NumChar LongInteger Number of characters to read
StopChar Char Character unto which to read
return value String read Text

Description
This command opens the specified file and reads a string of characters read from that file.

DocumentPosition specifies at which character to start reading. To read from the beginning of
the file, pass 0.

NumChar specifies how many characters should be read. If this is zero, StopChar has to
contain a char. The command will then read until it finds that char in the file.

Example
Alert(ReadFile("C:\test.txt";0;5))

Reads the first 5 characters in the file „test.txt“

Alert(ReadFile("C:\test.txt";0;0;“A“))

Reads the characters in the file „test.txt“ up to the first „A“

160/187
3 Command description

3.4.4 Serial communication

SetComport
SetComport (ComNr)

Parameter Type Description

ComNr Integer Number of COM port

Description
SetComport opens the specified COM port.

SendSerial
SendSerial (VarStr1)

Parameter Type Description

VarStr1 String Text

Description
SendSerial sends the specified string (or text) via the current COM port. (The buffer is cleared
beforehand)

ReceiveSerial
ReceiveSerial -> Text

Parameter Type Description

return value Text Text

Description
ReceiveSerial receives data from the current COM port. The returned buffer can be stored in a
variable of either type String or Text.

Example
SetComport (2)
SendSerial (“RoboterBereit“)
Wait (3000)
VarStr1 := ReceiveSerial
SetComport (1)

Receiving and sending via a serial COM port. The robot is connected to COM 1, an external
device (e.g. A camera) is connected to COM 2. As soon as the robot reached the start position,
COM 2 is opened and the start signal is sent. After a delay of 3 seconds, data is read from COM
2 (to which the camera hopefully sent some information). When the communication with the
device is complete, the old COM port has to be set again, so that the communication with the
robot is possible again.

161/187
3 Command description

3.4.5 TCP/IP

TCP_IP_Connect
TCPIP_Connect(Hostname; Portnumber {;Timeout} {;SessionSettings}) -> TCP Session ID

Parameter Type Description

Hostname String Name or IP of host
Portnummer Integer Port number of host
Timeout Integer Timeout in seconds
SessionSettings Integer Session settings
return value Integer TCP Session ID

Description
TCPIP_Connect opens a connection to the specified host. The command returns the session ID
which is used for subsequent read or write commands. Katana4D is trying to connect to the
specified host until the timeout runs out. (Default value is 30 seconds). With the fourth
parameter additional session settings can be specified:
0 = Synchronous (Standard)
1 = Asynchronous
2 = SSL, Synchronous
3 = SSL, Asynchronous
Example
VarInt1:=TCPIP_Connect(„192.168.1.1“;4455)

TCP_IP_OpenServer
TCPIP_OpenServer(Portnumber {;Timeout}) -> TCP Session ID

Parameter Type Description

Portnumber Integer Portnumber
Timeout Integer timeout in seconds
return value Integer TCP Session ID

Description
TCPIP_OpenServer starts a server that waits for a connection request on the specified port
number. If necessary a timeout can be set. If not set, the server waits indefinitely. The session
ID, which is needed for subsequent read or write commands is returned.
Example
VarInt1:=TCPIP_OpenServer(4455)

162/187
3 Command description

TCP_IP_CloseConnection
TCPIP_CloseConnection(TCPSessionID)

Parameter Type Description

TCPSessionID Integer TCP Session ID

Description
Mit TCPIP_CloseConnection closes the specified connection.

Example
TCPIP_CloseConnection(VarInt1)

TCP_IP_Ping
TCPIP_Ping(Hostname;Timeout) -> State

Parameter Type Description

Hostname String Name or IP to ping
Timeout Integer Timeout in seconds
return value Integer State (1/0)

Description
TCPIP_Ping can be used to verify that a given host is responding. If it does respond within the
specified timeout, 1 is returned, 0 otherwise.

Description
VarInt1:=TCPIP_Ping(„192.168.1.1“;1)

TCP_IP_Receive
TCPIP_Receive(TCPSessionID) -> Buffer

Parameter Type Description

TCPSessionID Integer TCP Session ID
return value Text buffer

Description
TCPIP_Receive empties the buffer of the specified TCP Session and returns it as Text.

Example
VarText1:=TCPIP_Receive(VarInt1)

163/187
3 Command description

TCP_IP_Send
TCPIP_Send(TCPSessionID;SendText)

Parameter Type Description

TCPSessionID Integer TCP Session ID
SendText Text Text to send.

Description
TCPIP_Send sends the specified Text via the specified TCP Session.

Example
TCPIP_Send(VarInt1;VarText1)

TCP_IP_State
TCPIP_State(TCPSessionID) -> State

Parameter Type Description

TCPSessionID Integer TCP Session ID
return value Integer State of TCP Session

Description
TCPIP_State returns the state of the specified TCP Session.
The command returns one of the following values:
0 Connection closed
2 Waiting for incoming connection
8 Connection established

Example
VarInt2:=TCPIP_State(VarInt1)

164/187
3 Command description

3.4.6 ModBus TCP

ModBusTCP_Connect
ModBusTCP_Connect(Host-IP {; Timeout} {;Port} {;OutputOffset})

Parameter Type Des

Host-IP String IP of host
Timeout Integer Timeout in ms
Port Integer Portnummer of host
OutputOffset Integer Offset for addressing outputs

Description
ModBusTCP_Connect opens a connection to the specified host (use the IP, not the host
name!).All the following parameters are optional: Timeout specifies the timeout for the
ModbusTCP commands of this connection (default is 1000ms), Port is the port the host is
listening on (default is 502). The last parameter (OutputOffset) tells Katana4D the offset at
which the output registers can be read. This offset can be found in the documentation of your
device. If no offset is known for the device, don't pass this parameter (default is 0).
If a ModbusTCP error occurs, an error message is displayed and the program is stopped.

Example
ModBusTCP_Connect(„192.168.1.1“)

ModBusTCP_Disconnect
ModBusTCP_Disconnect

Parameter Type Description

This command does not have any parameters.

Description
ModBusTCP_Disconnect disconnects the current ModbusTCP connection.

Example
ModBusTCP_Disconnect

ModBusTCP_ReadWord
ModBusTCP_ReadWord(Address) ->Value

Parameter Type Description

Address Integer Address of word to read.
return value Integer Word (16bit value)

Description
ModBusTCP_ReadWord reads the word at the specified address from the ModbutTCP device.
The command returns a 16 bit unsigned integer. If you need a signed integer, use the command

165/187
3 Command description

16BitINT_UnsignedTOSignedINT to convert the value.

Example
VarInt1:=ModBusTCP_ReadWord(1)

ModBusTCP_WriteWord
ModBusTCP_WriteWord(Address;Value)

Parameter Type Description

Address Integer Address of word to write
Value Integer Word(16bit unsigned Integer) to write

Description
ModBusTCP_WriteWord write the specified value to the specified address.
Only positive, unsigned values (0-65535) can be passed as the value to write. You can use
16BitINT_SignedTOUnsignedINT to convert an unsigned integer to a signed one.

Example
ModBusTCP_WriteWord(10;4786)

ModBusTCP_ReadBit
ModBusTCP_ReadBit(Address;Position) -> Value

Parameter Type Description

Address Integer Address of word the bit is in
Position Integer Bit-Nr. (0-15)
return value Integer Value(1 or 0)

Description
ModBusTCP_ReadBit returns the value (0/1) of the specified bit in the specified word of the
ModbusTCP device.

Example
VarInt1:=ModBusTCP_ReadBit(1;2)
Reads the second bit of the first word of the remote device.

ModBusTCP_WriteBit
ModBusTCP_WriteBit(Addresse;Position;Value)

Parameter Type Description

Address Integer Address of word the bit i9s in
Position Integer Bit-Nr. (0-15)
Value Integer Value (1 oder 0)

Description
ModBusTCP_WriteBit sets the specified bit in the specified word to the specified value (0/1).

166/187
3 Command description

Note
Internally the whole word is read and written back. So don't use this command if the program is
not the only thing that can change the values of that word. Doing so anyway may result the
word being set to unpredictable values!

Example
ModBusTCP_WriteBit(1;12;1)
Sets the 12th bit in the first word to 1.

167/187
3 Command description

3.4.7 Siemens S7 - Plugin

S7MPI_Connect
S7MPI_Connect (MPI-Address{; SegmentID; SlotNumber; RackNumber; DriverName})

Parameter Type Description

MPI-Address Integer MPI-Address
SegmentID Integer ID des Segments
SlotNumber Integer Number of slot
RackNumber Integer Number of rack
DriverName String Name of driver

Description
Connects to a a Siemens S7-3xx/4xx. The only mandatory parameter is the MPI-Address. The
following parameters are optional and have to be passed only if they are different from the
default values.
Default values:
SegmentID = 0
SlotNumber = 2
RackNumber = 0
DriverName= „S7ONLINE“

Example
S7MPI_Connect(2)

A connection to a S7 with MPI address 2 and the default values for all other parameters is
established.

S7MPI_Disconnect
S7MPI_Disconnect

Description
Closes the current connection to an S7.

S7MPI_DBReadString
S7MPI_DBReadString(DBNr; DBBNr) -> Char

Parameter Type Description

DBNr LongInteger Number of data block
DBBNr LongInteger Number of byte
return value Char Value of the specified byte

Description
Reads data byte DBBNr ofdata block DBNr and returns the value as a char (4D string of size 1).

168/187
3 Command description

Example
ALERT(S7MPI_DBReadString(1;0))

Reads byte 0 from data block 1 (Step7 address: DB1.DBB 0) and shows an alert displaying the
value.

S7MPI_DBReadByte
S7MPI_DBReadByte(DBNr; DBBNr) -> Byte

Parameter Type Description

DBNr LongInteger number of data block
DBBNr LongInteger number of byte
return value Byte value of specified byte

Description
Reads data byte DBBNr of data block DBNr and returns the value as an 8 bit integer (-127 to
+127)

Example
ALERT(STRING(S7MPI_DBReadByte(1;0)))

S7MPI_DBReadWord
S7MPI_DBReadWord(DBNr; DBWNr) -> 16bit Integer

Parameter Type Description

DBNr LongInteger number of data block
DBWNr LongInteger number of byte
return value 16bit Integer value of specified byte

Description
Reads data byte DBBNr of data block DBNr and returns the value as an 16 bit integer (-32767
to +32767)

Example
ALERT(STRING(S7MPI_DBReadWord(1;0)))

S7MPI_DBReadDWord
S7MPI_DBReadDWord(DBNr; DBWNr) -> 32bit Integer

Parameter Type Description

DBNr LongInteger number of data block
DBWNr LongInteger number of byte
return value 32bit Integer value of specified byte

Description
Reads four data bytes, starting at DBWNr in data block DBNr and returns the value as a 32 bit

169/187
3 Command description

integer (-2’147’483’647 to +2’147’483’647).

Example
ALERT(STRING(S7MPI_DBReadDWord(1;0)))

S7MPI_DBWriteString
S7MPI_DBWriteString(DBNr; DBBNr; Value)

Parameter Type Description

DBNr LongInteger number of data block
DBBNr LongInteger number of byte
Value String value to write to specified byte

Description
This command writes a string into a data block. The string is written starting at the specified
byte. Each character in the string is written into one subsequent byte.
Example
S7MPI_DBWriteString(1;10;“hello“)

The characters 'h', 'e', 'l', 'l',' and 'o' are written into DB1.DBB10 to DB1.DBB14.

S7MPI_DBWriteByte
S7MPI_DBWriteByte(DBNr; DBBNr; Value)

Parameter Type Description

DBNr LongInteger number of data block
DBBNr LongInteger number of byte
Value Integer value to write to specified byte (8 bit)

Description
This command writes the specified value (-127 to 127) into the specified byte in the specified
data block.

Example
S7MPI_DBWriteByte(1;2;-96)
Stores the number -96 into DB1.DBB 2.

170/187
3 Command description

S7MPI_DBWriteWord
S7MPI_DBWriteWord(DBNr; DBWNr; Value)

Parameter Type Description

DBNr LongInteger number of data block
DBWNr LongInteger number of word
Value Integer Value to write (16 bit)

Description
Writes the value (-32767 to +32767) into the specified word in the specified data block.

Example
S7MPI_DBWriteWord(1;2;-32000)

Stores -32000 in DB1.DBW 2.

S7MPI_DBWriteDWord
S7MPI_DBWriteDWord(DBNr; DBDNr; Value)

Parameter Type Description

DBNr LongInteger number of data block
DBDNr LongInteger number of double word
Value Integer value to write

Description
Writes the value (-2’147’483’647 to +2’147’483’647), into the specified double word in the
specified data block.

Example
S7MPI_DBWriteDWord(1;2;-350000)

Stores the number -350'000 in DB1.DBD 2.

S7MPI_ReadDigitalOutputByte
S7MPI_ReadDigitalOutputByte(ByteNr) -> Integer

Parameter Type Description

ByteNr LongInteger number of byte
return value Integer value

Description
All 8 bits of the digital output byte ByteNr are read and returned as an 8 bit integer (0-255).

Example
ALERT(String(S7MPI_ReadDigitalOutputByte(1)))

171/187
3 Command description

Shows an alert displaying the value of output byte 1.

S7MPI_ReadDigitalOutputBit
S7MPI_ReadDigitalOutputBit(ByteNr; BitNr) -> Boolean

Parameter Type Description

ByteNr LongInteger number of byte
BitNr LongInteger number of bit
return value Boolean value

Description
Returns the value of the specified bit in the specified output byte.

Example

If (S7MPI_ReadDigitalInputBit(126;7))
InputOn
End If

Executes the user method „InputOn“ if bit 7 of output byte 126 is set to 1.

S7MPI_WriteDigitalOutputByte
S7MPI_WriteDigitalOutputByte(ByteNr:LongInteger;Value)

Parameter Type Description

ByteNr LongInteger number of byte
Value Integer value

Description
This command sets the specified output byte. It is not possible to set a single bit.

Example
S7MPI_WriteDigitalOutputByte(1;0)
S7MPI_WriteDigitalOutputByte(1;255)

All bits of output byte 1 are first set to 0 and then to 1.

172/187
3 Command description

S7MPI_ReadDigitalInputByte
S7MPI_ReadDigitalInputByte(ByteNr) -> Integer

Parameter Type Description

ByteNr LongInteger number of byte
return value Integer value
Description
All 8 bits of the digital input byte ByteNr are read and returned as an 8 bit integer (0-255).

Example
ALERT(String(S7MPI_ReadDigitalInputByte(124)))

Shows an alert displaying the value of input byte 124.

S7MPI_ReadDigitalInputBit
S7MPI_ReadDigitalInputBit(ByteNr; BitNr) -> Boolean

Parameter Type Description

ByteNr LongInteger number of byte
return value Boolean value

Description
Returns the value of the specified bit in the specified output byte.

Example

If (S7MPI_ReadDigitalInputBit(124;0))
InputOn
End If

Executes the user method „InputOn“ if bit 0 of output byte 124 is set to 1.

S7MPI_ReadFlagBit
S7MPI_ReadFlagBit(ByteNr; BitNr) -> Boolean

Parameter Type Description

ByteNr LongInteger number of byte
BitNr LongInteger number of bit
return value Boolean value

Description
Reads the specified bit of the specified Flag Byte.

Example
If (S7MPI_ReadFlagBit(4;7))
FlagBitOn

173/187
3 Command description

End If

User method FlagBitOn is set, if bit 7 of flag byte 4 is set.

S7MPI_WriteFlagBit
S7MPI_WriteFlagBit(ByteNr;BitNr;Value)

Parameter Type Description

ByteNr LongInteger number of byte
BitNr LongInteger number of bit
Value LongInteger value (0,1)

Description
Sets the specified bit in the specified flag byte to the specified value. (If the specified value is
not 0 or1, the bit is not set)

Examplel
S7MPI_WriteFlagBit(4;7;1)

S7MPI_ReadFlagString
S7MPI_ReadFlagString(ByteNr) -> Char

Parameter Type Description

ByteNr LongInteger number of byte
return value Char value

Description
Returns the value of the specified flag byte as a character.

Example
ALERT(S7MPI_ReadFlagString(1))

S7MPI_ReadFlagByte
S7MPI_ReadFlagByte(ByteNr) -> Integer

Parameter Type Description

ByteNr LongInteger number of byte
return value Integer value

Description
Returns the value of the specified flag byte.

Example
ALERT(STRING(S7MPI_ReadFlagByte(1)))

174/187
3 Command description

S7MPI_ReadFlagWord
S7MPI_ReadFlagWord(ByteNr) -> Integer

Parameter Type Description

ByteNr LongInteger number of word
return value Integer value

Description
Reads the specified flag word.

Beispiel
ALERT(STRING(S7MPI_ReadFlagWord(1)))

S7MPI_ReadFlagDWord
S7MPI_ReadFlagDWord(ByteNr) -> Integer

Parameter Type Description

ByteNr LongInteger number of double word
return value Integer value

Description
Reads the specified flag double word.

Beispiel
ALERT(STRING(S7MPI_ReadFlagDWord(1)))

S7MPI_WriteFlagByte
S7MPI_WriteFlagByte(ByteNr; Value)

Parameter Type Description

ByteNr LongInteger number of byte
Value Integer Value

Description
Writes the specified 8 bit value (-127 to +127) into the specified flag byte.

Example
S7MPI_WriteFlagByte(4;15)

Stores the number 15 into flag byte 4

S7MPI_WriteFlagWord
S7MPI_WriteFlagWord(ByteNr; Value)

Parameter Type Description

ByteNr LongInteger number of byte
Value Integer Value to write

175/187
3 Command description

Description
Writes a 16 bit value (-32767 to +32767) into a flag word.

Example
S7MPI_WriteFlagWord(3;15)

Stores the number 15 into flag word 3.

S7MPI_WriteFlagDWord
S7MPI_WriteFlagDWord(ByteNr; Value)

Parameter Type Description

ByteNr LongInteger number of byte
Value Integer Value to write

Description
This command writes a 32 bit value (-2’147’483’647 to +2’147’483’647) into the specified flag
double word.

Example
S7MPI_WriteFlagDWord(1;48000)

Stores the number 48’000 in flag double word 1.

S7MPI_WriteFlagString
S7MPI_WriteFlagString(ByteNr; Value)

Parameter Type Description

ByteNr LongInteger number of byte
Value String value

Description
Each character in the string are written to an individual, subsequent flag byte, starting at the
specified one.

Example
S7MPI_WriteFlagString(1;”test”)

Writes the characters 't', 'e', 's' and 't' into flag bytes 1 to 4.

176/187
3 Command description

3.4.8 Cognex Camera

CognexCam_AufgabenfeldLesen
CognexCam_AufgabenfeldLesen -> String

Parameter Type Description

return value String state of job

Description
Reads the job field of the camera.
Possible states:
• Pick
• NoPart
• Calib1, 2, 3, 4
• Stop

CognexCam_KameraJobLaden
CognexCam_JobLaden (Dateiname)

Parameter Type Description

Dateiname String Job name

Description
Loads a camera job (filename as a string, without the .job extension).

CognexCam_KalibKoordinatenSenden
CognexCam_KalibKoordinatenSenden(X;Y)

Parameter Type Description

X Real X-Coordinate
Y Real Y-Coordinate

Description
Sends the specified (robot) coordinates to the camera.

CognexCam_KoordinatenLesen
CognexCam_KoordinatenLesen

Description
The coordinates of the camera are stored into the global camera variables (reals):
KameraX X-Coordinate
KameraY Y-Coordinate
KameraC Angle

177/187
3 Command description

CognexCam_OnlineSetzen
CognexCam_OnlineSetzen(Status)

Parameter Type Description

Status Integer 1 = online/0 = offline

Description
Sets the camera to on- or offline.

CognexCam_PickSetzen
CognexCam_PickSetzen(Status)

Parameter Type Description

Status Integer state (1/0)

Description
Sets the PickField of the camera.

CognexCam_StatusLesen
CognexCam_StatusLesen -> Integer

Parameter Type Description

return value Integer state of camera

Description
Reads the on-/offline state of the camera. Possible return values are 1 and 0.

CognexCam_FeederProfilLaden
CognexCam_FeederProfilLaden

Description
Loads the Feeder-Profile that is stored in the job.

CognexCam_FeederFlippen
CognexCam_FeederFlippen

Description
Flips the feeder.CognexCam_SetComport
CognexCam_SetComport (ComPortNr)

Parameter Type Description

ComPortNr Integer Number of COM port

Description
CognexCam_SetComport opens the specified COM port.

178/187
3 Command description

3.4.9 Katana 1.2

K1.2_SetDigitalOutput
K1.2_SetDigitalOutput(OutputNr; Value)

Parameter Typ Beschreibung

OutputNr Integer Number of the Output
Value Integer State 0/1

Beschreibung
Sets the digital output of the controller box

Beispiel
K1.2_SetDigitalOutput(2;1)

Set Output 2

K1.2_ReadDigitalInput
K1.2_ReadDigitalInput(InputNr) -> Integer

Parameter Typ Beschreibung

InputNr Integer Number of the Input
Result Integer State 0/1

Beschreibung
Reads the selected Input.

Beispiel
VarInt1 := K1.2_ReadDigitalInput(1)

Reads in Input 1 and saves the value in the variable 'VarInt1'.

K1.2_SetLED
K1.2_SetLED(State)

Parameter Typ Beschreibung

State Integer State of the LED

Beschreibung
Set the State of the LED:
States: 0 LED off
1 LED green
2 LED red
Beispiel
K1.2_SetLED(0)

179/187
3 Command description

3.5 Program flow control

Alert
Alert(“Text“)

Parameter Type Description

Text String Text of alert

Description
This command interrupts the program an displays the specified text to the user. The program
continues as soon as the user confirms the alert by clicking the ok button.

Message
Message(“Text“)

Parameter Type Description

Text String Tex of Message

Description
This command displays a message in a special window. This window disapperas as soon as a
new form is opened. The program is not interrupted by a message.

Confirm
Confirm („Text“{; OKTitel{; CancelTitel}})

Parameter Type Description

Text String Text of question
OKTitel String Text of OK button
CancelTitel String Text of Cancel button

Description
Displays a window with a question in which the user can either click OK(OKTitel, if specified) or
Cancel (CancelTitle, if specified). The answer is saved in the global variable„OK“.
OK button -> OK =1
Cancel button -> OK = 0

Example
Confirm („Yes?“)
If (OK=1)
Alert („Ok“)
Else
Alert („Cancel“)
End If

180/187
3 Command description

Request
Request („Text“{; Value{; OKTitel{; CancelTitel}}}) -> String

Parameter Type Description

Text String Text
Value String Vorgabewert
OKTitel String Titel für OK-Button
CancelTitel String Titel für Abbrechen-Button
return value String vom Benutzer eingegebner Wert

Description
Opens a window with a text field which lets the user enter a value (a default value can be
specified). Like in the 'Confirm' command, the global variable 'OK' is set, depending on whether
the user clicks OK or Cancel. If OK was clicked, the function returns the value entered by the
user. If Cancel was clicked, it will still return some value, but it might not make any sense.
Therefore you should always check the OK variable before using this functions return value.

Example
VarStr1 := Request („Gridpoint?“;“1“)

Wait
Wait (Milliseconds)

Parameter Type Description

Milliseconds Long Integer Time to wait in milliseconds

Description
This command stops the execution of the program for a specified amount of milliseconds.

RunUserMethod
RunUserMethod (Usermethod)

Parameter Type Description

Usermethod String Name of user method to run

Description
This commands executes the code stored as a user method. The name of the user method has
to be surrounded by double quotes. The user method can contain any number of lines of code
and it can also call other user methods.

Hint
A user method can also be executed by directly writing its name in the script.

Example
RunUserMethod(“MyFirstMethod”)
MyFirstMethod

Both versions do the same thing.

181/187
3 Command description

If Then Else
If (Condition)
Else
End If

Parameter Type Description

Condition Boolean Condition

Description
If the condition is true, all commands between „If“ and „Else“ are executed. Otherwise the
commands between „Else“ and „EndIf“ are executed.

Example
Confirm („Yes?“)
If (OK=1)
Alert („Ok“)
Else
Alert („Cancel“)
End If

A confirmation dialog („Yes?“) is displayed. Depending on what the user clicks, an alert with
either „OK“ or „Cancel“ is then displayed.

Repeat Until
Repeat
Until (Condition)

Parameter Type Description

Condition Boolean Condition

Description
The commands between „Repeat“ and „Until“ are repeated until the condition is true.

Example
i := 0
Repeat
i:=i+1
Alert(String(i))
Until (i=5)

The loop is executed 5 times and for each iteration an alert with the value of i is displayed.

RunProgram
RunProgram (Nr{; Repetitions}{; MainCalibration})

182/187
3 Command description

Parameter Type Description

Nr Integer Number of Program
Repetitions Integer Number of repetitions
MainCalibration Boolean perform a main calibration?

Description
Starts the program with the specified program number. The number of repetitions of the
program and whether a main calibration is performed before starting it, depend on the two
optional parameters. If parameter two and three are NOT specified, the programs default values
are used.

ExitProgram
ExitProgram (Nr)

Parameter Type Description

Nr Integer Number of Program to terminate

Description
This command stops a running program.

RunApplication
RunApplication (Name)

Parameter Type Description

Nr String Name of Application

Description
Starts the specified application.

ExitApplication
ExitApplication (Name)

Parameter Type Description

Nr String Name of Application

Description
Stops the specified application.

PauseProgram
PauseProgram (Nr{; Timeout}) -> Integer

183/187
3 Command description

Parameter Type Description

Nr Integer Number of program to pause
Timeout Integer Time to wait in milliseconds
return value Integer Status

Description
PauseProgram pauses a running program. The program can be restarted with
'ResumeProgram(..)'. Since a program is never paused in the middle of a command, pausing a
program may take a while, because it has to be waited for its current command to complete.
If the timeout parameter is not passed to this command, the pause request is sent to the
specified program and 1 is returned immediately (i.e. You don't know when the program is really
paused). If a timeout is specified, this command waits for the timeout to pass after sending the
pause request to the program. If the program paused itself by then, 1 is returned, 0 otherwise.
– if a 0 timeout is passed, this command waits indefinitely.
– The program can still pause itself after the timeout ran out, so make sure the timeout is long
enough.
– If there is no program with the specified number, 0 is returned.

Example
VarInt1:=PauseProgram(1;10000)

ResumeProgram
ResumeProgram (Nr) -> Integer

Parameter Type Description

Nr Integer Number of program to resume
return value Integer Status

Description
ResumeProgram starts the specified (paused) program. If there is no program with the specified
number, 0 is returned, 1 otherwise.

ProgramState
ProgramState(Nr) -> Integer

Parameter Type Description

Nr Integer Number of program
return value Integer status of program

Description
ProgramState returns the current status of the specified program. There are 5 possible
statuses:
0 Not running.
1 Running
2 Paused
3 Sleeping(Wait command)
4 waiting for the user to confirm some window.

184/187
3 Command description

Login
Login ({User}{; Password})

Parameter Type Description

User String User name
Password String Password

Description
If no parameters or only the user name is passed, the login window is displayed for the user to
log in. If only the user name is passed, this window already contains the user name. If boths
parameters are passed, the user is automatically logged in.

Logout
Logout

Description
Logs off the user and displays the start screen.

GetErrorMessage
GetErrorMessage -> String

Parameter Type Description

return value String Error message

Description
This command returns the error message. It can be called after an error occurred.

Hint
The event driven user method 'OnError' is executed when an error occurs. GetErrorMessage
can get the error message in that method.

185/187
3 Command description

3.6 Object recognition

OR_Start
OR_Start {(Dialog)}

Parameter Type Description

Dialog Integer Value for Dialog (1/2)

Description
Tests the grasped object by the use of a neural network. Thus, the sensor values of the gripper
and sensor fingers are read first. Then, these values are presented to that neural network which
is related to the selected Training Set in the Project ( „Object“ tab).
The function does not return any value, but it puts the order number of the „winning“ object (the
one connected with the output element showing the highest value of the neural network's output
layer) into the variable „OR_Winner“. Dependent which object wins, the following actions of the
robot can be different (see example below).

The parameter „Dialog“ defines whether or not a dialog with the user should happen during the
runtime of the program script. The dialog allows to give the correct feedback to the neural
network during the training phase including storage of the training sample. If no value is given
for Dialog, no dialog will be chosen (same as a value of 2).

1 = Dialog
2 = no Dialog

OR_Winner
OR_Winner -> Integer

Parameter Type Description

Function result Integer Order number of the object

Description
Based on the methods executed automatically with the script command „OR_Start“, the order
number of the winning object is written into the numeric variable OR_Winner. The number
relates directly to the order number of the object list in the project.

Example
`In the Project, three objects are defined:
`1. cover
`2. chocolate
`3. rubber

`The robot drives to the objects, one after the other (based on a script) and closes the gripper.
`Then the neural network is started:
OR_Start

186/187
3 Command description

`Depending on the result of the neural network's output, the according user method is executed:
If (OR_Winner=1)
PosCover
End If
If (OR_Winner=2)
PosChocolate
End If
If (OR_Winner=3)
PosEraser
End If

187/187