# Lagun Milling Machine - GMOCCAPY Configuration

LinuxCNC configuration for a Lagun 3-axis (X, Y, Z) milling machine with servo drives, controlled by a Mesa 5i24 FPGA card and the GMOCCAPY GUI. Units are imperial (inches).

Originally generated by PNCconf (July 2024), then modified for GMOCCAPY and dual-encoder feedback.

## Files

| File | Purpose |
|------|---------|
| `lagun_gmoccapy.ini` | Main config: axes, PID gains, encoder scales, limits, MDI commands |
| `lagun.hal` | Main HAL: loads drivers, wires encoders/PWM/PID/GPIO, tool change |
| `xhc-whb04b-6.hal` | Pendant HAL: jog, axis select, feed override, macro buttons |
| `gmoccapy_postgui.hal` | Post-GUI HAL: connects tool offset display to GMOCCAPY |
| `shutdown.hal` | Shutdown HAL: currently empty (placeholder) |
| `tool.tbl` | Tool table with 6 tools (T0-T5) |

## Hardware

### Controller
- **Mesa 5i24** PCI FPGA card (`hm2_pci`)
- 6 encoder channels, 6 PWM generators
- PWM frequency: 15,500 Hz
- Servo period: 1 ms (1,000,000 ns)

### Servo Drives and PWM Mapping

| Axis | PWM Channel | Output Scale |
|------|-------------|-------------|
| X | pwmgen.00 | +1 |
| Y | pwmgen.02 | -1 (inverted) |
| Z | pwmgen.04 | -1 (inverted) |

### Encoder Mapping

X and Y each have two encoders (motor + linear scale). Z has only a linear scale.

| Signal | Encoder Channel | Scale (counts/inch) | Purpose |
|--------|----------------|---------------------|---------|
| X linear | encoder.00 | 5085.5 | Position feedback (used for joint FB) |
| Y linear | encoder.01 | 5085.4 | Position feedback (used for joint FB) |
| Z linear | encoder.02 | -10075 | Position feedback (used for joint FB) |
| X motor | encoder.03 | -27939.6 | Velocity/damping feedback |
| Y motor | encoder.04 | 27453.6 | Velocity/damping feedback |
| Z motor | (none) | N/A | Not installed |

### GPIO Pin Assignments

**Relay outputs** (active low / inverted):

| GPIO | Function |
|------|----------|
| 041 | Spindle on/off relay |
| 044 | Z-axis servo enable relay |
| 046 | X-axis servo enable relay |

**Button inputs** (active low, currently unused/commented out):

| GPIO | Function |
|------|----------|
| 027 | Button (unassigned) |
| 028 | Button (unassigned) |
| 029 | ESTOP button |
| 030 | START button |
| 031 | STOP button |

The button inputs are configured as inputs but their HAL net connections are commented out because they were causing unexpected machine shutoff.

## Dual PID Feedback (X and Y Axes)

X and Y each use two PID loops running in parallel, whose outputs are summed:

1. **Motor encoder PID** (`pid.x` / `pid.y`): Uses D gain and FF1 for velocity damping. No I gain. Feedback from the motor-mounted encoder.
2. **Linear scale PID** (`pid.xl` / `pid.yl`): Uses high P and I gains for accurate position correction. Feedback from the linear scale mounted on the axis.

The outputs are summed via `sum2` components:
- `sum2.0`: X motor PID + X linear PID
- `sum2.1`: Y motor PID + Y linear PID
- `sum2.2`: Z linear PID only (no motor encoder)

The **linear scale** position is used as the joint feedback (`joint.N.motor-pos-fb`), so LinuxCNC tracks actual table position rather than motor position.

## Z-Axis Override Mechanism

The Z-axis has a special enable/disable mechanism for manual quill operation:

- A HAL `logic AND` gate combines two signals: `z-override` and `z-enable`
- The combined output `z-enable-comb` controls the Z servo PID enable and the GPIO 044 relay
- `z-override` defaults to TRUE at startup (CNC controls Z)
- M101 can set `z-override` to FALSE, disabling the Z servo so the quill can be moved manually
- M102 can set `z-override` back to TRUE to re-enable CNC Z control

**Workaround**: Because the Z servo is disabled during manual quill use, the quill position diverges from the commanded position. To prevent following-error faults, `MIN_FERROR` is set to 100 inches in the INI file (ideally it would be 0.2). An attempt to dynamically switch the ferror value via a `mux2` component exists in the HAL but is non-functional (the output signal is not connected to the joint).

## Spindle

On/off relay control only via GPIO 041. No speed control or encoder feedback. The spindle PID section in the INI exists but is effectively unused (FF0=1 with no feedback). Default spindle speed in the GUI is 500 RPM.

## Pendant (XHC WHB04B-6)

Wireless pendant loaded with `xhc-whb04b-6 -HsfB` (HAL-only, step, filtered, 6-axis model).

Connected to `joint.N.jog-*` pins (not `axis.x.jog-*`, which GMOCCAPY does not create).

### Macro Button Mapping

Macro buttons trigger MDI commands defined in the `[HALUI]` section of the INI:

| Button | MDI Index | G-code | Action |
|--------|-----------|--------|--------|
| Macro 1 | 01 | `G10 L20 P0 X[#<_x>/2.0]` | Halve X coordinate |
| Macro 2 | 02 | `G10 L20 P0 Y[#<_y>/2.0]` | Halve Y coordinate |
| Macro 3 | -- | (hardcoded) | Spindle speed increase |
| Macro 4 | -- | (hardcoded) | Spindle speed decrease |
| Macro 5 | 05 | `G10 L20 P0 X0` | Zero X |
| Macro 6 | 06 | `G10 L20 P0 Y0` | Zero Y |
| Macro 7 | 07 | `G10 L20 P0 Z0` | Zero Z |
| Macro 8 | -- | (hardcoded) | Spindle direction |
| Macro 10 | -- | (hardcoded) | Toggle ABS/REL DRO |
| Macro 15 | -- | (hardcoded) | Flood coolant toggle |
| Macro 16 | -- | (hardcoded) | Mist coolant toggle |

### Function Buttons

| Button | Action |
|--------|--------|
| M-Home | Home all axes (`halui.home-all`) |
| Safe-Z | MDI command 03 (debug/placeholder) |
| W-Home | MDI command 04 (debug/placeholder) |
| Probe-Z | MDI command 08 (debug/placeholder) |

Feed override is connected and functional via the pendant knob.

## Tool Change

Manual tool change using `hal_manualtoolchange`. A dialog pops up on screen prompting the operator to change the tool. Tool prepare requests are looped back (no automatic tool changer).

## Axis Limits and Homing

| Axis | Travel (inches) | Home Sequence |
|------|----------------|---------------|
| X | -24.0 to +24.0 | 2 |
| Y | -12.0 to +12.0 | 3 |
| Z | -4.0 to +1.0 | 1 (first) |

`NO_FORCE_HOMING = 1` is set, so the machine can be jogged and run programs without homing first.

## Startup G-code

```
G20 G40 G90 G94 G97 G64 P0.001
```

- G20: Inch mode
- G40: Cancel cutter compensation
- G90: Absolute distance mode
- G94: Feed per minute
- G97: RPM mode (constant spindle speed)
- G64 P0.001: Path blending with 0.001" tolerance

## E-Stop

The estop signal is looped back internally (`user-enable-out` -> `emc-enable-in`). There is no external hardware estop chain connected through LinuxCNC. The physical ESTOP button on GPIO 029 is configured as an input but not wired into the estop logic.