G28.2: home the machine from G-code (all joints, or Pn per joint)

[greatEndian]

G28.2 — home the machine from G-code

Lets a program or MDI line reference the machine, instead of requiring the
operator to press Home All in the GUI.

A P word is mandatory and says what to home:

• G28.2 P-1 — run the homing cycle on all joints, in HOME_SEQUENCE
  order (the same operation as the GUI's Home All, and like Home All it
  needs HOME_SEQUENCE set)
• G28.2 Pn — run the homing cycle on joint n only, where n is the
  0-based joint number matching its [JOINT_n] INI section
• G28.2 alone — an error. 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 rather than
  being what a truncated or mistyped line does (@BsAtHome). It is refused
  rather than ignored, so it cannot be mistaken for a cycle that ran.

P-2 (the volatile-unhome sentinel EMC_JOINT_HOME carries for the GUI,
halui and linuxcncrsh), any other negative, and fractional values are
refused too: -1 is G-code surface, -2 is not.

G28.2 is non-modal (modal group 0), following the existing G28.1 /
G30.1 pattern. It is a LinuxCNC extension; there is no standard Fanuc
equivalent.

What it's for

• Unattended / scripted power-up — a program or an automation layer can
  reference the machine without a human at the GUI.
• Re-homing a joint mid-program — @Sigma1912's case in the discussion
  below: a joint switched between rotary-axis and spindle use, whose
  reference is no longer valid once it has run as a spindle. G28.2 Pn
  re-establishes it in place, which also avoids the workaround that
  issue Connecting joint.n.index-enable to spindle.n.index-enable breaks spindle-synchronized motion #3556 currently forces.
• Operators who would rather type a reference command than click one.

Pn details

The joint index rides the joint field that EMC_JOINT_HOME already
carries, so this needs no NML change and no motion change, and behaves
identically on any kinematics.

How many joints Pn actually homes depends on joint n's HOME_SEQUENCE:

• a negative (synchronized) sequence homes the whole synchronized group
  — Pn on either joint of a gantry pair homes both (motion's existing
  gantry behavior);
• 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.

Pn is range-checked in task against the machine's configured joint count,
and an out-of-range number is refused before anything else happens:

Cannot home invalid joint 5 (this machine has joints 0..4; P-1 homes every joint)

There is deliberately no axis-letter form (G28.2 X): resolving an axis
letter to a joint needs the kinematics coordinate map and is ambiguous even
on trivkins (duplicate letters on gantries), and as @andypugh noted, homing
is a joint concept rather than an axis one. An axis word with G28.2 is an
error.

How it works

1. interp convert_home_cycle() emits the canon op HOME_CYCLE(), or
   HOME_CYCLE_JOINT(n) when a P word is present.
2. canon flushes queued segments and appends EMC_JOINT_HOME with the
   joint number (-1 for all).
3. task executes it in program order and waits for the cycle to finish
   before letting the program continue.
4. interp then resyncs its model of the current position from the machine
   (see Position model below) and read-ahead resumes.

Homing only advances while motion is in FREE mode (do_homing() is called
from there), so a home queued from a program or MDI running in TELEOP/COORD
would otherwise stall silently. Task dips motion into FREE for the duration
and restores the previous trajectory mode when the cycle completes —
invisibly to the task-level MANUAL/MDI/AUTO state.

Three details of that sequencing are worth calling out for review:

• Completion is tested against motion's aggregate homing_active, not
  against an OR of the per-joint .homing flags. On a machine that homes in
  several HOME_SEQUENCE groups, the sequence machine finishes one group and
  can spend a cycle or more before the next raises .homing, so there is a
  window where every joint reads .homing == false while the machine is
  still homing. Task samples far coarser than the servo cycle and can land in
  it. motion/homing.c documents the same deassertion lag in its own words.
  This is what the new homing_active status field is for.
• The mode restore is gated on all_homed() for non-identity
  kinematics, mirroring the condition motion itself applies in
  switch_to_teleop_mode() and the EMCMOT_COORD case. Restoring
  unconditionally would have task report DONE while motion refused the
  transition, leaving the machine in FREE with the GUI's mode controls dead.
