Jogging

sjog is the motion mediator for jogging controls. It accepts physical axis direction buttons, MPG handwheels, and Ctrl’s optional on-screen controls, applies the common jog permissions and hand-off behavior, and drives LinuxCNC’s axis or joint jog interfaces.

Use logical channels in LinuxCNC’s canonical axis order. For example, X uses channel 00 and Z uses channel 02.

Ctrl supplies the selected jog mode, jog increment, active feed mode, and runtime supervision automatically. These are internal connections between Ctrl and sjog; the machine configuration should not drive or replace them.

Start from the shipped scaffolding

Use the self-contained scaffolding shipped at /data/ctrl/configs/mill/sjog.hal or /data/ctrl/configs/lathe/sjog.hal as the base for the machine configuration. These files connect all known paths between sjog, Ctrl, and LinuxCNC, including the different pre-home joint mappings for a mill and lathe.

The scaffolding deliberately leaves machine-specific inputs unconnected. Choose signal names appropriate for the machine and connect its conditioned hardware directly to the public sjog input pins described below. Do not reproduce the Ctrl, motion, or HALUI connections already owned by sjog.hal.

Before and after homing

LinuxCNC distinguishes between joints, which represent physical motion channels, and axes, which represent operator-facing coordinates such as X, Y, and Z. Before homing establishes the machine coordinate system, sjog sends button and MPG requests to the physical joint mapped to the selected axis. After every configured joint is homed and LinuxCNC enters coordinated mode, sjog sends those requests to the logical axis instead.

For example, the shipped lathe scaffolding maps:

Selected coordinate	Before homing	After homing
X	Joint 0	X axis
Z	Joint 1	Z axis

The physical control wiring does not change during this transition. The operator continues using the same X or Z controls, and sjog changes the destination automatically as the machine moves from joint mode to coordinated axis mode.

Axis direction buttons

Each logical axis has a positive and negative button input. After debouncing and conditioning the physical signals, connect them to sjog.chan.NN.btn.plus and sjog.chan.NN.btn.minus:

net panel-x-plus  => sjog.chan.00.btn.plus
net panel-x-minus => sjog.chan.00.btn.minus
net panel-z-plus  => sjog.chan.02.btn.plus
net panel-z-minus => sjog.chan.02.btn.minus

When a button is allowed to move the machine

sjog accepts a jog request only when Ctrl’s jog control is active and the machine asserts its functional jog permit through sjog.machine-permit. Ctrl supplies its own runtime watchdog automatically.

sjog handles re-arming automatically. After power-up, a mode change, homing, or a temporary loss of permission, every direction button must return to neutral before motion can begin. A held button therefore cannot unexpectedly start the axis when permission returns. The integrator only needs to provide debounced and conditioned button inputs; it does not need to implement this latch or re-arm logic.

Pressing both directions on any channel stops jogging and disarms all direction buttons. Release every direction button before jogging again. This also applies when a physical button and an enabled on-screen control request opposite directions.

During commissioning, watch these sjog status outputs:

sjog.armed is true when all direction buttons have been released and sjog is ready to accept a new request. sjog clears it automatically after startup or a gate change.
sjog.control-alive is true while Ctrl is enabled and its heartbeat is fresh. A false value means jog requests are blocked by the runtime watchdog.
sjog.jog-inhibit is true while the jog gate is closed, preventing motion from accepting jog requests.
sjog.jog-stop becomes true when the jog gate closes after startup or direction inputs conflict, stopping an active jog.

The shipped scaffolding routes the stop and inhibit outputs to LinuxCNC. They are functional motion controls, not safety functions.

Incremental mode

When Ctrl is in incremental jog mode, each new button press moves by the increment selected in Ctrl. Holding the button does not repeat the step; release it and press again.

Continuous mode

When Ctrl is in continuous jog mode, movement continues while the button is held. After homing, sjog uses the logical axis outputs. Before homing, it uses the mapped joint outputs.

