KINS(9)

okay bestie, sit down, hydrate, because this is KINS(9) from the Kinematics Modules part of the LinuxCNC manual and it is a lot — but in a good way. It's the whole ✨ kins roster ✨: every kinematics component LinuxCNC ships, what each one does, and every knob you can turn on them. Part 1 energy only, more is coming, so don't go anywhere. 🫶

---

✨ NAME ✨

kins — kinematics definitions for LinuxCNC

For additional information, see the Documents 'Advanced Topics':

• Kinematics
• 5-Axis Kinematics
• Switchable Kinematics

---

🌈 SYNOPSIS 🌈

loadrt trivkins (use for most cartesian machines)

loadrt corexykins

loadrt genhexkins

loadrt genserkins

loadrt lineardeltakins (see separate manpage)

loadrt maxkins

loadrt pentakins

loadrt pumakins

loadrt rosekins

loadrt rotarydeltakins

loadrt rotatekins

loadrt scarakins

loadrt tripodkins

loadrt xyzab_tdr_kins

loadrt xyzac-trt-kins

loadrt xyzbc-trt-kins

loadrt 5axiskins

---

💅 DESCRIPTION 💅

So here's the tea, bestie: instead of exporting HAL pins and functions like a normal component, these guys hand LinuxCNC the forward and inverse kinematics definitions. That's their whole job. That's the vibe. 👑

---

🌀 trivkins — generalized trivial kinematics

Joint numbers get assigned sequentially, following the axis letters you list in the coordinates= parameter. Simple as that, no drama.

If you just... don't pass coordinates= at all, then joint numbers get handed out sequentially to every axis letter LinuxCNC knows about: "xyzabcuvw".

Example: loadrt trivkins

Assigns all axis letters to joint numbers in sequence:

x==joint0, y==joint1, z==joint2
a==joint3, b==joint4, c==joint5
u==joint6, v==joint7, w==joint8

Example: loadrt trivkins coordinates=xyz Assigns: x==joint0, y==joint1, z==joint2

Example: loadrt trivkins coordinates=xz Assigns: x==joint0, z==joint1

Example: loadrt trivkins coordinates=xyzy Assigns: x==joint0, y0==joint1, z==joint2, y1==joint3

The default kinematics type is KINEMATICS_IDENTITY. GUIs are allowed to roll out special features for configs that use this default type. Like, the AXIS GUI will just handle joint mode and world mode operations for you, so the operator never even sees the difference between joints and axes — iconic behaviour, honestly. And it's totally feasible because there's an exact correspondence between a joint number and its matching axis letter. 💯

You set the kinematics type with the kinstype= parameter:

kinstype=1     for KINEMATICS_IDENTITY (default if kinstype= omitted)
kinstype=[b|B] for KINEMATICS_BOTH
kinstype=[f|F] for KINEMATICS_FORWARD_ONLY
kinstype=[i|I] for KINEMATICS_INVERSE_ONLY

Example: loadrt trivkins coordinates=xyz kinstype=b

Use kinstype=B (KINEMATICS_BOTH) for configurations that need to move joints independently (joint mode) or as coordinated (teleop) movements in world coordinates. Both. She contains multitudes. ✨

When you're using the axis gui with KINEMATICS_BOTH, the '$' key toggles between joint mode and teleop (world) mode. Periodt.

An axis letter can show up more than once (duplicated!) to assign multiple joints to a single axis coordinate letter.

Example: coordinates=xyyzw kinstype=B Assigns: x==joint0, y==joint1 AND joint2, z==joint3, w==joint4

That example right there is a gantry configuration — the duplicated coordinate letters are saying "hey, two joints (joint1 and joint2) are moving one single axis (y)". Using kinstype=B lets the config toggle between joint and world modes of operation. There are Homing configuration options that let you synchronize the final homing move for selected joints — see the documentation for Homing Configuration. 🎀

NOTES for duplicated coordinates:

When duplicated coordinate letters are in play, specifying KINEMATICS_BOTH (kinstype=B) lets a gui support jogging of each individual joint in joint mode.

⚠️ Caution is required for machines where moving a single joint (in a set defined by a duplicated coordinate letter) can lead to gantry racking or other unwanted outcomes. Not cute. Not slay.

When the kinstype= parameter is omitted, operation defaults to KINEMATICS_IDENTITY (kinstype=1), and a gui may allow jogging based on a selected axis coordinate letter (or by a keyboard key) before homing is completed and the machine is still in joint mode. The joint that gets selected depends on the gui implementation, but typically only one of the multiple joints in the set will jog. So like — specifying KINEMATICS_BOTH is recommended, because it enables support for unambiguous, independent jogging of each individual joint. 👑