• The sequencing is scoped to the queued path only. Immediate homes —
  the GUI Home button, halui, linuxcncrsh — pass straight through exactly
  as before, since nothing calls emcTaskCheckPostconditions() for them and
  a mode dip taken there would never be undone.

Position model

When the cycle finishes, the interpreter resyncs current_* from the
machine — the same mechanism it uses after probing or a tool change: a
home_flag makes execute_block() return INTERP_EXECUTE_FINISH (so G28.2
is a read-ahead barrier), and read_inputs() then calls
refresh_actual_position(). No synch() — no tool-table reload, no
parameter-file rewrite.

This matters because an immediate (index/switchless) home rewrites the
joint's coordinate to HOME_OFFSET even when nothing physically moves
(HOME_SET_INDEX_POSITION). Without the resync a following G91 move, or an
arc centre given with I/J/K, is computed from the stale pre-home point;
on a wrapped rotary head re-homed mid-program with G28.2 Pn — the headline
use case — the axis would then sweep the whole error. (Raised in review.)

G5x / G92 offsets that were active before the G28.2 stay applied
afterward and now refer to the newly established machine zero — documented,
not silently changed.

Supporting fixes

Both are needed for a queued home to reach motion at all:

• task: EMC_JOINT_HOME_TYPE was missing from
  emcTaskCheckPreconditions(), so a queued home hit the default case and
  was silently dropped before ever reaching motion. It now returns
  WAITING_FOR_MOTION (drain prior motion, then home).
• motion: homing required motion_state == FREE. It is now also
  permitted when motion is in position with an empty queue and a FREE
  transition is already pending (!teleoperating && !coordinating) — the
  transient state the queued G28.2 dip passes through. An immediate home
  from TELEOP/COORD is still refused with must be in joint mode to home,
  exactly as before this PR (this was tightened after review found the first
  version also silently accepted an immediate c.home(n) / halui /
  linuxcncrsh home on an already-homed machine).

Also included: homing_active added to emcmot_status_t and
EMC_MOTION_STAT (with its constructor initializer and NML serializer
entry), and a new EMC_TASK_EXEC::WAITING_FOR_HOMING state.

Documentation

G28.2 is added to the quick-reference index (gcode.html.in), the
modal-group table and the allocated-G-codes table, the qtvcp MDI help, and
hal_glib's modal-group map, plus its own section in g-code.adoc covering
the syntax, why the P word is mandatory, the HOME_SEQUENCE requirement
for P-1, the
negative/positive shared-sequence Pn cases, the mode-dip and
position-resync behaviour, and an error list matched to the interpreter.

Deliberately not in this PR

• G28.3 (unhome) was dropped after review. No reviewer could name a use
  a numbered parameter would not serve better under NO_FORCE_HOMING=1, and
  it was the only operation here able to leave a running program on an
  unreferenced machine. Unhoming remains available from the GUI, halui and
  linuxcncrsh.
• [RS274NGC]GCODE_HOMING=1 (plain G28 references the machine first)
  was split out and will be proposed separately. It needs real-machine
  validation of the home-then-coordinated-return sequence that sim cannot
  fully exercise.

Testing

Seven test cases under tests/interp/g28.2/: joint-pword, sequencing,
flush-order, invalid-pword, immediate-mode-guard, home-all-sequence,
position-model.

• home-all-sequence — G28.2 P-1 (first-home and from a program) on a
  config with three HOME_SEQUENCE groups; homes every joint in order, no
  spurious group-gap failure. A bare G28.2 is refused and homes nothing.

• invalid-pword — the rest of the P surface: an unconfigured joint
  number, P-2, another negative, a fraction and the bare form are each
  refused up front, each name P-1, and leave the homed state and the
  trajectory mode untouched.

• immediate-mode-guard — an immediate home/unhome from teleop is refused
  with the mode untouched (regression test for the idle-home tightening).

• position-model — a G91 move (rotary C and linear X) after G28.2 Pn
  is computed from the homed position; fails without the resync (lands at
  stale + increment).

