matrixkins - Calibrated kinematics for 3-axis machines


loadrt matrixkins [count=N|names=name1[,name2...]]


The matrixkins component implements custom kinematics for 3-axis Cartesian machines that allows compensating minor alignment inaccuracies in software.


By default identity matrix is used, which is equal to trivial kinematics:

| X_joint | | 1 0 0 | | X_axis |
| Y_joint | = | 0 1 0 | * | Y_axis |
| Z_joint | | 0 0 1 | | Z_axis |

Adjusting the calibration matrix allows compensating out many mechanical issues, including:

1. Scale error of each axis.
2. Perpendicularity between each pair of axes.
3. Parallelism between spindle rotational axis and Z movement.
4. Perpendicularity between spindle rotational axis and X/Y movement.

The matrix coefficients are set by parameters C_xx .. C_zz. For 3 axis machine, the equations become:

X_joint = C_xx * X_axis + C_xy * Y_axis + C_xz * Z_axis
Y_joint = C_yx * X_axis + C_yy * Y_axis + C_yz * Z_axis
Z_joint = C_zx * X_axis + C_zy * Y_axis + C_zz * Z_axis

If the machine has more than 3 axes, the rest are passed through without adjustment.


For a 3 axis milling machine, the following process can be used to accurately measure and compensate the mechanical alignment.

Tools required:

1. Dial indicator that can be mounted on spindle.
2. Straight rod that can be mounted on spindle.
3. Calipers.


1. Head tramming

Mechanically tram the spindle to the table surface as well as you can. The perpendicularity of spindle vs. table cannot be compensated in software, and the spindle axis will act as the reference for all further steps.

You can measure the perpendicularity by mounting the dial indicator on the spindle. Search for "mill tramming" online for detailed process.

2. X and Y axis squaring

Cut octagon out of some rigid material. It is best to cut a roughing path first and a thin finishing pass last, to get the best accuracy. Make the octagon as large as your calipers can measure. Before unmounting the workpiece, mark the X and Y directions on it.

Measure width along X and Y axes. If your axis scales are set correctly, they should be identical. If they are not, you can adjust c[0] and c[4] to compensate. Note that endmill diameter will affect the actual dimensions of the test octagon, but not the ratio between sides.

Measure width along both diagonals. If the X and Y axes are square to each other, the readings should be identical.

To compensate, set C_xy = (B^2 - A^2) / (2 * A * B) where A is the diagonal in X+/Y+ direction and B is the diagonal in X+/Y- direction.

This adjusts Y axis direction while keeping X axis as it was. Alternatively you can set C_yx to adjust X axis instead. The choice affects alignment with respect to e.g. table slots.

3. X axis squaring to spindle

Mount the dial indicator so that it rotates around the spindle axis, like in tramming measurement. Mark a spot on the table where the indicator touches when it is in positive X direction from spindle center. Zero the dial indicator.

Rotate dial indicator 180 degrees around the spindle. Move X axis in positive direction until the indicator touches the same spot. Ideally indicator reads 0 again.

To compensate, set C_zx = D / X where D is the new dial indicator reading, and X is the length moved along X axis.

4. Y axis squaring to spindle

Same as step 3, except move the machine in positive Y direction.

To compensate, set C_zy = D / Y where D is the new dial indicator reading, and Y is the length moved.

5. Z axis parallelism to spindle in X direction

Mount straight rod to the spindle. Position dial indicator so that it measures horizontally against the positive X side of the rod, close to the spindle.

Spin the spindle by hand to see if there is any runout. Zero the dial indicator at the midway position.

Raise Z axis until dial indicator measures close to the bottom end of the rod. Spin the spindle by hand and take note of the midway value.

Set C_xz = - X / Z where X is the dial indicator difference between bottom and top and Z is the amount you raised the Z axis.

6. Z axis parallelism to spindle in Y direction

Same as step 5, except measure on the positive Y side of the rod.

Set C_yz = - Y / Z where Z is the dial indicator difference and Z is the amount you raised the Z axis.


Specify matrixkins in LinuxCNC INI file as:


In your HAL configuration file, set the parameters C_xx .. C_zz:

setp matrixkins.C_xx 1 # X axis scale
setp matrixkins.C_xy 0
# Skew Y axis towards X axis
setp matrixkins.C_xz 0
# Skew Z axis towards X axis
setp matrixkins.C_yx 0
# Skew X axis towards Y axis
setp matrixkins.C_yy 1
# Y axis scale
setp matrixkins.C_yz 0
# Skew Z axis towards Y axis
setp matrixkins.C_zx 0
# Skew X axis towards Z axis
setp matrixkins.C_zy 0
# Skew Y axis towards Z axis
setp matrixkins.C_zz 1
# Z axis scale

The parameters can be modified during runtime using halcmd. To avoid sudden movements, it is better to turn off machine power before changes.

If recalibration is performed with already existing calibration being in effect, the adjustment values should be added to the old values instead of replacing them.


matrixkins.N.dummy bit out (default: 1)