Skip to content

Commit 3bb38b6

Browse files
committed
genserkins, pumakins: declare the arm kinematics the machine frame
A robot's working transform reports the flange in the base frame, ABB's tool0 and KUKA's $NULLFRAME: the tool is applied on top by the interpreter, not by the maths, so the type G43.4 switches to is also the machine with the tool left out, the frame G13.1 and G49 cancel to and G53.5 moves in. pumakins and genserkins declare that one type both primary and machine. G13.1 and G49 leave a robot on its arm kinematics, where a robot controller leaves it, and the identity type, joints as axes, is reached by number; G53.5 moves the flange along a base axis and holds the rest, the orientation included, interpolated in joint space, and G28.5 and G30.5 with it. A machine frame type does not read the tool offset in the parameter block, so a module whose working transform does read it declares a type without it. The machine frame is described as the frame with the tool left out rather than with the orientation left out, since on a robot the rotary letters are the flange angles the module reports, not joints; the G13.1, G49 and G43.4 descriptions say machine frame where they said identity. tests/ptp-robot checks that G53.5 moves the flange from the arm kinematics and from the identity alike, and that G13.1, G43.4 and G49 all leave the robot on the arm kinematics, in place of the refusal it checked before.
1 parent ddbb440 commit 3bb38b6

11 files changed

Lines changed: 195 additions & 102 deletions

File tree

‎configs/sim/axis/vismach/puma/remap_subs/428remap.ngc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ o<428remap>sub
33
#<kinstype> = 0
44

55
G12.1 P#<kinstype> ; select kinstype 0, syncs interp and motion
6-
; (G13.1 is identity, which is type 1 on this module)
6+
; (G13.1 is the machine frame, this type on a robot; identity is type 1)
77