• tests/interp/g28.2: 7/7. tests/interp 98/98, tests/motion-logger,
  tests/motion, tests/abort and tests/remap: green. cppcheck clean.
  Every one of the 5 commits builds with --enable-werror.

• Real hardware (@Sigma1912, Mesa 7I95T, gantry): g28.2 (now spelled
  g28.2 p-1) homes all
  joints; g28.2 p0 homes the gantry pair; g28.2 p4 homes the named joint;
  and a program of the form g0 x100 / g01 a-5 / g28.2 p0 / g01 x50 runs the
  first moves, re-homes the gantry, then completes — all correct. (Run
  against an earlier revision; a re-run against the current branch is
  welcome.)

Credits

Thanks to everyone who reviewed earlier revisions and took this to real
hardware — the Pn per-joint form, the G28.3 removal, the joint-vs-axis
decision and the position-model fix all came out of that feedback.

[Sigma1912]

Would it be possible to add a parameter for homing individual joints?

Example:

{G28.2, G28.3} P1 to home/ unhome joint 1

This would be very useful for configurations with joints that switch between rotary and spindle use. It would also circumvent #3556 that complicates the current way of 'rehoming'

[greatEndian]

Home individual axis-

G28.2XC will force home axis X and C ...
G28.3YZ will force unhome axis YZ ...

for non trivial kinematics we need to start discussion how to handle it per joint..

[Sigma1912]

What happens if we try to run a program in unhomed state ( will that trigger an interpreter error?):

Example 1 :

G28.3
G1 x2

How are these commands handled when used inside a gcode program? (I presume it is like a queue buster command that halts the read ahead until all queued command have been executed) :

Example 2 :

G1 x1
G28.3
G28.2
G1 x2

[greatEndian]

Example 1 :
force unhome
if NO_FORCE_HOMING==1 program run
else message to home again

Example 2 :
program run
force unhome
force home
program run

[Sigma1912]

for non trivial kinematics we need to start discussion how to handle it per joint..

Using axes is probably enough for the majority of use cases and most machine operators would likely not even know about the joint-axis mappings on their particular machines.
However, it might be useful for more exotic configurations (eg for homing/unhoming extra joints that do not have axis letters assigned).
It seems an easy enough addition to introduce an optional parameter word with the joint number (but I might be wrong about that) ;)

[grandixximo]

I think the cleanest direction is to keep the G-code surface dead simple and put the real effort into execution. For per-joint homing, Sigma's Pn is the right primitive: the joint index rides the field that EMC_JOINT_HOME already carries, so G28.2 P1 needs no NML or motion change and behaves the same on any kinematics. Bare G28.2 stays home-all. Gantries need no extra word since Pn reuses the existing single-joint homing behavior, but that's worth a doc note: on a synchronized (negative HOME_SEQUENCE) pair, homing either joint brings its partner, while on a positive shared sequence Pn homes only the named joint and you'd use bare G28.2 to do both. I'd leave the axis-letter form (G28.2 X) out for now, since resolving axis letters to joints needs the kinematics coordinates map and isn't actually trivial even on trivkins (duplicate letters for gantries), so it's better as its own later piece.

The part that really needs rethinking isn't the syntax, it's how a queued home executes. Homing only runs in free mode, and nothing currently flips the machine into free for a G-code-triggered home, so just relaxing the motion guard means the command can silently stall in teleop. It needs to be sequenced in task: drain motion, switch to free, home, wait for it to actually finish, then restore the prior mode. And if homing fails, the program has to abort rather than carry on unreferenced. A nice consequence is the trivkins question answers itself: home-all works everywhere, but a partial home can only resume coordinated motion on identity kinematics, because non-trivkins won't re-enter teleop until everything's homed.

There's also the unhome-then-keep-running hole Sigma raised. The existing force-homing check only fires at program start, so G28.3 mid-program followed by a move slips through. Rather than checking every move, we re-apply that same NO_FORCE_HOMING gate at the home/unhome sync point the command already forces, so it's governed by exactly the same policy as starting a program, with no cost on the motion path.

Given all that, I'd split it: land the explicit G28.2/G28.3 (with Pn) first, and hold GCODE_HOMING plain-G28, which adds the home-then-return move on top, until it's been signed off on real hardware.

[andypugh]

"Homing" is 100% a Joint thing, not an axis thing, so I don't think that I support the G28.2 X C style.
(Also, it is a break in G-code syntax to use an axis letter without a number, I think?)

Using P1 to home a single joint seems reasonable to me. The command can be repeated to home another joint.

However, is is already possible to home through the linuxcncrsh and similar interfaces, so I am not entirely sure there is a use-case for this.

One for discussion at a developer meeting, I think.

[Sigma1912]

However, is is already possible to home through the linuxcncrsh and similar interfaces, so I am not entirely sure there is a use-case for this.

As I pointed out above, one use case is the rehoming of joints that are switched between rotary and spindle modes. This needs to be done inside a gcode program and currently requires a rather complex hal setup plus a workaround for #3556 (which is a serious bug)

[grandixximo]

Big step in the right direction. The free-mode dip and restore, failure-abort-leave-in-FREE, the HOME/UNHOME asymmetry, the flush_segments ordering fix and the out-of-range Pn fix are all solid.

Main concern is the HOME completion check. You infer "homing stopped" from the per-joint .homing OR going false, then test all_target_homed. On a machine that homes in separate HOME_SEQUENCE steps, the sequence machine finishes one group and spends a cycle or more before the next group sets .homing, so there is a window where every joint reads .homing == false while not yet fully homed. Task samples coarser than the servo cycle, lands in that gap, and aborts a good home-all with "did not complete". Single-joint Pn and all-in-one-sequence are fine; multi-sequence home-all (bare G28.2 and GCODE_HOMING plain-G28) is exposed. The clean fix is the aggregate signal that already exists in RT, get_homing_is_active() / homing_active (homing.c), plumbed into status, rather than edge-detecting the per-joint OR.

Non-trivkins teleop restore: success and restore are gated on the target joint, not all_homed(). On non-identity kins switch_to_teleop_mode() refuses unless the whole machine is homed, so a Pn home that succeeds for its joint while the machine is not fully homed (e.g. after an earlier G28.3 Pk) leaves motion silently stuck in FREE while task marks it DONE and runs the next line, and the coordinated move then has no valid frame. Gate the teleop restore on all_homed() for non-identity kins (or verify the mode took) and abort if it can't.

Two smaller ones. The sequencing now wraps every EMC_JOINT_HOME/UNHOME, including GUI Home-All and unhome, so those hit the same path and race; worth scoping to the queued path. And the UNHOME success test (!any_target_homed over all joints) mis-scores a volatile unhome (joint == -2), which leaves non-volatile joints homed; G28.3 never sends -2 but this path now catches all unhomes, so guard it.

Last, GCODE_HOMING plain-G28 is still bundled and rides the same multi-sequence home-all path, on sim-only validation. I'd land the explicit G28.2/G28.3 (with Pn) first and hold plain-G28 until it has a hardware sign-off.

[grandixximo]

@Sigma1912 on GCODE_HOMING plain-G28 specifically, the one part still lacking real-machine validation is the home-then-return sequence (home-all, cross into teleop, then the coordinated return move), which sim can't fully exercise. Since this is your use case, are you able to test it on real hardware, or do you know someone who can? That would let us keep it in rather than defer it.

[Sigma1912]

a plain G28 references the machine first, before its normal return move, only when the machine is not already fully homed

How is this supposed to work as I cannot possibly command G28 from either MDI or Program when not fully homed?

1. test with real hardware (Mesa 7I95T):
   Machine homed, MDI g28.2 -> correctly homes all joints
   Machine homed, MDI g28.2 p0 -> correctly homes joints 0 and 1 in my gantry setup
   Machine homed, MDI g28.2 p4 -> correctly homes joint 4

This seems to work !

2. test with real hardware (Mesa 7I95T):
   Machine homed, MDI g28.3 p0 -> joint_0 is unhomed, error : all joints must be homed before going into coordinated mode
   Manual Control tab shows joints and Menu 'Machine' . 'Homing', 'Unhoming', 'Zero Coordinate System' are grayed out.
   No further command is possible until the controller is switched off and on again (F2)

Not sure if this is the intended behavior but I don't quite see an application for this.

Just so we are on the same page, I cloned and built the 'g28' branch, git log --minimal shows this (which seems current):

[Sigma1912]

Tried this gcode:

g0 x10
g28.3 p2
g28 x160
g0 x100
m2

with [RS274NGC] GCODE_HOMING = 1

Machine moves to X10, then rehomes all joints and exits:

all joints must be homed before going into coordinated mode
USRMOT: ERROR: invalid command
need to be enabled, in coord mode for linear move

[grandixximo]

I think, as far as I understand the code, in the INI file if you set

[RS274NGC]
GCODE_HOMING=1

You should be able to actually run a gcode that starts with G28

Edit:
Cross posted, then seems like possibly the race I spotted, or another race maybe hitting.

[grandixximo]

Correction to my last note: on a closer read it isn't the race I flagged. The race would print "G28.2 home did not complete", and none of Sigma's errors say that. His failures are all mode errors, so this is the other finding, the non-trivkins mode-restore gap.

The tell is all joints must be homed before going into coordinated mode, which only fires from motion's COORD guard on non-identity kinematics, so the gantry trips it. g28.3 p0 unhomes one joint, the machine is no longer fully homed, and on success the code restores the prior COORD/TELEOP mode gated on the target joint rather than all_homed(). On non-identity kins the restore is refused, with no recovery, hence the F2 wedge. Test 3 is the same bug cascading: the g28.3 p2 breaks the mode state, then g28 home-all can't re-enter coord, so the return and the following g0 fail with "need to be enabled, in coord mode".

Fix: after a (un)home that leaves the machine not fully homed, don't restore a coordinated mode. Leave it in FREE and abort with a clear error instead of wedging.

And Sigma's opening point is the real one for GCODE_HOMING: with NO_FORCE_HOMING=0 you can't start a program unhomed, so a homed machine's G28 is just the pure return; the home-first branch is only reachable by unhoming mid-program, which is exactly the path that breaks here. I'd land explicit G28.2/G28.3 (with Pn) now and drop GCODE_HOMING plain-G28.

[Sigma1912]

I'd land explicit G28.2/G28.3 (with Pn) now

Given that G28.2 (Pn) can be called without the need to unhome first what is the intended use case for G28.3 (Pn)?

[grandixximo]

I guess that's for @greatEndian to answer, I've been thinking about it, unless it's about compatibility with something out of tree that only supports G28.3 in combination with G28.2 I don't see a good argument to keep it either...

[grandixximo]

@greatEndian please can you have another look at the questions here and illuminate with some answers?

[greatEndian]

@Sigma1912 @grandixximo @andypugh thanks for the real-hardware run..

@Sigma1912 — that was worth more than the sim work. Both failures you hit are real bugs, and I can name both. Answers in order.

1. What is G28.3 Pn actually for?

It is not a precursor to G28.2 — you are right that homing does not need it. It is a way to declare "this joint's reference is no longer physically valid".

Your own case is the clearest one: a joint that switches between rotary-axis and spindle use. While it runs as a spindle, the homed flag is a lie — the encoder count no longer corresponds to a known machine position, but nothing in the controller knows that. G28.3 Pn marks it unreferenced, and with NO_FORCE_HOMING=0 the machine then refuses further coordinated motion until G28.2 Pn re-references it. The same applies to anything that invalidates a reference without moving the joint through a normal cycle: a decoupled indexer, a released brake or clutch, a re-gripped chuck.

So the pair is: G28.3 Pn = "stop trusting this joint", G28.2 Pn = "trust it again". If that argument does not convince you, I have no objection to landing G28.2 Pn alone and dropping G28.3 — it is the weaker half.

2. The F2 wedge (your tests 2 and 3) — confirmed bug

@grandixximo's second diagnosis is correct, it is the mode-restore gap and not the completion race. On success the code restores the prior trajectory mode gated on the target joint only:

} else if (success) {
emcStatus->task.execState = EMC_TASK_EXEC::DONE;
if (homingPriorMode != EMC_TRAJ_MODE::FREE) {
emcTrajSetMode(homingPriorMode); // <-- not gated on all_homed()
}
}

