Implement G52 offsets

This implementation of `G52` is intended to be compatible with Fanuc,
including sharing offset registers with `G92`.

LinuxCNC rs274ngc persists `G92` offsets across machine startup, M02
and M30, but Fanuc does not.  Because users familiar with Fanuc may
expect the offset to be volatile, and be surprised (perhaps badly)
when the offset persists, this patch adds a `.ini` file option to
disable it.

Other implementation details:

- `G52` shares registers with `G92`, `#5210` (flag) and `#5211`
  through `#5219` (9 axis offsets)
- `G52` offsets are applied in the same way as `G92`, after workpiece
  coordinate offsets and rotation.
- `G52` and `G92`/`G92.n` may be freely mixed, and in the light of the
  shared registers, interactions behave as expected.
  - `G52 X0 Y0` zeros the offsets, but does not reset the `#5210`
    flag.  This is not expected to cause unexpected behavior; the flag
    apparently exists only to implement `G92.2` and `G92.3`.
  - `G52` and `G92` share DRO readouts and preview offset display.
- `G92` offset persistence may be disabled by setting
  `PERSISTENT_G92_OFFSET = false` in the `[RS274NGC]` section of the
  `.ini` file.  By default, `G92` is persistent.

Signed-off-by: John Morris <[email protected]>

docs/src/gcode/coordinates.txt

@@ -9,7 +9,7 @@ These include:
 
 * Machine Coordinates (G53)
 * Nine Coordinate System Offsets (G54-G59.3)
-* Global Offsets (G92)
+* Global Offsets (G92) and Local Offsets (G52)
 
 == Machine Coordinate System
 
@@ -56,11 +56,11 @@ In the VAR file scheme, the first variable number stores the X offset,
 the second the Y offset and so on for all six axes. There are numbered
 sets like this for each of the coordinate system offsets.
 
-Each of the graphical interfaces has a way to set values for these offsets.
-You can also set these values by editing the VAR file itself and then
-restart LinuxCNC so that the LinuxCNC reads the new values however this is
-not the recommended way. Using G10, G92, G28.1, etc are better ways to
-set the variables.
+Each of the graphical interfaces has a way to set values for these
+offsets.  You can also set these values by editing the VAR file itself
+and then restart LinuxCNC so that the LinuxCNC reads the new values
+however this is not the recommended way. Using G10, G52, G92, G28.1,
+etc are better ways to set the variables.
 
 .Example of G55 parameters
 [width="40%",cols="^,^,^",options="header"]
@@ -133,11 +133,59 @@ The G10 L2x command can be used to set coordinate system offsets:
 * 'G10 L20 P(1-9)' - Set offset(s) so current position becomes a value.
                          (see <<gcode:g10-l20,G10 L20>> for details)
 
-== Global Offsets[[sec:g92-offsets]]
+== Local and Global Offsets[[sec:g52-and-g92-offsets]]
 
-=== The G92 Commands
+=== The G52 command[[sec:g52]]
 
