cnc_wams/web-rtcp-5axis-sim-plan/docs/gmoccapy-xyzab-reference.md

gmoccapy XYZAB Reference

Date: 2026-06-26

This document records how the LinuxCNC gmoccapy_XYZAB.ini simulation maps into the Web RTCP 5-axis simulator. It is a reference boundary, not a browser port of the native gmoccapy GTK runtime.

Source Inputs

Primary input:

work/working3/gmoccapy_XYZAB_execution_analysis.md
linuxcnc/configs/sim/gmoccapy/gmoccapy_XYZAB.ini
linuxcnc/configs/sim/gmoccapy/core_sim_XYZAB.hal
linuxcnc/configs/sim/gmoccapy/spindle_sim.hal
linuxcnc/configs/sim/gmoccapy/simulated_home.hal
linuxcnc/configs/sim/gmoccapy/gmoccapy_postgui.hal
work/working3/gmoccapy_button_icons/button_icon_inventory.csv
work/working3/gmoccapy_button_icons/files/

Project assets generated from those inputs:

app/src/ui-reference/gmoccapy-button-icons.json
app/src/assets/gmoccapy-icons/
app/src/profiles/gmoccapy-xyzab.js
app/src/runtime/gmoccapy-communication-model.js
app/src/runtime/gmoccapy-hal-model.js

Native LinuxCNC Configuration

gmoccapy_XYZAB.ini defines a simulated five-axis machine:

• UI: [DISPLAY] DISPLAY = gmoccapy.
• UI poll cycle: [DISPLAY] CYCLE_TIME = 100 ms.
• Task process: [TASK] TASK = milltask.
• Motion module: [EMCMOT] EMCMOT = motmod.
• Realtime periods: BASE_PERIOD = 100000 ns, SERVO_PERIOD = 1000000 ns.
• Coordinates: [TRAJ] COORDINATES = X Y Z A B.
• Kinematics: [KINS] KINEMATICS = trivkins coordinates=xyzab.
• Joint count: [KINS] JOINTS = 5.
• Homing policy: [TRAJ] NO_FORCE_HOMING = 0.
• HALUI: [HAL] HALUI = halui.

The native profile is a trivkins simulation. It is not a TCP/RTCP proof and must not be promoted as source-derived table-rotary-tilting kinematics.

Native Startup Order

The native command is:

linuxcnc linuxcnc/configs/sim/gmoccapy/gmoccapy_XYZAB.ini

The LinuxCNC script performs these stages:

1. Parse INI and export CONFIG_DIR, INI_FILE_NAME, and config-local PATH.
2. Start linuxcncsvr -ini <ini> for NML buffers.
3. Start realtime, RTAPI, and HAL.
4. Load task process with halcmd loadusr -Wn inihal milltask -ini <ini>.
5. Load halui with halcmd loadusr -Wn halui halui -ini <ini>.
6. Execute normal [HAL] HALFILE entries: core_sim_XYZAB.hal, spindle_sim.hal, and simulated_home.hal.
7. Run halcmd start.
8. Start the display with gmoccapy -ini <ini>.
9. After gmoccapy creates gmoccapy.* pins and calls halcomp.ready(), execute [HAL] POSTGUI_HALFILE = gmoccapy_postgui.hal.

The postgui file is order-sensitive because it references gmoccapy.* pins that do not exist during ordinary HALFILE loading.

Native Communication Model

gmoccapy talks to LinuxCNC through local LinuxCNC mechanisms:

• Command path: gmoccapy -> linuxcnc.command() -> NML emcCommand -> milltask.
• Status path: milltask -> NML emcStatus/emcError -> linuxcnc.stat()/error_channel().
• HAL path: gmoccapy.* pins <-> HAL shared memory.
• HALUI path: halui exposes LinuxCNC commands and status as HAL pins.
• REMAP path: [RS274NGC] REMAP and [PYTHON] run inside the task/interpreter side, not inside the GUI.

The Web application does not connect to native NML buffers, HAL shared memory, or realtime threads. Web buttons dispatch through store.dispatch, task policy gates, source-derived runtimes where available, and UI status snapshots.

HAL Topology

core_sim_XYZAB.hal loads trivkins and motmod, then loops commanded joint positions directly back to feedback:

joint.0 X command -> joint.0 feedback
joint.1 Y command -> joint.1 feedback
joint.2 Z command -> joint.2 feedback
joint.3 A command -> joint.3 feedback
joint.4 B command -> joint.4 feedback

It also creates the simulation loops:

• iocontrol.0.user-enable-out -> iocontrol.0.emc-enable-in.
• iocontrol.0.tool-prepare -> iocontrol.0.tool-prepared.
• iocontrol.0.tool-change -> iocontrol.0.tool-changed.
• spindle.0.forward, spindle.0.reverse.
• iocontrol.0.coolant-flood, iocontrol.0.coolant-mist.

spindle_sim.hal simulates speed feedback:

spindle.0.speed-out -> limit2 -> sim_encoder -> encoder -> spindle.0.speed-in
near_speed.out -> spindle.0.at-speed

simulated_home.hal creates simulated X/Y/Z home switches at X=1, Y=0.5, Z=2.

gmoccapy_postgui.hal maps native HAL state into GUI pins:

• gmoccapy.spindle_feedback_bar.
• gmoccapy.spindle_at_speed_led.
• gmoccapy.tooloffset-x.
• gmoccapy.tooloffset-z.

It also re-establishes the simulated tool-change loop after unlinking conflicting pins.

G-code Gates

Because NO_FORCE_HOMING = 0, MDI and Auto require the normal LinuxCNC sequence:

reset estop
machine on
home all axes
load a program or MDI command
switch to the correct mode
interpreter idle
run MDI or AUTO_RUN

The native stack enforces this in three layers:

1. gmoccapy widget sensitivity and page state.
2. gladevcp actions and gmoccapy callback checks.
3. LinuxCNC task, interpreter, motion, IO, and HAL validation.

The Web project mirrors this as UI disabled reasons, linuxcnc-task-policy gates, and runtime preconditions. The gmoccapy-xyzab profile is allowed as a reference selection, but full LinuxCNC 5-axis source-derived RUN proof remains limited to profiles that have project runtime support.

Button Icon Boundary

The icon inventory from working3/gmoccapy_button_icons was converted into a project-local manifest:

app/src/ui-reference/gmoccapy-button-icons.json

The copied icons live in:

app/src/assets/gmoccapy-icons/

These assets prove UI origin and visual mapping only. Button correctness still depends on the Web store, task policy, runtime state, and browser interaction evidence.