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:

```text
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:

```text
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:

```bash
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:

```text
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:

```text
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:

```text
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:

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

The copied icons live in:

```text
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.