-This set of commands include;
+'G52' is used in a part program as a temporary "local coordinate
+system offset" within the workpiece coordinate system.  An example use
+case is when machining several identical features at different
+locations on a part.  For each feature, 'G52' programs a local
+reference point within workpiece coordinates, and a subprogram is
+called to machine the feature relative to that point.
+
+'G52' axis offsets are programmed relative to workpiece coordinate
+offsets 'G54' through 'G59.3'.  As a local offset, 'G52' is applied
+after the workpiece offset, including rotation.  Thus, a part feature
+will be machined identically on each part regardless of the part's
+orientation on the pallet.
+
+[CAUTION]
+
+As a temporary offset, set and unset within the localized scope of a
+part program, in other g-code interpreters 'G52' does not persist
+after machine reset, 'M02' or 'M30'.  In LinuxCNC, 'G52' shares
+parameters with 'G92', which, for historical reasons, *does* persist
+these parameters.  See <<sec:g92-persistence-cautions,G92 Persistenc
+Cautions>> below.
+
+[CAUTION]
+
+'G52' and 'G92' share the same offset registers.  Therefore, setting
+'G52' will override any earlier 'G92' setting, and 'G52' will persist
+across machine reset when 'G92' persistence is enabled.  These
+interactions may result in unexpected offsets.  See
+<<sec:g92-g52-interaction-cautions,G92 and G52 Interaction Cautions>>
+below.
+
+Programming 'G52 X1 Y2' offsets the current workpiece coordinate
+system X axis by 1 and Y axis by 2.  Accordingly, on the DRO, the
+current tool position's X and Y coordinates will be reduced by 1 and
+2, respectively.  Axes unset in the command, such as Z in the previous
+example, will be unaffected: any previous 'G52' Z offset will remain
+in effect, and otherwise the Z offset will be zero.
+
+The temporary local offset may be canceled with 'G52 X0 Y0'.  Any axes
+not explicitly zeroed will retain the previous offset.
+
+'G52' shares the same offset registers as the legacy 'G92', and thus
+'G52' is visible on the DRO and preview labeled with 'G92'.
+
+=== The G92 commands[[sec:g92-commands]]
+
+'G92' is typically used in two conceptually different ways: as a
+"global coordinate system offset" or as a "local coordinate system
+offset".  The 'G92' set of commands includes:
 
 * 'G92' - This command, when used with axis names, sets values to offset
     variables.
@@ -149,25 +197,61 @@ This set of commands include;
 
 * 'G92.3' - This command applies offset values that have been suspended.
 
-When the commands are used as described above, they will work pretty
-much as you would expect.
-
-To make the  current point, what ever it is,
-have the coordinates X0, Y0, and Z0 you would use G92 X0 Y0 Z0.
-G92 *does not* work from absolute machine coordinates.
-It works from *current location*.
-
-G92 also works from current location as modified by any other offsets
-that are in effect when the G92 command is invoked. While testing for
-differences between work offsets and actual offsets it was found that a
-G54 offset could cancel out a G92 and thus give the appearance that no
-offsets were in effect. However, the G92 was still in effect for all
-coordinates and did produce expected work offsets for the other
-coordinate systems.
-
-It is a good practice to clear the G92 offsets at the end of their
-use with G92.1 or G92.2. When starting up LinuxCNC if any offsets are
-in the G92 variables they will be applied when an axis is homed.
+As a global offset, 'G92' is used to shift all workpiece coordinate
+systems 'G54' through 'G59.3'.  An example use case is when machining
+several identical parts in fixtures with known locations on a pallet,
+but the pallet location may change between runs or between machines.
+Each fixture location offset, relative to a reference point on the
+pallet, is preset in one of the workpiece coordinate systems, 'G54'
+through 'G59.3', and 'G92' is used to "touch off" on the pallet
+reference point.  Then, for each part, the corresponding workpiece
+coordinate system is selected and the part program is executed.
+
+[NOTE]
+'G10 R-' workpiece coordinate system rotation is specific to the
+'rs274ngc' interpreter, and the 'G92' offset is applied 'after'
+rotation.  When using 'G92' as a global offset, workpiece coordinate
+system rotations may have unexpected results.
+
+As a local coordinate system, 'G92' is used as a temporary offset
+within the workpiece coordinate system.  An example use case is when
+machining a part with several identical features at different
+locations.  For each feature, 'G92' is used to set a local reference
+point, and a subprogram is called to machine the feature starting at
+that point.
+
+[NOTE]
+The use of 'G92' is discouraged for programming with local coordinate
+systems in a part program.  Instead, see <<sec:g52,'G52'>>, a local
+coordinate system offset more intuitive when desired offset relative
+to the workpiece is known but current tool location may not be known.
+
+Programming 'G92 X0 Y0 Z0' sets the current tool location to the
+coordinates X0, Y0, and Z0, without motion.  G92 *does not* work from
+absolute machine coordinates.  It works from *current location*.
+
+'G92' also works from current location as modified by any other
+offsets that are in effect when the 'G92' command is invoked. While
+testing for differences between work offsets and actual offsets it was
+found that a 'G54' offset could cancel out a 'G92' and thus give the
+appearance that no offsets were in effect. However, the 'G92' was
+still in effect for all coordinates and did produce expected work
+offsets for the other coordinate systems.
+
+By default, 'G92' offsets are cleared after the machine is started and
+after a 'M02' or 'M30'.  Programmers that often use 'G92' as a global
+offset and do not use 'G92' or 'G52' for local coordinate systems may
+wish for the offset to persist between machine resets.  Enable 'G92'
+persistence by setting 'PERSISTENT_G92_OFFSET = true' in the
+'[RS274NGC]' section of the '.ini' file.
+
+[NOTE]
+
+Especially when enabling 'G92' offset persistence, it is good practice
+to clear the 'G92' offsets at the end of their use with 'G92.1' or
+'G92.2'. When starting up LinuxCNC with 'G92' persistence enabled, any
+offsets in the 'G92' variables will be applied when an axis is homed.
+See <<sec:g92-persistence-cautions,G92 Persistence Cautions>> below.
 
 === Setting G92 Values
 
