feat(rs274ngc): add ROTARY_MODULO axis mode

[grandixximo]

Summary

Continuous-modulo rotary mode for A/B/C axes. Absolute moves take shortest path, large literals (e.g. A=200000) accepted, position parameters wrapped to 0 up to but not including 360 degrees. Internal commanded position and motion-side HAL pins remain accumulated to keep stepgens, encoders and PID loops consistent across wrap, per @andypugh's note in #3902.

Closes #3902.

Behavior

• New INI flag [AXIS_<L>] ROTARY_MODULO = 1, mutex with WRAPPED_ROTARY
• Startup warn if MIN_LIMIT/MAX_LIMIT range is not ~360 deg
• find_ends shortest-delta target on G53 + absolute + relative paths
• #5423-#5425, #5064-#5066, #<_a/_b/_c>, #<_abs_a/b/c> wrapped on read
• G33 / G33.1 / G76 hard-error if modulo axis word appears in block
• Accumulated physical position reachable from G-code via #<_hal[joint.N.pos-fb]>

Out of scope

• Mid-program restart-from-line semantics
• DRO visual wrap in GUIs (HAL-side wrap component is the suggested workaround)
• 5-axis kinematics modulo on coupled tilt axes (warning only)

Test plan

• Sim config with A axis, ROTARY_MODULO=1, run program that drives A to large value then G0 A0, verify motion is ~residual angle not full unwind
• Verify #5423 reads wrapped, HAL pin reads accumulated
• Verify mutex error on WRAPPED_ROTARY=1 + ROTARY_MODULO=1
• Verify hard-error on G33 A... with modulo A
• Existing programs with WRAPPED_ROTARY=0 (default) unchanged
• Existing programs with WRAPPED_ROTARY=1 unchanged

In action

[grandixximo]

If this lands, future work I see worth tracking:

• Mid-program restart-from-line: commercial controls replay/simulate then approach the wrapped end state; LinuxCNC's existing restart machinery does not handle this for modulo axes.
• DRO visual wrap in GUIs (axisui, gmoccapy, qtdragon, etc.): right now users get a wrapped value through #<_hal[...]> or via a HAL wrap component, but native GUI support would be cleaner.
• 5-axis kinematics: this PR only warns if the axis MIN/MAX range is not approximately 360 degrees; coupled tilt axes on TCP machines may need more careful handling.
• Optional native motion-layer modulo: today the wrap lives at the interpreter and parameter-readout layer, with HAL pins kept accumulated to stay stepgen-safe. A proper motion-side modulo (with joint sync) could remove the accumulated/wrapped split entirely.
• Eventual deprecation path for the sign-of-commanded direction behavior of WRAPPED_ROTARY=1, once ROTARY_MODULO has time in the wild.

Happy to take any of these as follow-up PRs if there is interest.

[djdelorie]

Does this affect G1 moves? I think people would be surprised if a G1 move didn't do exactly what it was told to do...

[grandixximo]

Does this affect G1 moves? I think people would be surprised if a G1 move didn't do exactly what it was told to do...

I think it would be even more confusing having G0 act differently from G1, it is an opt in configuration, user should expect changes, when enabling option for modulo motion for an axis, I'm not clear as to why it should be G0 only, that makes it more confusing, a clear flag, that axis works modulo, G0 and G1 is more sensible, and similar to what commercial counterparts do.

[djdelorie]

