linuxcnc/nc_files/macros.md

# Macros & Subroutines

Custom M-codes and G-code subroutines for the Lagun mill LinuxCNC configuration.

## Mode Flags (Bitmask)

Several macros (`pocket_circ`, `pocket_rect`, `frame_rect`, `frame_circ`, `slot`) accept a `mode` parameter as a bitmask:

| Bit | Value | Set (1) | Clear (0) |
|-----|-------|---------|-----------|
| 0 | +1 | Conventional milling | Climb milling |
| 1 | +2 | Both-ways milling | One-way milling |
| 2 | +4 | Plunge entry | Helix entry |
| 3 | +8 | Outside | Inside |

Default mode (0) = climb, one-way, helix entry, inside.

## Global Named Parameters

These optional globals configure macro behavior when set before calling:

| Parameter | Description | Default |
|-----------|-------------|---------|
| `#<_td>` | Tool diameter (from tool table) | **Required** - used by all material-removal macros |
| `#<_z_clearance>` | Safe Z retract height | Falls back to ztop param |
| `#<_rampang>` | Ramp/helix entry angle in degrees | 5.0 |
| `#<_stepover>` | Stepover distance for spiral pocketing | 40% of tool diameter |

A negative `fincut` value causes macros to rough only, leaving material for a separate finishing pass.

## M-Codes (Shell Scripts)

### M101 - Enable Z-Axis
Sets HAL signal `z-override` to True, enabling CNC control of Z.

### M102 - Disable Z-Axis
Sets HAL signal `z-override` to False, allowing manual quill control.

## Drilling Subroutines

### drill.ngc - Peck Drill
Fully automatic drilling with optional peck cycle.

```
o<drill> call [x][y] [ztop][zbot] [peck]
```

| # | Name | Description |
|---|------|-------------|
| #1 | X | Hole X position |
| #2 | Y | Hole Y position |
| #3 | Z Start | Top of material / start Z |
| #4 | Z End | Final drill depth |
| #5 | Peck | Depth per peck (0 = no peck) |

Calls M101 to enable Z-axis. Retracts to Z Start between pecks with 0.020" rapid-approach gap.

### drill_man.ngc - Manual Drill
Positions XY then pauses for operator to manually plunge.

```
o<drill_man> call [x][y]
```

Calls M102 to disable Z-axis, then M0 pause.

### drill_retr.ngc - Semi-Manual Drill with Retract
Positions XY, retracts Z to clearance, disables Z for manual plunge, then re-enables and retracts on resume.

```
o<drill_retr> call [x][y] [z_clearance]
```

## Material Removal Subroutines

### pocket_circ.ngc - Circular Pocket
Cuts a circular pocket using an outward spiral from center.

```
o<pocket_circ> call [x][y] [diameter] [ztop][zbot] [fincut] [mode]
```

| # | Name | Description |
|---|------|-------------|
| #1 | X | Center X |
| #2 | Y | Center Y |
| #3 | Diameter | Pocket diameter |
| #4 | Z Top | Start Z |
| #5 | Z Bottom | Final depth |
| #6 | Finish Cut | Finish allowance (negative = rough only) |
| #7 | Mode | Bitmask (see above) |

Supports helix or plunge entry. Spirals outward with stepover, then does a pre-finish circle and optional finish circle at full diameter.

### pocket_rect.ngc - Rectangular Pocket
Cuts a rectangular pocket. Uses helical or straight plunge, then an outward spiral that transitions to linear passes when the spiral hits the rectangle boundary.

```
o<pocket_rect> call [x1][y1] [x2][y2] [zstart][zend] [fincut] [mode]
```

| # | Name | Description |
|---|------|-------------|
| #1,#2 | X1, Y1 | First corner |
| #3,#4 | X2, Y2 | Opposite corner |
| #5 | Z Start | Start Z |
| #6 | Z End | Final depth |
| #7 | Finish Cut | Finish allowance |
| #8 | Mode | 0=CCW/helix, 1=CW/helix, 2=CCW/plunge, 3=CW/plunge |

Contains internal sub `o<xp>` for filling corners after the spiral exceeds the rectangle bounds.

### frame_rect.ngc - Rectangular Frame
Cuts along the perimeter of a rectangle (inside or outside).

```
o<frame_rect> call [x1][y1] [x2][y2] [ztop][zbot] [mode] [radius]
```

| # | Name | Description |
|---|------|-------------|
| #1,#2 | X1, Y1 | First corner |
| #3,#4 | X2, Y2 | Opposite corner |
| #5 | Z Top | Start Z |
| #6 | Z Bottom | Final depth |
| #7 | Mode | Bitmask |
| #8 | Radius | Corner radius (0 = sharp corners) |