@@ -181,8 +265,16 @@ zero. A 'G92 X2' will set an offset of 0.0000 and the displayed position
 will not change. A 'G92 X5.0000' will set an offset of 3.0000 so that the
 current displayed position becomes 5.0000.
 
+=== G92 Persistence Cautions[[sec:g92-persistence-cautions]]
+
+By default, the values of a 'G92' offset will remain in the VAR file.
+This may happen unintentionally when a program is aborted while 'G92'
+offsets are in effect.  In this case, the saved 'G92' offsets will be
+restored after a machine reset or startup.
+
 The G92 parameters are:
 
+* 5210 - Enable/disable flag (1.0/0.0)
 * 5211 - X Axis Offset
 * 5212 - Y Axis Offset
 * 5213 - Z Axis Offset
@@ -193,9 +285,11 @@ The G92 parameters are:
 * 5218 - V Axis Offset
 * 5219 - W Axis Offset
 
-If you are seeing unexpected positions as the result of a commanded move, as a
-result of storing an offset in a previous program and not clearing them at the
-end then issue a G92.1 in the MDI window to clear the stored offsets.
+where 5210 is the 'G92' enable flag (1 for enabled, 0 for disabled)
+and 5211 are the axis offsets. If you are seeing unexpected positions
+as the result of a commanded move, as a result of storing an offset in
+a previous program and not clearing them at the end then issue a G92.1
+in the MDI window to clear the stored offsets.
 
 If G92 values exist in the VAR file when LinuxCNC starts up, the G92
 values in the var file will be applied to the values of the current
@@ -209,16 +303,31 @@ G92 was applied to the machine origin. If you issue a G92.1 and the DRO
 now reads all zeros then you had a G92 offset in effect when you last
 ran LinuxCNC.
 
-Unless your intention is to use the same G92 offsets in the next
-program, the best practice is to issue a G92.1 at the end of any G Code
-files where you use G92 offsets.
+When 'G92' offset persistence is enabled, unless your intention is to
+use the same G92 offsets in the next program, the best practice is to
+issue a G92.1 at the end of any G Code files where you use G92
+offsets.
 
-[CAUTION]
-When a file is aborted during processing that has G92 offsets in effect a
-startup will cause them to become active again. Always have your preamble
-to set the environment as you expect it.
+When a file is aborted during processing that has 'G92' offsets in
+effect a startup will cause them to become active again.  As a
+safeguard, always have your preamble to set the environment as you
+expect it.  Additionally, 'G92' persistence may be disabled by setting
+'PERSISTENT_G92_OFFSET = false' in the '[RS274NGC]' section of the
+'.ini' file.
+
+=== G92 and G52 Interaction Cautions[[sec:g92-g52-interaction-cautions]]
+
+'G52' and 'G92' share the same offset registers.  When 'G92'
+persistence is enabled in the '.ini' file (see <<sec:g92-commands,G92
+Commands>>), 'G52' offsets will also persist after machine reset,
+'M02' or 'M30'.  When 'G92' persistence is enabled, beware that a
+'G52' offset in effect during a program abort may result in unintended
+offsets when the next program is run.  See <<sec:g92-persistence-cautions,G92
+Persistence Cautions>> above.
+
+== Sample Programs Using Offsets
 
