docs, tests: document and cover G28.2

Docs: new "G28.2 Home from G-code" section in g-code.adoc (syntax, the
mandatory P word and why there is no bare form, the HOME_SEQUENCE
requirement for P-1, the negative/positive shared-sequence Pn cases, the
mode-dip and position-resync behaviour, error conditions); G28.2 added
to the modal-group-0 lists in overview.adoc, remap.adoc, gcode.html.in,
hal_glib.py and mdi_text.py, with the qtvcp MDI help carrying the same
P-word rules.

Tests (tests/interp/g28.2/): joint-pword and invalid-pword drive rs274 /
task directly; the rest run a sim under milltask -
 - sequencing: the FREE-mode dip is invisible at the task level; an
   invalid Pn does not wedge task.mode;
 - immediate-mode-guard: an immediate home from teleop is still refused;
 - home-all-sequence: G28.2 P-1 as a first-home on a HOME_SEQUENCE
   config, and a bare G28.2 refused without homing anything;
 - invalid-pword: the rest of the P word's surface - an unconfigured
   joint number, P-2, another negative and a fraction are all refused up
   front, name P-1 as the way to home everything, and leave the homed
   state and trajectory mode alone;
 - flush-order: a move before G28.2 runs before the home;
 - position-model: a G91 move (rotary C and linear X) after G28.2 Pn is
   computed from the homed position, not the stale one - fails without
   the resync (lands at stale+increment).

Author: greatEndian

docs/src/gcode.html.in

@@ -165,6 +165,7 @@ tr.head td, tr.head th { background: black; color: white; }
     <tr><td><a href="gcode/g-code.html#gcode:g10-l2">G10 L2</a></td><td>P R</td><td>Set Coordinate System</td></tr>
     <tr><td><a href="gcode/g-code.html#gcode:g10-l20">G10 L20</a></td><td>P</td><td>Set Coordinate System</td></tr>
     <tr><td><a href="gcode/g-code.html#gcode:g28-g28.1">G28, G28.1</a></td><td/><td>Go/Set Predefined Position</td></tr>
+    <tr><td><a href="gcode/g-code.html#gcode:g28.2">G28.2</a></td><td>P</td><td>Home from G-code</td></tr>
     <tr><td><a href="gcode/g-code.html#gcode:g30-g30.1">G30, G30.1</a></td><td/><td>Go/Set Predefined Position</td></tr>
     <tr><td><a href="gcode/g-code.html#gcode:g53">G53</a></td><td/><td>Move in Machine Coordinates</td></tr>
     <tr><td><a href="gcode/g-code.html#gcode:g92">G52, G92</a></td><td/><td>Coordinate System Offset</td></tr>

docs/src/gcode/g-code.adoc

@@ -73,6 +73,7 @@ as the 'L number', and so on for any other letter.
 |<<gcode:g17-g19.1,G17 - G19.1>>   |Plane Select
 |<<gcode:g20-g21,G20 G21>>         |Set Units of Measure
 |<<gcode:g28-g28.1,G28 - G28.1>>   |Go to Predefined Position
+|<<gcode:g28.2,G28.2>>             |Home from G-code
 |<<gcode:g30-g30.1,G30 - G30.1>>   |Go to Predefined Position
 |<<gcode:g33,G33>>                 |Spindle Synchronized Motion
 |<<gcode:g33.1,G33.1>>             |Rigid Tapping
@@ -997,6 +998,81 @@ It is an error if :
 
 * Cutter Compensation is turned on
 