Supports all four combinations of inside/outside and climb/conventional. Plunges at center (inside) or corner (outside), then traces the rectangle with optional corner radii.

### frame_circ.ngc - Circular Frame
Cuts along the perimeter of a circle (inside or outside).

```
o<frame_circ> call [x][y] [diameter] [ztop][zbot] [fincut] [mode]
```

| # | Name | Description |
|---|------|-------------|
| #1 | X | Center X |
| #2 | Y | Center Y |
| #3 | Diameter | Circle diameter |
| #4 | Z Top | Start Z |
| #5 | Z Bottom | Final depth |
| #6 | Finish Cut | Finish allowance |
| #7 | Mode | Bitmask |

Uses a small arc entry/exit move (capped at 15% of diameter) for smooth engagement.

### slot.ngc - Slot
Cuts a slot (obround/stadium shape) between two points.

```
o<slot> call [x1][y1] [x2][y2] [width] [ztop][zbot] [fincut] [mode]
```

| # | Name | Description |
|---|------|-------------|
| #1,#2 | X1, Y1 | Slot start center |
| #3,#4 | X2, Y2 | Slot end center |
| #5 | Width | Slot width |
| #6 | Z Top | Start Z |
| #7 | Z Bottom | Final depth |
| #8 | Finish Cut | Finish allowance |
| #9 | Mode | Bitmask |

Plunges at start, cuts to end, then traces the obround profile. Supports optional pre-finish pass when fincut > 0.

### bore.ngc - Helical Bore
Helical-interpolation boring subroutine.

```
o<bore> call [x][y] [d] [zstart][zend] [stepdown]
```

| # | Name | Description |
|---|------|-------------|
| #1 | X | Center X |
| #2 | Y | Center Y |
| #3 | D | Bore diameter |
| #4 | Z Start | Start Z |
| #5 | Z End | Final depth |
| #6 | Stepdown | Depth per helical pass |

Spirals down in full-circle passes, then does a partial-arc cleanup and spring pass at final depth. Returns to center and Z0.

## Typical Program Header
```
#<_z_clearance> = 0.0
#<_rampang>     = 5.0

G10 L1 P1 Z0.0 R0.25  ; set tool P1 offset and radius
T1   ; select tool
M06  ; manual toolchange

M101 ; enable z-axis
G90  ; absolute coordinates
G54  ; fixture #1

F5.0 ; feedrate
```

## Known Bugs

1. **drill_retr.ngc: Sub name mismatch.** Opened as `o<drill_retr>` (line 1) but closed as `o<drill_man_retract>` (line 23). This will cause a runtime error - LinuxCNC requires matching sub/endsub names.

2. **bore.ngc: Parameter comment is wrong.** The inline comment says `; x, y, d, stepdown, zstart, zend` but the actual parameter order used by the code is `x, y, d, zstart, zend, stepdown`. Anyone calling based on the comment would get wrong results.

3. **bore.ngc: Undocumented `#<_td>` dependency.** Uses global `#<_td>` for tool-diameter compensation but never validates it. If unset (defaults to 0), the bore toolpath radius becomes `D/2` instead of `(D - tool_dia)/2`, cutting an oversized bore.

4. **drill.ngc: First peck cycle is a no-op.** The loop initializes `#<h> = #3` (Z Start) then immediately does `G1 Z#<h>` - moving to where the tool already is. First real cut happens on the second iteration. Wastes one retract cycle.

5. **pocket_circ.ngc: Suspicious angle calculation.** Line 66 has a `TODO` comment from the author: `; TODO: what the heck is the denominator here doing?` The finish-plunge angle divides by `[#4-#5]` (ztop - zbot). If ztop is 0 this produces a division by a potentially small number, which may cause unexpected arc endpoints.

6. **pocket_rect.ngc: Incomplete rectangular clearing.** The spiral-to-rectangle transition has commented-out code (lines 141-151) and a note saying "subroutines might be the best way to do this". The `o<xp>` helper sub attempts to fill the remaining area but uses a different algorithm. Corners may not be fully cleared depending on geometry.

7. **slot.ngc: Test code after endsub.** Lines 79-83 contain hardcoded test calls that execute whenever the file is loaded. These should be removed or moved to a separate test file. The test calls also only provide 7 of 9 parameters (fincut and mode default to 0).

8. **frame_circ.ngc: lead-in arcs can be larger than actual pocket size.** this causes overcutting. not good.

9. **some combination of values will cause hangs.** This is in several macros. linuxcnc does not have stall/timeout detection; if a macro gets stuck in an infinite loop, it hangs linuxcnc.

## Other Todos

1. Change macros to use UPPERCASE_WITH_UNDERSCORES naming (both the filenames, and the usage of them in all .ngc files)
2. Purge all .cnc programs
3. Maybe: Use tool diameter instead of the td global. (we will use tool change stuff)