-== Sample Program Using Offsets
+=== Sample Program Using Workpiece Coordinate Offsets
 
 This sample engraving project mills a set of four .1 radius circles in
 roughly a star shape around a center circle. We can setup the
@@ -293,4 +402,6 @@ run after this one will also use that G92 offset. Furthermore it would
 save the G92 values when you shut down the LinuxCNC and they will be
 recalled when you start up again.
 
+=== Sample Program Using G52 Offsets
 
+(To be written)

docs/src/gcode/g-code.txt

@@ -705,8 +705,10 @@ Important Concepts:
   you have to use G54-59.3 to select a coordinate system.
 * When a rotation is in effect jogging an axis will only move that axis
   in a positive or negative direction and not along the rotated axis.
-* If a 'G92' origin offset was in effect before 'G10 L2',
-  it will continue to be in effect afterwards.
+* If a 'G52' local offset or 'G92' origin offset was in effect before
+  'G10 L2', it will continue to be in effect afterwards.
+* When programming a coordinate system with R, any 'G52' or 'G92' will
+  be applied *after* the rotation.
 * The coordinate system whose origin is set by a 'G10' command may be
   active or inactive at the time the 'G10' is executed.
   If it is currently active, the new coordinates take effect immediately.
@@ -752,7 +754,7 @@ G10 L10 P- axes <R- I- J- Q->
 
 G10 L10 changes the tool table entry for tool P so that if the
 tool offset is reloaded, with the machine in its current position
-and with the current G5x and G92 offsets active, the current coordinates
+and with the current G5x and G52/G92 offsets active, the current coordinates
 for the given axes will become the given values. The axes that are
 not specified in the G10 L10 command will not be changed. This could be
 useful with a probe move as described in the <<gcode:g38,G38>> section.
@@ -791,7 +793,7 @@ G10 L11 is just like G10 L10 except that instead of setting the entry
 according to the current offsets, it is set so that the current
 coordinates would become the given value if the new tool offset
 is reloaded and the machine is placed in the G59.3 coordinate
-system without any G92 offset active.
+system without any G52/G92 offset active.
 
 This allows the user to set the G59.3 coordinate system according to a
 fixed point on the machine, and then use that fixture to measure tools
@@ -2205,7 +2207,8 @@ program a G92.2 (to remove them - they are still stored).
 See the <<cha:coordinate-system,Coordinate System>> Section for an
 overview of coordinate systems.
 
-See the <<sec:g92-offsets,Offsets>> Section for more information.
+See the <<sec:g52-and-g92-offsets,Offsets>> Section for more
+information.
 
 See the <<gcode:parameters,Parameters>> Section for more information.
 

docs/src/gcode/gcode_fr.txt

@@ -742,8 +742,8 @@ coordonnées.
 * Quand un mouvement de rotation est en cours, jogger un axe, déplacera celui-ci
 seulement dans le sens négatif ou positif et non pas le long de l'axe de
 rotation.
-* Si un décalage d'origine créé avec 'G92' est actif avant la commande 'G10 L2',
-il reste actif après.
+* Si un décalage d'origine créé avec 'G92' ou 'G92' est actif avant la
+commande 'G10 L2', il reste actif après.
 * Le système de coordonnées dont l'origine est définie par la commande 'G10'
 peut être actif ou non au moment de l'exécution de 'G10'. Si il est actif à
 ce moment là, les nouvelles coordonnées prennent effet immédiatement.
@@ -789,7 +789,7 @@ G10 L10 P- axes <R- I- J- Q->
 
 G10 L10 modifie les valeurs de l'outil 'P' dans la table d'outils, de sorte
 que si la compensation d'outil est rechargée, avec la machine à la position
