Creating Custom Kinematics

Important

The open source tool wkhtmltopdf is required to generate the documentation for the kinematics from the comments in the function block. However, this component is no longer included in the setup of CODESYS version 3.5 SP15 and higher.

You can download the DLL from https://wkhtmltopdf.org/downloads.html. Create a directory named DocScripting\3.5.xx.x\bin in the installation directory of CODESYS and save the file wkhtmltox.dll there.

Caution: Since wkhtmltox.dll no longer supports images by default in Version 0.12.6 and higher, you need to use Version 0.12.5 or lower.

Important

When an instance of a kinematic transformation of an axis group is used, the inputs of the instance must not be changed anymore.

To change the parameterization of the kinematic transformation, you need to use the configuration if possible, or create multiple instances.

When you create custom kinematics, you need to observe the following:

Kinematics are described by special function blocks which can be stored in libraries or in the POUs view of the project.
For CODESYS to list the kinematics in the configurator, the associated function blocks have to implement the MC_KIN_REF_SM3 interface (part of SM3_Transformation.library).
You can define kinematics as a combination of two other kinematics. Kinematics with the possibility of attaching tool plates or tools also have to implement the ISMPositionKinematics2 interface. Kinematics that specify a tool plate or tool have to implement the ISMToolKinematics2 interface.
If you implement only ISMPositionKinematics / ISMToolKinematics instead of ISMPositionKinematics2 / ISMToolKinematics2, then "unavailable" orientations could be processed incorrectly.
When you also implement the interface ISMPositionKinematics_Offset, you can use the orientation mode Axis.
When the POU has the sm_kin_libdoc attribute, the comment specified in the function block is used in the configurator as a description of the kinematics. "Restructured Text" formatting is used for this. Note, however, that links are not supported.
Design-related parameters, such as arm lengths and angles, are created as VAR_INPUT variables of the function block. You should comment the parameters because the comment serves as a description in the configurator. If the parameters are a numeric type and their value range is restricted, then they must be provided with the sm_kin_param_range attribute.
The syntax of the value range is [a .. b] for closed intervals and ]a .. b[ for open intervals. The combined forms ]a .. b] and [a .. b[ are also possible. For this purpose, a and b have to be appropriate literals for the parameter type. The special values +inf and -inf are possible for open interval limits. Examples: [0 .. 1], [1 .. +inf[, ]-inf .. -5].
Parameters can by any numeric type or BOOL. Parameters should have an initial value that is used as the default value. You can specify the unit of the parameter with the optional attribute sm_kin_param_unit (example: "rad", "°", "deg"). You should use the unit "u" for lengths and distances. The application and the scaling of the drives determine whether these units are "mm", "cm", or "m".
If there is no library documentation available for the function block, then the comment of the FB element is displayed at the respective positions as a fallback option.
The language configured in CODESYS is the displayed language for the LibDoc documentation. If a localization is not available in this language, then the default language of the library is used.
The axis names of the kinematics are defined by the FB attribute sm_kin_axes. The value of the attribute is a list of axis names (example: "A1, A2, A3").
An optional icon is specified with the FB attribute sm_kin_icon. The value is specified in the form <image pool>.<identifier>. The image pool is specified relative to the function block.
If you create a custom kinematics function block with revolute joints (for example, Kin_Scara3_Z_Config), then you should use the period concept for theses axes and implement the ISMKinPeriodHandling interface. For rotary axes, only the inverse kinematic transformation (CartesianToAxes) is responsible for the calculation of the angle. Then CODESYS SoftMotion automatically shifts this angle to the correct period. For example, if the transformation calculates an angle in the range ]-180°, 180°], then CODESYS SoftMotion shifts this angle to the range [0°, 360°[, provided that the software boundaries of the drive are 0° .. 360°. Moreover, you should implement the ISMKinematicsWithConfiguration3 interface. This is the only way to make sure that the kinematics for CP movements work without any problems.
In the case of coupled kinematics with an irregular layout of position and orientation kinematics, you should implement the ISMCoupledKinematics3 interface. In this way, the system can detect whether or not an axis for position or orientation kinematics belongs with the respective axis number.
Note: You should implement the ISMKinematicWithConfigurations2.CPConnectible method in such a way that the period settings are ignored on comparison. Then CPConnectible returns the value TRUE, even if the period setting is different.

All inverse transformations have an input of type CONFIGDATA that contains a byte array with information about the configuration of the kinematics. The forward transformations have a corresponding output. Kinematics with a configuration have to implement the ISMKinematicWithConfigurations interface. These kinematics each include a function block that has to implement the ISMConfigurationData interface (function for the serialization of the configuration data). The name of this function block has to be the same name as kinematics plus the postfix _config. You can use this FB for modifying the configuration in the application (by means of the function block SMC_SetKinConfiguration block). However, kinematics should not hold any instance of the corresponding FB.

Tip

For step-by-step instructions, see the Custom Kinematics chapter.