Creating your own kinematics

Notice

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

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

You must consider the following points if you create your own kinematics:

The kinematics are defined by special function blocks that can be saved in libraries or in the POUs view of your project.

For CODESYS to list the kinematics in the configurator, the associated function blocks must implement the MC_KIN_REF_SM3 interface (constituent part of SM3_Transformation.library).

You can define a kinematic design as a combination of two other kinematics. Kinematic designs with the possibility of attaching tool plates or tools must also implement the ISMPositionKinematics2 interface. Kinematic designs that specify a tool plate or tool must implement the ISMToolKinematics2 interface.

If you implement only ISMPositionKinematics / ISMToolKinematics instead of ISMPositionKinematics2 / ISMToolKinematics2, then unavailable orientations might be processed incorrectly.

When you also implement the interface ISMPositionKinematics_Offset, you can use the orientation mode Axis.

The comment of the function block is used in the configurator for the description of the kinematic design if the block has the attribute sm_kin_libdoc. For this purpose, restructured text formatting is used. Please 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 as a description in the configurator. If the parameters are a numeric type and their value range is restricted, then they should 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. Parameter 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 LibDoc documentation is not 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 kinematic design 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 your own kinematics function block is created with rotary axes, then the period concept for these axes should be used. (Example: see POU Kin_Scara3_Z_Config). In the configuration, a period should be configurable for each rotary axis that supports a value range over 360°. Moreover, the interface ISMKinematicsWithConfiguration3 should be implemented. This is the only way to make sure that the kinematics for CP movements work without any problems.

Note: The method ISMKinematicWithConfigurations2.CPConnectible should be implemented in such a way that the period settingis 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. Kinematic designs with a configuration must implement the ISMKinematicWithConfigurations interface. These kinematics each include a function block that must implement the ISMConfigurationData interface (function for the serialization of the configuration data). The name of this function block must be the same as the name of the kinematic design 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 expressly not maintain an instance of the corresponding FB.