docs, tests: document and cover G28.2

Docs: new "G28.2 Home from G-code" section in g-code.adoc (syntax, the
HOME_SEQUENCE requirement for the bare form, 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.

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;
 - bare-home-sequence: the bare form as a first-home on a HOME_SEQUENCE
   config;
 - 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,73 @@ 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` and takes no axis
+words.
+
+* 'G28.2' - runs the homing cycle on every joint, in `HOME_SEQUENCE` order
+  (the same operation as the GUI *Home All*). The bare 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 the bare `G28.2` to home the shared group together;
+** no sequence, or a sequence not shared with any other joint, homes just
+   joint 'n'.
+--
+
+.G28.2 Example Lines
+[source,ngc]
+----
+G28.2       (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 negative or is not a whole number.
+* 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,24 @@ 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.
+
+G28.2 - 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.
+
+It is an error if cutter compensation is on, 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/bare-home-sequence/checkresult

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

tests/interp/g28.2/bare-home-sequence/sim.tbl

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+
+"""
+Bare G28.2 (no P word) on a config that sets HOME_SEQUENCE.
+
+The other tests here only exercise G28.2 Pn. Bare G28.2 goes through a
+different motion path -- do_home_joint(-1) -> do_home_all() -> the
+HOME_SEQUENCE state machine -- and needs HOME_SEQUENCE set, exactly like
+the GUI Home All button. This config has three single-joint sequence
+groups (0, 1, 2).
+
+Checks:
+ 1. Bare G28.2 issued from MDI homes every joint and completes without a
+    task error.
+ 2. The task-level mode is not disturbed by the FREE-mode dip.
+ 3. Homing walks the sequence groups in order (joint 0, then 1, then 2) --
+    and the completion poll does not trip on the gap between groups, where
+    all per-joint .homing flags read false while the machine is still
+    homing. A false "did not complete" would abort the MDI command and
+    leave the machine unhomed in FREE.
+ 4. Bare G28.2 from a program (AUTO) works the same way.
+"""
+
+import linuxcnc
+import hal
+
+import sys
+import time
+
+h = hal.component("python-ui")
+h.ready()
+
+c = linuxcnc.command()
+s = linuxcnc.stat()
+e = linuxcnc.error_channel()
+
+
+def poll():
+    s.poll()
+
+
+def fail(msg):
+    print("FAIL: " + msg)
+    sys.exit(1)
+
+
+def drain_errors():
+    msgs = []
+    while True:
+        err = e.poll()
+        if not err:
+            return msgs
+        msgs.append(err[1])
+
+
+def wait_idle(timeout=15.0):
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        poll()
+        if s.exec_state == linuxcnc.EXEC_DONE and s.interp_state == linuxcnc.INTERP_IDLE:
+            return True
+        time.sleep(0.01)
+    return False
+
+
+def wait_homed(expected, timeout=15.0):
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        poll()
+        if list(s.homed[:3]) == expected:
+            return True
+        time.sleep(0.01)
+    return False
+
+
+c.state(linuxcnc.STATE_ESTOP_RESET)
+c.state(linuxcnc.STATE_ON)
+poll()
+if list(s.homed[:3]) != [0, 0, 0]:
+    fail("machine came up homed: {}".format(list(s.homed[:3])))
+
+c.mode(linuxcnc.MODE_MDI)
+time.sleep(0.2)
+poll()
+mode_before = s.task_mode
+drain_errors()
+
+# --- 1: bare G28.2 from MDI homes everything -------------------------------
+c.mdi("G28.2")
+
+# Watch the homed flags flip on in sequence order while the cycle runs.
+order = []
+t0 = time.time()
+while time.time() - t0 < 15.0:
+    poll()
+    for j in range(3):
+        if s.homed[j] and j not in order:
+            order.append(j)
+    if list(s.homed[:3]) == [1, 1, 1]:
+        break
+    time.sleep(0.005)
+
+if list(s.homed[:3]) != [1, 1, 1]:
+    fail("bare G28.2 did not home all joints: homed={}".format(list(s.homed[:3])))
+if order != [0, 1, 2]:
+    fail("joints did not home in HOME_SEQUENCE order: saw {}".format(order))
+
+if not wait_idle():
+    fail("bare G28.2 (MDI) did not return to idle/DONE")
+
+errs = drain_errors()
+if any("did not complete" in m or "did not start" in m for m in errs):
+    fail("bare G28.2 reported a spurious homing failure: {!r}".format(errs))
+poll()
+if s.exec_state == linuxcnc.EXEC_ERROR:
+    fail("bare G28.2 left task in EXEC_ERROR (errors={!r})".format(errs))
+if s.task_mode != mode_before:
+    fail("task_mode changed across bare G28.2: {} -> {}".format(mode_before, s.task_mode))
+print("PASS: bare G28.2 from MDI homes every joint in sequence order, mode untouched")
+
+# --- 2: and again from a program -----------------------------------------
+c.mode(linuxcnc.MODE_MANUAL)
+c.teleop_enable(0)          # to joint mode, so the unhome is allowed
+time.sleep(0.3)
+c.unhome(-1)
+if not wait_homed([0, 0, 0]):
+    fail("could not unhome for the AUTO re-test: {}".format(list(s.homed[:3])))
+
+c.mode(linuxcnc.MODE_AUTO)
+time.sleep(0.2)
+c.program_open("test.ngc")
+time.sleep(0.2)
+drain_errors()
+c.auto(linuxcnc.AUTO_RUN, 0)
+
+if not wait_homed([1, 1, 1]):
+    fail("bare G28.2 from a program did not home all joints: {}".format(list(s.homed[:3])))
+if not wait_idle():
+    fail("program with bare G28.2 did not finish")
+errs = drain_errors()
+if errs:
+    fail("program with bare G28.2 raised errors: {!r}".format(errs))
+print("PASS: bare G28.2 from a program homes every joint")
+
+print("done! it all worked")
+sys.exit(0)