Proposal: mc_axis — a PLCopen MC Part 1 axis component for HAL (extra joints, axes without G-code)

[yurc]

LinuxCNC already drives axes that are not interpolated by the trajectory planner: extra joints
(motmod num_extrajoints=, joint.N.posthome-cmd) and drives in HAL-only configurations. Today the
in-tree tool for that is limit3: it follows an input with position/velocity/acceleration limits, but it
has no notion of a command. The logic around it cannot tell when a move is done (a near guesses), cannot
halt a move (dropping enable drives the output to 0), does not see a following error or a drive fault,
and clips a target outside the limits instead of refusing it.

mc_axis is the axis of PLCopen Motion Control Part 1 — the model PLC programmers already know — as a
plain HAL component, one instance per axis:

• commands as pins: power (MC_Power), execute + mode/position/velocity/acceleration/
  deceleration/jerk (MC_MoveAbsolute / MC_MoveRelative / MC_MoveVelocity), halt, stop, reset,
  home (the drive's own homing, CiA-402), set-position (MC_SetPosition);
• outputs per PLCopen: busy, done, active, command-aborted, error, error-id, axis-error-id,
  in-velocity, state (PLCopen state diagram: Disabled, Standstill, Homing, DiscreteMotion,
  ContinuousMotion, Stopping, ErrorStop), plus command numbers (command-id, done-id, aborted-id,
  failed-id) so that several callers can share one axis;
• soft limits refuse a target (error 5); the following error is always checked while powered (error 4);
  a drive fault or a drive leaving operation-enabled puts the axis into ErrorStop; reset leaves it;
• profile: trapezoid for position moves, jerk-limited S-curve for velocity moves; optional
  drive-profile hands a move to a drive in CiA-402 Profile Position.

Wiring to an extra joint is the same three nets as with limit3 (pos-cmd → joint.4.posthome-cmd,
joint.4.pos-fb → pos-fb, joint.4.homed → stat-op-enabled); to an EtherCAT drive it is the
cia402 component of linuxcnc-ethercat (nets in the man page notes).

Why in LinuxCNC: it lets LinuxCNC run PLC-style machines without G-code — positioners, pallet handlers,
conveyors, a rotary table beside a mill — with the axis semantics a PLC has; logic on top (ladder, or
anything that writes HAL pins) only raises execute and reads done/error.

Field run (2026-10-06). Inovance SV660N servo on EtherCAT (linuxcnc-ethercat, cyclic synchronous
position), mc_axis + cia402, LinuxCNC 2.10 uspace. Buttons drove the same HAL pins
through our PLC layer (not part of this proposal). MC_SetPosition 0 at 1333.46° without motion, then
(axis position, degrees):

• A (MoveAbsolute 100 at 50°/s): 0 → 21.7 → 41.4 → 61.1 → 81.2 → 100.05 in ~2 s, done;
• B (MoveAbsolute 0): 100 → 77.6 → 58.0 → 38.1 → 18.5 → 0.00, done;
• A, halted after 1.1 s: stopped at 56.40, Standstill;
• B: 56.4 → 34.8 → 15.6 → −0.006.

Drive encoder 31071849 → 33403250 (+2331401 counts ≈ 100.05° × 23301.69 counts/°) → 31071713, so the
shaft really moved; no drive fault (statusword bit 3) during the run. With power held at 0 the drive was
never enabled (statusword 0x1650 throughout).

On the branch:

• src/hal/components/mc_axis.comp (man page from description/notes), a row in
  docs/src/hal/components.adoc, docs/po4a.cfg;
• tests/mc-axis/ — power, MoveAbsolute (Done, velocity ≤ maxv), Halt (the move CommandAborted, the halt
  Done), a target outside the soft limits refused without motion, SetPosition, MoveRelative,
  MoveVelocity + Halt, drive fault → ErrorStop → Reset, power off. Pins through hal.set_p/get_p,
  every wait on a HAL state, one timeout in test.sh; the component is built in-tree, so no skip;
• configs/sim/axis/extrajoints/mc_axis.{ini,hal,txt} — 1extrajoint with mc_axis instead of limit3,
  sim_pin buttons for position / execute / halt / reset.

runtests on the branch (master 7f67ef2e4, uspace, Ubuntu 24.04, no sudo): tests/mc-axis 1/1 passed
(22 checks); tests/limit3 + tests/halcompile 17/17 passed; halcompile of the component without warnings.

Branch: https://github.com/SyncTwin/linuxcnc/tree/synctwin/mc-axis

Question: would you take mc_axis into the tree, next to limit3? If yes I'll open a PR against
master. Opinions on naming (pins; mc_axis vs e.g. plcopen_axis) and on scope (e.g. leaving
drive-profile for a later PR) are welcome.

[grandixximo]

Makes me wonder if we should have adopted cia402 component in linuxcnc rather than linuxcnc-ethercat...

[andypugh]

In addition to limit3 there is also simple_tp:
https://linuxcnc.org/docs/devel/html/en/man/man9/simple_tp.9.html
Though what you describe could probably replace and enhance that.

[yurc]

simple_tp the component is used only by pncconf's axis test (pncconf/tests.py); the planner itself lives in motion (simple_tp.c: free jog, teleop jog, external offsets), with copies of the formula in anglejog.comp and eoffset_per_angle.comp.

On the branch (synctwin/mc-axis), mc_axis can now replace the component:

• mode 3 (track): follows a moving position target for as long as execute is held, with velocity and acceleration read every period. Same braking law as simple_tp, so the same lag of v²/2a. It is not PLCopen Part 1: ContinuousUpdate (§2.4.6) ends with the move, so MoveAbsolute stops at the first target that moves after Done. The model is CODESYS SMC_TrackSetValues, without its set-velocity input.
• virtual 1: no drive, feedback = command (the CODESYS bVirtual idea).

setp tp.virtual 1
setp tp.mode 3
setp tp.power 1
setp tp.limits-enable 0
net tp-tgt <target-pos> => tp.position
net tp-en  <enable>     => tp.execute tp-halt.in   (not: tp-halt.out => tp.halt)
net tp-vel <maxvel>     => tp.velocity tp.maxv
net tp-acc <maxaccel>   => tp.acceleration tp.maxa

tests/mc-axis-vs-simple-tp runs both in one thread on the same inputs: steps, a moving target, reversal, enable toggled mid-move, maxvel/maxaccel changed mid-move. Both stay at the limits (peaks 80 and 500), neither overshoots, and over 9 arrivals mc_axis is never later than simple_tp (0–5 periods earlier). The largest position difference is 0.075. With mode 0 (MoveAbsolute + ContinuousUpdate) the test fails. Known differences: mc_axis integrates the mean velocity of the period, so its stop is v·dt/2 longer, and track mode has no jerk.

On hardware (EtherCAT servo, bare shaft, CSP, 1 ms), track mode following a 15°/s ramp lags 0.626°, against 0.625° from v²/2d. The commanded position stops on a halted target with 0.0004° overshoot, and the axis follows again without a new execute.

limit3 is a different job: it matches the input's velocity (no lag), clamps at the limits instead of failing, and has load and smooth_steps. In PLCopen terms that is synchronized motion (MC_GearIn). mc_axis does not cover it.

The side-by-side test also showed an overshoot of up to a·dt²/2 in mc_axis's own stop; that is fixed on the branch (ccbaeaf).