---
name: linuxcnc-axis-manual-execution
description: "Run and validate LinuxCNC G-code through the AXIS graphical interface in the repository's isolated simulation workflow. Use when a manual UI execution, DRO movement check, or desktop shortcut needs to be reproduced; do not use this as permission to drive physical hardware."
---

# Linuxcnc Axis Manual Execution

Use this skill for the repository's manual AXIS simulation workflow. The default target is the 3-axis tutorial configuration and `linuxcnc/nc_files/3dtest.ngc`.

## Scope and Safety

- Treat this workflow as simulation-only. Do not connect it to or operate a physical machine unless the user separately authorizes that and the hardware configuration, limits, and emergency controls have been verified.
- A program is not considered executed merely because AXIS opened it or switched to AUTO. Require visible DRO/coordinate movement and a normal interpreter completion at `M2`.
- Stop and report the first real LinuxCNC error. Debug/text messages are not motion errors by themselves.

## Repository Entrypoints

- Manual launcher: `scripts/launch_axis_3dtest_manual.sh`
- Desktop shortcut: `/home/mes006/Desktop/3axis-tutorial.desktop`
- Source program: `linuxcnc/nc_files/3dtest.ngc`
- Source AXIS model/configuration: `linuxcnc/configs/sim/axis/vismach/3axis-tutorial`

The launcher copies the model/configuration into a temporary runtime directory, sets `AXIS_OPEN_FILE` to the source program, points `PROGRAM_PREFIX` at `linuxcnc/nc_files`, enables the AXIS homing prompt, and raises the temporary Z positive limit to `100 mm`. The source `.ngc`, `.ini`, variable, and position files must remain unchanged.

Before every startup and again after LinuxCNC exits, the launcher closes any existing LinuxCNC simulation by attempting `axis-remote --quit`, `halcmd stop`, `halcmd unload all`, and realtime stop; it then terminates matching LinuxCNC/AXIS service processes, waits for them to exit, and removes `/tmp/linuxcnc.lock` only when no matching service remains. The input-method daemon is not stopped: immediately before startup, IBus is switched to the English `xkb:us::eng` engine, English is made the first input source, and the X keyboard layout is set to `us`, so AXIS shortcuts are not intercepted while Chinese input remains available for later use. Cleanup output is printed so stale-session failures remain visible.

## Manual UI Procedure

1. Start the launcher directly or open the desktop shortcut. Wait for an AXIS window whose title contains `3dtest.ngc` and `3axis-tutorial`.
2. Reset E-stop with the red E-stop control (AXIS `F1`), then turn machine power on (AXIS `F2`). Accept the homing prompt if it appears.
3. Ensure all three axes are homed. If the prompt is absent, select X, Y, and Z in the Manual Control panel and click `Home Axis` for each, or use AXIS `Machine -> Home All` / `Ctrl+Home`. Homing only X is insufficient: AXIS can enter AUTO while refusing to move.
4. Click the AXIS Run toolbar button (blue play icon) or press `r`. Do not use the LinuxCNC Python command API as a substitute when the request is specifically for a manual UI test.
5. Watch the DRO and program highlight. Success requires `motion_line`/highlight progress, actual X/Y/Z values changing, and the interpreter returning to idle at the program's `M2`. Use `Esc` to stop an unexpected run.
6. Close AXIS after the test. The launcher removes its temporary runtime directory when LinuxCNC exits.

## Verification Evidence

Record at least:

- AXIS window title and selected source path.
- State transitions: E-stop reset, machine ON, all homed, AUTO/RUNNING.
- Initial and final DRO coordinates plus evidence that coordinates changed during motion.
- Final motion/current line and interpreter idle state.
- Any `NML_ERROR`/`RCS_ERROR` text; do not classify `(DEBUG,...)` messages as errors.

For `3dtest.ngc`, the expected geometry reaches roughly `56 mm` on each XYZ coordinate after the G20 inch-to-mm conversion. The unmodified tutorial configuration has a Z positive limit of `0.001 mm`, so use the launcher-managed temporary configuration rather than launching the base INI directly.

## Known Program Pitfalls

- `nestedcall.ngc` currently contains `O<g20sub> callsub`, which the installed LinuxCNC interpreter reports as `Unexpected character after O-word`; do not use it as a passing baseline without an explicit source-level compatibility decision.
- A loaded file with `task_mode=AUTO` but `homed=[1,0,0]` is not a successful run. Home Y and Z before diagnosing G-code behavior.