Overview
Based on the SoftMotion specification, inherits a series of interfaces to implement kinematic models that can be loaded by AxisGroup objects. It is designed to calculate the motion patterns of each robot joint to ensure the tool tip—Tool Center Point (TCP)—can follow the commanded path with the desired pose. Kinematics or kinematic transformations form the basis of this calculation.
The product components are as follows:
SF512x_Kinematics: The main library for the product SF512x. After loading this main library, the internal kinematic transformation models can be selected in AxisGroup.
The following table provides an overview of each product component
| Product components | Description |
| SF512x_Kinematics | The main library of product SF512x. After loading the main library, the internal kinematic transformation models can be selected in AxisGroup. |
Installation and Uninstallation
Installation
Installation Requirements
Recommended platform version: CODESYS higher than CODESYS V3.5 SP20 Patch6+.
Recommended platform library files: CODESYS Math Libraries.
Auxiliary component: Ensure the calling program has loaded the Licensing component.
RTE component: Ensure the controller RTE has preloaded the Licensing component.
Controller hardware: Series controllers produced by Sinsegye.
Installation Process
Open the Library Manager page in any opened project:
Click the button:
Click : Select the SF512x_Kinematics_v3p5_sp20_patch6+_v2.0.1.1.compiled-library (main product library file) under the personal path to install. After completion, click :
Return to the interface, click , and search for SF512x_Kinematics:
Double-click to complete the installation in the project.
Update
In the interface
Click :
Double-click the middle column containing the version number to select the latest/other version for installation.
Uninstallation
In the interface, search for the keyword SF512x_Kinematics, select the version to be uninstalled, and click Uninstall:
Technical Specifications
Quick Start
Software and Hardware Configuration for This Example
|
Hardware: Series controllers produced by Sinsegye |
Software: SF512x_Kinematics |
Experimental Schematic Diagram
The basic implementation interfaces for kinematics transformation are AxesToCartesian and CartesianToAxes, mathematically representing the forward-inverse mapping between robot axis coordinate system and the Cartesian coordinate system. The following is a simple diagram:
Experimental Procedures
Project environment preparation: correctly install the main library and related dependencies according to Section II. Installation and Uninstallation, and ensure that the product has a real physical connection with the used Sinsegye controller and that they are on the same network segment.
Create a new project, and double-click to select the page as follows:
Scan the network and test the connection with the controller hardware to proceed to the next step of testing.
Right-click on to create an object.
Left-click - , and select , taking this Scara robot model as an example.
Fill in the robot configuration parameters and the product authorization code, and then bind the virtual axis object/actual axis object.
You can then test related functions of the library based on this object. Taking as an example, add this control in the visualization interface, specify the object, and directly control the movement of virtual/actual axes.
Function Introduction
SoftMotion Interface Support List
SF512x_Kinematics currently supports the following CODESYS SoftMotion interface (TRAFO namespace):
| Interface | Support Status | Interface Significance |
| TRAFO.MC_KIN_REF_SM3 | Supported | Basic kinematic reference interface, providing fundamental capabilities of the kinematic object |
| TRAFO.ISMKinematicWithInfo2 | Supported | Extended kinematics information interface, providing axis quantity, axis properties, and pose space information |
| TRAFO.ISMKinematicWithInitialization | Supported | Initialization interface, defining the initialization lifecycle and state availability |
| TRAFO.ISMPositionKinematics_Offset2 | Supported | Position kinematics interface with a tool offset, supporting forward and inverse solutions in offset scenarios |
| TRAFO.ISMKinematicWithConfigurations2 | Supported | Configuration management interface, supporting dimension validation, default values, and continuity determination for configuration data |
Parameter Initialization
Example: Subclass interface mapping taking SCARA model as an example
The robot structure is described as follows:
| Joints | Type | Positive direction | Description |
| A1 | Rotating joint | Vertical base upward (right-hand rule) | The first arm rotates around the Z-axis of the base |
| A2 | Rotating joint | Vertical base upward (right-hand rule) | The second arm rotates around the Z-axis at the end of A1 |
| A3 | Linear joint | The positive direction is upward | TCP translates vertically along the Z-axis |
| A4 | Helical joint | The positive direction is upward | Rotation simultaneously causes TCP to move along the Z-axis (ZC coupling) |
Definition of kinematic zero position: The two active links form a straight line, with the first active link aligned along the base symmetry axis of the base (i.e., the positive X-axis direction of the MCS coordinate system). The Z-axis is perpendicular to the base and points upward, while the Y-axis is determined by the right-hand rule.
ZC coupled (ZCcoupled) characteristic: When the A4 joint rotates, the TCP generates linear displacement along the Z-axis while rotating around it. This displacement is determined by the parameter dPitchZC (amount of movement per revolution, unit: mm).
The following table shows the parameter mapping relationship of the interfaces in the subclass "Taking the SCARA Model as an Example" to illustrate the implementation form of the interface definition in the project.
| Parameter Name | Type | Unit | Scope | Description |
| dOffsetA1 | LREAL | ° | [-360, 360] | Joint angle offset at the kinematic zero position of the A1 axis |
| dLowerA1 | LREAL | ° | [-360, 360] | Lower limit of A1 axis motion range |
| dUpperA1 | LREAL | ° | [-360, 360] | Upper limit of A1 axis motion range |
| dOffsetA2 | LREAL | ° | [-360, 360] | Joint angle offset at the kinematic zero position of the A2 axis |
| dLowerA2 | LREAL | ° | [-360, 360] | Lower limit of A2 axis motion range |
| dUpperA2 | LREAL | ° | [-360, 360] | Upper limit of A2 axis motion range |
| dOffsetA3 | LREAL | mm | [-400, 400] | Joint movement distance offset at the kinematic zero position of the A3 axis |
| dLowerA3 | LREAL | mm | [-400, 400] | Lower limit of A3 axis motion range |
| dUpperA3 | LREAL | mm | [-400, 400] | Upper limit of A3 axis motion range |
| dOffsetA4 | LREAL | ° | [-720, 720] | Joint angle offset at the kinematic zero position of the A4 axis |
| dLowerA4 | LREAL | ° | [-720, 720] | Lower limit of A4 axis motion range |
| dUpperA4 | LREAL | ° | [-720, 720] | Upper limit of A4 axis motion range |
| dLinkLength1 | LREAL | mm | [0, 800] | Length of link 1 (common perpendicular length between joint 1 and joint 2 axes) |
| dLinkLength2 | LREAL | mm | [0, 800] | Length of link 2 (common perpendicular length between joint 2 and joint 3 axes) |
| dPitchZC | LREAL | mm | [-200, 200] | TCP displacement along Z-axis when A4 axis rotates 360° clockwise (downward movement is negative) |
| sLicenseCode | STRING(255) | — | — | Product authorization code for license verification |
Method List
Initialize
Return value type: TRAFO.SMC_Error
Function: Perform the initialization of the kinematics function block. This method must be successfully called before any other method can be called.
Note: 1. Complete parameter loading and validity verification; 2. Complete license or runtime prerequisite verification 3. Initialize the runtime status and write "Initialized" flag 4. Return standard error codes to enable the upper layer to determine failure causes
Return value SMC_NO_ERROR — successful initialization SMC_TRAFO_NOT_INITIALIZED — Invalid parameter or authorization failure
IsInitialized
Return value type: BOOL
Function: Check whether the kinematics function block has been successfully initialized.
Note: This method is the only one that can be safely called prior to the invocation of Initialize, and it can return the state of the internal flag “isInit”. It will returns TRUE when Initialize is successfully executed; otherwise, it will return FALSE.
NumAxes (Properties)
Return value type: UDINT
Function: Return the number of axes of this kinematic model. Taking the Scara robot as an example, it consistently returns 4, corresponding to the four joint axes A1, A2, A3, and A4.
GetKinematicsName
Return value type: STRING(255)
Function: Return a readable name string of the kinematic model, for identification and debugging. Taking the SCARA model as an example, it consistently returns the string 'Kin_Scara4_ZCcoupled'.
GetAxisProperties
Input type: udiAxis (UDINT) — Axis number [0..NumAxes-1] Input/Output (In_Out): props (TRAFO.Axis_Properties) — Axis property structure output
Function: Return property information of the specified axis, including axis type (rotation/linear) and motion range limits. CODESYS SoftMotion obtains the kinematic constraints of each axis with this method.
Taking the SCARA model as an example: properties of each axis:
| Axis number | udiAxis | Type | Limit source |
| A1 | 0 | Rotary | dLowerA1 / dUpperA1 |
| A2 | 1 | Rotary | dLowerA2 / dUpperA2 |
| A3 | 2 | Linear | dLowerA3 / dUpperA3 |
| A4 | 3 | Linear (actually spiral) | dLowerA4 / dUpperA4 |
Note: Although the A4 axis is physically a rotating spiral joint, it is declared as a Linear type here. This is a special treatment method of SoftMotion ZC coupled kinematics to ensure the controller correctly processes its linear equivalent input.
AxesToCartesian
Input/Output (In_out)(const): a (TRAFO.AXISPOS_REF) — Input: Position of each axis (degrees/mm) Input/Output (In_Out): f (TRAFO.SMC_Frame) — Output: TCP pose (position + pose matrix) cd (TRAFO.CONFIGDATA) — Output: Serialized configuration data Return value type: TRAFO.SMC_Error
Function: Forward Kinematics (FK). Calculate the TCP pose in Cartesian space from joint space coordinates.
Note: AxesToCartesian shall receive joint space positions and output Cartesian pose and configuration data; the output pose must be consistent with CONFIGDATA to support inverse kinematics and path planning. Standard error codes shall be returned when geometric or matrix calculation exceptions occur. Return SMC_NO_ERROR — Calculation succeeded - SMC_CP_ERROR_CREATING_PARAM_TRANSFORM — Failed to create rotation matrix.
CartesianToAxes
Input/Output (In_Out): a (TRAFO.AXISPOS_REF) — Output: position of each axis (degrees/mm) Input/Output (In_out)(const): f (TRAFO.SMC_Frame) — Input: TCP pose aRef (TRAFO.AXISPOS_REF) — Input: Position of the reference axis position (used for disambiguation) cd (TRAFO.CONFIGDATA) — Input: Configuration data (elbow selection/cycle selection) Return value type: TRAFO.SMC_Error
Function: Inverse Kinematics (IK). Calculate the position of each joint axis from the Cartesian pose of TCP.
Note: 1. Input the Cartesian pose, configuration data, and reference axis position; output joint space position. 2. Must support configuration constraints and period disambiguation to avoid solution jumps; 3. Return a standard position limit error code when the target exceeds the reachable domain. Taking the SCARA model as an example: This subclass can perform inverse kinematics, coupling compensation, and period disambiguation. aRef is used to resolve ambiguity of rotary axes in multi-turn motion (>360° range), keeping the results as close as possible to the current actual position to avoid axis jumps. Return value SMC_NO_ERROR — Calculation succeeded - SMC_AXIS_INVERSE_TRAFO_EXCEEDING_POSLIMITS — Target position exceeds workspace limits
AxesToOrientation
Input/Output (In_out)(const): a (TRAFO.AXISPOS_REF) — Input: Position of each axis Input/Output (In_out): m (TRAFO.SMC_Matrix3) — Output: Pose rotation matrix of the flange coordinate system Return value type: TRAFO.SMC_ERROR
Function: Calculate the pose (rotation matrix) of the flange coordinate system from the joint axis position, which is the pose subset extraction of AxesToCartesian.
Note: The pose matrix can be extracted by reusing the positive solution results, or the pose can be solved independently. The output must be consistent with AxesToCartesian.
IsSingularity
Input/Output (In_out)(const): a (TRAFO.AXISPOS_REF) — Input: Position of each axis Return value: BOOL
Function: Determine whether the given joint position is at a singular point.
Note: A reproducible singularity determination rule shall be provided, and the return value shall be kept stable and consistent in the vicinity of the singularity. Return value TRUE — at singular position; FALSE — non-singular.
GetOrientationImage
Input/Output (In_out): oriInfo (TRAFO.OrientationSpace) — Output: Pose space description of the flange coordinate system.
Function: Describe all the flange coordinate system pose information generated by this kinematic transformation to SoftMotion. It is used for pose interpolation planning within SoftMotion.
Note: Define the pose degrees of freedom, zero-position pose, and principal rotation axis to support the upper interpolator in the pose space planning.
Taking the SCARA model as an example: - oriInfo.dof = 0: The flange post degree of freedom is 0 (only rotate around the Z-axis, with no independent pose degree of freedom) - oriInfo.mOriZero = identity matrix: The flange coordinate system aligns with the MCS at zero position - oriInfo.vRot = (0, 0, 1): The rotation axis is the Z-axis - oriInfo.vU = (0, 0, 1): The Z-axis direction of the flange aligns with the Z-axis of MCS.
GetConfigurationDataSize
Return value type: INT
Function: Return the size in bytes of the configuration data (CONFIGDATA) used by the kinematic model, which is a constant value. Taking the Scara robot as an example, it always returns 2, corresponding to ConfigData.abyData[0]: elbow selection (0=left elbow, 1=right elbow).
GetDefaultConfigurationData
Input/Output (In_out): cd (TRAFO.CONFIGDATA) — Output: Default configuration data. Return value: BOOL
Function: Return the default kinematic configuration, serialized into a CONFIGDATA structure for use during initialization. Return value: TRUE — successfully return the default configuration.
CPConnectible
Input/Output (In_out)(const): cd1 (TRAFO.CONFIGDATA) — Input: Configuration 1 Input/Output (In_out)(const): cd2 (TRAFO.CONFIGDATA) — Input: Configuration 2 Return Value: BOOL
Function: Determine whether continuous path (CP) interpolation can be performed between the two configurations without causing a jump in axis position. SoftMotion uses this method to determine whether adjacent path segments can be smoothly connected.
Interface characteristics (meeting equivalence relations): - Reflexivity: CPConnectible(c, c) = TRUE - Symmetry: CPConnectible(c1, c2) = CPConnectible(c2, c1) - Transitivity: If c1↔︎c2 and c2↔︎c3, then c1↔︎c3
AxesToConfiguration_Offset
Input/Output (In_out)(const): a (TRAFO.AXISPOS_REF) — Input: Position of each axis Input/Output (In_out)(const): vOffset_TCP (TRAFO.SMC_Vector3D) — Input: Position offset relative to the TCP coordinate system Input/Output (In_out): cd (TRAFO.CONFIGDATA) — Output: Configuration data of offset kinematics
Function: Calculate the configuration data corresponding to the offset TCP from the joint position, taking into account additional tool offsets. This function belongs to the ISMPositionKinematics_Offset2 interface, and is used for tool offset compensation scenarios.
Note: When vOffset_TCP is a zero vector, the returned result is the same as the cd output of AxesToCartesian. When the offset is non-zero, the link geometry is modified equivalently (as if lengthening the second link), potentially resulting in different elbow configurations from the original kinematics.
CartesianToAxes_Offset
Input/Output (In_out): a (TRAFO.AXISPOS_REF) — Output: Position of each axis Input/Output (In_out)(const): v_MCS (TRAFO.SMC_Vector3D) — Input: Position of the offset TCP in the MCS vOffset_TCP (TRAFO.SMC_Vector3D) — Input: Tool offset in the TCP coordinate system aRef (TRAFO.AXISPOS_REF) — Input: Position of the reference axis cd (TRAFO.CONFIGDATA) — Input: Configuration data of the offset kinematics Return value type: TRAFO.SMC_Error
Function: Calculate the position of the joint axis from the Cartesian position of the offset TCP, given the tool offset. This function belongs to the ISMPositionKinematics_Offset2 interface, and is used when the Tool Center Point (TCP) is not at the origin of the flange.
Note: Because the flange pose is unknown at the time of invocation, standard CartesianToAxes cannot be used to directly handle tool offsets; this method is used to handle offsets through the geometric characteristics of positional kinematics. When vOffset_TCP is zero, the result is equivalent to directly calling CartesianToAxes.
Supplementary note: Taking the SCARA model as an example, the meaning of each byte in CONFIGDATA.abyData is as follows:
| Byte index | Variable | Meaning | Value Description |
| abyData[0] | Elbow Selection | Control IK Elbow Orientation | 2=left elbow (A20), 0=automatically follow the current state |
| abyData[1] | nPeriod4 | A4 axis rotation cycle selection | 0=automatically select the nearest cycle; 0=select cycle [-180°+360°*(n-1), 180°+360°*(n-1)] |
The SMC_SetKinConfiguration function block allows dynamic modification of configuration data during motion.
Supported Configurations
| Type | Remarks | Simplified Diagram (Representative) |
| Scara Type | 3-axis and 4-axis: Kin_Scara3_ZCCC, Kin_Scara3_CCZ, Kin_Scara4_CCZC_ZCcoupled, and Kin_Scara4_ZCcoupled_Type1 | |
| Delta type | Kin_Delta_P3C_Type3 | |
| Tripod type | Kin_Tripod_P3Z | |
| Parallel 2D type | Kin_P2C_Type1、Kin_P2C_Type2、Kin_P2Y、Kin_PCC、Kin_P2X_Type1、Kin_P2X_Type2 | |
| Serial 2D type | Kin_SCCC | |
| Universal 6-axis type | Kin_Ac6_RZRYRYRXRYRZ_J6Offset、Kin_Ac6_TXTYTZRYRXRZ | |
Scara-type Configuration
The Scara-type configuration follows a design of 2 rotational axes in plane + 1 vertical linear axis + possible additional end axes (common 3-axis/4-axis variants), and easily forms a “rotation-plane-dominant, Z-axis-independent” geometric structure in Cartesian space.
The workspace typically approximates a ring or fan shape in the XY plane; the Z-axis generally performs an independent linear motion. Standard illustrations are as follows:
Delta-type Configuration
Delta-type robots feature parallel structures (multiple telescoping rods/links). The joint-to-end mapping follows parallel constraints, often offering advantages in dynamics and stiffness. The workspace is typically shaped like a “donut/inverted pyramid” (wider at the top and gradually converging at the middle/edges), which makes the mechanism well-suited for high speed and acceleration. Standard illustrations are as follows:
Universal 6-axis Configuration
It typically features 6 rotational joints to achieve comprehensive pose reachability (full 6 degrees of freedom), enabling direct description of both Cartesian position and pose in general. Inverse kinematics often yields multiple solutions (commonly referred to as “wrist/elbow” branches), and the configuration data are required to resolve ambiguity and ensure continuity. Singularities usually occur in forms of “wrist singularity/elbow singularity”. Standard illustrations are as follows:
Tripod-type Configuration
It is typically configured as a parallel structure with “3 arms/3 constraints” (often used to achieve parallel constraints in a specific pose space), and its end-effector reachability is determined by the length of the parallel links and geometric constraints. Standard illustrations are as follows:
Parallel Planar Configuration
Structural feature: The end effector (or execution point) is constrained to the same plane by multiple branches/links simultaneously, typically representing “parallel geometric mapping with multiple constraints”. Workspace: It is usually shaped as a ring/doughnut or inverted V determined by parallel constraints, and becomes more sensitive when approaching the boundaries. Standard illustrations are as follows:
Series Planar Configuration
Structural feature: The execution point achieves planar mapping through sequentially connected joint chains, typically via 2-rotation/1-rotation+1-extension/equivalent planar 2-DOF chains. The workspace is generally more regular (elliptical/annular band), with boundaries determined by link lengths and angular reachability. Illustrations are as follows: