[grandixximo]

Draft. Where the multiaxis kinematics work is going, open early so it can be argued with. As pieces are agreed I split them into small PRs, rebase this, and carry on, so nothing stalls behind it.

Status (2026-11-02)

Merged so far: #4372 (switchkins, more than three types), #4414 (G12.1/G13.1), #4455 (a module reports where the tool points), #4546 (six kinematics fixes), #4548 (G43.4/G49 over the switch), #4550 (the Jacobian entry point, every module), #4551 (the tilted work plane maths split per machine), #4581 ([AXIS_<letter>] TYPE in the interpreter, canon and motion), #4608 (the nutating sims' third kinematics type), #4600 (the tilted work plane, G68.2/G68.4/G69, the preview drawing it, G52 in a plane, [RS274NGC] RETAIN_WORK_PLANE, and a work offset change that takes the plane along), #4595 (switchkins as one implementation for .c, .comp and out of tree), #4594 (the GUIs and the preview by TYPE), #4586 (pumakins wrist), #4673 (the tool frame helpers checked in realtime), #4679 (the preview's first plane cut), #4702 (every module as a parameter block and pure functions, callable outside realtime), #4685 (a non-finite inverse no longer hangs the servo thread), #4676 (genserkins on posemath), #4724 (the genhexkins forward as a true Newton iteration), #4708 (pumakins arm joints).

Open now: #4730, item 1 below. This branch is master plus what follows.

Next, one PR at a time:

1. The frames of maxkins, xyzab_tdr_kins and genserkins, the point-to-point moves and the orientation codes, G53.1 to G53.7 and G68.3, then the tool offset under a tilt, G43.5, G28.5/G30.5 and the machine frame (24 commits). Open as interp, motion: the point-to-point moves and the tool orientation codes, G53.1 to G53.7 and G68.3 #4730.
2. The limits from the joints, item 6, with the maxkins box read on its carriage (7 commits).
3. The orientation axes by TYPE, several primary types and twinspindlekins, the genserkins Jacobian from its DH frames, and the planner fixes for joint-space segments (10 commits).
4. The joint travel along each move, the run-time half of item 7 (2 commits).
5. The tool frame in status and the tool marker along it, then world jogs along the plane or the tool (5 commits).
6. 3+2 under the machine frame kinematics, and the preview drawing on the part there (3 commits).
7. The frames of genhexkins and pentakins, read from the pose, with the tilted work plane on a parallel machine (5 commits).
8. G53.6 under the machine frame kinematics holding the tool tip all along its move (3 commits).
9. G92, G10 L20, G43 and M6 held back while G43.4 is on, the rest of item 8 (1 commit).

Then the load-time half of item 7, and item 9.

Problems found in the existing code on the way, and where they were fixed:

• Round-tripping every module forward and back found six bugs, among them a kinematics switch whose forward could not solve, which left the hexapod driving twenty units per strut with nothing commanded: kinematics: six fixes found by round-tripping every module #4546.
• G53 and the G28/G30 return ignored the rotary tool offset on axes that are not wrapped, since 2009: rs274ngc: back the rotary tool offset out of machine coordinates #4416.
• Task lost two cycles after a kinematics selection, so the kinematics in force between two selections on consecutive lines could be skipped: task: a kinematics selection is seen on the next line, and the test reads it there #4563, with the test fixed in tests: kins-switch holds the joints from the program's own switch to identity #4564.
• B and C used the linear minimum displacement where A used the angular one, so on an inch machine a small B or C move was dropped: Honor [AXIS_<letter>] TYPE in the interpreter, canon and motion #4581.
• pumakins let joints 4 and 6 jump a full turn when the wrist crossed a half turn: pumakins: keep joints 4 and 6 within a half turn of the previous value #4586. Joints 1, 2 and 3 do the same, and can be a turn off anywhere: on the puma sim, the waist at 169 comes back as -191 when world mode is turned on: pumakins: keep every joint within a half turn of the previous value #4708.
• A kinematics module whose inverse answered a non-finite value in coordinated mode hung the servo thread: motion: a non-finite inverse in coordinated mode no longer hangs the servo thread #4685.
• The genhexkins forward moved its angles by an angular velocity step rather than a Newton step: 12.6 iterations from a one-cycle seed and one solve in ten failing at a large tilt, against 3 and none: genhexkins: take the forward's Newton step in roll, pitch and yaw rates #4724.
• G92.1, G92.2 and G92.3 dropped their own errors, so one refused under cutter radius compensation or a tilted work plane did nothing without a word: fixed here, with item 8.
• In this branch: genserkins' inverse took the whole Newton step and could converge on a pose whole turns away, which the joint limits then refuse; motion checked a move's joint limits from the joints the machine stands in rather than where the queue leaves them, so a short program was checked from its starting pose; and the preview never read its point back from the joints at a kinematics switch, so after G12.1 or G13.1 with a rotary tilted it drew the rest of the program 40 to 70 mm away from where the machine goes.

Plan, in order:

1. Switchkins: one implementation, used by .comp, .c, in tree and out of tree. The registration half merged as switchkins: allow more than three kinematics types #4372; the rest is in this branch.

2. Small fixes that stand on their own: 5axiskins gets a .tool-offset pin like every other module, maxkins gets one or a doc note saying it has none, and G53 stops ignoring the rotary tool offset on non-wrapped axes.

3. The kinematics interface learns to answer two more questions: where the tool points, and how joint motion maps to world motion. One entry point each, both weak, both defaulting to today's behaviour, and a tool frame convention written down so every module answers the same way rather than each author choosing one.

4. Those answers, and forward and inverse alongside them, become pure functions of what the caller passes in: joint values, a parameter block carrying the tool and the kinematics type, and no state kept inside the module. Today the maths reads its geometry from HAL pins and keeps scratch in haldata, so the only way to call it from anywhere else is to write a second copy of it. One implementation, parameters supplied at the call site.

5. Two stages the offset chain was missing. Both came out of the discussion below, both wanted 3 and 4 first, and both are in this branch now.

   A frame composed on top of the active coordinate system, with its own cancel, so the blocks in between are programmed in the tilted plane while G54 itself is untouched. Fanuc spells this G68.2, and that is the spelling here: G68.2 in its four forms, G68.3 reading the plane off the tool, G68.4 composing onto the active plane, G69 cancelling. In tree it is a stage in rotate_and_offset_pos() plus modal group 9. Nothing is rewritten, so nothing needs restoring: an abort cancels it unless [RS274NGC] RETAIN_WORK_PLANE keeps it, as Fanuc's D3R does, and on_abort_with_twp_reset.ngc is gone with the rest of the remap. As in the Fanuc manual, G52 in a plane shifts it along its own axes, and with Fanuc's 3TW behaviour a work offset change takes the plane along.

   A move whose target is defined but whose path is left to the joints: run the inverse once at the endpoint, then interpolate the joints to reach it, the slowest setting the pace. That is how the commercial controls cross a singularity or flip a head without changing coordinate system. In tree it is one segment type in the planner, JOINT_TRAVERSE and JOINT_FEED in canon, and three non-modal codes on G0 and G1, like G53, each stripping one more layer of interpretation from the destination: G53.4 to a program point, offsets and plane applied, the form a post writes; G53.5 to the machine frame, the carriage or a robot's flange in machine coordinates with the tool left out, in program units and with no offset, the form for parking and tool change; G53.7 to joint values, J2=-5 sending joint 2 to -5 in the joint's own units with nothing converted, the form that works on every machine. Which kinematics type is the machine frame the module declares with a flag, KINSTYPE_MACHINE, next to KINSTYPE_IDENTITY and KINSTYPE_PRIMARY: the carriage on a mill, the flange in the base frame on a robot (ABB tool0, KUKA $NULLFRAME), where pumakins and genserkins flag their arm type. G13.1 and G49 cancel to it, so a robot stays on its arm kinematics and only G12.1 P1 selects raw joints. A module that declares nothing has its identity type stand in, and there a letter carries a unit class and a joint does not, so G53.5 is refused where the letters name joints of the other kind, which [JOINT_n] TYPE declares. With G1 the move takes the time the straight move would at F. G53.1, G53.3 and G53.6 orient the tool to the plane, and G53.2 solves the same orientation without moving, publishing the pose on the read-only parameters #<_orient_x> to #<_orient_z>, #<_orient_rot1> to #<_orient_rot3> and #<_orient_valid>, mirrored on #5071 to #5080, so a program can read the answer and use it in a move of its own. P picks the solution nearest first and Q says whether the joints that carry the work take part; the module's tool frame inverse answers, so no config carries the formula, and the two trsrn configs run their demos with no remap left.

   Between them these are the reason not to add a set of offsets per kinematics type. Controls do let you add coordinate systems, Fanuc G54.1 P1 to P48, Siemens G505 to G599, and none of them ties a set to the active kinematics or transformation: selection is explicit in the program, or it belongs to a channel. More coordinate systems is a fair request on its own; binding them to the kinstype is the workaround for these two absences.

6. Limits taken from the joints instead of from static per-axis INI values. Joint limits are the physical fact. The region they imply in axis space depends on the tool and on where the rotaries are, and is not a box, which is why a box in the INI cannot describe it and config authors have to pick a conservative one and lose travel. Built now, in three parts, each with a test that was red before it.

   Travel is the [JOINT_n] limits, every move, every kinematics type. The [AXIS_L] box is the machine frame envelope: the carriage, or the flange, in machine coordinates, the frame that does not move when the head tilts or a tool is loaded, which is how Siemens and Fanuc read axis limits, machine-axis space after the transformation. Every move is checked against the box where its joints put the machine frame, G0 and G53.5 alike, so a tool centre point move whose tip lies past the box with the carriage inside it is accepted and a G53.5 to a carriage position past the box is refused. No box on tip coordinates: the tip is not the carriage, and a tip fence would be a feature of its own. One box, one meaning, so nothing needs resetting at a switch, which retires the setp ini.L.min_limit the docs prescribed and the puma's M129 workaround. A module that declares no machine frame keeps the box on the world in force, as today. The one behaviour change for an existing switchkins config that declares only its identity: under TCP the box moves from the tip to the carriage.

   Velocity and acceleration come off the Jacobian. Canon samples every segment through the module's Jacobian ahead of motion, on the kinematics type and the tool offset the program is under, and lowers its velocity and acceleration to what the slowest joint can give within its own limits: the rate of each joint along the tangent, the share the changing rate takes at that speed (what a carriage on a circle feels as centripetal), and the bulge between samples so a peak between them is covered. Lines and arcs, traverse and feed, probe and rigid tap. A turn of a tilted head under the tool centre point, which swings the carriage through a circle the head's own limit never mentions, runs at the carriage's pace instead of tripping the carriage's following error; a full circle of the tip with C turning a revolution under it rides both. World jogs get the same in motion, every servo cycle, from the Jacobian at the joints the machine stands in, the planners capped so no joint is asked for more than its limits and the jog keeping its direction. [AXIS_L] MAX_VELOCITY and MAX_ACCELERATION keep meaning the world of the type in force; the joint cap sits on top. A module that runs only in realtime, one without the parameter block form, caps nothing, as before. A pole, where a joint would have to move at any speed for the path to advance, gives an operator message and the move crawls rather than being dropped, since a dropped segment sends the next one along another path; refusing it ahead of time is item 7.

   The same query finishes a repair the tool orientation codes already needed. Solutions are now unwrapped onto the nearest turn of the current pose before ranking, so a C at 180 asked for a pose at C -90 goes to C 270, 90 degrees away, instead of turning 270 degrees the long way. The ranking also keeps each rotary inside its [JOINT_n] travel, and inside the [AXIS_n] travel of the axis it turns unless that axis wraps: a pose goes onto the nearest turn that lies inside the limits, the long way round where the short way runs out, and a pose no turn brings inside is dropped before ranking. A program that winds a rotary, an incremental G68.4 plane in a loop with G53.6, is refused at plan time with that reason, where before motion refused it partway through.

7. The joint limit check moves earlier and samples inside segments. It exists already, in inRange(), but only at move endpoints and only once the block has reached motion, so a program that will overtravel says so partway into the cut rather than before it starts. With 4 in place the same check runs at load time, against the tool and the kinematics type each block will actually use. A verify button in a GUI is then a presentation of that, not a subsystem of its own.

   The run-time half is built. Canon follows every joint along each move on the samples the segment cap of 6 already reads: between two samples it looks for a joint peaking past its travel, from the joint positions and rates at both ends, and reads the inverse at the peak to confirm it. A move that would take a joint past [JOINT_n] MIN_LIMIT or MAX_LIMIT anywhere along it, or end there, is refused before it reaches motion, with the line, the joint, where it would go and how far along the move; the move and everything after it are dropped and the program stops at that line. A tilted head turning under the tool centre point, whose carriage would pass its travel halfway round with both ends inside, is refused that way instead of being stopped by motion partway through the cut. Only a point the inverse itself puts past a limit refuses a move: a sample the module cannot answer, or a change of solution branch between samples, ends the check for that move, and a joint that starts the move past a limit is not refused on that side. Lines that run from line steps over are not refused.

   Two things this needs pinned before it is written. The interpreter has no seam for the query: all 66 GET_EXTERNAL_* accessors take at most an index, an axis, a spindle, a pocket, and never geometry, so one taking a segment is a new shape for that interface. And a load-time answer can go stale, since the interpreter runs ahead and motion.switchkins-type is a HAL_IN pin, so until 9 lands the type a block is checked against is not necessarily the type it runs under.

   Where a module cannot answer, cheaply or at all, the check skips rather than refuses. Refusing a reachable program leaves the user no recourse; missing an unreachable one is still caught by inRange() at runtime. That asymmetry decides every ambiguous case in 6 and 7.

   Checking a program that switches type raises a question the tree currently leaves implicit: whether a type's coordinates are geometric. Most are, and for those a scan is one stream of world points with only the inverse changing at the switch. identity is not, since world becomes the joints, so a datum in millimetres lands on a rotary joint in degrees; nothing notices, which is why switchkins.adoc asks the operator to clear the offsets before switching.

   The joint-space syntax that question wanted is G53.7 above: joint values by joint number, no offsets, the joint limits directly. Whether a type should also declare its space for the scan stays open.

8. Per-mode restrictions. G28, G30, G53, G92, G52 and M6 do not mean the same thing in every kinematics type, and today each one quietly does whatever the module happens to leave it doing. Refusing outright beats guessing, and with 4 in place the control knows enough to decide rather than to be told. The first of them is in: G53, G28 and G30 keep meaning the world of the kinematics in force, which on a table-side kinematics turns with the table, and G53.5, G28.5 and G30.5 are the machine frame forms; a configuration that wants the machine codes to mean that frame sets MACHINE_MOVES_IN_MACHINE_FRAME, and off the machine frame type G53, G28 and G30 then run as G53.5, G28.5 and G30.5. The rest is in too: while G43.4 or G43.5 is on, the current point is the tool tip with the length along the tilted tool, so G92, G92.1, G92.2, G92.3, G10 L20 and M6 wait for the G49, and a new length is G43.4 H rather than a plain G43; G52, G54 to G59.3 and G10 L2 read no position and stay, as Siemens and Heidenhain allow their frames under TCP, and G43.1 and G43.2 change the offset in effect and keep the switch.

9. Retire motion.switchkins-type, once the grace period has run. Which release that is has still to be decided.

10. The axes a machine orients with. The interpreter and canon took X Y Z U V W as lengths and A B C as angles by letter, and [AXIS_<letter>] TYPE was read by the AXIS GUI alone, so a V configured ANGULAR on a mm machine moved 25.4 times too far under G20; and the orientation codes wrote their answer into A B C whatever axes turn the tool. Now TYPE is honored in the interpreter and canon, [TRAJ] FEED_AXES names the axes F is measured along, and each kinematics type names the axes it orients the tool with, so a head that tilts on V is driven on V. Built. The TYPE half is merged, Honor [AXIS_<letter>] TYPE in the interpreter, canon and motion #4581.

G12.1 and G13.1 are #4414, split out of this branch and standing on their own.

On tool length specifically: the offset is a nine-axis pose from the interpreter, canon adds it into the coordinate, and each rotary kinematics takes the Z component back through a HAL pin and re-applies it along the real tool direction. That round trip is exact when the config wires the pin, and silently wrong otherwise: a missing net costs the full tool length, and an X or Y offset is applied in the rotating work frame while the tool is bolted to the machine. The mechanism works; it has no owner.

Why 4 is worth the trouble: every other way of answering "will this program overtravel" builds a second model of the machine, in the verification package or in the post, and the two descriptions drift apart. If the kinematics module can be called with parameters the caller chooses, LinuxCNC can check a program against the same code that will run it, with no second model to keep in sync. That is not available to anyone whose kinematics is locked inside the control.

In this branch now