Machines that implement homing for all joints (including the provisions for synchronizing the final homing move for multiple joints) may be homed at machine startup and automatically switch to world mode, where per-coordinate jogging is available. Main character homing arc. 🌟

---

🌀 corexykins — CoreXY Kinematics

X = 0.5*(JOINT_0 + JOINT_1)
Y = 0.5*(JOINT_0 - JOINT_1)
Z = JOINT_2

[KINS]JOINTS= must specify 3 or more joints (maximum 9). No negotiating.

If it's enabled by the number of [KINS]JOINTS= you specified, then JOINT_3,4,5,6,7,8 correspond to coordinates A,B,C,U,V,W respectively. 🦋

---

🌀 genhexkins — Hexapod Kinematics

Gives you six degrees of freedom in position and orientation (XYZABC). The location of base and platform joints is defined by HAL parameters. The forward kinematics iteration is controlled by HAL pins. (See switchkins documentation for more info)

• genhexkins.base.N.x
• genhexkins.base.N.y
• genhexkins.base.N.z
• genhexkins.platform.N.x
• genhexkins.platform.N.y
• genhexkins.platform.N.z — Parameters describing the Nth joint's coordinates.
• genhexkins.spindle-offset — Added to all joints Z coordinates to change the machine origin. Facilitates adjusting spindle position.
• genhexkins.base-n.N.x
• genhexkins.base-n.N.y
• genhexkins.base-n.N.z
• genhexkins.platform-n.N.x
• genhexkins.platform-n.N.y
• genhexkins.platform-n.N.z — Parameters describing unit vectors of Nth joint's axis. Used to calculate strut length correction for cardanic joints and non-captive actuators.
• genhexkins.screw-lead — Lead of strut actuator screw, positive for the right-handed thread. Default is 0 (strut length correction disabled).
• genhexkins.correction.N — Current values of strut length correction for non-captive actuators with cardanic joints.
• genhexkins.convergence-criterion — Minimum error value that ends iterations with converged solution.
• genhexkins.limit-iterations — Limit of iterations, if exceeded iterations stop with no convergence.
• genhexkins.max-error — Maximum error value, if exceeded iterations stop with no convergence.
• genhexkins.last-iterations — Number of iterations spent for the last forward kinematics solution.
• genhexkins.max-iterations — Maximum number of iterations spent for a converged solution during current session.
• genhexkins.tool-offset — TCP offset from platform origin along Z to implement RTCP function.

🫶 To avoid joints jump, change tool offset only when the platform is not tilted.

---

🌀 genserkins — generalized serial kinematics

Kinematics that can model a general serial-link manipulator with up to 6 angular joints. (See switchkins documentation for more info)

The kinematics use Denavit-Hartenberg definition for the joint and links. The DH definitions are the ones used by John J Craig in "Introduction to Robotics: Mechanics and Control". The parameters for the manipulator are defined by HAL pins. Note that this uses a convention sometimes known as "Modified DH Parameters" and this must be borne in mind when setting up the system. https://w.wiki/NcY

• genserkins.A-N
• genserkins.ALPHA-N
• genserkins.D-N — Parameters describing the Nth joint's geometry.

---

🌀 maxkins — 5-axis kinematics example

Kinematics for Chris Radek's tabletop 5 axis mill named 'max', with a tilting head (B axis) and a horizintal rotary mounted to the table (C axis). Provides UVW motion in the rotated coordinate system. The source file, maxkins.c, may be a useful starting point for other 5-axis systems. 💖

---

🌀 pentakins — Pentapod Kinematics

Gives five degrees of freedom in position and orientation (XYZAB). The location of base and effector joints is defined by HAL parameters. The forward kinematics iteration is controlled by HAL pins.

• pentakins.base.N.x
• pentakins.base.N.y
• pentakins.base.N.z
• pentakins.effector.N.r
• pentakins.effector.N.z — Parameters describing the Nth effector joint's radius and axial position.
• pentakins.convergence-criterion — Minimum error value that ends iterations with converged solution.
• pentakins.limit-iterations — Limit of iterations, if exceeded iterations stop with no convergence.
• pentakins.max-error — Maximum error value, if exceeded iterations stop with no convergence.
• pentakins.last-iterations — Number of iterations spent for the last forward kinematics solution.
• pentakins.max-iterations — Maximum number of iterations spent for a converged solution during current session.
• pentakins.tool-offset — TCP offset from effector origin along Z to implement RTCP function.

🫶 To avoid joints jump, change tool offset only when the platform is not tilted.

---

🌀 pumakins — kinematics for puma typed robots

Kinematics for a puma-style robot with 6 joints.

• pumakins.A2
• pumakins.A3
• pumakins.D3
• pumakins.D4 — Describe the geometry of the robot.

---

🌀 rosekins — kinematics for a rose engine using

a transverse, longitudinal, and rotary joint (3 joints). 🌸

---

🌀 rotarydeltakins — kinematics for a rotary delta machine

Rotary delta robot (3 Joints). ✨

---

🌀 rotatekins — Rotated Kinematics

The X and Y axes are rotated 45 degrees compared to the joints 0 and 1. That's it, that's the whole vibe. 🎀

---

🌀 scarakins — kinematics for SCARA-type robots

(See switchkins documentation for more info)

• scarakins.D1 — Vertical distance from the ground plane to the center of the inner arm.
• scarakins.D2 — Horizontal distance between joint[0] axis and joint[1] axis, ie. the length of the inner arm.
• scarakins.D3 — Vertical distance from the center of the inner arm to the center of the outer arm. May be positive or negative depending on the structure of the robot.
• scarakins.D4 — Horizontal distance between joint[1] axis and joint[2] axis, ie. the length of the outer arm.
• scarakins.D5 — Vertical distance from the end effector to the tooltip. Positive means the tooltip is lower than the end effector, and is the normal case.
• scarakins.D6 — Horizontal distance from the centerline of the end effector (and the joints 2 and 3 axis) and the tooltip. Zero means the tooltip is on the centerline. Non-zero values should be positive, if negative they introduce a 180 degree offset on the value of joint[3]. 😭

---

bestie we're only partway through the kins lore, so hold that thought — part 2 is coming and it's gonna be just as much. 💜

🦋 tripodkins — Tripod Kinematics 🦋

okay so the whole vibe here: the joints represent the distance of the controlled point from three predefined locations — those locations are the motors, bestie — and that hands you three degrees of freedom in position (XYZ). that's it, that's the kinematic ✨

and the motor spots are configurable through these three:

• tripodkins.Bx
• tripodkins.Cx
• tripodkins.Cy

the location of the three motors is (0,0), (Bx,0), and (Cx,Cy). no cap, that's the entire layout 💅

---

🌸 xyzac-trt-kins — 5 Axis mill (Table Rotary/Tilting) 🌸

it's giving tilting table (A) plus a horizontal rotary mounted to the table (C axis), and it's a 5 joint situation: 0:x, 1:y, 2:z, 3:a, 4:c. it comes with provisions to switch between the xyzac and trivkins kinematic types 🫶

you can alter the joint mapping with the coordinates parameter, in exactly the same way trivkins supports it. (see the switchkins documentation for more info — iykyk 😌)

🌈 xyzbc-trt-kins — 5 Axis mill (Table Rotary/Tilting) 🌈

same energy, different letters: 5 Joints 0:x, 1:y, 2:z, 3:b, 4:c, with provisions to switch between the xyzbc and trivkins kinematic types. joint mapping is alterable with the coordinates parameter, same way trivkins supports it. (switchkins documentation has the tea, go sip it 💖)

👑 5axiskins — 5 Axis bridge mill 👑

XYZBCW — so the W coordinate values (typically used for tool motion, fr fr) get incorporated into XYZ positioning. heads up tho: only 5 joints are needed by the kinematics module, but an additional joint is needed to display W values. (yes, switchkins documentation again, it's iconic)

by default, 5axiskins uses coordinates XYZBCW assigned consecutively to joints 0..5. the module coordinates parameter may be used to:

• assign multiple joints to an axis letter, and/or
• assign joints to additional coordinates A, U, V with a one-to-one correspondence to the assigned joints

Example: XYZBCWYV (8 joints total numbered 0..7) uses two joints for Y (joints 1,6) and adds an additional coordinate V that has a one-to-one relation to joint 7. ate and left no crumbs ⭐

Note: these kinematics may be used with the vismach 5axisgui, providing that the joint-letter assignments agree with the default ordering expected by it (XYZBCW -> joints 0..5). don't freeball the order, bestie, it will not slay 🙈

---

✨ SEE ALSO ✨

• Kinematics section in the LinuxCNC documentation 📖
• The HAL component userkins.comp is a template for making kinematic modules using the halcompile tool. the unmodified template supports an identity xyz configuration that uses 3 joints. see userkins(9) for more info 🧚

---

and that's the whole page, babe — LinuxCNC Documentation, dated 2014-12-22, and this gorgeous thing is KINS(9). go forth and move some axes, main character 💜🎀