The machine’s LinuxCNC configuration still owns the jog velocity. sjog gates the request but does not set the configured speed.

G95 power feed

In G95 feed-per-revolution mode, a continuous direction button can provide manual power feed. It becomes active when the spindle is on, the machine is homed, coordinated motion is active, and the active feed per revolution is positive.

The travelled distance follows the spindle feedback:

distance = |spindle revolution change| × feed per revolution × feed override

The LinuxCNC feed override scales the requested feed per revolution. A zero or negative value results in no power-feed movement. Rapid and spindle overrides are not consumed by sjog; they retain their normal LinuxCNC meaning.

For simultaneous linear axes, sjog reduces each axis contribution so the combined move keeps the requested feed. Mark rotary channels with chan.NN.linear = false; they do not participate in power feed. sjog.power-feed-active shows when at least one axis is moving this way.

G95 power feed is responsive manual motion. It can lose positional lead at acceleration or velocity limits and must not be used for threading or other spindle-synchronized machining.

Lathe angled power feed

On a lathe, angled power feed rotates the complete physical and touchscreen X/Z direction cross by up to 45 degrees in either direction. The angle is measured in machine space from +Z toward +X, and the combined X/Z move retains the selected feed per revolution. Other jog modes and MPG movement are unchanged.

The mode disarms when jogging becomes unavailable or an MPG moves. Changing the angle while a direction is held stops motion until every direction returns to neutral. An unused activation expires after five minutes; after movement begins, returning to neutral starts a ten-second grace period. Active movement does not expire, and stopping the spindle alone does not disarm the mode.

Rapid modifier

Connect the rapid button to sjog.button-rapid-override. While it is held with a direction button, sjog requests normal continuous jog instead of G95 power feed. Drive sjog.button-power-feed-exclusive when the machine reserves its direction buttons for power feed.

If the operator presses the direction first, sjog waits briefly for the rapid button. The default window is 50 ms (sjog.rapid-chord-timeout). Changing the rapid state after that window requires the direction buttons to be released before motion can restart.

MPG handwheels

Choose one handwheel with an axis selector or separate handwheels for individual axes. This choice is independent of machine type: a mill or lathe can use either layout. The shipped mill scaffolding demonstrates a shared handwheel, while the lathe scaffolding demonstrates independent handwheels.

Select the layout in sjog.hal before LinuxCNC starts. It cannot be switched while LinuxCNC is running, but the machine configuration can be changed later.

Shared handwheel

Load sjog with its default personality:

loadrt sjog

For one handwheel shared by several axes, connect these inputs:

Pin	Meaning
`sjog.mpg-counts`	Signed accumulated encoder count; do not provide a per-cycle delta
`sjog.mpg-axis`	Selected canonical axis index (`0` = X, `2` = Z, and so on)
`sjog.mpg-scale`	Machine units represented by one count
`sjog.mpg-enable`	Global physical MPG enable

Use an accumulated encoder count, not a count change from the current servo cycle. Only the selected axis receives the count stream. An invalid or unavailable selection produces no motion.

Independent handwheels

Load sjog with personality 1:

loadrt sjog personality=1

For each fitted handwheel, connect sjog.chan.NN.mpg.counts, sjog.chan.NN.mpg.scale, and sjog.chan.NN.mpg.enable. Keep the global sjog.mpg-enable true. Several enabled handwheels may move their axes at the same time.

This layout has no shared count, axis-selection, or scale pins. It is not switchable at runtime.

Count continuity and control hand-off

Keep the encoder count running continuously; it should increase in one direction and decrease in the other. While the MPG is blocked, sjog follows the physical count without commanding movement. When the MPG becomes available again, old handwheel movement is not replayed.

Normal MPG movement uses position mode: each encoder count requests the configured amount of travel. Turning the handwheel faster produces counts faster, but it does not change each count into a velocity command.

Direction buttons take precedence over MPG handwheels. After the operator releases a direction button, sjog waits one servo cycle before enabling the handwheel. This prevents the two controls from overlapping during the hand-off.