On your gantry (non-identity kinematics) switch_to_teleop_mode() refuses unless the whole machine is homed, so after g28.3 p0 the restore is rejected by motion — that is your all joints must be homed before going into coordinated mode — task still marks the command DONE, and nothing recovers the mode. Hence the grayed-out controls and the F2. Test 3 is the same bug cascading: the mode state is already broken before g28 runs.

Fix: never restore a coordinated mode when the machine is not fully homed. Leave motion in FREE and abort with a clear operator error instead of wedging. I will also verify the mode actually took rather than assuming emcTrajSetMode() succeeded.

3. The home-completion race — confirmed, and upstream documents it

Accepted. Inferring "homing stopped" from the per-joint .homing OR is unsafe, and homing.c says so itself at line 546:

"The homing status variable turns false before homing_active state turns false. This means that a new homing command on a joint might fail due to the homing state machine being active while all joints already are in the 'not homing' state."

That is exactly the window my poll can land in on a multi-HOME_SEQUENCE home-all, producing a spurious "did not complete" abort on a perfectly good home. Single-joint Pn and single-sequence machines are not exposed, which is why the sim tests and Sigma's test 1 passed.

Fix as you suggested: use the aggregate get_homing_is_active() (homing.h:65), plumbed through emcmot status into emcStatus, instead of edge-detecting the per-joint OR. It is not currently in NML status, so that is a small status-field addition.

4. Volatile unhome and GUI scoping — both accepteddesign leaves non-volatile joints homed and would be reported as a failure. G28.3 never sends -2, but since this path now catches every unhome it needs the guard.

• The sequencing currently intercepts EMC_JOINT_HOME_TYPE / EMC_JOINT_UNHOME_TYPE unconditionally in emcTaskIssueCommand, so GUI Home-All and Unhome ride the same mode-dip path. That was not intended — I will scope it to the queued/program-order path.

5. GCODE_HOMING plain-G28 — I agree, drop it from this PR

@Sigma1912's opening question settles it. With NO_FORCE_HOMING=0 a program cannot start unhomed, so on a homed machine G28 is just the ordinary return move and the home-first branch is unreachable. The only way to reach it is to unhome mid-program — which is precisely the path that broke on your machine. A feature whose only reachable path is the broken one does not belong in this PR.

It is interleaved with the Pn work in 3d238db and touches ~15 files, so this is a rebase rather than a revert, but it is the right split: land explicit G28.2 / G28.3 (with Pn), hold plain-G28 for its own PR with hardware sign-off.

6. Axis letters

@andypugh — already dropped. The implemented form is Pn only, for the reasons you and @grandixximo both gave: homing is a joint concept, and an axis letter without a number is a syntax break. There is no G28.2 X C in the branch. Happy to have it on a developer-meeting agenda.

Next push

1. homing_active into status, replace the completion check
2. Gate mode restore on all_homed(), abort-in-FREE instead of wedging
3. Guard the volatile-unhome scoring
4. Scope sequencing to the queued path
5. Separate out GCODE_HOMING

@Sigma1912, if you are willing to re-run tests 2 and 3 after that push, that closes the loop on the part sim cannot reach.

Best regards

[Sigma1912]

So the pair is: G28.3 Pn = "stop trusting this joint", G28.2 Pn = "trust it again". If that argument does not convince you, I have no objection to landing G28.2 Pn alone and dropping G28.3 — it is the weaker half.

I'm just having trouble seeing the actual use case in a program. If I reach a state in the program execution where I 'don't trust' a joint would I not just simply use G28.2 to home it?
If there is anything that impedes it from homing then the homing process will fail anyway.
If I switch a rotary from spindle mode to rotary mode, why would I use G28.3 to unhome it from the program just to have to home it from the gui when I could use G28.2 instead and just be done?

TESTRESULTS:

1. test with real hardware (Mesa 7I95T):
   Machine homed, MDI g28.2 -> correctly homes all joints
   Machine homed, MDI g28.2 p0 -> correctly homes joints 0 and 1 in my gantry setup
   Machine homed, MDI g28.2 p4 -> correctly homes joint 4