+[[gcode:g28.2]]
+== G28.2 Home from G-code(((G28.2 Home from G-code)))
+
+This non-modal code lets a program or MDI line reference the machine
+instead of requiring the operator to use the GUI's *Home All* button. It
+follows the same modal-group-0 pattern as `G28.1`/`G30.1`, takes no axis
+words, and *requires* a `P` word saying what to home.
+
+* 'G28.2 P-1' - runs the homing cycle on every joint, in `HOME_SEQUENCE`
+  order (the same operation as the GUI *Home All*). This form requires the
+  config to set `[JOINT_n]HOME_SEQUENCE`; exactly as with *Home All*, a
+  config with no `HOME_SEQUENCE` cannot home all joints at once and the
+  command fails, leaving the machine in joint mode.
+* 'G28.2 Pn' - runs the homing cycle on joint 'n' only, where 'n' is the
+  0-based joint number matching its `[JOINT_n]` INI section (the same
+  numbering used by `HOME_SEQUENCE` and by joint jogging). Other joints are
+  left as they are, and `HOME_SEQUENCE` is not required for the `Pn` form.
+  How many joints actually home depends on the `HOME_SEQUENCE` of joint 'n':
++
+--
+** a *negative* (synchronized) sequence homes the whole synchronized group -
+   `Pn` on either joint of a gantry pair homes both;
+** a *positive* sequence shared with other joints homes only joint 'n' -
+   use `G28.2 P-1` to home the shared group together;
+** no sequence, or a sequence not shared with any other joint, homes just
+   joint 'n'.
+--
+
+[WARNING]
+There is no bare `G28.2`. Homing drives joints onto their switches at
+homing speed, ignoring soft limits, from wherever the machine happens to
+be, so homing the whole machine has to be asked for explicitly with `P-1`
+rather than being what a truncated or mistyped line does. A `G28.2` with no
+`P` word is an error and stops the program.
+
+.G28.2 Example Lines
+[source,ngc]
+----
+G28.2 P-1   (home all joints, in HOME_SEQUENCE order)
+G28.2 P1    (home joint 1 only)
+----
+
+A queued `G28.2` dips motion into free mode for the duration of the homing
+cycle and restores whatever mode (manual/MDI/auto) was active once it
+finishes, so the mode dip is invisible at the task level. Motion still
+enforces its own safety: the home is honored only when the machine is idle
+(in position with no queued motion) or in joint mode, and a home is refused
+mid-motion. Homing inhibits and per-joint limit handling are unchanged.
+
+[NOTE]
+When the homing cycle finishes, the interpreter resyncs its model of the
+current position from the machine (the same way it does after probing or a
+tool change), so a following move made in incremental distance mode
+(`G91`), or an arc whose center is given with `I`/`J`/`K`, is computed from
+where the machine actually is after homing. `G28.2` is a queue point: read
+ahead stops at it and resumes once the cycle has run. `G5x`/`G92` offsets
+that were active before the `G28.2` are still applied afterward and now
+refer to the newly established machine zero; clear or re-establish them if
+that is not what you want.
+
+[NOTE]
+There is no G-code unhome. Clearing a joint's reference is done from the
+GUI, halui or linuxcncrsh.
+
+[NOTE]
+`G28.2` is a LinuxCNC extension; there is no standard Fanuc equivalent.
+
+It is an error if:
+
+* Cutter radius compensation is active (`G41`, `G41.1`, `G42` or `G42.1`).
+* An axis word is present ('G28.2' takes no axis words).
+* The 'P' word is missing.
+* The 'P' word is not a whole number, or is negative other than `P-1`.
+* The 'P' word names a joint number the machine does not have.
+
 [[gcode:g30-g30.1]]
 == G30, G30.1 Go/Set Predefined Position(((G30 Go/Set Predefined Position)))
 

docs/src/gcode/overview.adoc

@@ -960,7 +960,7 @@ 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, G52, G53, G92, G92.1, G92.2, G92.3,
+|Non-modal codes (Group 0)              | G4, G10 G28, G28.2, G30, G52, G53, G92, G92.1, G92.2, G92.3,
 |Motion (Group 1)                       | G0, G1, G2, G3, G33, G38.n, 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

docs/src/remap/remap.adoc

@@ -1851,7 +1851,7 @@ All the listed G-codes are already defined in the current implementation of Linu
 |25 |    |      |      |      |      |      |      |      |      | 
 |26 |    |      |      |      |      |      |      |      |      | 
 |27 |    |      |      |      |      |      |      |      |      | 
-|28 |G28 |G28.1 |      |      |      |      |      |      |      | 
+|28 |G28 |G28.1 |G28.2 |      |      |      |      |      |      |
 |29 |    |      |      |      |      |      |      |      |      | 
 |===
 

lib/python/common/hal_glib.py

@@ -287,7 +287,7 @@ class _GStat(GObject.GObject):
     STATE_ON = linuxcnc.STATE_ON
     STATE_OFF = linuxcnc.STATE_OFF
 
