Library Kinematics

Transformation
Siemens
LKinTrans for SIMATIC Industry
Online
https://support.industry.siemens.com/cs/ww/en/view/109758302 Support
 Legal information

Legal information
Use of application examples
Application examples illustrate the solution of automation tasks through an interaction of several
components in the form of text, graphics and/or software modules. The application examples are
a free service by Siemens AG and/or a subsidiary of Siemens AG (“Siemens”). They are non-
binding and make no claim to completeness or functionality regarding configuration and
equipment. The application examples merely offer help with typical tasks; they do not constitute
customer-specific solutions. You yourself are responsible for the proper and safe operation of the
products in accordance with applicable regulations and must also check the function of the
respective application example and customize it for your system.
Siemens grants you the non-exclusive, non-sublicensable and non-transferable right to have the
application examples used by technically trained personnel. Any change to the application
examples is your responsibility. Sharing the application examples with third parties or copying the
application examples or excerpts thereof is permitted only in combination with your own products.
The application examples are not required to undergo the customary tests and quality inspections
of a chargeable product; they may have functional and performance defects as well as errors. It is
your responsibility to use them in such a manner that any malfunctions that may occur do not
result in property damage or injury to persons.

Disclaimer of liability
Siemens shall not assume any liability, for any legal reason whatsoever, including, without
limitation, liability for the usability, availability, completeness and freedom from defects of the
application examples as well as for related information, configuration and performance data and
any damage caused thereby. This shall not apply in cases of mandatory liability, for example
under the German Product Liability Act, or in cases of intent, gross negligence, or culpable loss of
life, bodily injury or damage to health, non-compliance with a guarantee, fraudulent
non-disclosure of a defect, or culpable breach of material contractual obligations. Claims for
damages arising from a breach of material contractual obligations shall however be limited to the
 Siemens AG 2018 All rights reserved

foreseeable damage typical of the type of agreement, unless liability arises from intent or gross
negligence or is based on loss of life, bodily injury or damage to health. The foregoing provisions
do not imply any change in the burden of proof to your detriment. You shall indemnify Siemens
against existing or future claims of third parties in this connection except where Siemens is
mandatorily liable.
By using the application examples you acknowledge that Siemens cannot be held liable for any
damage beyond the liability provisions described.