However it doesn't like when an unconfigured joint number is requested:
Machine homed, MDI g28.2 p5 ->Gui goes into joint mode and shows error :

 G28.2 home did not start -- check machine mode, motion.homing-inhibit, and whether a homing cycle is already in progress

Jogging is now in joint mode but recovers on next gcode execution (either MDI command or program start). That is a bug

2. test with real hardware (Mesa 7I95T):
   Machine homed, MDI g28.3 p0 -> error message:

 G28.3 unhome succeeded but left the machine not fully homed -- staying in joint mode, as non-identity kinematics cannot re-enter coordinated motion until every joint is homed

3. test with real hardware (Mesa 7I95T):
   Running gcode program:

g0 x100
g01 a-5 f1000
g28.2 p0
g01 x50 f500
m2

Runs as expected. executes the first two lines then rehomes x gantry and executes the last move.

Conclusion:

• G28.2 needs to check if an unconfigured joint is requested.
• G28.3 still not sure what to think about a gcode that ejects the controller into a state that requires the user to rehome through the gui. Other opinions?

[grandixximo]

The only way I find G28.3 having a use case, is when these codes live in some conditionals that depend on external output, and IMO you must have NO_FORCE_HOMING = 1 for G28.3 to make sense at all, and they can be easily replaced by simple flags like #<_axis_n_is_unreferenced> = 1 and that would be valid and easy to use with or without NO_FORCE_HOMING.
Also in an earlier sentence you wrote g28.3 is not a precursor to G28.2, and in the following example you propose, it is exactly that.
No real argument to keep it, I'm also for removing it, unless a real use case is proposed.

[BsAtHome]

For safety reasons, can we make G28.2 do nothing without a P value? And use P-1 for home all.

[greatEndian]

@BsAtHome agreed, and it is done on the branch (7380a1ef26). The P word is
now mandatory:

G28.2 P-1   home every joint, in HOME_SEQUENCE order
G28.2 P1    home joint 1 only
G28.2       error

One deliberate reading of "do nothing": the bare form is refused, not
silently ignored —

G28.2 requires a P word: P-1 homes every joint, or P0, P1, ... home one joint by its number

A quiet no-op would be indistinguishable from a homing cycle that ran, and the
operator would go on to cut against a reference that was never re-established.
The error stops the program at that line and names the spelling that does what
was meant. If you would rather it be literally silent, say so and I will change
it — but I think refusing is the safer half of "do nothing".

Everything else negative stays refused: P-2 (the volatile-unhome sentinel
EMC_JOINT_HOME carries for the GUI, halui and linuxcncrsh), any other
negative, and fractions. -1 is now G-code surface; -2 is not, and should not
become it by way of the P word.

Two knock-on fixes that would otherwise have contradicted the new rule:

• the task-level range error used to read "omit the joint to home them all", and
  now reads Cannot home invalid joint 5 (this machine has joints 0..4; P-1 homes every joint);
• the qtvcp MDI help (mdi_text.py) taught the bare form, and now teaches
  P-1.

Docs updated to match, including the error list. Nothing in the homing path,
the mode dip or the completion test changed — this is command surface only.

Tests: tests/interp/g28.2/bare-home-sequence is now home-all-sequence
(P-1 walks the HOME_SEQUENCE groups; a bare G28.2 is refused and homes
nothing), and invalid-pword covers the rest of the surface — an unconfigured
joint number, P-2, another negative, a fraction and the bare form: each
refused up front, each naming P-1, with the homed state and the trajectory
mode untouched. 7/7 in tests/interp/g28.2, 90/90 in tests/interp, cppcheck
clean.

@Sigma1912 this changes the spelling you ran on the 7I95T: g28.2 becomes
g28.2 p-1, while your p0 and p4 lines are unchanged. If you get a chance
to re-run those, I would appreciate it. It also lands where you pointed in
August — you proposed P-1 for home-all first.

@grandixximo your approval predates this, so it needs another look.

[grandixximo]

it conflicts due to recent changes, please rebase, sorry...