-    group0 = ('G4', 'G10','G28', 'G30', 'G52', 'G53', 'G92', 'G92.1', 'G92.2', 'G92.3')
+    group0 = ('G4', 'G10','G28', 'G28.2', 'G30', 'G52', 'G53', 'G92', 'G92.1', 'G92.2', 'G92.3')
     group1 = ('G0', 'G1', 'G2', 'G3', 'G33', 'G38.n', 'G73', 'G76', 'G80', 'G81',\
              'G82', 'G83', 'G84', 'G85', 'G86', 'G87', 'G88', 'G89')
     group2 = ('G17', 'G18', 'G19', 'G17.1', 'G18.1', 'G19.1')

lib/python/qtvcp/lib/mdi_text.py

@@ -27,6 +27,7 @@ def gcode_titles():
               'G21': 'Set Units to Millimeters',
               'G28': 'Go to Predefined Position',
               'G28.1': 'Set Predefined Position',
+              'G28.2': 'Home from G-code',
               'G30': 'Go to Predefined Position',
               'G30.1': 'Set Predefined Position',
               'G33': 'Spindle Synchronized Motion',
@@ -209,6 +210,7 @@ def gcode_descriptions(gcode):
                   'G21': G21,
                   'G28': G28,
                   'G28.1': G28_1,
+                  'G28.2': G28_2,
                   'G30': G30,
                   'G30.1': G30_1,
                   'G33': G33,
@@ -467,6 +469,29 @@ def gcode_descriptions(gcode):
 G28.1 - stores the current absolute position into
 parameters 5161-5166.
 """
+
+G28_2 = """G28.2 Home from G-code
+Runs the homing cycle, the same operation as the GUI
+Home All button, so a program or MDI line can
+reference the machine. Takes no axis words, and
+requires a P word saying what to home.
+
+G28.2 P-1 - homes all joints, in HOME_SEQUENCE order
+(the config must set HOME_SEQUENCE).
+
+G28.2 Pn - homes joint n only, where n is the
+0-based joint number matching its [JOINT_n] INI
+section. On a synchronized (negative HOME_SEQUENCE)
+joint pair, Pn on either joint homes both.
+
+There is no bare G28.2: homing the whole machine has
+to be asked for with P-1.
+
+It is an error if cutter compensation is on, if the P
+word is missing or is not -1 or a whole joint number,
+or if Pn names a joint the machine does not have.
+"""
+
 G30 = """G30 Go to Predefined Position
 G30 uses the values stored in parameters 5181-5189
 as the X Y Z A B C U V W final point to move to.

tests/interp/g28.2/flush-order/checkresult

@@ -0,0 +1,2 @@
+#!/bin/sh
+exit 0 # test failure is indicated by test.sh exit value

tests/interp/g28.2/flush-order/sim.tbl

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+
+"""
+Regression test for the flush_segments() ordering fix in HOME_CYCLE()/
+HOME_CYCLE()/HOME_CYCLE_JOINT()
+(emccanon.cc).
+
+STRAIGHT_FEED/STRAIGHT_TRAVERSE buffer points into chained_points for
+arc-blend lookahead and only reach interp_list on a flush (see
+see_segment()/flush_segments()). Without an explicit flush_segments() call
+at the start of the home canon functions, a queued move immediately
+before a G28.2 could silently get reordered to run *after* the home
+instead of before it.
+
+test.ngc queues "G1 X2" (a multi-cycle move, slow enough to poll mid-flight)
+immediately followed by "G28.2 P0". This script polls position and homed
+state throughout the run and asserts joint 0 never reports homed=1 before
+its position has actually reached the X2 target -- if the move were
+silently deferred to after the home (the bug), homed would flip true while
+position was still near its starting point.
+"""
+
+import linuxcnc
+import hal
+
+import sys
+import time
+
+h = hal.component("python-ui")
+h.ready()
+
+c = linuxcnc.command()
+s = linuxcnc.stat()
+
+
+def poll():
+    s.poll()
+
+
+def fail(msg):
+    print("FAIL: " + msg)
+    sys.exit(1)
+
+
+c.state(linuxcnc.STATE_ESTOP_RESET)
+c.state(linuxcnc.STATE_ON)
+c.mode(linuxcnc.MODE_AUTO)
+time.sleep(0.2)
+
+c.program_open("test.ngc")
+time.sleep(0.2)
+c.auto(linuxcnc.AUTO_RUN, 0)
+
+saw_position_near_target = False
+homed_while_short_of_target = None
+t0 = time.time()
+while time.time() - t0 < 10.0:
+    poll()
+    if s.position[0] > 1.9:
+        saw_position_near_target = True
+    if s.homed[0] and not saw_position_near_target:
+        homed_while_short_of_target = s.position[0]
+        break
+    if s.exec_state == linuxcnc.EXEC_DONE and s.interp_state == linuxcnc.INTERP_IDLE:
+        break
+    time.sleep(0.001)
+
+if homed_while_short_of_target is not None:
+    fail("joint 0 reported homed while X was still at {} (target 2.0) -- "
+         "the queued move was reordered to run after G28.2 P0".format(homed_while_short_of_target))
+
+if not saw_position_near_target:
+    fail("X never reached its target -- move did not run at all")
+
+t1 = time.time()
+while time.time() - t1 < 5.0:
+    poll()
+    if s.exec_state == linuxcnc.EXEC_DONE and s.interp_state == linuxcnc.INTERP_IDLE:
+        break
+    time.sleep(0.01)
+
+if not s.homed[0]:
+    fail("joint 0 never ended up homed")
+
+print("PASS: the queued move completed before G28.2 P0 homed the joint")
+print("done! it all worked")
+sys.exit(0)

