Switchable Kinematics (switchkins)

When using an identity kinematics type, the module parameter coordinates can be used to assign letters to joints in arbitrary order from the set of allowed coordinate letters. Examples:

The joint assignments provided for identity kinematics when using the coordinates parameter are identical to those provided for the trivkins module. However, duplication of axis letters to assign multiple joints for a coordinate letter is not generally applicable for serial or parallel kinematics (like genserkins, pumakins, genhexkins, etc.) where there is no simple relationship between joints and coordinates.

Duplication of axis coordinate letters is supported in the kinematics modules xyzac-trt-kins, xyzbc-trt-kins, and 5axiskins (bridgemill). Typical applications for duplicate coordinates are gantry machines where two motors (joints) are used for the transverse axis.

Switchable kinematics initialize with motion.switchkins-type==0 implementing their eponymous kinematics method. If the the motion.switchkins-type pin is not connected — as in legacy configurations — only the default kinematics type is available.

A module providing more than three kinematics types has one kinstype.is-N pin per type.

G12.1 and G13.1 ask motion for a kinstype directly and need no HAL connection at all.

A kinstype can also be selected by writing the pin motion.switchkins-type, which is sourced from an analog output pin like motion.analog-out-03 so that it can be set by M68 commands:

G12.1 P- selects a kinstype and G13.1 cancels back to identity kinematics. Which kinstype that is, the module declares (see Code Notes), not fixed to a number; on a module whose slides do not line up with its frame it is the machine frame type the module declares instead:

These codes ask motion for the kinstype directly and synchronize task and motion themselves, so no HAL connection and no separate sync command are needed. The G-code words and the motion.switchkins-type pin are both acted on when they change, so whichever asked most recently is the one in force. motion.kins-type reports what is currently selected.

The pin is deprecated, see the warning under HAL Connections.

The kinstype in force is readable in G-code as #<_kins_type>, which lets a subroutine restore whatever its caller had selected:

Selection is not cancelled by the end of a program or by an abort, so that the kinstype continues to match the position readout. A program that should leave the machine in identity kinematics ends with G13.1.

A module that declares no identity or machine frame kinstype refuses G13.1 with an error and can still be driven by number with G12.1; see Code Notes for how a module declares its types.

For tool length work there are spellings that name the kinematics by what it is rather than by number: G43.4 applies the tool length offset and switches to the kinstype the module declares its working transform, and the G49 that cancels it switches back to identity. See the G-code documentation for G43.4 and G49, and for G12.1 and G13.1, for the full description.

Writing motion.switchkins-type through an analog output pin needs the HAL connection shown above. Kinstype selection is then managed using G-code sequences like:

These G-code command sequences are typically implemented in G-code subroutines as remapped M-codes or with conventional M-code scripts.

Suggested codes (as used in sim configs) are:

Conventional User M-codes:

Remapped M-codes:

LinuxCNC trajectory planning uses limits for position (min,max), velocity, and acceleration for each applicable coordinate letter specified in the configuration INI file. Example for letter L (in the set XYZABCUVW):

The INI file limits specified apply to the type 0 default kinematics type that is activated at startup. These limits may not be applicable when switching to alternative kinematics. However, since an interpreter-motion synchronization is required when switching kinematics, INI-HAL pins can be used to setup limits for a pending kinematics type.

The relevant INI-HAL pins for a joint number (N) are:

The relevant INI-HAL pins for an axis coordinate (L) are:

A user-provided M-code can alter any or all of the axis coordinate limits prior to changing the motion.switchkins-type pin and synchronizing the interpreter and motionparts of LinuxCNC. As an example, a bash script invoking halcmd can be hardcoded to set any number of HAL pins:

Scripts like this can be invoked as a user M-code and used prior to the kins switching M-code that updates the motion.switchkins-type HAL pin and forces an interp-motion sync. Typically, separate scripts would be used for each kinstype (0,1,2).

When identity kinematics are provided as a means to control individual joints, it may be convenient to set or restore limits as specified in the system INI file. For example, a robot starts with a complex (non-identity) kinematics (type0) after homing. The system is configured so that it can be switched to identity kinematics (type1) in order to manipulate individual joints using the conventional letters from the set XYZABCUVW. The INI file settings ([AXIS_L]) are not applicable when operating with identity (type1) kinematics. To address this use case, the user M-code scripts can be designed as follows:

M129 (Switch to identity type1)

M128 (restore robot default kinematics type 0)

Like INI file limit settings, coordinate system offsets (G92, G10L2, G10L20, G43, etc) are generally applicable only for the type 0 default startup kinematics type. When switching kinematics types, it may be important to either reset all offsets prior to switching or update offsets based on system-specific requirements.

External offsets (set to an axis (L) via axis.L.eoffset-request) are preserved during kinematics switches. When an offset is active on an axis before the switch (visible in axis.L.eoffset), the trajectory planner maintains that same offset after the switch, similar to how it maintains the commanded position from a G-code. This ensures consistent machine behavior regardless of the active kinematics.

If maintaining the offset will be an issue due to axis limit changes or other concerns, be sure to clear and possibly disable the eoffset before making a kinematics switch.

Custom kinematics can be coded and tested on Run-In-Place (RIP) builds. A template file src/emc/kinematics/userkfuncs.c is provided in the distribution. This file can be copied/renamed to a user directory and edited to supply custom kinematics with kinstype==2: the in-tree modules register its USERK_OPS as that kinstype, so the forward and inverse in the copy are what runs.

The user custom kinematics file can be compiled from out-of-tree source locations for rt-preempt implementations or by replacing the in-tree template file (src/emc/kinematics/userkfuncs.c) for rtai systems.

Preempt-rt make example:

A complete kinematics module can be built out-of-tree with halcompile using the same switchkins implementation the in-tree modules use, so it gets the kinematics switching, the kinstype.is-N pins, the coordinates= identity mapping and the G-code and HAL controls without reimplementing any of them.

The implementation is the switchkins_core module. It provides no kinstypes of its own; it exports switchkinsInit() and the rest of the switchkins.h interface, and the identity kinematics and helpers kins_module.h declares. A module of your own includes switchkins.h, supplies switchkinsSetup() and a kinsDescribe() that replays it through switchkinsDescribeWith(), and calls switchkinsRunSetupWith() and switchkinsInit() from EXTRA_SETUP(), which halcompile runs after hal_init() and before hal_ready(). See Code Notes for the calls.

The template is src/hal/components/switchkinscomp.comp. Copy and rename it (both the file and the component name) and replace the example kinstype with the real kinematics. Start from the template, not from an in-tree component such as millturn.comp: those link the switchkins objects into the module through hal/components/Submakefile, which a halcompile build outside the tree does not do.

The HAL file loads switchkins_core ahead of the module:

A module loaded without switchkins_core ahead of it fails to load, and the error names the first switchkins or kinematics function it could not find:

A module written as a plain C file links switchkins_main.o (switchkins_main.c) for its rtapi_app_main(). That main program reads the (optional) module command-line parameters (coordinates, sparm) and passes them to the module-provided function switchkinsSetup():

which sets the configuration settings, names the geometry table and registers the kinstypes with switchkinsRegisterOps(). The pointer arguments are the older route for kinstypes 0,1,2; a module using them leaves the rest alone. switchkinsRunSetup() in switchkins_setup.c is what runs switchkinsSetup() and registers what it returned, for the main program and for kinsDescribe() alike.

A module written as a halcompile component gets rtapi_app_main() from halcompile instead. It supplies the same switchkinsSetup() and a kinsDescribe() that replays it, and from its EXTRA_SETUP() routine, which halcompile runs after hal_init() and before hal_ready(), runs switchkinsSetup() and then switchkinsInit():

switchkinsRunSetupWith() and switchkinsDescribeWith() take the module’s switchkinsSetup() as an argument, so they work from switchkins_core. switchkinsRunSetup() and the kinsDescribe() in switchkins_setup.c call the switchkinsSetup() they were linked with, and only a module built in tree links them.

Where the switchkins code comes from depends on where the component is built. Out of tree, the switchkins_core module provides it, loaded ahead of the component (see Building a switchkins module of your own). In tree, the component links the objects into itself instead, named in hal/components/Submakefile:

A switchkinsSetup() with the kinematics itself left out: the table, the ops table of the machine’s own kinstype, and the shared identity and userk ops for the other two:

For the surrounding shape, the in-tree switchkinsSetup() routines are in src/emc/kinematics: 5axiskins.c, xyzac-trt-kins.c, genserkins.c, scarakins.c and the others listed at the top of this document. None of them registers a fourth kinstype yet, so a call for one has no in-tree example to copy.