Other information
Siemens reserves the right to make changes to the application examples at any time without
notice. In case of discrepancies between the suggestions in the application examples and other
Siemens publications such as catalogs, the content of the other documentation shall have
precedence.
The Siemens terms of use (https://support.industry.siemens.com) shall also apply.

Security information
Siemens provides products and solutions with industrial security functions that support the secure
operation of plants, systems, machines and networks.
In order to protect plants, systems, machines and networks against cyber threats, it is necessary
to implement – and continuously maintain – a holistic, state-of-the-art industrial security concept.
Siemens’ products and solutions constitute one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems, machines
and networks. Such systems, machines and components should only be c onnected to an
enterprise network or the Internet if and to the extent such a connection is necessary and only
when appropriate security measures (e.g. firewalls and/or network segmentation) are in place.
For additional information on industrial security measures that may be implemented, please visit
https://www.siemens.com/industrialsecurity.
Siemens’ products and solutions undergo continuous development to make them more secure.
Siemens strongly recommends that product updates are applied as soon as they are available
and that the latest product versions are used. Use of product versions that are no longer
supported, and failure to apply the latest updates may increase customer’s exposure to cyber
threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS Feed
at: https://www.siemens.com/industrialsecurity.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 2
 1 Introduction

Table of contents
Legal information ..................................................................................................... 2
1 Introduction .................................................................................................... 4
1.1 Overview ........................................................................................... 4
1.2 Mode of operation.............................................................................. 4
1.3 Components used ............................................................................. 5
2 Engineering .................................................................................................... 6
2.1 Description of interface ...................................................................... 6
2.1.1 Overview ........................................................................................... 6
2.1.2 FB LKinTrans_Main ........................................................................... 6
2.1.3 FB LKinTrans_InvKinTrans ................................................................ 7
2.1.4 FB LKinTrans_FwdKinTrans .............................................................. 8
2.1.5 PLC Tags .......................................................................................... 9
2.1.6 PLC Types ........................................................................................ 9
2.2 Project integration............................................................................ 13
2.2.1 Requirements .................................................................................. 13
2.2.2 Import .............................................................................................. 13
2.2.3 Call and parametrization .................................................................. 13
2.3 User defined kinematics transformation ........................................... 15
2.3.1 Inverse transformation ..................................................................... 15
2.3.2 Forward transformation .................................................................... 16
2.3.3 Use of calculation mode................................................................... 16
 Siemens AG 2018 All rights reserved

2.3.4 Modulo ............................................................................................ 17

2.4 Operation ........................................................................................ 17
2.4.1 Preconditions................................................................................... 17
2.4.2 Enabling .......................................................................................... 18
2.4.3 Cyclic call and monitoring ................................................................ 20
2.4.4 Disabling ......................................................................................... 21
2.5 Error handling .................................................................................. 21
2.5.1 Error identifiers ................................................................................ 21
2.5.2 Diagnostic information ..................................................................... 22
2.5.3 Error reaction and acknowledgement ............................................... 24
3 Application example..................................................................................... 25
3.1 Project configuration ........................................................................ 25
3.2 Operation ........................................................................................ 26
4 Additional information ................................................................................. 27
4.1 Distinction to user defined TO Kinematics ........................................ 27
4.2 Function set for standard kinematics ................................................ 27
4.3 Command value source ................................................................... 29
4.4 Practical advices.............................................................................. 30
4.4.1 Behavior of motion interface ............................................................ 30
4.4.2 Zone monitoring and kinematics trace.............................................. 31
4.4.3 Performance .................................................................................... 31
5 Update notes ................................................................................................ 32
5.1 Changelog ....................................................................................... 32
5.2 Update guideline.............................................................................. 32
6 Appendix....................................................................................................... 33
6.1 Service and Support ........................................................................ 33
6.2 Application Support.......................................................................... 34
6.3 Links and Literature ......................................................................... 34
6.4 Change documentation .................................................................... 34

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 3
 1 Introduction

1 Introduction
1.1 Overview
The SIMATIC Library Kinematics Transformation (LKinTrans) provides an interface
for programming customized kinematics transformations with direct specification of
the Cartesian command values.

Figure 1-1: Library Kinematics Transformation

 Siemens AG 2018 All rights reserved

The command values of various output axes can be linked to the command values
of various input axes. The output axes are controlled by the library by using the
motion interface functionality of the TO axis. Therefore, no TO Kinematics is
needed for transformation.

1.2 Mode of operation

The function block LKinTrans_Main is the main block of the library. Its tasks are:
 Calling the inverse and forward transformation programmed by the user
 Controlling the motion interface of the output axes
 Monitoring the consistency of both transformation directions
For programming the specific transformation equations, the function blocks
LKinTrans_InvKinTrans and LKinTrans_FwdKinTrans must be filled by the user.
The parameter needed for calculating the transformation can be transferred with
the parameter structure. This type also includes further information, such as link
constellation, extent of the transformation (only position, position and velocity or
position, velocity and acceleration) and the coordinate system frame of the
transformation.
While the input axes are representing the (virtual) Cartesian and orientation axes of
the kinematics (X, Y, Z, A, B…), the output axes are representing the (real) joint
axes of the mechanic (A1, A2, A3…).
The position transformations of all TO Kinematics V4.0 kinematics types are
available within the library. In order to use them, the respective functions need to

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 4
 1 Introduction

be called in the LKinTrans_InvKinTrans and LKinTrans_FwdKinTrans function

block.
Figure 1-2: Mode of operation
Input Axes Output Axes

LKinTrans_Main

LKinTrans_InvKinTrans
A1 = X + 1
A2 = Y + 2
...

X, Y, Z, A... A1, A2, A3...

LKinTrans_FwdKinTrans

. X = A1 – 1 .
Y = A2 – 2
. ...
.
. .

Parameter (Config, Status, Monitoring)

LKinTrans_typeParameter
 Siemens AG 2018 All rights reserved

When enabled, the main function block is cyclically writing into the motion interface
of the output axes by using the MC_MotionInPosition command. The handling of
the motion interface (e.g. enable, cyclic call, disable) is an internal functionality of
the LKinTrans main block; the user does not need to take care of it.
Also, the consistency between forward and inverse transformation can be
monitored in order to ensure a correct result.

1.3 Components used

This application example has been created with the following hardware and
software components:

Table 1-1: Hardware and software components

Component Number Article number Note
CPU 1516T-3 PN/DP 1. 6ES7 516-3TN00-0AB0 Other S7-1500T(F) CPU
with FW V2.5
SIMATIC STEP 7 2. 6ES7822 1AE00-0YY0 -
Professional V15 (TIA
Portal)

This application example consists of the following components:

Table 1-2: Application example components

Component File name Note
LKinTrans library 109758302_LKinTrans_Lib_V_1_1_0.zip -
LKinTrans example project 109758302_LKinTrans_Prj_V_1_1_0.zap15 -
LKinTrans manual 109758302_LKinTrans _Doc_V_1_1_0_en.pdf -

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 5
 2 Engineering

2 Engineering
2.1 Description of interface
2.1.1 Overview

Following library blocks are relevant for the user:

 FB LKinTrans_Main
 FB LKinTrans_InvKinTrans
 FB LKinTrans_FwdKinTrans
Besides other tasks, the LKinTrans_Main block is calling the user kinematics
transformation which has to be programmed in the function blocks
LKinTrans_InvKinTrans (inverse transformation) and LKinTrans_FwdKinTrans
(forward transformation).
Furthermore, the forward and inverse transformation function can be used
standalone for informational reasons, e.g. calculating the joint positions out of
Cartesian positions and vice versa.

Table 2-1: Size of the blocks

Block Symbol Size in code work- Size in load memory
memory [Kbytes] [Kbytes]
 Siemens AG 2018 All rights reserved

FB35250 LKinTrans_Main 19 215

FC35250 LKinTrans_FwdKinTrans 0,3 14
FC35251 LKinTrans_InvKinTrans 0,3 14

2.1.2 FB LKinTrans_Main

In the following, the interface of the LKinTrans_Main FB with its data types and
meaning is shown. The assignment of all IN and IN_OUT parameter is mandatory.

Figure 2-1: LKinTrans_Main

LKinTrans_Main

Bool enable valid Bool

UDInt cycleTime busy Bool

Transforma
Bool
tionActive
error Bool

status Word

diagnostics "LKinTrans_typeDiagnostics"
Array["LKINTRANS_AX_LOWER inputAxes Array["LKINTRANS_AX_LOWER
_LIM".."LKINTRANS_IN_AX_ _LIM".."LKINTRANS_IN_AX_
UPPER_LIM"] of DB_ANY UPPER_LIM"] of DB_ANY
Array["LKINTRANS_AX_LOWER outputAxes Array["LKINTRANS_AX_LOWER
_LIM".."LKINTRANS_OUT_AX_ _LIM".."LKINTRANS_OUT_AX_
UPPER_LIM"] of DB_ANY UPPER_LIM"] of DB_ANY
parameter
"LKinTrans_typeParameter" "LKinTrans_typeParameter"

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 6
 2 Engineering

Table 2-2: Parameter of LKinTrans_Main

Name P-Type Type Comment
enable IN Bool TRUE: enable functionality of
FB
cycleTime IN UDInt Cycle time of FB call in
nanoseconds
valid OUT Bool TRUE: valid set of output
values available at the FB
busy OUT Bool TRUE: FB is not finished and
new output values can be
expected
transformatio OUT Bool TRUE: output axes are in
nActive control of FB
error OUT Bool TRUE: an error occurred
during the execution of the FB
status OUT Word 16#0000 - 16#7FFF: status of
the FB, 16#8000 - 16#FFFF:
error identification
diagnostics OUT "LKinTrans_typeDiagnostics" Diagnostics information of FB
inputAxes IN_OUT Array["LKINTRANS_AX_ Array of input axes
LOWER_LIM".."LKINTRANS
_IN_AX_UPPER_LIM"] of
DB_ANY
 Siemens AG 2018 All rights reserved

outputAxes IN_OUT Array["LKINTRANS_AX_ Array of output axes

LOWER_LIM".."LKINTRANS
_OUT_AX_UPPER_LIM"] of
DB_ANY
parameter IN_OUT "LKinTrans_typeParameter" Parameter structure

NOTE Internal use of input axes entries

If a frame is used (See parameter-structure), the entries of the input axes are
used as the following:
 inputAxes["LKINTRANS_AX_LOWER_LIM"]:
X-Axis
 inputAxes["LKINTRANS_AX_LOWER_LIM" + 1]:
Y-Axis
 inputAxes["LKINTRANS_AX_LOWER_LIM" + 2]:
Z-Axis
 inputAxes["LKINTRANS_AX_LOWER_LIM" + 3..n]:
Orientation A, B, …
This means that e.g. the axis assigned to the first entry is always regarded as the
Cartesian X-Axis.

2.1.3 FB LKinTrans_InvKinTrans

In this function block, the user specific inverse kinematics transformation must be
programed. Inverse transformation means to calculate from Cartesian axes values
into joint axes values. The function block LKinTrans_InvKinTrans is called by the
main FB. It is also possible to use it stand alone e.g. for calculation reasons.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 7
 2 Engineering

Figure 2-2: LKinTrans_InvKinTrans

LKinTrans_InvKinTrans
Array["LKINTRANS_AX_LOWER Array["LKINTRANS_AX_LOWER
_LIM".."LKINTRANS_IN_AX_ cartesian _LIM".."LKINTRANS_OUT_AX_
axesData
UPPER_LIM"] of Data UPPER_LIM"] of
"LKinTrans_typeMotionData" "LKinTrans_typeMotionData"
status Word
parameter
"LKinTrans_typeParameter" "LKinTrans_typeParameter"

Table 2-3: Parameter of LKinTrans_InvKinTrans

Name P-Type Data Type Comment
cartesian IN Array["LKINTRANS_AX_LOWER_LIM".." Cartesian data (position, velocity,
Data LKINTRANS_IN_AX_UPPER_LIM"] of acceleration)
"LKinTrans_typeMotionData"
axesData OUT Array["LKINTRANS_AX_LOWER_LIM".." Joint axes data (position, velocity,
LKINTRANS_OUT_AX_UPPER_LIM"] of acceleration)
"LKinTrans_typeMotionData"
status OUT Word Transformation status
parameter IN_OUT "LKinTrans_typeParameter" Parameter structure
 Siemens AG 2018 All rights reserved

2.1.4 FB LKinTrans_FwdKinTrans

In this function block, the user specific forward kinematics transformation must be
programed. Forward transformation means to calculate from joint axes values into
Cartesian axes values. The function block LKinTrans_FwdKinTrans is called by the
main FB. It is also possible to use it stand alone e.g. for calculation reasons.

Figure 2-3: LKinTrans_FwdKinTrans

LKinTrans_FwdKinTrans
Array["LKINTRANS_AX_LOWER Array["LKINTRANS_AX_LOWER
_LIM".."LKINTRANS_OUT_AX_ cartesian _LIM".."LKINTRANS_IN_AX_
axesData
UPPER_LIM"] of Data UPPER_LIM"] of
"LKinTrans_typeMotionData" "LKinTrans_typeMotionData"
status Word
parameter
"LKinTrans_typeParameter" "LKinTrans_typeParameter"

Table 2-4: Parameter of LKinTrans_FwdKinTrans

Name P-Type Data Type Comment
axesData IN Array["LKINTRANS_AX_LOWER_LIM".." Joint axes data (position, velocity,
LKINTRANS_OUT_AX_UPPER_LIM"] of acceleration)
"LKinTrans_typeMotionData"
cartesian OUT Array["LKINTRANS_AX_LOWER_LIM".." Cartesian data (position, velocity,
Data LKINTRANS_IN_AX_UPPER_LIM"] of acceleration)
"LKinTrans_typeMotionData"
status OUT Word Transformation status
parameter IN_OUT "LKinTrans_typeParameter" Parameter structure

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 8
 2 Engineering

2.1.5 PLC Tags

User constants
The length of input axes array, output axes array and kinematics parameter array is
variable.

NOTE The array length of the input axes array must be at least 3.

NOTE When using a kinematics with less than 3 degrees of freedom, the dimensions
which are not used should not be assigned.

Table 2-5: PLC Tags

Name Type Value Comment
LKINTRANS_OUT_AX_UPPER_LIM Int 4 Upper limit of output axes array
LKINTRANS_IN_AX_UPPER_LIM Int 4 Upper limit of input axes array
LKINTRANS_KIN_PARA_UPPER_LIM Int 15 Length of parameter array [0...n]
LKINTRANS_AX_LOWER_LIM Int 1 Lower limit of input and output
axes array
 Siemens AG 2018 All rights reserved

2.1.6 PLC Types

Parameter type LKinTrans_typeParameter

The parameter structure is the main structure of LKinTrans. It is separated into
parameter for configuration, status and monitoring.

Table 2-6: Parameter of LKinTrans_typeParameter

Name Type Value Comment
config "LKinTrans_typeConfig" - Configuration parameter
status "LKinTrans_typeStatus" - Status parameter
monitoring "LKinTrans_typeMonitoring" - Monitoring parameter

Configuration type LKinTrans_typeConfig

The configuration of the kinematics is done in the LKinTrans_typeConfig structure.
 With the calcMode it is possible to declare which values are calculated directly
by the transformation, and which are derived from the calculated position.
 It is possible to program more than one kinematics in the transformation
function. The transId parameter serves as a selector.
 Normally, the kinematics transformation is using variable parameters like arm
length, position offset and so on. These parameters are transferred from the
user program to the transformation function with the kinParameter array.
 The origin of the kinematics transformation usually is defined in the kinematics
zero point, whereas the Cartesian input values can be defined in any
coordinate system. By using the kinFrame parameter, the position and rotation
of the kinematics zero point in the coordinate system of the input values is set.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 9
 2 Engineering

NOTE The coordinate system frame kinFrame has got the same definition as the
kinematics coordinate system (KCS) of the TO Kinematics. The translation (x, y,
z) is done first, the rotation (first a, then b, then c) is done afterwards.

Table 2-7: Parameter of LKinTrans_typeConfig

Name Type Value Comment
calcMode USInt 0 Extend of transformation:
0: only Position,
1: position and velocity,
2: position, velocity, acceleration
transID DInt 0 Transformation identifier
kinParameter Array[0.."LKINTRANS_LAST - kinematics parameter
_PARAMETER"] of LReal
kinFrame "LKinTrans_typeFrame" - Transformation frame

Frame type LKinTrans_typeFrame

The kinematics frame LKinTrans_typeFrame is a subtype of the configuration
structure and defines the position of the kinematics zero point in the coordinate
system of the input values.
 Siemens AG 2018 All rights reserved

Table 2-8: Parameter of LKinTrans_typeFrame

Name Type Value Comment
x LReal 0.0 Translation in x
y LReal 0.0 Translation in y
z LReal 0.0 Translation in z
a LReal 0.0 Rotation around z axis
b LReal 0.0 Rotation around y axis
c LReal 0.0 Rotation around x axis

Status type LKinTrans_typeStatus

Information about the status of the user kinematics is given in the
LKinTrans_typeStatus type.
 The link constellation of the kinematics is defined by the joint axes position.
This information is only necessary for kinematics structures with singularities. It
is set automatically with enabling the main LKinTrans FB. In order to do so, the
user has to take care of setting the linkConstellation to its correct value in the
forward transformation.
 The modulo settings of all input and output axes are stored in the modulo
status structure when enabling the LKinTrans FB. Furthermore, the current
modulo cycle of the command and actual value is written. This information is
used for internal purpose.
 The actual position in each Cartesian direction including orientation axes
(actualCartesianPosition) is given by the transformed actual position of the
output axes. It is only updated if the transformation is active.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 10
 2 Engineering

Table 2-9: Parameter of LKinTrans_typeStatus

Name Type Value Comment
linkConstellation DWord 16#0 Link constellation
modulo "LKinTrans_typeModuloStatus" - Modulo settings
actualCartesianPosition Array["LKINTRANS_AX_LOWER_ - Actual Cartesian
LIM".."LKINTRANS_IN_AX_UPPER position
_LIM"] of LREAL

Monitoring type LKinTrans_typeMonitoring

In the LKinTrans_typeMonitoring structure, all parameter which ensure a safe
operation are summed up.
 The programed forward and inverse transformation needs to fit to each other,
meaning that the following rule must apply:
𝑣𝑎𝑙𝑢𝑒 → 𝑖𝑛𝑣𝑇𝑟𝑎𝑛𝑠 → 𝑣𝑎𝑙𝑢𝑒 ′ → 𝑓𝑤𝑑𝑇𝑟𝑎𝑛𝑠 → 𝑣𝑎𝑙𝑢𝑒 ′′ ≅ 𝑣𝑎𝑙𝑢𝑒
This is checked by the LKinTrans_Main FB with enabling the consistency
check (enableConsistencyCheck = TRUE). For further information about
consistency monitoring, see chapter 2.4.3.
 The axis command values for velocity and acceleration, which are written into
the motion interface, are not limited by the maximum axes dynamic. To prevent
damage, LKinTrans is able to abort the movement before risky values apply on
the axes. The outputAxesDynamicLimitFactor determines how big the dynamic
values of the motion interface can be in relation to the maximum axis dynamic
 Siemens AG 2018 All rights reserved

values by the following equation:

max(𝑀𝑜𝑡𝑖𝑜𝑛𝐼𝑛) = max(𝐴𝑥𝑖𝑠) ∗ 𝑜𝑢𝑡𝑝𝑢𝑡𝐴𝑥𝑒𝑠𝐷𝑦𝑛𝑎𝑚𝑖𝑐𝐿𝑖𝑚𝑖𝑡/100
 When enabling, either the input or the output axes are manipulated in order to
set them on the correct position by redefinition (input axes) or pulling (output
axes, see chapter 2.4.2 for further information). The
enableTransformationMode can be used to have an effect on the enabling
behavior.
 It is possible to define a maximum distance which the particular output axis can
move during their pull operation in outputAxesMaxPullDistance[…]. If the value
is exceeded, error ERR_PULL_AXIS_DEVIATION is thrown before movement.
By setting the value smaller or equal 0, the monitoring of the respective axis is
deactivated.
Table 2-10: Parameter of LKinTrans_typeMonitoring
Name Type Value Comment
enableConsistencyCheck Bool FALSE TRUE: enable consistency
check of transformation
(use following error limit of
respective axis)
outputAxesDynamicLimit LReal 105.0 Percentage: maximum
Factor motionIn dynamic in
relation to maximum axes
limits (velocity,
acceleration), 1...1000%
enableTransformation USInt 0 0: redefine or pull,
Mode 1: only redefine,
2: only pull,
other: Error
outputAxesMaxPull Array["LKINTRANS_AX_LOWER_ 10.0 (All) Maximum distance which
Distance LIM".."LKINTRANS_OUT_AX_ axes can be pulled
UPPER_LIM"] of LReal

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 11
 2 Engineering

Diagnostic type LKinTrans_typeDiagnostics

The diagnostics type provides information about FB errors.

Table 2-11: Parameter of LKinTrans_typeDiagnostics

Name Type Value Comment
status Word 16#0 Status of the FB or error identification when
error occurred
subfunctionStatus Word 16#0 Status or return value of called FBs, FCs and
system blocks
stateNumber DInt 0 State in the state machine of the FB when
the error occurred
timestamp Date_And_ DT#1990-01- Time stamp when error occurred
Time 01-00:00:00
additionalValue1 Word 16#0 Additional error specification
 Siemens AG 2018 All rights reserved

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 12
 2 Engineering

2.2 Project integration

2.2.1 Requirements

To run the application LKinTrans, a basic TIA Portal V15 project with a S7-1500T
controller and the used number of TO PositioningAxis or TO SynchronousAxis
need to be set up.
2.2.2 Import

The table below lists the steps for integrating the blocks, tags and types of the
LKinTrans library into the TIA Portal project. The folders can be imported by drag
and drop into the corresponding folder in the PLC project tree (see Figure 2-4).

Table 2-12: Steps for importing the library folders

No. Action

1. Copy the folder LKinTrans_Tags with drag & drop into the “PLC tags” in the PLC

2. Copy the folder LKinTrans_Types with drag & drop into the “PLC data types” in the PLC

3. Copy the folder LKinTrans_Blocks with drag & drop into the “Program blocks” in the PLC

4. Now the blocks can be configured and called in the user program
 Siemens AG 2018 All rights reserved

Figure 2-4: Integrating the library blocks into the program blocks

2.2.3 Call and parametrization

The main function block of the library is LKinTrans_Main. It has to be called

synchronous with the processing of the assigned output axes, which means that it
is typically called in OB "MC-PreServo".

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 13
 2 Engineering

It is necessary to create the variables for parameter structure, input axes reference
and output axes reference out of the library types and tags. All other input
parameters are elementary data types. The assignment of the variables can be
done once, e.g. in the OB "Startup". For further information about configuring the
parameter structure, see chapter 2.1.6.

Figure 2-5: Interface variables which rely on library tags and types

If the FB call is in a Pre- or Post-Servo OB, it is recommended to link the input

parameter cycleTime directly with the Input parameter CycleTime of the OB, in
order to keep it consistent if for example the bus cycle changes. An example call of
the FB is shown in Figure 2-6.

Figure 2-6: Example call of the LKinTrans_Main FB instance

 Siemens AG 2018 All rights reserved

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 14
 2 Engineering

2.3 User defined kinematics transformation

2.3.1 Inverse transformation

The inverse kinematics transformation of the user defined kinematics has to be

programmed in the function block LKinTrans_InvKinTrans.
The Cartesian data (position, velocity and acceleration) are the input parameter,
the axes data (position, velocity and acceleration) are the output parameter.
Information about the transformation is offered in an In/Out-parameter. The result
of the calculation (valid, error) should be written into the status parameter.
The code is separated into four regions:
1. INPUT: Copy input values into process values
2. CALL_INV_FRAME_TRANS: Inverse frame transformation for input process
values
3. CALL_INV_TRANS_FC: Inverse kinematics transformation from framed input
process values to output process values
4. OUTPUT: Copy output process values into output values

NOTE In the standard case, only region three is relevant for the user programming

The frame transformation is necessary in order to transform the coordinate system

 Siemens AG 2018 All rights reserved

in which the Cartesian input values are defined into the system that the
transformation is using (example: input values in WCS, kinematics transformation
in KCS).
For the kinematics transformation area, it is possible to program the equations
directly (example 1 in the listed code sequence below), encapsulate the equations
into functions (example 2) or mix both ways.

//--------------------------------------------------------------------------------
// Begin of user area - place transformation equations here
//--------------------------------------------------------------------------------
REGION CALL_INV_TRANS_FC
// call selected transformation ID
// get cartesian positions from variable statCartesianData
// write axes positions into variable statAxesData
CASE #parameter.config.transID OF

1: //example 1: Direct programming of equations

#statAxesData[1].position := #parameter.config.kinParameter[2] *
#statCartesianData[1].position;
#statAxesData[2].position := #parameter.config.kinParameter[2] *
#statCartesianData[2].position;
#statAxesData[3].position := #parameter.config.kinParameter[2] *
#statCartesianData[3].position;

2: //example 2: call user function

#status := "LKinTrans_TransformationUserInv"
(cartesianData := #statCartesianData,
linkConstellation := #parameter.status.linkConstellation,
calcMode := #parameter.config.calcMode,
axesData => #statAxesData,
kinParameter := #parameter.config.kinParameter);

ELSE
//ID not defined
#status := #ERR_NO_TRANSFORMATION_SELECTED;
END_CASE;
END_REGION

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 15
 2 Engineering

2.3.2 Forward transformation

The forward kinematics transformation of the user defined kinematics has to be

programmed in the function block LKinTrans_FwdKinTrans.
Basically, it has the same structure as the inverse transformation explained in
chapter 2.3.1. However, here the input data are the joint values, the output data
are the Cartesian values and the kinematics transformation is done before the
frame transformation.
2.3.3 Use of calculation mode

Sometimes, it is necessary to not only calculate the position transformation, but

also the velocity or even the acceleration transformation. This leads to a better
quality of velocity pre-control.
The calculation mode is controlling the source of the command values of the output
axes motion interface. The following rules apply:
 calcMode = 0:
– MotionIn position: from transformation
– MotionIn velocity: derivation from motionIn position
– MotionIn acceleration: derivation from motionIn velocity
 calcMode = 1:
– MotionIn position: from transformation
–
 Siemens AG 2018 All rights reserved

MotionIn velocity: from transformation

– MotionIn acceleration: derivation from motionIn velocity
 calcMode = 2:
– MotionIn position: from transformation
– MotionIn velocity: from transformation
– MotionIn acceleration: from transformation

The next code sequence shows an example use of the calcMode parameter. The
velocity and acceleration values must be assigned in the corresponding calculation
mode; otherwise there might be dynamic issues with the output axes.

IF #parameter.status.linkConstellation = 16#0 THEN

//transformation for link constellation 0
//position transformation
;//...

IF #parameter.config.calcMode > 0 THEN

//velocity transformation -> df(s)/dt
;//...

END_IF;

IF #parameter.config.calcMode > 1 THEN

//acceleration transformation -> df(v)/dt
;//...

END_IF;

//ELSIF #linkConstellation = 16#1 THEN

// ...code if needed
END_IF;

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 16
 2 Engineering

2.3.4 Modulo

All input and output axes can be parametrized with modulo. By enabling the
transformation, the settings of all axes are stored in the status structure. The
modulo range does not need to be taken into account while programming the
transformation. This task is done by the main FB.

2.4 Operation
2.4.1 Preconditions

A few preconditions must be met before the user transformation can be enabled.
Also, some preparatory work might be necessary.

Axes state
The following table lists the preconditions of the used input and output axes and
the respective error message if the condition is not fulfilled.

Table 2-13: Preconditions

Precondition Input axis Output axis Error Message
Technology type TO_PositioningAxis, TO_PositioningAxis, ERR_..._AXIS_INVALID
TO_SynchronousAxis TO_SynchronousAxis
 Siemens AG 2018 All rights reserved

Axis type Virtual Axis Virtual Axis, Real Axis ERR_INPUT_AXIS_

NOT_VIRTUAL
Enabled (Axis Not relevant Yes ERR_..._AXIS_STATE
StatusWord Bit 0)
Error pending (Bit 1) No No ERR_..._AXIS_STATE
Homing Done (Bit 5) Not relevant Yes ERR_..._AXIS_STATE
Standstill (Bit 7) Yes Yes ERR_..._AXIS_STATE

Furthermore, error ERR_OUTPUT_AXES_IN_USE is set if at least one output axis

is in use by:
 The control panel (statusWord Bit 4)
 A synchronous operation (Bit 22)
 A path motion (Bit 29)

Axes settings
The following settings of the axes are used by the LKinTrans Main FB and may be
set properly according to the used application:
 Input axes:
 Lower following error limit (for consistency monitoring)
<TOAxis>.FollowingError.minValue
 Output axes:
 Lower following error limit (for consistency monitoring)
<TOAxis>.FollowingError.minValue
 Default velocity, acceleration, deceleration, jerk (for pulling)
<TOAxis>.DynamicDefaults.velocity
<TOAxis>.DynamicDefaults.acceleration

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 17
 2 Engineering

<TOAxis>.DynamicDefaults.deceleration
<TOAxis>.DynamicDefaults.jerk
 Maximum velocity, acceleration, deceleration, jerk (for dynamic monitoring
and stopping after error)
<TOAxis>.DynamicLimits.maxVelocity
<TOAxis>.DynamicLimits.maxAcceleration
<TOAxis>.DynamicLimits.maxDeceleration
<TOAxis>.DynamicLimits.maxJerk

Transformation settings
For the transformation, some data might be necessary to set up before activating
the transformation:
 Transformation identifier (<parameter>.config.transID)
 kinematics parameter (<parameter>.config.kinParamter)
 kinematics frame (<parameter>.config.kinFrame)

2.4.2 Enabling

The user transformation is enabled by setting the LKinTrans Main FB input enable
 Siemens AG 2018 All rights reserved

= TRUE. Certain steps are done to ensure a safe start up, which are explained in
the following.

Initial consistency check

Initially, the forward kinematics transformation is called in order to set up
kinematics information depending on the axes position like link constellation.
If the consistency check is enabled, the resulting Cartesian position is used as
input for the inverse transformation. The resulting joint axes position should not
differ from the respective actual position more than the parameterized following
error, otherwise error ERR_TRANS_CONSISTENCY occurs.

Figure 2-7: Initial consistency check

LKinTrans_Main

LKinTrans_InvKinTrans Output Axes

A1 = X + 1
A2 = Y + 2
...

-
> followingError.minValue ?

LKinTrans_FwdKinTrans
X = A1 – 1
Y = A2 – 2
...

Setting up link between input and output axes

Before the input axes can be linked to the output axes, their positions must be
consistent to each other. This can be ensured in two ways:

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 18
 2 Engineering

 Redefine the position of the input axes to their command position resulting
from the output axes position (Figure 2-8). MC_Home is used for this.
 Pull the output axes to their command position resulting from the input axes
position (Figure 2-9). MC_MoveAbsolute is used for this.

Figure 2-8: Redefine input axes

Input Axes Output Axes

LKinTrans_Main

Command LKinTrans_FwdKinTrans
Actual
X, Y, Z X = A1 – 1
A1, A2, A3
Y = A2 – 2
...

Figure 2-9: Pull output axes

Input Axes Output Axes

LKinTrans_Main
 Siemens AG 2018 All rights reserved

Actual Command
X, Y, Z LKinTrans_InvKinTrans A1, A2, A3
A1 = X + 1
A2 = Y + 2
...

The decision between redefine and pull is done by the FB. Pull is used if at least
one input axis is in use by:
 The control panel (statusWord Bit 4)
 A synchronous operation (Bit 22)
 A path motion (Bit 29)
If no input axis is in use, the input axes are redefined.
In the other case, the output axes are pulled to their respective command position.
An example would be if the path was previously interrupted by MC_GroupInterrupt
command.

Movement of kinematics axes

If pulling is executed, the joint axes are positioned to their respective command
position calculated by the inverse transformation.
CAUTION

For the positioning, the dynamic defaults of the respective axes are used
(<TOAxis>.DynamicDefaults…).
The maximum positioning distance for each axis is limited by the parameter array
<parameter>.monitoring.outputAxesMaxPullDistance. If at least one distance would
be exceeded, the error ERR_PULL_AXIS_DEVIATION is thrown.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 19
 2 Engineering

It is possible to affect this behavior by adapting the parameter

<parameter>.monitoring.enableTransformationMode.
 enableTransformationMode = 0:
– Redefine if all input axes are not in use
– Else: pulling of the output axes. If one maximum pull distance is exceeded,
error ERR_PULL_AXIS_DEVIATION is thrown
 enableTransformationMode = 1:
– Only redefine is possible
– If one input axis is in use, error ERR_INPUT_AXES_IN_USE is thrown
 enableTransformationMode = 2:
– Only pulling is possible
– If one maximum pull distance is exceeded, error
ERR_PULL_AXIS_DEVIATION is thrown

Enable not successful

If enabling is not successful, the status output is showing the error identifier and
error is set to TRUE, while all other outputs remain FALSE. Further error
information is visible in the diagnostics output.

Enable successful
If enabling is successful, the status output switches from 16#7000 (no call) to
 Siemens AG 2018 All rights reserved

16#7002 (subsequent call), busy and valid are set TRUE. Once the
transformationActive output is TRUE, the FB is in control of the output axes (motion
interface enabled).

2.4.3 Cyclic call and monitoring

In the cyclic processing state, the command values of all input axes are read in and
used as input for the inverse kinematics transformation in function block
LKinTrans_InvKinTrans. The results are used as command values for the motion
interface of the output axes.
Furthermore, the actual values of the output axes are also read in and processed in
the forward transformation, providing the actual Cartesian position of the
kinematics in <parameter>.status.actualCartesianPosition.

NOTE The actual Cartesian position of the kinematics is not represented by the actual
position of the input axes. It is rather determined by the transformed actual
position of the output axes.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 20
 2 Engineering

Figure 2-10: Cyclic processing state

LKinTrans_Main
Input Axes Output Axes
LKinTrans_InvKinTrans
In_Cmd Out_Cmd
A1 = X + 1
A2 = Y + 2
...

LKinTrans_FwdKinTrans
Out_Act
X = A1 – 1
In_Act Y = A2 – 2
...

If the consistency check is enabled, the command output values are used as input
data for the forward transformation. The resulting Cartesian values are compared
to the command input value by value. If at least one deviation is bigger than the
respective following error setting, error ERR_TRANS_CONSISTENCY occurs (See
Figure 2-11).

Figure 2-11: Cyclic consistency check

Input Axes

LKinTrans_Main
 Siemens AG 2018 All rights reserved

LKinTrans_InvKinTrans
A1 = X + 1
A2 = Y + 2
...

- > followingError.minValue ?

LKinTrans_FwdKinTrans
X = A1 – 1
Y = A2 – 2
...

2.4.4 Disabling

By setting the input enable = FALSE, the FB is disabled. The FB status switches to
16#7000 (No call). The axes command values are set to the last value at the
motion interface. All output axes are stopped immediately with their particular limit
for deceleration and jerk (<TOAxis>.DynamicLimits.MaxDeceleration and
<TOAxis>.DynamicLimits.MaxJerk).
For more information about stopping behavior when disabling the motion interface,
refer to the MC_MotionInPosition command documentation.

2.5 Error handling

2.5.1 Error identifiers

The following table shows the relevant error identifiers. Their range is between
16#8000 and 16#8FFFF. The range reserved for user errors of the kinematics
transformations (sub status of ERR_TRANS_INV and ERR_TRANS_FWD) is
starting at 16#9000.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 21
 2 Engineering

Table 2-14: Error identifiers

Name Type Value Comment

ERR_INPUT_AXIS_INVALID Word 16#8200 Entry of input axes array is not
valid
ERR_OUTPUT_AXIS_INVALID Word 16#8201 Entry of output axes array is not
valid
ERR_CALC_MODE_INVALID Word 16#8202 Calculation mode is not valid
ERR_TIME_INVALID Word 16#8203 Cycle time is smaller or equal
zero
ERR_INPUT_AXIS_NOT_VIRTUAL Word 16#8204 Input axis is not virtual
ERR_NO_TRANSFORMATION_ Word 16#8205 No transformation selected (sub
SELECTED status of ERR_TRANS_INV or
ERR_TRANS_FWD)
ERR_ENABLE_MODE_INVALID Word 16#8206 Enable mode is not valid
ERR_INPUT_AXIS_STATE Word 16#8400 Input axis state is not valid (no
error, standstill)
ERR_OUTPUT_AXIS_STATE Word 16#8401 Output axis state is not valid
(enabled, no error, homed,
standstill)
ERR_UNDEFINED_STATE Word 16#8600 Error due to an undefined state
in state machine
ERR_MOTION_IN Word 16#8601 Error at motionIn command
ERR_REDEFINE_CMD Word 16#8602 Error at redefine command
 Siemens AG 2018 All rights reserved

ERR_PULL_AXIS_CMD Word 16#8603 Error at pull command

ERR_PULL_AXIS_DEVIATION Word 16#8604 Pulling distance is bigger than
limit
ERR_MOTION_IN_ABORTED Word 16#8606 MotionIn command is aborted
by other axis command
ERR_MOTION_IN_LIMIT Word 16#8607 Dynamic for motion interface is
bigger than limit of axis
ERR_INPUT_AXES_IN_USE Word 16#8608 At least one input axis is in use;
redefine not possible
ERR_OUTPUT_AXES_IN_USE Word 16#8609 At least one output axis is in use
ERR_MODULO Word 16#8610 Modulo setting of one axis is not
vaild
ERR_TRANS_CONSISTENCY Word 16#8700 Forward and inverse
transformation are not fitting
ERR_TRANS_INV Word 16#8701 Error at inverse transformation
ERR_TRANS_FWD Word 16#8702 Error at forward transformation

2.5.2 Diagnostic information

The FB output diagnostics provides further information about an error such as

timestamp, error identifier and last FB state (for internal use only).
For some errors, additional information is offered in the subfunctionStatus (if the
error occurred in a sub function) or the additionalValue1 (if the error can have
various reasons).

Sub function status

The sub function status is relevant for the errors listed in the following table.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 22
 2 Engineering

Table 2-15: Meaning of subfunctionStatus

Error identifier Meaning of subfunctionStatus
ERR_INV_TRANS User defined transformation error or no transformation selected
ERR_FWD_TRANS User defined transformation error or no transformation selected
ERR_REDEFINE_CMD ErrorID parameter of MC_Homing
ERR_PULL_AXIS_CMD ErrorID parameter of MC_MoveAbsolute
ERR_MOTION_IN ErrorID parameter of MC_MotionInPosition
ERR_MODULO 16#1: Modulo range is invalid
Other Errors Not relevant

Additional value
The additional value parameter is relevant for the errors listed in the following table.

Table 2-16: Meaning of additionalValue1

Error identifier Meaning of additionalValue1
ERR_INPUT_AXIS_INVALID 16#1: array length not valid
16#2: no axes assigned
ERR_OUTPUT_AXIS_INVALID 16#1: array length not valid
16#2: no axes assigned
 Siemens AG 2018 All rights reserved

ERR_INPUT_AXIS_NOT_VIRTUAL Input axis number (e.g. n = 1: axes array index 1)

ERR_INPUT_AXIS_STATE Input axis number
ERR_OUTPUT_AXIS_STATE Output axis number
ERR_OUTPUT_AXES_IN_USE Output axis number
ERR_MODULO Input or output axis number
ERR_PULL_AXIS_DEVIATION Output axis number
ERR_REDEFINE_CMD Input axis number
ERR_PULL_AXIS_CMD Output axis number
ERR_MOTION_IN Output axis number
ERR_MOTION_IN_ABORTED Output axis number
ERR_TRANS_CONSISTENCY 16#100n: while initial check; position of output axis n not
consistent (e.g. n = 1: axes array index 1)
16#200n: while check after redefine; position of output axis n not
consistent
16#300n: while check after pull; position of input axis n not
consistent
16#400n: while cyclic check; position of input axis n not
consistent
ERR_MOTION_IN_LIMIT Dynamic limit of output axis would be exceeded (See parameter
outputAxesDynamicLimitFactor)
16#100n: Velocity limit of axis n
16#200n: Acceleration limit of axis n
16#300n: Deceleration limit of axis n
(e.g. 16#2003: Acceleration limit of output axes array index 3)
Other Errors Not relevant

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 23
 2 Engineering

2.5.3 Error reaction and acknowledgement

Reaction
If an FB error occurs (error = TRUE), the status output shows the error number and
the diagnostic output further information. The motionIn functionality is aborted. All
output axes are immediately stopped with their maximum deceleration and
unlimited jerk, in order to ensure a fast stop. The error reason can be diagnosed in
the status and diagnostics output.

CAUTION Trapezoidal stop with axis deceleration limit

The output axis declaration limit (<TOAxis>.DynamicLimits.MaxDeceleration)
must be set to a value which fits mechanical restrictions. If not, mechanical
damage may result.

Acknowledgement
A pending error can be acknowledged by setting the enable input to FALSE. The
output signals error and status are reset. However, the error information in the
diagnostic structure is kept until the FB is enabled again.
TO errors are not acknowledged by the FB. This has to be done by the user.
 Siemens AG 2018 All rights reserved

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 24
 3 Application example

3 Application example
3.1 Project configuration
The application example "LKinTrans_Example_V_1_1" shows a basic
implementation of the LKinTrans Library.
From technology side of view, only jogging of the input axes is implemented, which
makes the application very small. It is suitable as a base for testing own user
transformations.
The project contains the following configuration:
 CPU 1516T-3 PN/DP, Firmware V2.5
 3 Input axes (technology objects Axis_X, Axis_Y, Axis_Z)
 3 Output axes (technology objects Axis_A1, Axis_A2, Axis_A3)
 Transformation type: Cartesian 3D with gear factor
– parameter[0]: Gear factor between X and A1
– parameter[1]: Gear factor between Y and A2
– parameter[2]: Gear factor between Z and A3

Figure 3-1: Configuration of application example

LKinTrans_Main
 Siemens AG 2018 All rights reserved

Input Axes Output Axes

LKinTrans_InvKinTrans

Axis_X
A1 = X * Par[0] Axis_A1
A2 = Y * Par[1]
A3 = Z * Par[2]

Axis_Y Axis_A2

LKinTrans_FwdKinTrans

Axis_Z X = A1 / Par[0] Axis_A3

Y = A2 / Par[1]
Z = A3 / Par[2]

A list with the relevant OBs is shown in the following. No additional FCs or FBs are
used.

Table 3-1: Used OBs

OB Number Content
Startup 100 Configuration of LKinTrans:
 Assignment of axes
 Calculation mode
 Transformation ID
 kinematics parameter
 Consistency check
MC-PreServo 67 Call of FB LKinTrans_Main instance
Main 1 Axes functions:
 Reset, enable and homing of Axis_A1, Axis_A2 and Axis_A3

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 25
 3 Application example

OB Number Content
 Reset and enable of Axis_X, Axis_Y and Axis_Z
 Jog of Axis_X, Axis_Y and Axis_Z

Two additional data types are defined in order to keep the project organized:
 typeAxesControl: Variables for axes functions (enable, reset…)
 typeKinTransControl: Variables which are connected to the FB
LKinTrans_Main interface
All relevant variables for axes and LKinTrans control are located in DB
"DataGlobal".

3.2 Operation
After download of the PLC, the application example can be controlled by the
following steps (See Figure 3-2):
1. Open the watch table Control
2. Enable all axes with DataGlobal.axesControl.enableAxes
3. Home output axes DataGlobal.axesControl.homeOutputAxes
4. Enable transformation with DataGlobal.kinTransControl.enable – If enabling
was successful, the status switches to 16#7002.
 Siemens AG 2018 All rights reserved

5. Jog in Cartesian directions. The position of Axis A1, A2 and A3 is changing

according to the configured gear factor.

Figure 3-2: Operation of application example

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 26
 4 Additional information

4 Additional information
4.1 Distinction to user defined TO Kinematics
Besides the use of LKinTrans, it is also possible to define a user defined
kinematics on a S7-1500T with the TO kinematics type "User-defined…". The
following table gives a short overview about the functionality of both solutions.

Table 4-1: Distinction between TO Kinematics and LKinTrans user defined transformation
Feature TO Kinematics LKinTrans
Maximum degrees of freedom 4 No limitation
Programming of path movement MC Commands Free specification
Zone monitoring Yes With workaround (See chapter
4.4.2)
Consideration of joint axes limits Yes No
into dynamic planning

4.2 Function set for standard kinematics

The forward and inverse position transformation for all kinematics types of the TO
Kinematics V4.0 is available in the LKinTrans_Kinematics folder of the library.
 Siemens AG 2018 All rights reserved

These functions are called in LKinTrans_FwdKinTrans and LKinTrans_InvKinTrans

by default. The transID used is equal to the identifier of the TO Kinematics twin.

Parametrization and boundaries

All transformations are defined the same way as the respective TO Kinematics
twin. More information about axes assignment, parameter meaning and
permissible traversing range can be found in the TO Kinematics function manual
(See links in chapter 6.3).
The frame of a possible tool is set in parameter 10 to 13.

NOTE When using a standard kinematics transformation function, the minimum value
for library constant LKINTRANS_KIN_PARA_UPPER_LIM is 13.
LKINTRANS_AX_LOWER_LIM must be set to 1.
The minimum value for LKINTRANS_OUT_AX_UPPER_LIM and
LKINTRANS_IN_AX_UPPER_LIM is 4.

Table 4-2: Meaning of parameter for standard kinematics transformation functions

Parameter number Meaning
0 Not used
1 See respective TO Kinematics type
2 See respective TO Kinematics type
3 See respective TO Kinematics type
4 See respective TO Kinematics type
5 See respective TO Kinematics type
6 See respective TO Kinematics type
7 See respective TO Kinematics type

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 27
 4 Additional information

Parameter number Meaning

8 Not used
9 Not used
10 Toolframe position x
11 Toolframe position y
12 Toolframe position z
13 Toolframe rotation A
> 13 Not used

NOTICE Invalid Frame definition

Depending of the type of kinematics (2D or 3D; with Orientation or without),
some dimensions of kinematics frame and tool frame might be invalid. This is not
checked by the transformation and may lead to unwanted behavior. Please refer
to the TO Kinematics function manual for a list of valid frame settings.

Axes assignment
When using a kinematics frame or a tool frame, it is recommended to connect the
input axis for Orientation A (forth entry of input axes array) to virtual axis, even if it
is not used. Unlike the types offered by TO Kinematics, there is no distinction
between "with orientation" or without.
 Siemens AG 2018 All rights reserved

For 2D types, it is not recommended to assign input axis Y (second entry of input
axes array) and output axis A3 (third entry of output axes array).

Inverse transformation
The inverse transformations LKinTrans_<Type>_Inv are used to calculate from
Cartesian values to axes values. All FC have the same interface, descripted in the
following.

Figure 4-1: LKinTrans_<Type>_Inv

LKinTrans_<Type>_Inv
Array[*] of cartesian Array[*] of
axesData
"LKinTrans_typeMotionData" Data "LKinTrans_typeMotionData"
link
DWord
Constellation
USInt calcMode
kinParameter
Array[*] of LReal Array[*] of LReal

Table 4-3: Parameter of LKinTrans_<Type>_Inv

Name P-Type Data Type Comment
cartesianData IN Array[*] of Cartesian values
"LKinTrans_typeMotionData"
linkConstellation IN DWord Link constellation
calcMode IN USInt 0: Only Position,
1: Position and Velocity,
2: Position, Velocity, Acceleration
(Note: Only position transformation
is available)

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 28
 4 Additional information

Name P-Type Data Type Comment

axesData OUT Array[*] of Axes values
"LKinTrans_typeMotionData"
kinParameter IN_OUT Array[*] of LReal kinematics parameter

Forward transformation
The forward transformations LKinTrans_<Type>_Fwd are used to calculate from
axes values to Cartesian values. All FC have the same interface, descripted in the
following.

Figure 4-2: LKinTrans_<Type>_Fwd

LKinTrans_<Type>_Fwd
Array[*] of cartesian Array[*] of
axesData
"LKinTrans_typeMotionData" Data "LKinTrans_typeMotionData"
link
USInt calcMode DWord
Constellation
kinParameter
Array[*] of LReal Array[*] of LReal

Table 4-4: Parameter of LKinTrans_<Type>_Fwd

Name P-Type Data Type Comment
axesData IN Array[*] of Axes values
 Siemens AG 2018 All rights reserved

"LKinTrans_typeMotionData"
calcMode IN USInt 0: Only Position,
1: Position and Velocity,
2: Position, Velocity, Acceleration
(Note: Only position transformation
is available)
cartesianData OUT Array[*] of Cartesian values
"LKinTrans_typeMotionData"
linkConstellation OUT DWord Link constellation
kinParameter IN_OUT Array[*] of LReal kinematics parameter

Status identifier
The following table shows the meaning of the status parameter.

Table 4-5: Status identifier of standard transformations

Name Type Value Comment

TRANSFORMATION_VALID Word 16#0 Transformation is valid
USER_ERR_PARA_INVALID Word 16#9000 At least one parameter is invalid
USER_ERR_NOT_REACHABLE Word 16#9001 Position is not reachable
USER_ERR_SINGULARITY Word 16#9002 Axes are in singularity
USER_ERR_AXES_ARRAY_INVALID Word 16#9003 Axes array length is invalid
USER_ERR_PARA_ARRAY_INVALID Word 16#9004 Parameter array length is too
small

4.3 Command value source

When using TO Kinematics, the interpolation and therefore the coordinated
movement of all axes is done by the system. This is a task of the user when using

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 29
 4 Additional information

LKinTrans. It is possible to control the (Cartesian) input axes in any way, for
example:
 Single axis commands: use of single axis commands for moving in a single
direction e.g. for jog mode.
 TO Kinematics: assignment of the input axes to a kinematics type "Cartesian
portal" for almost the full TO Kinematics functionality.
 Motion interface: with using the motion interface of the input axes, it is possible
to move the kinematics independently in any direction.
 Camming: For some tasks, it is required to couple the path movement to a
master cycle.

4.4 Practical advices

4.4.1 Behavior of motion interface

The MC_MotionInPosition command is used to control the output axes. This

command has input parameter for position, velocity and acceleration.

Use of input data when enabled

Once enabled, the input parameters are used for the following:
 MotionIn position: <TOAxis>.position
 MotionIn velocity: <TOAxis>.velocity
 Siemens AG 2018 All rights reserved

 MotionIn acceleration: <TOAxis>.acceleration

In practice, the values have the following effect:
 MotionIn position: input of the position controller
 MotionIn velocity: input of the velocity pre-control
 MotionIn acceleration: no effect for the actual movement of the axis
So, the position value of the motion interface is leading the movement of the axis,
supported by the motion interface velocity. The command acceleration has no
effect on the actual movement.

CAUTION Undesired fast movement of kinematics

If the motion interface velocity is generated by derivation of the transformed
position (calcMode = 0), the FB input cycleTime is determining the motion
interface velocity. If the stated time (in nanoseconds) is smaller than the actual
call cycle of the FB, the calculated velocity is bigger than the desired velocity.
This may lead to damage, as the value is directly used as pre-control for the
speed controller.

Use of input data when aborted

When the motion interface functionality is aborted (disable, function error or TO
error), the command values of the axis are the last motion interface values.
Starting from these values, the axis is stopped by using the maximum axis limits for
acceleration, deceleration and jerk.
This leads to the behavior, that for example an acceleration that is not consistent
with the velocity has no effect when the motion interface is enabled, but when the
motion interface is disabled, the stop profile is starting at the "wrong" acceleration.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 30
 4 Additional information

4.4.2 Zone monitoring and kinematics trace

If the Cartesian position source is not TO Kinematics, you can still use the zone
monitoring functionality and the kinematics trace of the TO Kinematics.
For this, it is necessary to define a dummy kinematics object of type "Cartesian
portal" and to connect it with the Cartesian input axes. Then, the dummy
kinematics is used in feedback mode, tracking the movement of the Cartesian
axes. This movement can be recorded with the kinematics trace.
If a collision with a previously defined zone occurs, an error on the dummy
kinematics object is set. However, the movement is not stopped. The user should
respond on a collision with an appropriate reaction on the real kinematics axes.

Figure 4-3: Definition of a dummy kinematics object

Input Axes Output Axes
LKinTrans_Main

Axis_X Axis_A1

Axis_Y Axis_A2

Axis_Z Axis_A3
 Siemens AG 2018 All rights reserved

Zone monitoring

Kinematics trace
Cartesian portal

Kinematics object

4.4.3 Performance

Performance table
The LKinTrans library might take a lot of performance due to the use of the motion
interface technology. The following table lists the time for one FB call in the OB
"MC-PreServo" with the following configuration:
 2 or 3 input axes
 1:1 transformation of position, velocity, acceleration (Cartesian portal 3D)
 No Frame transformation
 2 or 3 output axes
 Monitoring active

Table 4-6: Performance table

Approx. time for FB call in microseconds
Controller
3 In / Out Axes 2 In / Out Axes
S7-1511T-1 PN 3000 µs 2400 µs
S7-1515T-2 PN 1800 µs 1400 µs
S7-1516T-3 PN/DP 530 µs 400 µs
S7-1517T-3 PN/DP 160 µs 140 µs

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 31
 5 Update notes

5 Update notes
5.1 Changelog
From V1.0 to V1.1
The following changes were made with LKinTrans V1.1:
 New feature: Position transformation of all TO kinematics V4.0 kinematics
types available
 New feature: Input and output axes can now be set as modulo axes
 Modification: Names of Library constants changed
 Modification: Lower limit of axes array is now variable
 Modification: Data type of <LKinTrans_typeParameter>.config.transID changed
from INT to DINT
 Modification: Blocks LKinTrans_FwdKinTrans and LKinTrans_InvKinTrans
changed from function to function block
 Modification: Names of sub blocks changed; blocks shifted into subfolders
 Modification: Extended information for some error identifiers

5.2 Update guideline

 Siemens AG 2018 All rights reserved

From V1.0 to V1.1

The former transformation functions LKinTrans_FwdKinTrans and
LKinTrans_InvKinTrans are now implemented as function blocks. If they were used
stand-alone, an instance must now be created. See chapter 2.1 for more
information about the block interface.
The lower limit of the input and output axes array is now variable with constant
LKINTRANS_AX_LOWER_LIMIT. The default value is 1. Adapt this value in case
of inconsistencies.

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 32
 6 Appendix

6 Appendix
6.1 Service and Support
Industry Online Support
Do you have any questions or need assistance?
Siemens Industry Online Support offers round the clock access to our entire
service and support know-how and portfolio.
The Industry Online Support is the central address for information about our
products, solutions and services.
Product information, manuals, downloads, FAQs, application examples and videos
– all information is accessible with just a few mouse clicks at:
https://support.industry.siemens.com

Technical Support
The Technical Support of Siemens Industry provides you fast and competent
support regarding all technical queries with numerous tailor-made offers
– ranging from basic support to individual support contracts. You send queries to
Technical Support via Web form:
www.siemens.com/industry/supportrequest
 Siemens AG 2018 All rights reserved

SITRAIN – Training for Industry

With our globally available training courses for our products and solutions, we help
you achieve with practical experience, innovative learning methods and a concept
that’s tailored to the customer’s specific needs.
For more information on our offered trainings and courses, as well as their
locations and dates, refer to:
www.siemens.com/sitrain

Service offer
Our range of services includes the following:
 Plant data services
 Spare parts services
 Repair services
 On-site and maintenance services
 Retrofitting and modernization services
 Service programs and contracts
You can find detailed information on our range of services in the service catalog:
https://support.industry.siemens.com/cs/sc

Industry Online Support app

You will receive optimum support wherever you are with the "Siemens Industry
Online Support" app. The app is available for Apple iOS, Android and Windows
Phone:
https://support.industry.siemens.com/cs/ww/en/sc/2067

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 33
 6 Appendix

6.2 Application Support

Siemens AG
Digital Factory Division
Factory Automation
Production Machines
DF FA PMA APC
Frauenauracher Str. 80
91056 Erlangen, Germany
mailto: tech.team.motioncontrol@siemens.com

6.3 Links and Literature

Table 6-1: Links and Literature
No. Topic
\1\ Siemens Industry Online Support
https://support.industry.siemens.com
\2\ Link to this entry page of this application example
https://support.industry.siemens.com/cs/ww/en/view/109758302
\3\ Link to TO Kinematics function manual
https://support.industry.siemens.com/cs/ww/en/view/109749264
 Siemens AG 2018 All rights reserved

\4\ Link to S7-1500T Motion Control manual

https://support.industry.siemens.com/cs/ww/en/view/109749263

6.4 Change documentation

Table 6-2: Change documentation
Version Date Modifications
V1.0 06/2018 First version
V1.1 10/2018 Update

Library Kinematics Transformation

Entry-ID: 109758302, V1.1, 10/2018 34