tests/interp/g28.2/flush-order/test-ui.py

@@ -0,0 +1,99 @@
+[EMC]
+DEBUG = 0
+VERSION = 1.1
+
+[DISPLAY]
+DISPLAY = ./test-ui.py
+
+[TASK]
+TASK = milltask
+CYCLE_TIME = 0.001
+
+[RS274NGC]
+PARAMETER_FILE = sim.var
+
+[EMCMOT]
+EMCMOT = motmod
+COMM_TIMEOUT = 4.0
+BASE_PERIOD = 0
+SERVO_PERIOD = 1000000
+
+[HAL]
+HALUI = halui
+HALFILE = LIB:core_sim.hal
+
+[TRAJ]
+NO_FORCE_HOMING =       1
+AXES =                  3
+COORDINATES =           X Y Z
+HOME =                  0 0 0
+LINEAR_UNITS =          inch
+ANGULAR_UNITS =         degree
+DEFAULT_LINEAR_VELOCITY = 1.2
+MAX_LINEAR_VELOCITY =   4
+
+[KINS]
+JOINTS = 3
+KINEMATICS = trivkins
+
+[AXIS_X]
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+MIN_LIMIT =        -40.0
+MAX_LIMIT =        40.0
+
+[AXIS_Y]
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+MIN_LIMIT =        -40.0
+MAX_LIMIT =        40.0
+
+[AXIS_Z]
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+MIN_LIMIT =        -4.0
+MAX_LIMIT =        4.0
+
+[JOINT_0]
+TYPE =             LINEAR
+HOME =             0.000
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+BACKLASH =         0.000
+INPUT_SCALE =      4000
+OUTPUT_SCALE =     1.000
+MIN_LIMIT =        -40.0
+MAX_LIMIT =        40.0
+FERROR =           0.050
+MIN_FERROR =       0.010
+
+[JOINT_1]
+TYPE =             LINEAR
+HOME =             0.000
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+BACKLASH =         0.000
+INPUT_SCALE =      4000
+OUTPUT_SCALE =     1.000
+MIN_LIMIT =        -40.0
+MAX_LIMIT =        40.0
+FERROR =           0.050
+MIN_FERROR =       0.010
+
+[JOINT_2]
+TYPE =             LINEAR
+HOME =             0.0
+MAX_VELOCITY =     4
+MAX_ACCELERATION = 1000.0
+BACKLASH =         0.000
+INPUT_SCALE =      4000
+OUTPUT_SCALE =     1.000
+MIN_LIMIT =        -4.0
+MAX_LIMIT =        4.0
+FERROR =           0.050
+MIN_FERROR =       0.010
+
+[EMCIO]
+TOOL_CHANGE_QUILL_UP = 1
+RANDOM_TOOLCHANGER = 0
+TOOL_TABLE = sim.tbl