88
o2 if [[#<_task> EQ 1] AND [#<_kins_type> NE #<kinstype>]]
99
(debug,M428: Wrong kinematics type)

‎docs/src/gcode/g-code.adoc‎

Lines changed: 46 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -952,9 +952,11 @@ G13.1
952952

953953
'G12.1' selects one of the kinematics provided by a switchable kinematics
954954
module; the 'P' word is the kinematics number. 'G13.1' cancels back to
955-
identity kinematics, where joints and coordinates are the same thing.
956-
Which number that is is declared by the module itself, so 'G13.1' means
957-
the same kinematics whatever order a module lists its types in.
955+
the machine frame kinematics: the identity kinematics, where joints and
956+
coordinates are the same thing, on a machine whose slides line up with its
957+
frame, and the arm kinematics with no tool on a robot. Which number that is
958+
is declared by the module itself, so 'G13.1' means the same kinematics
959+
whatever order a module lists its types in.
958960

959961
[WARNING]
960962
Deprecation notice: selecting the kinematics by writing the
@@ -970,12 +972,12 @@ planned in one kinematics and executed in another. Because of that, both
970972
codes stop any blending that was in progress, in the same way 'G4' does.
971973

972974
The kinematics module decides what each number means, and declares
973-
which one is identity. See the `switchkins` section of the kins(9) man
974-
page for the modules that support switching and the order in which they
975+
which one is the machine frame. See the `switchkins` section of the kins(9)
976+
man page for the modules that support switching and the order in which they
975977
list their kinematics. A machine whose kinematics module is not
976978
switchable rejects the change, and 'G13.1' is an error on a switchable
977-
module that declares no identity kinematics; such a module can still be
978-
driven by number with 'G12.1'.
979+
module that declares no identity or machine frame kinematics; such a module
980+
can still be driven by number with 'G12.1'.
979981

980982
Selecting a kinematics does not move the machine. It changes how joint
981983
positions and coordinate positions map onto each other, so the position
@@ -996,14 +998,14 @@ G12.1 P#<saved> (put back whatever the caller was using)
996998
Nothing cancels the selection on its own. It survives the end of the
997999
program and an abort, so that the kinematics keeps matching what the
9981000
position readout shows. End a program with 'G13.1' if it should leave the
999-
machine in identity kinematics.
1001+
machine in the machine frame kinematics.
10001002

10011003
.G12.1, G13.1 Example
10021004
[source,ngc]
10031005
----
10041006
G12.1 P1 (switch to kinematics 1)
10051007
G0 X0 Y0
1006-
G13.1 (back to identity kinematics)
1008+
G13.1 (back to the machine frame kinematics)
10071009
----
10081010

10091011
It is an error if:
@@ -1012,7 +1014,7 @@ It is an error if:
10121014
* The 'P' word is negative.
10131015
* The 'P' word names a kinematics the module does not provide.
10141016
* A 'P' word is used with 'G13.1'.
1015-
* 'G13.1' is used and the module declares no identity kinematics.
1017+
* 'G13.1' is used and the module declares no identity or machine frame kinematics.
10161018

10171019
[[gcode:g17-g19.1]]
10181020
== G17 - G19.1 Plane Select(((G17 - G19.1 Plane Select)))
@@ -1076,7 +1078,7 @@ G28 Z2.5 (rapid to Z2.5 then to Z location specified in #5163)
10761078
The 'absolute' position is the machine coordinate system of the kinematics in
10771079
force, see <<gcode:g53,G53>>: on a kinematics that is not the identity it is
10781080
that kinematics' world, not the slides, and the stored position is a world
1079-
position too. <<gcode:g28.5,G28.5>> is the form that moves the slides, and with
1081+
position too. <<gcode:g28.5,G28.5>> is the machine frame form, and with
10801082
`MACHINE_MOVES_IN_MACHINE_FRAME` set in the `[RS274NGC]` section of the INI
10811083
file 'G28' and 'G28.1' are 'G28.5' and its store whenever the kinematics in
10821084
force is not the machine frame kinematics.
@@ -1222,8 +1224,9 @@ with its frame, and the move is a <<gcode:g53.4,point-to-point move>> there,
12221224
rapid, with no offset, tool length, rotation or work plane applied. The
12231225
values are in the machine units of the INI file, as for 'G28'. The stored
12241226
position has to be a machine frame position: store it with 'G28.1' or 'G30.1'
1225-
while the identity kinematics is in force, where the world is that frame, or
1226-
under any kinematics with `MACHINE_MOVES_IN_MACHINE_FRAME` set.
1227+
while the machine frame kinematics is in force, what 'G13.1' selects, where
1228+
the world is that frame, or under any kinematics with
1229+
`MACHINE_MOVES_IN_MACHINE_FRAME` set.
12271230

12281231
* 'G28.5' - moves every letter the machine has to the stored position.
12291232
* 'G28.5 axes' - moves the letters named by 'axes' to the given machine
@@ -1844,9 +1847,9 @@ declares its working transform, so the program runs with tool length
18441847
compensation in the module's working kinematics. The switch happens
18451848
first and the offset applies after it, as if the two had been written
18461849
on consecutive lines. 'G49' is the matching cancel: it clears the
1847-
offset and switches back to identity kinematics, as long as the offset
1848-
in effect is still 'G43.4''s and no 'G12.1' or 'G13.1' has selected a
1849-
kinematics since.
1850+
offset and switches back to the machine frame kinematics, what 'G13.1'
1851+
selects, as long as the offset in effect is still 'G43.4''s and no 'G12.1'
1852+
or 'G13.1' has selected a kinematics since.
18501853

18511854
The H word, the offset itself and the parameters it lands in are
18521855
'G43''s. Which kinematics is the working one is declared by the module
@@ -1949,11 +1952,13 @@ It is an error if:
19491952

19501953
* 'G49' - cancels tool length compensation
19511954

1952-
'G49' also switches a switchable kinematics module back to its identity
1953-
kinematics when it cancels a 'G43.4' or 'G43.5', undoing the switch that made. It
1954-
leaves a kinematics selected by 'G12.1' or 'G13.1' alone, as it does
1955-
after a plain 'G43', and a module that declares no identity kinematics
1956-
gets the plain cancel.
1955+
'G49' also switches a switchable kinematics module back to its machine
1956+
frame kinematics, what 'G13.1' selects, when it cancels a 'G43.4' or
1957+
'G43.5', undoing the switch that code made. It leaves a kinematics selected
1958+
by 'G12.1' or 'G13.1' alone, as it does after a plain 'G43', and a module
1959+
that declares no identity or machine frame kinematics gets the plain
1960+
cancel. On a robot the arm kinematics is the machine frame, so there the
1961+
cancel switches nothing.
19571962

19581963
It is OK to program using the same offset already in use. It is also
19591964
OK to program using no tool length offset if none is currently being
@@ -2167,19 +2172,23 @@ one more layer of interpretation from the destination than the one before:
21672172
without leaving its coordinate system and without the trajectory planner
21682173
trying to hold the tool tip on a line the joints cannot follow at speed.
21692174
* 'G53.5' takes the same axis letters as a position in the machine frame
2170-
with the orientation left out: 'X', 'Y' and 'Z' are the carriage, the
2171-
point the rotary joints do not move, in machine coordinates, and the
2172-
rotary letters are the rotary joints themselves. On a machine whose slides
2173-
line up with its frame, which every shipped module is, that is the slides:
2174-
each letter names the joints the module's identity mapping gives it, which
2175-
the `coordinates=` parameter and the `[TRAJ]COORDINATES` line describe,
2176-
and the two joints of a gantry take one value together. A module whose
2175+
with the tool left out: 'X', 'Y' and 'Z' are the point the tool hangs
2176+
from, the pivot of a head or the flange of a robot, in machine
2177+
coordinates, and the rotary letters are the orientation as the machine
2178+
frame kinematics reports it, on a mill the rotary joints themselves. On a
2179+
machine whose slides line up with its frame that is the slides: each
2180+
letter names the joints the module's identity mapping gives it, which the
2181+
`coordinates=` parameter and the `[TRAJ]COORDINATES` line describe, and
2182+
the two joints of a gantry take one value together. A module whose
21772183
carriage does not line up, a slanted slide or a composite Y on a mill-turn,
21782184
declares a machine frame type of its own (see the
21792185
<<cha:switchable-kinematics,Switchable Kinematics>> chapter) and 'G53.5'
21802186
goes through it, so that 'Y10' is machine Y whichever slides make it, and
2181-
a letter not given holds its machine coordinate rather than a joint.
2182-
Values are in program units, so 'G20' scales them like any other axis
2187+
a letter not given holds its machine coordinate rather than a joint. On a
2188+
robot the machine frame is the arm kinematics with no tool, the flange in
2189+
the base frame, so 'Z10' puts the flange at base Z 10 with its orientation
2190+
held and 'A', 'B' and 'C' are the flange angles the module reports; the
2191+
move is still interpolated in joint space. Values are in program units, so 'G20' scales them like any other axis
21832192
word. No offset, tool length, rotation or work plane applies. On a mill
21842193
whose joint 2 carries the Z slide, 'G53.5 G0 Z0' puts that slide at zero
21852194
whatever the head and the tool are doing, where under a tool centre point
@@ -2192,19 +2201,20 @@ one more layer of interpretation from the destination than the one before:
21922201
+
21932202
An axis letter carries a unit class and a joint does not, so where the
21942203
machine frame is the joints 'G53.5' is refused on a machine whose letters
2195-
name joints of the other kind. A serial robot answers X with its first
2196-
rotary joint, which turns in degrees, and there the whole code is refused
2197-
rather than that one letter. Which joints turn is what `[JOINT_n] TYPE`
2198-
declares.
2204+
name joints of the other kind: a module that declares no kinematics types
2205+
and answers X with a rotary joint, which turns in degrees, has the whole
2206+
code refused rather than that one letter. Which joints turn is what
2207+
`[JOINT_n] TYPE` declares.
21992208

22002209
* 'G53.7' takes joint values, one word per joint, and works on every machine:
22012210
'J2=-5' sends joint 2 to -5. The number after 'J' is the joint number, the
22022211
`[JOINT_n]` section and the `joint.n` HAL pins, and the value after '=' is
22032212
the joint's own position, what `joint.n.pos-cmd` shows, in the joint's own
22042213
units. Nothing is converted, not even 'G20' and 'G21'. A joint left out
22052214
keeps its position, and the two joints of a gantry pair must both be given,
2206-
with one value. This is the form for a robot, and for any machine where the
2207-
letters do not name the joints they look like.
2215+
with one value. This is the form that names a joint outright, a robot's
2216+
joints by number, and the only form on a machine whose letters do not name
2217+
the joints they look like and whose module declares no machine frame.
22082218

22092219
With 'G0' the speed comes from the joint limits in the INI file,
22102220
`[JOINT_n] MAX_VELOCITY` and `MAX_ACCELERATION`, scaled so that no joint

‎docs/src/motion/kinematics-conventions.adoc‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -73,17 +73,22 @@ the zero pose or a switch would jump the reported position; a module without
7373
one keeps it too, so that `G53.5` machine frame positions and `G53` positions
7474
coincide with the rotaries at zero.
7575

76-
The machine frame is the frame with the orientation left out: XYZ is the
77-
pivot, the point the rotary joints do not move, in machine coordinates, and
78-
the rotary letters are the rotary joints as they are. On a machine whose
79-
slides line up with its frame that is the identity type, and it is what
80-
`G13.1` and `G49` select and `G53.5` moves in. A machine whose carriage does
81-
not line up, a slanted slide, a composite Y made by two slides, an offset
82-
pivot, declares a machine frame type of its own next to its identity type,
83-
and its identity type then keeps the plain meaning, joints are axes, which a
84-
consumer uses to skip the maths. The zero-pose rule holds for the machine
85-
frame type as it does for the identity: the working transform and the machine
86-
frame type agree with the rotaries at zero.
76+
The machine frame is the frame with the tool left out: XYZ is the point the
77+
tool hangs from, the pivot of a head or the flange of a robot, in machine
78+
coordinates, and the rotary letters are the orientation as the machine frame
79+
type reports it, the rotary joints on a mill, the flange angles on a robot.
80+
It is what `G13.1` and `G49` select and `G53.5` moves in. On a machine whose
81+
slides line up with its frame it is the identity type. A machine whose
82+
carriage does not line up, a slanted slide, a composite Y made by two slides,
83+
an offset pivot, declares a machine frame type of its own next to its
84+
identity type, and its identity type then keeps the plain meaning, joints are
85+
axes, which a consumer uses to skip the maths. A robot's working transform
86+
reports the flange in the base frame, the tool applied on top by the
87+
interpreter and not by the maths, so the one type is both the working
88+
transform and the machine frame, what ABB calls `tool0` and KUKA
89+
`$NULLFRAME`. The zero-pose rule holds for the machine frame type as it does
90+
for the identity: the working transform and the machine frame type agree with
91+
the rotaries at zero.
8792

8893
Orientations are measured against the machine frame, and there are two of them.
8994
A module reports the tool frame and the work frame separately, each in machine
@@ -568,7 +573,9 @@ the last answer after a switch. A type also says what it IS: `identity` marks
568573
the no-transform type, joints are axes; `primary` the working transform
569574
`G43.4` and `G43.5` switch to; `machine` the machine frame type `G13.1` and
570575
`G49` cancel to and `G53.5` moves in, which a module leaves unset when its
571-
identity type is that frame (see the Switchable Kinematics chapter). A module with
576+
identity type is that frame and sets on its working transform when that
577+
reports the flange with no tool, as the robot modules do (see the Switchable
578+
Kinematics chapter). A module with
572579
several types has one geometry table and one ops table per type, registered
573580
with `switchkinsRegisterOps()`; a module with one type describes itself in a
574581
`kins_module` and links `kins_single.c`.

‎docs/src/motion/switchkins.adoc‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ what it is rather than by number: 'G43.4' applies the tool length
228228
offset and switches to the kinstype the module declares its working
229229
transform, 'G43.5' does the same and lets the lines after it give the
230230
tool axis as a vector, and the 'G49' that cancels either switches back
231-
to identity. See the G-code documentation for 'G43.4', 'G43.5' and
231+
to the machine frame kinstype, what 'G13.1' selects. See the G-code documentation for 'G43.4', 'G43.5' and
232232
'G49', and for 'G12.1' and 'G13.1', for the full description.
233233

234234
=== M-code commands
@@ -574,8 +574,8 @@ kinematics.h:
574574

575575
. *KINSTYPE_IDENTITY* no transform: the joints are the world
576576
. *KINSTYPE_PRIMARY* the module's working transform
577-
. *KINSTYPE_MACHINE* the machine frame: the pivot in machine coordinates,
578-
the rotaries as joints
577+
. *KINSTYPE_MACHINE* the machine frame: the tool left out, XYZ the pivot
578+
or the flange in machine coordinates
579579

580580
A kinstype registered with switchkinsRegisterOps() carries its flag in
581581
the ops table itself, as the 'identity', 'primary' or 'machine' field; a
@@ -595,15 +595,24 @@ are not in the conventional order still gets working spellings. With
595595
INI file, 'G53', 'G28' and 'G30' move in the machine frame kinstype's
596596
world too whenever another kinstype is in force; the five axis sims set
597597
it. The
598-
machine frame type is the machine with the orientation left out, XYZ the
599-
pivot in machine coordinates and the rotary letters the rotary joints;
600-
on a machine whose slides line up with its frame that is the identity
601-
type, so a module that declares no machine frame kinstype has its
602-
identity kinstype stand in, and every shipped module is of that kind. A
603-
module whose carriage does not line up, a slanted slide or a composite Y
604-
on a mill-turn, declares its machine frame kinstype separately and keeps
605-
KINSTYPE_IDENTITY for a kinstype whose joints really are the axes, since
606-
motion and the planner skip the maths on that flag alone. At most one
598+
machine frame kinstype is the machine with the tool left out, XYZ the
599+
pivot or the flange in machine coordinates and the rotary letters the
600+
orientation as that kinstype reports it; on a machine whose slides line
601+
up with its frame that is the identity kinstype, so a module that
602+
declares no machine frame kinstype has its identity kinstype stand in,
603+
and every shipped machine tool module is of that kind. A robot's
604+
working transform reports the flange in the base frame, the tool applied
605+
on top by the interpreter and not by the maths, so pumakins and
606+
genserkins declare that one kinstype both primary and machine: 'G13.1'
607+
and 'G49' leave a robot on its arm kinematics, as ABB's `tool0` and
608+
KUKA's `$NULLFRAME` do, and its identity kinstype is reached by number.
609+
A machine frame kinstype does not read the tool offset in the parameter
610+
block; a module whose working transform does declares a kinstype without
611+
it. A module whose carriage does not line up, a slanted slide or a
612+
composite Y on a mill-turn, declares its machine frame kinstype
613+
separately and keeps KINSTYPE_IDENTITY for a kinstype whose joints
614+
really are the axes, since motion and the planner skip the maths on that
615+
flag alone. At most one
607616
kinstype may be declared identity, at most one primary and at most one
608617
machine frame, and declaring a kinstype the module does not provide
609618
fails the module load. A module that declares nothing keeps working

‎include/kinematics.h‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -120,20 +120,23 @@ extern KINEMATICS_TYPE kinematicsType(void);
120120
** numeric-only and G13.1 refuses to guess.
121121
**
122122
** The machine frame type is the one whose world is the machine frame
123-
** with the orientation left out: XYZ is the pivot, the point the rotary
124-
** joints do not move, in machine coordinates, and the rotary letters are
125-
** the rotary joints as they are. On a machine whose slides line up with
126-
** its frame that is the identity type, and where a module declares no
127-
** machine frame type its identity type stands in. A module whose
128-
** carriage does not line up, a slanted slide or an offset pivot, declares
129-
** its machine frame type separately and keeps identity for a type whose
130-
** joints really are the axes, since a consumer skips the maths on that
131-
** flag alone.
123+
** with the tool left out: XYZ is the point the tool hangs from, the pivot
124+
** of a head or the flange of a robot, in machine coordinates, and the
125+
** rotary letters are the orientation as that type reports it, the rotary
126+
** joints on a mill, the flange angles on a robot. On a machine whose
127+
** slides line up with its frame that is the identity type, and where a
128+
** module declares no machine frame type its identity type stands in. A
129+
** module whose carriage does not line up, a slanted slide or an offset
130+
** pivot, declares its machine frame type separately and keeps identity
131+
** for a type whose joints really are the axes, since a consumer skips
132+
** the maths on that flag alone. A robot's working transform is its
133+
** flange in the base frame with no tool in the maths, so it is the
134+
** machine frame type as well and carries both flags.
132135
*/
133136
#define KINSTYPE_IDENTITY 0x1 /* no transform: the joints are the world */
134137
#define KINSTYPE_PRIMARY 0x2 /* the module's working transform */
135-
#define KINSTYPE_MACHINE 0x4 /* the machine frame: the pivot in machine
136-
coordinates, the rotaries as joints */
138+
#define KINSTYPE_MACHINE 0x4 /* the machine frame: the tool left out, XYZ
139+
the pivot or flange in machine coordinates */
137140

138141
/* flags of a kinematics type, 0 when neither applies, or -1 for a type
139142
** the module does not provide (and for every type on a machine with plain

0 commit comments

Comments
 (0)