Items 5, 6, 8 and 10, the last of 3, and the run-time half of 7. Items 1, 4 (#4702) and most of 3 are merged, as is the TYPE half of 10 (#4581); the orientation axes build on 4 and 5 and sit near the top:

• Item 3, the rest: 5axiskins reports its frames since kinematics: modules as functions of a parameter block, callable outside realtime #4702. maxkins, xyzab_tdr_kins and genserkins report theirs here, the maxkins tilt following its conventional-directions pin. genhexkins and pentakins report theirs from the pose, below. Of the in-tree modules that tilt a tool or a part, scorbot-kins still reports none.
• Item 5: the frame, the point-to-point moves, the orientation codes and G68.3, as above, with the interpreter evaluating the module ahead of motion. The inverse ahead of motion runs to a fixed point, because a module may read the joints it is handed and one pass from a stale seed answers for the wrong rotary angles. In motion a point-to-point segment keeps the last forward solution and clears a status flag when the forward fails inside it rather than parking the reported position at zero, and an external offset waits while a point-to-point segment is queued, since its joints were solved without it. Three repairs the work turned up: G68.3 no longer leaks its axis words into a stray traverse, the python preview applies SET_G68_FRAME in program units like every other length canon call, and orientation answers from the module are unwrapped onto the nearest turn of the current pose before nearest-first ranking. The bridgemill sim runs its sphere demo five ways, one per method: G53.2 with a fused orient-and-travel move, G53.6 orient-then-move, real quill drilling through G53.5 and G53.7, a G12.1 kinematics switch, and the historical W-as-tool-length program kept with the quill drawing locked, which reveals that the old trick only ever worked because the quill was not drawn.
• After item 5: a tool offset change under a tilt keeps the joints where they are and reads the programmed point back from them, so G43 with the head tilted moves the point, not the machine, and the interpreter predicts the same through the loader. The X and Y of a tool offset turn with the tool frame the module reports, where every TCP module used to leave them on the work axes. G43.5 gives the tool axis as a vector, I J K on G0 and G1. The machine frame is a declared kinematics type, G53.5, G28.5 and G30.5 move in it, G13.1 and G49 cancel to it, and the robots declare their arm type as such, so on a puma G53.5 Z50 lifts the flange along base Z holding the rest.
• Item 6: the [AXIS_L] box read on the machine frame for every move, on maxkins its carriage through the joint map, the segment cap in canon, the jog cap in motion, as above. kinslimits prints the cap canon reads for a move next to the Jacobian.
• Item 7, run-time half: canon refuses a move whose joints leave their travel along it, as above, and task fails the line, in a program and in MDI.
• Item 10: every G20/G21 conversion of a position, an offset, a stored position (#5161, #5181, #5211, #5221 onward) or a tool offset goes by TYPE, in the interpreter and in canon, and WRAPPED_ROTARY and LOCKING_INDEXER_JOINT apply to any angular axis. The length F applies to is the feed axes that move, else the other linear axes, else the angular ones in degrees, which with the defaults is today's XYZ, else UVW, else ABC. Motion still measures a line by letter, so canon scales the rates it sends and the move takes the time canon planned. With every TYPE and FEED_AXES at its default canon's output is unchanged: all 632 programs under tests/ and nc_files/, through rs274 with and without a sim INI, give the same canon calls byte for byte. On the way, B and C get the angular minimum displacement A had; they used the linear one. A kinematics type names its orientation axes in kins_ops.orient, or they come from the joint map; G43.5, G53.3 and G53.6 drive those axes, and a module whose type orients with an axis TYPE makes LINEAR is refused at load. A module may flag several types primary, one per head: G43.4 and G43.5 stay on the type in force when it is primary and otherwise take the lowest-numbered primary. twinspindlekins shows it all on one machine: a B tilting head between a main spindle on C and a sub spindle on W, an ANGULAR W, each spindle a primary type in the frame of its own part, and its sim config drills the same ring of tilted holes into both parts through one subroutine that names no rotary.
• On top: motion publishes the tool frame in the work frame, the preview points the tool marker along it, and world jogs of X, Y and Z go along the machine, the active plane or the tool, one frame axis at a time, each world axis within its own limits. Under an identity type, G13.1 on a five axis machine, the tool frame is the primary type's at the same joints, so the marker still leans with the tool and a tool jog still goes along the tilted tool, as Fanuc, Heidenhain and Siemens jog in the tool direction whatever the transformation in force.
• 3+2 under the machine frame kinematics, what G13.1 selects, Fanuc's second feature coordinate system: requested by Sigma1912 for a mill-turn, the rotaries set once and the slides alone moving. The interpreter takes a fixed map from the primary kinematics to the machine frame with the rotaries held and applies it after the whole offset chain, so a plane is cut on the part and G53.1 uses a table rotary under G13.1 too. A rotary word keeps the map, as Fanuc, Heidenhain and Siemens keep their plane; G43 and G49 in the plane take it again with the new length, and a kinematics switch in a plane takes it again or drops it. Status keeps the two apart, as the standard controls report them: g68_offset and g68_rotation stay the plane as defined under every kinematics type, and the map goes in g68_kins_offset and g68_kins_rotation, as Siemens keeps CYCLE800's workpiece frame apart from its table and tool frames. Under G13.1 the preview, the backplot and the tool marker are drawn on the part, as the Siemens and Heidenhain simulations hold the workpiece fixed: motion reports the primary type's forward of the commanded joints as part_position, the backplot draws it, and the preview maps each point it draws the same way outside realtime, so a switch between G13.1 and the TCP kinematics moves nothing on the screen.
• A parallel machine, genhexkins or pentakins: its forward iterates, so its frames come from the pose the forward or inverse last solved, the platform's A B C, rather than from the joints, as PI, Siemens and PMAC read the orientation of a hexapod. The tool frame in status, the tool jog, G68.3 and the orientation codes then work on it: G53.6, G53.3 and G53.2 turn the pose's angles, the hexapod taking the shortest rotation from where it stands and no turn about the tool, and G53.1, which turns rotary joints alone, is refused, as Heidenhain gives a machine without rotary axes only STAY. The X and Y of a tool offset turn with the platform. The [AXIS_L] box is the platform's pose with the tool left out, as a robot's is its flange and as PI puts its soft limits on the platform.
• G53.6 under G13.1 keeps the tool tip on its point all along the move, not only at its ends. It is the primary type's line, the tip held and the rotaries turning, which motion follows every servo cycle with that type's inverse while G13.1 stays in force, so an abort or a feed hold part way leaves the tip on its point and no kinematics to switch back, as Fanuc gives G53.6 in G49 and Heidenhain's PLANE ... MOVE compensates without M128. Canon caps it and checks the joints' travel along it on that type, and the preview draws it as under the TCP kinematics. Reported by Sigma1912.
• Item 8, the rest: while the switch G43.4 or G43.5 made is in effect, G92, G92.1, G92.2, G92.3, G10 L20 and M6 are refused with a message to cancel it with G49 first, and a plain G43 with one to change the length with G43.4 H. The current point is then the tool tip with the length along the tilted tool: an offset taken from it outlives the G49, where the same numbers name another point, a tool change moves it, and a plain G43 ended the switch with the machine left on the TCP kinematics. Fanuc refuses G92 and G43 in tool centre point control (PS5421), Siemens refuses PRESETON on axes under a transformation (17600), and Heidenhain resets M128 before a TOOL CALL. G52, G54 to G59.3 and G10 L2 stay, as Siemens and Heidenhain allow their frames and datum shifts under TCP, and G43.1 and G43.2 change the values of the offset in effect and keep the switch. The rule follows the switch, not the kinematics type: after G12.1 or G13.1, on a hexapod or robot running G43 on its primary type, and on a machine without switchable kinematics, nothing changes.

User visible

Fourteen G-codes, all of them non-modal except the plane itself, which has its own cancel. G68.2, G68.4 and G69 are on master since #4600:

code	what it does
G68.2	define a tilted work plane on top of the active coordinate system, by Euler angles, by angles about fixed axes, by three points or by two vectors
G68.3	define one from where the tool points now
G68.4	compose one onto the plane already active
G69	cancel the plane
G53.1	turn the rotaries until the tool is normal to the plane, the linear joints staying where they are
G53.2	the same, solved without moving; the pose is published on parameters for the program to use
G53.3	the same, and take the tool to an X Y Z given in the plane
G53.6	the same, holding the tool centre point where it is
G53.4	point-to-point to a destination in program coordinates, offsets and plane applied
G53.5	point-to-point to the machine frame, the carriage or the flange in machine coordinates with the tool left out, in program units and with no offset
G53.7	point-to-point to joint values, J2=-5 naming joint 2 in its own units
G28.5, G30.5	the machine frame forms of G28 and G30, through the same stored positions
G43.5	the tool axis as a vector, I J K on G0 and G1, the rotaries solved by the module

P on the orientation codes picks among the poses that reach the plane, nearest first, and Q1 frees the joints that carry the work to take part. The point-to-point codes are modifiers of G0 and G1, and with G1 the move takes the time the straight move would at the programmed feed. J<n>=<value> is a new word form, read only where G53.7 uses it.

Alongside them:

• #<_orient_x> to #<_orient_z>, #<_orient_rot1> to #<_orient_rot3> and #<_orient_valid> hold the pose G53.2 last solved: X Y Z in the plane, then the rotary angles in the order the kinematics orients with, first and second the way Fanuc and Siemens number them, whatever their letters, 0 for a third the machine does not have. Mirrored on #5071 to #5076 and #5080; read-only, and reading one before the first G53.2 is an error.
• #<_kins_orient_1> to #<_kins_orient_3> name the axes the kinematics type in force orients with, 0 for X to 8 for W and -1 for none, and #<_kins_orient_1_head> to #<_kins_orient_3_head> say whether each turns the head or the table. A five axis machine leaves the third at -1; a robot reads A B C.
• The two trsrn_twp configs run on the native codes: no remap, no python, no twp-status pin. Their python maths is the oracle in tests/kins-twp.
• [RS274NGC] MACHINE_MOVES_IN_MACHINE_FRAME, off by default: G53, G28 and G30 run as G53.5, G28.5 and G30.5 whenever the kinematics in force is not the machine frame type, and G28.1 and G30.1 store the machine frame position, so the slides land where the words say whatever the tool and the head are doing. A GUI's preview reads a program on the type the machine is on, read from the status buffer, and the G53 the GUI restates the machine's position with stays in the world of that type.
• stat.kins_type and stat.kins_type_flags in python, with linuxcnc.KINSTYPE_IDENTITY, KINSTYPE_PRIMARY and KINSTYPE_MACHINE: the type motion runs and what the module declares each type to be.
• A tool offset's X and Y follow the tool on 5axiskins, maxkins, the trt and trsrn modules, xyzab_tdr_kins and twinspindlekins; genhexkins and pentakins turn them with the platform, scorbot-kins reports no tool frame and keeps them on the work axes, and a robot arm, flagged its machine frame, has no tool offset to turn.
• [AXIS_L] MIN_LIMIT and MAX_LIMIT are the machine frame box on a module that declares its machine frame, on maxkins its carriage and on a hexapod or pentapod its platform with the tool left out; the velocity and acceleration limits keep their meaning and the joint cap sits on top. A switch no longer needs the limits reset to keep the joints safe; it may still want the velocity limits reset where a letter changes unit at the switch, which the puma's M128 and M129 do and nothing else.
• A module declares which of its types is the identity, which are primary (one per head where a machine has several) and which is the machine frame, .identity, .primary and .machine in the ops table or switchkinsDeclare() the old way; motion.kins-type and the switchkins-type N declared: line at load say what it declared.
• stat.tool_frame, the tool's axes seen from the work, the primary type's under an identity type, None where no type reports frames; the preview draws the tool marker along it, with [DISPLAY] GEOMETRY as the fallback.
• stat.part_position, where the tool stands against the part: position itself except under G13.1 and the like, where position is in machine coordinates. The backplot draws it.
• World jogs along the active plane or the tool: jog_frame() and stat.jog_frame in python, motion.jog-frame, the halui.jog-frame.* pins, and in AXIS the View menu, % to cycle and a status label. Both requested by Sigma1912.
• G53.1 is refused on a parallel machine, which has no rotary joint to turn; G53.6, G53.3 and G53.2 work there as on any five axis machine.
• A tilted work plane under G13.1 is cut on the part (3+2), and stat.g68_kins_offset and stat.g68_kins_rotation in python give the map it is cut through, the identity under any other type.
• While G43.4 or G43.5 is on, G92, G92.1, G92.2, G92.3, G10 L20, M6 and a plain G43 are refused; G49 first, or G43.4 H for a new length.
• No existing pin or G-code changes name. Configs using the .tool-offset net keep working; the tool comes from motion now and the net is only read until motion has spoken.

Left for later

• The load-time half of item 7, the same check when a program is loaded, and with it the refusal of a pole that today only crawls with a message.
• A rotary axis in the feed group, with a reference radius per rotary that turns its degrees into length (Siemens FGREF, Fanuc parameters 1408/1465). It is for a 4th axis without TCP, a wrap on a cylinder, where F today counts the linear axes only; with TCP the path is already measured on the part. Small and independent of this branch; I'll build it if someone in the community wants it and can test it on their machine.

Testing

tests/kins-params, tests/kins-jacobian, tests/kins-frames, tests/tool-frame, tests/kins-tool-offset, tests/kins-twp, tests/twp-native, tests/ptp-iterative, tests/ptp-machine-frame, tests/workplane-retain and tests/kins-limits cover the new code; tests/kins-limits holds the three tests that were red before item 6, the swing of a 400 mm pivot under G0 C180 and under an arc, the box read on the carriage instead of the tip, and the same swing as a world jog, each joint following its command through limit3 at 20 percent over its own limits the way a drive does, so a command over the limits falls behind and trips the following error; the last runs the xyzacb nutating head through the plane, the orientation codes and the point-to-point moves against the python maths, and checks that every point-to-point move keeps its joints on one line in joint space, all together, so a wrong interpolation fails three of its checks. tests/ptp-robot puts pumakins through the same codes, where G53.5 moves the flange along a base axis and G53.7 names the joints. tests/axis-type and tests/interp/axis-type check TYPE, FEED_AXES and a wrapped V through rs274 and through motion, the second failing on master at its first check; tests/kins-switch reads the orientation axes of each type, tests/kins-orient-linear checks the refusal of a LINEAR orientation axis, and tests/twinspindle solves and reaches the same tilted hole on either spindle of twinspindlekins and runs its demo. tests/kins-limits/travel swings a tilted head under the tool centre point until the carriage would leave its travel halfway round, and checks the refusal in MDI and in a program and that run from line steps over it; tests/twp-table runs G53.1 on a table-table machine once more with A limited to one side on the axis and not on the joint. tests/twp-static runs the same programs under the tool centre point kinematics and under G13.1 on a table machine and a head machine and checks the joints agree, then the rotary word, a switch in the plane, the status split, the plane jog, an abort with RETAIN_WORK_PLANE and the preview, which under G13.1 must draw the plane, a rotary turn and the live plot where the TCP kinematics draws them and follow a switch either way to where the machine goes. tests/twp-static then holds the tool tip through G53.6 under G13.1 on both machines, through an abort and a feed hold part way, refuses one whose carriage would pass its travel half way round, and checks the preview draws it as the TCP kinematics does. tests/kins-switch refuses G92, G92.1, G92.2, G92.3, G10 L20, M6 and G43 under G43.4 and G43.5, passes G43.4 H, G43.1, G43.2, G10 L2, G52 and G55 there, and the refused codes again after G49 and under a type G12.1 selected. tests/twp-parallel runs G53.6, G53.3, G68.3, the refused G53.1 and the [AXIS_L] box on a hexapod and a pentapod, and tests/kins-frames checks their frames against the pose. tests/twp-jog-frame jogs along the plane and the tool on a head machine, the tool jog under the identity type too, every servo cycle within each axis's limits, then a machine not homed and the machine frame on a table machine; tests/glcanon checks the tool marker against the frame in status. The four comp sim configs give identical positions to master through the same MDI sequence, in every kinematics type.

Testers wanted

Everything above runs in the sims, and the sims follow their commands exactly. What I cannot see from here is a real five axis machine or a real robot, where the joint cap either keeps a drive inside its following error window or it does not. If you run a 5axiskins, xyzac-trt, xyzbc-trt, maxkins or trsrn config, or a pumakins or genserkins arm, a session on this branch would tell me a lot:

• A G0 or G1 that turns a rotary under TCP with the head tilted, at full rapid, and whether it slows to the carriage's pace or trips a following error. Same with a world jog of the rotary in teleop mode.
• Whether the [AXIS_L] box now reads right on your machine: a tip past the box with the carriage inside accepted, G53.5 past the box refused, and any move you expected to be accepted that is refused, with the line and the message.
• On a robot, G53.5 along a base axis, and whether G13.1 and G49 leave you where you expect.
• A config on an out-of-tree kinematics module: whether it still loads and whether motion.kins-type says what it declared.
• Anything slower than it was: a long program with short segments on an iterative kinematics is where the per-segment sampling would show.

EMCCANON_KINS_DEBUG=1 in the environment makes canon print the cap it read for every segment on stderr, and kinslimits prints it for one move from the command line.

[BsAtHome]

What is the migration path for people having their own out-of-tree kinematics switch component?

[grandixximo]

What is the migration path for people having their own out-of-tree kinematics switch component?

Their module needs no source change. G12.1 and G13.1 reach a module through the same kinematicsSwitch() the pin does, so a component that is switchable today is driven by G12.1 today without knowing G12.1 exists.

I checked rather than assumed. I built an out-of-tree component that deliberately does not use switchkins.h or switchkins.c: its own switchkins type, its own kinematicsSwitch(), its own kinstype pins, the shape somebody would have written before there was a supported way to reach the in-tree code. Against this branch:

G12.1 P1   kins-type=1, its type 1 kinematics active
G13.1      kins-type=0
G12.1 P7   its own BAD VALUE, motion stays on 0

with no source change, and no deprecation warning, since the pin is never written.

The config keeps working as well. The pin is deprecated, not gone, so an existing M68/M66 config runs as before with one warning per session. Moving off it is a config edit, not code:

M68 E3 Q1 / M66 E0 L0    ->   G12.1 P1
M68 E3 Q0 / M66 E0 L0    ->   G13.1

and the [HAL] net from the analog output goes with them. The sim configs in this PR are worked examples, halui buttons and remapped M-codes included.

One group does have something to do, and it is not the one you asked about: anybody keeping a copy of switchkins.c in their own tree. Their current build is unaffected, but rtapi_app_main() has moved out to switchkins_main.c, so next time they re-sync that copy they either take that file too or call switchkinsInit() themselves. They also no longer need the copy, since switchkins.h is installed now and switchkinscomp.comp shows both routes.

Announcing it is worth raising at a weekly meeting. Nothing is removed in this PR.

[Sigma1912]

Just a thought:
Work offsets in one kinematics are usually not applicable in another one. So when using switchable kinematics I have often found it would be nice to have different sets of G54..G59 offsets.
Maybe a parameter offset set by the 'motion.kins-type' value?

[grandixximo]

That matches what switchkins.adoc already warns about: coordinate system offsets are described as generally applicable only to the type 0 startup kinematics, with advice to reset them or update them before switching. So the problem is real, and today it rests on the operator remembering.

Can I ask what you switch between, and whether you cut in both types? I am trying to tell two situations apart. If both types leave the axis letters describing the same physical point, then your G54 values are still correct after the switch, and what is missing is having a different one become active. If one of the types is identity, the stored numbers stop describing anything, since X becomes joint 0 and may not even carry the same units, and then a different set does not help either; the values want clearing.

Which of these is it for you: does the zero point of the part sit somewhere different once you switch, or is the part zero the same and you simply want a different one of G54 to G59.3 selected?

On the mechanism, do you mean an association living in the INI, a coordinate system named per kinematics type? There is nothing like that today. Or do you mean it read at runtime? kins-type is a status pin, so it reports rather than commands, but you could net it into a motion analog input and branch on it with M66 in a sub, which would work now. I am unsure whether that belongs in the core or stays the sort of thing an integrator wires up, and your answer would tell me which problem I am actually looking at.

[Sigma1912]

Which of these is it for you: does the zero point of the part sit somewhere different once you switch, or is the part zero the same and you simply want a different one of G54 to G59.3 selected?

Here are two examples, the tool may cut in all kinematic modes.

Example1: Serial manipulator arm
https://github.com/LinuxCNC/linuxcnc/tree/master/configs/sim/axis/vismach/melfa-sim
To overcome singularities in industrial robots we need to be able to switch between joint and cartesian mode inside a gcode program. Here the values as well as the units change from one kinematic mode the other.

Example2: Tilted work plane
https://github.com/LinuxCNC/linuxcnc/tree/master/configs/sim/axis/vismach/5axis/table-rotary_spindle-rotary-nutating
The switch to TOOL/TWP mode requires a transformation of the offset values from one coordinate frame to another (rotated AND translated). The new work offset (that describes the same point on the work piece) has thus different values that must be activated after the switch. The original offsets must be restored after switching back.

Currently I have two ways of dealing with this:

1. Keep the offsets in separate WCS systems (eg use G54 for one and G59 for the other mode). Switching from one to the other is easily handled in the custom M command used to switch the kinematics

2. Stash the offset values in parameters (so they can be restored when switching back) and then overwrite the old ones.
   This can also be handled in the custom M command but requires much thought to ensure that the correct offset values are restored in all circumstances. Generally I VERY much dislike to alter values in the offset table in the background. There is a lot that can go wrong (eg in case of an abort)

On the mechanism, do you mean an association living in the INI, a coordinate system named per kinematics type? There is nothing like that today. Or do you mean it read at runtime? kins-type is a status pin, so it reports rather than commands, but you could net it into a motion analog input and branch on it with M66 in a sub, which would work now.

Maybe a different set of G54...G59.3 values. One set for each kins-type.
I have also thought about having G54...G58 for kins-type 0, G54.1 ... G58.1 for kins-type 1, G54.2 ... G58.2 for kins-type 2 and so on (for backwards compatibility G59..g59.3 maybe the same for all)

There are also some other things to think about when working in different kinematic modes ( eg G28 , G30, G53, G92/G52, M6) it might be useful to have way of blocking certain Gcodes / Axiswords in a given mode.
I have made a patch that allows blocking certain axis letters at runtime using a magic-comment. (Just as an illustration, not suggesting to use it)
ca9c334

[grandixximo]

Both examples are clear and they moved my view: I had been assuming identity was mostly a jogging mode, and you cut in all modes. I looked at how the commercial controls handle both cases, and in each of them the closest thing we could do in LinuxCNC turns out not to be an offset set.

For the singularity case, the target stays in Cartesian coordinates and only the interpolation changes: a move that runs the inverse once at the endpoint and then interpolates the joints linearly to reach it. Coordinates and units never change, so the offsets keep applying and there is nothing to switch. In tree that is a new move type from canon into the trajectory planner, and the existing KINEMATICS_INVERSE_FLAGS already carry enough to pin which solution branch it lands on. G-code would need a way to ask for it.

For the tilted plane, an extra stage in the offset chain rather than new values in it: a frame composed on top of the active G54, with its own cancel, so the blocks in between are programmed in the tilted plane while G54 itself is untouched. That is a stage in rotate_and_offset_pos() plus the modal state to go with it. Nothing is rewritten, so nothing needs restoring and on_abort_with_twp_reset.ngc has nothing left to do. Orienting the tool normal to the plane, your G53.1, does need the kinematics to say where the tool points and to solve for the rotaries, which is item 3 above.

On having more of them: that part has plenty of precedent and I would be happy to look at it separately. Fanuc adds G54.1 P1 to P48, or to P300 on the 30i, and Siemens adds G505 to G599. What I cannot find anywhere is a control that ties a set to the active kinematics or transformation. Selection is always explicit in the program, or it belongs to a channel or path. So more coordinate systems yes, but I would rather not bind them to the kinstype.

Which leaves me reading one set per kinstype as paying for the two absences above rather than as the thing you actually want. You have run this in production and I have not, so I would rather hear where that is wrong. Would a composing frame cover your case 2, or would it miss something?

Your other point stands either way. Per-mode restrictions on G28, G30, G53, G92 and M6 look right to me, and refusing outright beats guessing.

[Sigma1912]

Nice that you have an overview of what other controllers are doing. Makes more sense adopting something that is established rather than coming up with something quirky that falls on our feet somewhere down the road.
My big deficit (or at least one of them) is that I often have zero experience how things work
on commercial machines so I end up reinventing the wheel and often do it in a slightly odd manner because I don't really know what I'm doing. :)

Which leaves me reading one set per kinstype as paying for the two absences above rather than as the thing you actually want. You have run this in production and I have not, so I would rather hear where that is wrong. Would a composing frame cover your case 2, or would it miss something?

That is how I started out, an offset built into the kinematics. The reason I moved away from that was that in it's current form LinuxCNC is totally unaware of what is going on in a custom kinematics.
So if we can handle things like G53 etc. internally then I'm probably happy with not having different sets of offsets.

Basically what I'd like is to NOT have to tamper directly with the values in the offset table.

[grandixximo]

That is the same conclusion from the other side, and it names the dependency. A composing frame is only worth having if motion knows the frame is there; otherwise G53 and G28 keep meaning whatever each module happens to do with them, and we are back to the operator remembering. That is items 3 and 4 above, which is why they come before anything in the offset chain.

What "aware" has to mean concretely: the module answers where the tool points and how joint motion maps to world motion, both as plain functions of the joint values and a parameter block, with no state hidden in HAL pins. Once the control can call the kinematics rather than only drive it, G53 resolves in machine axis space, the per-mode restrictions you listed get checked rather than guessed, and a frame composes on top of G54 with nothing rewriting the table.

So no per-kinstype offset sets, nothing tampering with the table in the background, and the tilted plane becomes a frame that cancels. Your two examples are the cases I will hold it to.

[Sigma1912]

Sounds great!

[grandixximo]

One more thing the tool round trip does not cover, found while giving 5axiskins and maxkins the .tool-offset pin every other rotary module has.

Both modules add the W coordinate to the pivot to tip distance, so W is already a tool-length route: G43.1 W5 followed by a block that commands W0 puts the kinematics on the right radius and lands on the same joint solution as a Z-column offset does. It is easy to miss, because G43.1 W5 on its own changes nothing. convert_tool_length_offset() pushes w_current down by the offset, canon adds it back, and a block with no W word hands the module zero. Command W once and it is correct from there on.

So on these two modules the tool length has three spellings: the W column with W commanded, the sum2 into pivot-length that the bridge mill sim uses, and now a .tool-offset pin. They all compute the same radius and they all add, so using two double counts. None of them is written down anywhere, which is the actual problem.

This is the same shape as the rest of items 3 and 4. Each module infers the tool from whatever it happens to be handed, every config picks a different one of the three, and nobody owns which is meant. Once the tool arrives as a parameter at the call site there is one answer instead of three.

[Sigma1912]

I have a set of kinematics that probably cover most 5 axis machine (tool side rotation, work side rotation and mixed) including nutating joints and tilted work plane. I have long wonder if I should add those to the collection:
https://github.com/Sigma1912/LinuxCNC_Demo_Configs/tree/main/5axis-twp

[grandixximo]

Yes, and I would take the kinematics first.

The nutating ones are what items 3 and 4 need most. A nutating head is where "where does the tool point" stops being obvious, so a weak default every module answers is only worth having if something in tree can break it. Today the only nutating configs are the two trsrn ones, which are yours already.

On the TWP remap I would rather you decide with item 5 in front of you. I am proposing to move that mechanism into rotate_and_offset_pos() as a frame that composes on top of G54 and cancels, which would leave the Python doing less or nothing. That does not make the configs useless, the opposite: they are the executable spec for what the frame has to do, and the baseline for checking whether a C version matches. But adding them as tree configs while I am proposing to replace the mechanism should be a decision rather than a side effect. I would rather have them in than not, and you know the ground better than I do.

One request if the kins come in: could they take the tool length through a .tool-offset pin the way the trt modules do? I have just been through this on 5axiskins and maxkins and found three spellings of the same quantity with none of them written down. Three more modules each picking their own makes that worse, and settling it now is cheap.

[Sigma1912]

I'm not in hurry it's been sitting here for a while now.
I have no problem making adjustments to make it fit better.

[grandixximo]

I had a go at the split on the two trsrn configs in tree, to see how it lands: https://github.com/grandixximo/linuxcnc/tree/twp-remap-split

Your generic remap.py plus a remap_funcs_twp.py beside each config. Your two snrtr files carry exactly the two branches the tree had inline, xyzacb-snrtr is the (C, A) maths and xyzbca-snrtr is the (C, B) maths, so it was mostly substitution. Adapted for the tree: ini read through linuxcnc.ini, kinematics switched with G12.1, and kins_set_values converts the two joint angles to degrees because the modules in tree read those pins in degrees. Pin names unchanged, so neither .comp is touched.

I ran both configs through eight orientations under G53.1 P0/P1/P2, G53.3, G53.6 and G68.3 before and after, and it looks right: nothing that worked stopped working, and P1, P2, G53.6 and G68.3 now do something where they used to fail or silently no-op.

Three things I hit in your files:

xyzbca-snrtr has the wrong default tool-x. Both files aim for the same thing in the comment, the oriented x-vector parallel to the machine xy-plane. Tool x is the first column of Rp*Rs*Rz(tc), so that is entry [2][0] == 0, and since Rp is Rz only the bottom row of Rs enters:

bottom row [-Sv*Ss, t, s]  ->  tc = atan2(Sv*Ss, t)
bottom row [t, Sv*Ss, s]   ->  tc = atan2(-t, Sv*Ss)

xyzacb-snrtr has the second row and the second formula and is right. xyzbca-snrtr has the first row and the second formula, so it orients tool y horizontal instead. Looks copied from the sibling. Invisible in use, which is presumably why it survived: the tool still points where it was told to, only x and y in the tilted plane swap, so G68.3 R starts a quarter turn off. I used the tree's form in the port.

xyzacb_snrtr_kins.comp declares hal_float_t *virtual_rot; twice, lines 34 and 38, so it does not compile.

xyzacb-snrtr/remap_funcs_twp.py, kins_calc_primary, vertical tool branch sets theta_1 = 0 and then returns the empty list, so any G53.n to vertical fails. xyzbca-snrtr says return [0] there. I took return [0].

The commit is authored by me at the moment and the code is yours, so I would set you as author before it goes anywhere. Happy either way: take the branch and send it yourself, or tell me it looks right and I will.

[Sigma1912]

Thanks for looking through this. I'll need to have a good look and report back.

[Sigma1912]

I have found a problem with G13.1/G12.1 when either is in a 'on_abort' call.

Testing with configs/sim/axis/vismach/5axis/table-rotary_spindle-rotary-nutating/xyzbca-trsrn_twp

This config has [RS274NGC]ON_ABORT_COMMAND = o <on_abort_with_twp_reset> call

I have noticed strange behavior with the remapped gcodes after issuing MDI commands that trigger this routine. For example, it looks like the g682 function gets stuck on yield INTERP_EXECUTE_FINISH

You can get an indication of the issue if you uncomment the first line in the on_abort sub:

o<on_abort_with_twp_reset> sub
(msg, on_abort START)    ; <<<< UNCOMMENT this line so the msg shows on start
M68 E2 Q0       ; reset twp-state to 'undefined' (0)
G13.1           ; back to identity kins
G64 P0.01       ; reset the toolpath tolerance as this sometimes gets set to zero on estop events
G54             ; switch to G54
(msg, on_abort END)
o<on_abort_with_twp_reset> endsub
M2

Now start the config, clear estop and switch the machine on which calls the on_abort routine. Note though that it does apparently NOT reach the end since we don't get the message on the last line:

Further testing has shown that having either a G13.1 or G12.1 P0 in the on_abort routine triggers the problem while the former M68 E3 Q0 does not.