5. calibxyzkins - Calibrated XYZ Kinematics Module for LinuxCNC¶

The calibxyzkins module extends the standard LinuxCNC trivial kinematics module trivkins by applying a mathematical correction to compensate for systematic positioning errors in gantry robots and similar cartesian machines. This is particularly useful for correcting:

Mechanical inaccuracies in manufacturing or assembly
Structural deformations under load
Non-perpendicular axes alignment
Position-dependent errors

5.1. Coordinate Transformation¶

The module implements a coordinate transformation that corrects the relationship between joint positions and actual machine coordinates using both linear and quadratic terms:

\([x', y', z']^T = A [x, y, z]^T + B [x^2, y^2, z^2]^T + C\)

Where:

\((\cdot)^T\): Transpose operator
\(A\): 3×3 linear transformation matrix (scaling, rotation, shear, etc.)
\(B\): 3×3 quadratic transformation matrix (corrects non-linear distortions)
\(C\): 3×1 offset vector (constant position offset)
\(x, y, z\): joint positions
\(x', y', z'\): axes coordinates

The default values of the parameters are:

\(A\): 3x3 identity matrix
\(B\): all zeros
\(C\): all zeros

5.2. Installation¶

Prerequisites:

LinuxCNC development environment
Standard build tools (make, gcc)

To build the module, run:

cd linuxcnc/components/linuxcnc_calibrated_xyz_kins
make

To install the module system-wide, run:

sudo make install

5.2.1. Loading the Module¶

The module can be loaded as any other HAL component. Depending on the machine configuration, the coordinates and kinstype parameters can be used to specify the axis-to-joint mapping.

Examples:

Basic usage (equivalent to trivkins):
```
loadrt calibxyzkins
```
Specify coordinate mapping:
```
loadrt calibxyzkins coordinates=xyz
```

Gantry configuration with duplicated Y axis:

loadrt calibxyzkins coordinates=xyyz kinstype=B

5.3. Module Parameters¶

coordinates

Specifies the axis-to-joint mapping, as in trivkins:
- coordinates=xyz: Standard 3-axis mapping (X→joint0, Y→joint1, Z→joint2)
- coordinates=xyyz: Gantry with dual Y motors (X→joint0, Y→joint1&joint2, Z→joint3)
- coordinates=xyzabc: 6-axis machine. Note that calibration is only applied to the X, Y, and Z axes.
kinstype

Specifies the kinematics type, as in trivkins:
- kinstype=1: KINEMATICS_IDENTITY (default)
- kinstype=B: KINEMATICS_BOTH
- kinstype=F: KINEMATICS_FORWARD_ONLY
- kinstype=I: KINEMATICS_INVERSE_ONLY

5.4. HAL Parameters¶

Calibration Matrix A (Linear Terms):

calibxyzkins.calib-a.xx (float, RW, default: 1.0)
calibxyzkins.calib-a.xy (float, RW, default: 0.0)
calibxyzkins.calib-a.xz (float, RW, default: 0.0)
calibxyzkins.calib-a.yx (float, RW, default: 0.0)
calibxyzkins.calib-a.yy (float, RW, default: 1.0)
calibxyzkins.calib-a.yz (float, RW, default: 0.0)
calibxyzkins.calib-a.zx (float, RW, default: 0.0)
calibxyzkins.calib-a.zy (float, RW, default: 0.0)
calibxyzkins.calib-a.zz (float, RW, default: 1.0)

Calibration Matrix B (Quadratic Terms):

calibxyzkins.calib-b.xx (float, RW, default: 0.0)
calibxyzkins.calib-b.xy (float, RW, default: 0.0)
calibxyzkins.calib-b.xz (float, RW, default: 0.0)
calibxyzkins.calib-b.yx (float, RW, default: 0.0)
calibxyzkins.calib-b.yy (float, RW, default: 0.0)
calibxyzkins.calib-b.yz (float, RW, default: 0.0)
calibxyzkins.calib-b.zx (float, RW, default: 0.0)
calibxyzkins.calib-b.zy (float, RW, default: 0.0)
calibxyzkins.calib-b.zz (float, RW, default: 0.0)

Calibration Vector C (Offset Terms):

calibxyzkins.calib-c.x (float, RW, default: 0.0)
calibxyzkins.calib-c.y (float, RW, default: 0.0)
calibxyzkins.calib-c.z (float, RW, default: 0.0)

Joint Limits:

calibxyzkins.min-limit.x (float, RW, default: -∞)
calibxyzkins.min-limit.y (float, RW, default: -∞)
calibxyzkins.min-limit.z (float, RW, default: -∞)
calibxyzkins.max-limit.x (float, RW, default: +∞)
calibxyzkins.max-limit.y (float, RW, default: +∞)
calibxyzkins.max-limit.z (float, RW, default: +∞)

5.5. HAL Pins¶

Inverse Kinematics Solver Settings:

calibxyzkins.max-iter (u32, IO, default: 10)
- Maximum number of Newton-Raphson iterations for the inverse kinematics.
calibxyzkins.tol (float, IO, default: 1e-3)
- Convergence tolerance for the inverse kinematics solver.

5.6. Inverse Kinematics¶

The module uses the Newton-Raphson method to solve the inverse kinematics problem iteratively:

Initialize the \(3 \times 1\) vector of joint positions \(\mathbf{x}\) (bounded by joint limits if specified)
Compute function: \(F = A \, \mathbf{x} + B \, \mathbf{x}^2 + C - \text{target_position}\)
Compute Jacobian: \(J = A + 2 \, B \, \text{diag}(\mathbf{x})\)
Update joints: \(\mathbf{x} := \mathbf{x} - J^{-1} F\)
Repeat until convergence (\(\|F\| < \text{tolerance}\)) or max iterations reached.

5.7. Debugging¶

Verbose output of the inverse kinematics solver can be enabled by compiling the code with the CALIB_XYZ_INVERSE_PRINT_ITER macro defined.