Because the common case is (at least in my experience) that you do a lot of G1 milling moves and the rotary axis "winds up" the angle (I've seen it in the hundreds of thousands of degrees). At the end of the job (or start of the next operation) there's a G0 A0 to reset the rotary, and it takes many minutes even at rapid RPMs. What the user really wants is to do all the winding up according to plan, and at the end just move as quickly as you can to the angle requested (i.e. always less than 360 degrees of actual motion).
So, G1 is "do exactly what I tell you" and G0 is "get there as fast as you can". That means we're allowed to take shortcuts with G0 but not with G1, so there is an expectation that they'll act differently already.

[grandixximo]

How about you try it? I don't think I changed G1 behavior in a way of which you will disapprove, test and see

[grandixximo]

You know how to download the .deb from GitHub?

[grandixximo]

Absolute moves take shortest path, and accept numbers over 360 or below -360, your small G1 moves always want the shortest path, and so do your G0 moves, there is no distinction or different behavior needed to solve your issue, shortest path is the valid wanted behavior in both cases

[grandixximo]

Does this affect G1 moves? I think people would be surprised if a G1 move didn't do exactly what it was told to do...

Sorry, I did not explain well, yes it does effect G1 moves, but ONLY absolute moves (G90), and only those moves that require the axis to move more than 180 degree, example

G1A2000
G1A2005
G1A1990

all of the above no change

G1A2000
G1A2190

The above type moves ONLY have changed, and take the shortest path moving backward in respect to what was programmed, A axis would move -170 incrementally from A2000 ending up on A1830 in the joint position.

[djdelorie]

I'll try it when I get a chance, sure. I was worried about commands like "G1 X5 A7200" to do a simple rotary spiral flattening, for example, with a "G0 A0 X0" to return. If that G1 didn't go around 20 times the result would be incorrect.

[grandixximo]

You can use G91 for the special cases where you need multiple turns, I only modified G90 behavior

[djdelorie]

Hmm... if I was willing to generate modulo g-code, I would have just use WRAPPED_ROTARY. I think anything that changes what G1 does is going to be problematic, and I wouldn't have modified G1 at all. Ideally, no change to gcode should be needed.

[grandixximo]

Fair concern, let me be straight about where I land.

I will add M26/M27 to this PR as a follow-up commit: M26 enables shortest-path on modulo axes (the default when ROTARY_MODULO=1), M27 forces literal absolute for the cases where you genuinely want the wind-up. That covers your spiral example as a per-block override without changing the default rule. M26/M27 land in a free slot since M100-M199 is reserved for user scripts, so no conflict with anyone's existing M-files.

That is the ground I am willing to give. I do not want to split G0 and G1 under the same flag, and I looked for commercial precedent before saying that. Siemens 840D in modulo mode treats absolute as shortest for both G0 and G1, with per-block overrides like A=DC(45) and A=ACP(270) for direction control. Heidenhain uses modal M126/M127 uniformly for rapid and feed. Fanuc Type B rotary picks direction by sign of value, again uniform. None of them carve G0/G1 asymmetry, and I think the reason is that mixing wrapped parameter reads, accumulated HAL pins, short G0 and long G1 gives the operator four views of one axis.

I do understand this asks users with existing G-code to adapt if they turn the flag on, but the flag is opt-in and off by default, and I think the behavior is useful and intuitive for most people who would reach for it. This is LinuxCNC, not any one user's machine, and a feature that aligns with how Siemens, Heidenhain, and Fanuc handle rotary modulo seems worth having available.

I will push the M26/M27 commit shortly. If you try the .deb after that, feedback welcome.

[grandixximo]

Updated M27 semantics in the latest commit. The original M27 (literal multi-turn absolute) had an unsafe entry condition: with accumulated AA_current large from prior M26 sections, a block like M27; G0 A0 would compute delta = 0 - AA_current and execute that as physical motion. On long-running jobs AA_current can grow without bound, so M27 became a foot-cannon.

Closing that hole would have required an additional reset primitive (M94-style rebase of AA_current plus joint-side motor_offset compensation to keep the motor stationary). That brings in axis-to-joint mapping, FREE-mode gating, and kin-chain validation. Significantly heavier than the rest of this PR, and the whole machinery exists only to defuse a hazard M27 itself introduces.

Redesigned M27 to instead modulo the input mod 360 and use the sign of the input for direction:

• positive (or zero) input: forward to target within the current turn
• negative input: backward to target within the current turn
• inputs outside +/-360 are accepted and wrapped (A720 becomes A0, A-540 becomes A-180)
• resulting move is always less than one full turn, regardless of accumulated state

This matches Heidenhain M127 default and Siemens ACP/ACN per-block intent on a modulo axis. Multi-turn motion (helical winding, wire wrapping) is now exclusively the domain of G91, which is the universal idiom on Heidenhain (IA+) and Siemens too.

Net: foot-cannon eliminated by construction, no reset machinery needed, smaller PR scope, cleaner mapping to industry semantics. Docs in m-code.adoc updated.

[Sigma1912]

Where are we at with this PR? The OP seems to have lost interest, but it looks like something worth having.

[djdelorie]

I haven't lost interest, I just haven't yet had time to test it.

[grandixximo]

I don't have a machine to test this, and since it's mostly in my head, and I already screwed it once, it has to be tested before merge, just waiting on that...

[Sigma1912]

I have the hardware so I can do testing. I'll report back.

[Sigma1912]

Works for me on real hardware as described in the documentation.

This implementation is clearly not as easy to use as the 'G1 does multi turn' , 'G0 does shortest move' logic that was envisioned by the OP.
However I also see that the split behavior for 'G0' / 'G1' moves would require a lot of work on handling motor position command and feedback.
And I agree that we should follow established behavior used in brand name controllers.

• ROTARY_MODULO=1, run program that drives A to large value then G0 A0, verify motion is ~residual angle not full unwind, Check, jog rotary to -90000, MDI: A0 moves axis to -90360.
• Verify mutex error on WRAPPED_ROTARY=1 + ROTARY_MODULO=1 Check, (tested having both entries on same axis)
  -Verify hard-error on G33 A... with modulo A Check, G33 not affected if A word not present.
• Verify #5423 reads wrapped, HAL pin reads accumulated Check

[grandixximo]

You should test #3990 as well then, that should be OP original ask

[Sigma1912]

You should test #3990 as well then, that should be OP original ask

While certainly a more direct solution for the OP's use case, I somewhat dislike having the interpreter using user accessible offsets like that.
This seems like something that would be done in a user remap (although we cannot remap G0, G1) or a filter script.

So right now I would tend to favor the ROTARY_MODULO version as the more solid one.

[grandixximo]

Ok then, opening this to review, I guess ready to merge...

[grandixximo]

Pushed a fix on top of what you tested.

M27 took its direction from the value after offsets were subtracted, so on an axis with a G54 rotary offset a G53 G0 A0 or a G28 landed on the mirrored angle instead of the commanded one. Direction now comes from the programmed word, offsets are applied after. G28, G30 and the tool change position always take the shortest path, since they carry no programmed sign.

I also inverted the startup limit warning. It complained about a range that is not ~360 deg, but ~360 is the range that cannot work: the commanded position accumulates, so motion is refused once it passes MIN_LIMIT/MAX_LIMIT. It now warns on a bounded range and stays quiet when the limits are absent. M27 also reverts to M26 at program end.

M26 output is unchanged from what you tested, so your results should still hold. If you have the machine handy, the only new ground is M27 with a G54 A offset active: G53 G0 A0 and G28 should finish on the commanded angle. Sim coverage added in tests/interp/rotary-modulo.

[Sigma1912]

Fancy simulations! I like it.