G28 with features

[greatEndian]

G-code machine homing: G28.2 / G28.3 and optional GCODE_HOMING for plain G28

What this is

Adds the ability to reference (home) a machine from G-code, instead of
only from the GUI, in three small, opt-in pieces:

• G28.2 — run the homing cycle on all joints (in HOME_SEQUENCE order)
• G28.3 — unhome all joints
• [RS274NGC]GCODE_HOMING=1 (INI opt-in) — a plain G28 references the
  machine first, before its normal return move, only when the machine is
  not already fully homed

Plus two small fixes that make a queued (in-program / MDI) home actually
reach motion (see below).

G28.2 / G28.3 are non-modal (modal group 0) codes, following the
existing G28.1 / G30.1 pattern. Bare form — axis words are ignored; they
act on all joints.

What it's for

• Unattended / scripted power-up — a program or MDI line can reference
  the machine, so an operator (or an automation layer) doesn't have to open
  the GUI and click Home All.
• Operators who prefer a typed reference command over the GUI.
• GCODE_HOMING=1 lets you put a plain G28 at the top of a program: on a
  cold machine it homes first, then returns; on an already-homed machine it
  is a pure return move and costs nothing.

Relation to industrial-standard G28

• Plain G28 return-to-reference behavior is unchanged and still matches
  the Fanuc/Haas convention: go to the machine reference point through the
  intermediate point given by the axis words.
• GCODE_HOMING=1 makes the first G28 after power-up also establish
  the reference (run the homing cycle), which mirrors how a Fanuc-style
  control without absolute encoders performs its zero-return/reference on a
  G28. Once referenced, subsequent G28s are pure returns, exactly as on
  those controls.
• G28.2 / G28.3 (explicit home / unhome) are LinuxCNC extensions — there
  is no standard Fanuc equivalent — kept in the spirit of the existing
  G28.1 / G30.1 reference-point codes.

[RS274NGC]GCODE_HOMING=1 — behavior

Situation	Plain G28 does
Flag absent / =0 (default)	Stock LinuxCNC G28 (return only)
=1, machine not fully homed	Home all joints, then the G28 return
=1, machine fully homed	Pure return (no homing)
=1, G30 / G28.2 / G28.3	Unchanged (flag is G28-only)

Default-off is bit-identical to stock: the homing call is only emitted under
FEATURE(GCODE_HOMING) for G_28.

How it works (single channel)

1. interp convert_home: under FEATURE_GCODE_HOMING and move == G_28,
   emit a new canon op HOME_CYCLE_IF_UNHOMED() before the waypoint /
   return moves (so it completes while joint positions are still unknown).
2. canon queues EMC_JOINT_HOME carrying an EMC_HOME_ALL_IF_UNHOMED
   (-3) sentinel in its existing joint field.
3. task resolves the sentinel at execution time: if all_homed(), drop the
   home (queued return alone = legacy G28); otherwise issue the normal
   home-all (emcJointHome(-1)) — the same path G28.2 and the GUI Home
   All already use.

The sentinel mechanism itself adds no new message field and no NML-layout
change, and touches neither homing.c nor the motion command path — it
resolves entirely in task by reusing the existing joint field with a
reserved value. (The small command.c idle-homing fix below is a separate
prerequisite, shared with G28.2.)

Supporting fixes (also needed for G28.2)

• task: EMC_JOINT_HOME_TYPE / EMC_JOINT_UNHOME_TYPE were missing from
  emcTaskCheckPreconditions(), so a queued home/unhome hit the default
  case and was silently dropped before reaching motion. They now return
  WAITING_FOR_MOTION (drain prior motion, then home).
• motion: single-channel homing required motion_state == FREE; now it is
  also permitted when motion is otherwise idle (in position, queue empty), so
  a home issued from MDI or a program is honored. Refusing mid-motion still
  holds.

Testing

• Interpreter (rs274 -i): GCODE_HOMING=1 plain G28 emits
  HOME_CYCLE_IF_UNHOMED() ahead of the return traverse; G30 does not home;
  G28.2 homes unconditionally; default-off G28 emits no homing.
• Builds clean (interp / task / motion).
• On-machine homing sign-off (a real reference run triggered from MDI / a
  program) is pending and will be added.

Credits

Developed in collaboration with @grandixximo, with whom I discussed the requirements that
shaped this feature. Thanks for the design discussion and for driving the
real-world G28 / homing-from-G-code use case.

[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?