-courante et avec les G5x et G92 actifs, les coordonnées courantes pour
+courante et avec les G5x et G52/G92 actifs, les coordonnées courantes pour
 l'axe spécifié deviendront les coordonnées spécifiées. Les axes non spécifiés
 dans la commande G10 L10 ne seront pas modifiés.
 
@@ -826,7 +826,7 @@ G10 L11 est identique à G10 L10 excepté qu'au lieux de fixer les valeurs
 par rapport aux décalages de coordonnées courants, il les fixe de sorte que les
 coordonnées courantes deviennent celles spécifiées par les paramètres si la
 nouvelle compensation d'outil est rechargée et que la machine est placée dans
-le système de coordonnées G59.3, système sans aucun décalage G92 actif.
+le système de coordonnées G59.3, système sans aucun décalage G52/G92 actif.
 
 Ceci permet à l'utilisateur de fixer le système de coordonnées G59.3 à
 un point fixe de la machine et d'utiliser cet emplacement pour mesurer

docs/src/gcode/overview.txt

@@ -284,11 +284,14 @@ example '##2'  means the value of the parameter whose index is the
 
 * '5181-5189' - "G30" Home for X, Y, Z, A, B, C, U, V & W. Persistent.
 
-* '5211-5219' - "G92" offset for X, Y, Z, A, B, C, U, V & W. Persistent.
+* '5210' - 1 if "G52" or "G92" offset is currently applied, 0
+   otherwise.  Volatile by default; persistent if
+   'PERSISTENT_G92_OFFSET = true' in the '[RS274NGC]' section of the
+   '.ini' file.
 
-* '5210' - 1 if "G92" offset is currently applied, 0 otherwise. Persistent.
-
-* '5211-5219' - 'G92' offset (X Y Z A B C U V W).
+* '5211-5219' - Shared "G52" and "G92" offset for X, Y, Z, A, B, C, U,
+  V & W.  Volatile by default; persistent if 'PERSISTENT_G92_OFFSET =
+  true' in the '[RS274NGC]' section of the '.ini' file.
 
 * '5220' - Coordinate System number 1 - 9 for G54 - G59.3. Persistent.
 
@@ -947,7 +950,7 @@ being in effect. The modal groups are shown in the following Table.
 [width="80%", cols="4,6", options="header"]
 |====
 |Modal Group Meaning                   | Member Words
-|Non-modal codes (Group 0)             | G4, G10 G28, G30, G53 G92, G92.1, G92.2, G92.3, 
+|Non-modal codes (Group 0)             | G4, G10 G28, G30, G52, G53, G92, G92.1, G92.2, G92.3, 
 .2+|Motion (Group 1)                   | G0, G1, G2, G3, G33, G38.x, G73, G76, G80, G81
                                        | G82, G83, G84, G85, G86, G87, G88, G89
 |Plane selection (Group 2)             | G17, G18, G19, G17.1, G18.1, G19.1
@@ -994,7 +997,7 @@ G-code from group 1 is implicitly in effect on a line (by having been
 activated on an earlier line), and a group 0 G-code that uses axis
 words appears on the line, the activity of the group 1 G-code is
 suspended for that line. The axis word-using G-codes from group 0 are
-G10, G28, G30, and G92.
+G10, G28, G30, G52 and G92.
 
 It is an error to include any unrelated words on a line with 'O-' flow
 control.
@@ -1171,7 +1174,7 @@ position of each item on the line, but by the following list:
 * Set distance mode (G90, G91). 
 * Set retract mode (G98, G99).
 * Go to reference location (G28, G30) or change coordinate system 
-  data (G10) or set axis offsets (G92, G92.1, G92.2, G94). 
+  data (G10) or set axis offsets (G52, G92, G92.1, G92.2, G94). 
 * Perform motion (G0 to G3, G33, G38.x, G73, G76, G80 to G89), as modified
   (possibly) by G53. 
 * Stop (M0, M1, M2, M30, M60).