thad/linuxcnc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

big overhaul

Browse Source
This commit is contained in:
Thaddeus Hughes
2026-04-05 20:51:43 -05:00
parent f39f90977d
commit ad1f8719d6
121 changed files with 2457 additions and 1700 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
nc_files/macros.md
View File

@@ -2,9 +2,11 @@
Custom M-codes and G-code subroutines for the Lagun mill LinuxCNC configuration.
All macro `.ngc` files live in `nc_files/subs/` and are loaded automatically via the `SUBROUTINE_PATH` setting in the INI.
## Mode Flags (Bitmask)
Several macros (`pocket_circ`, `pocket_rect`, `frame_rect`, `frame_circ`, `slot`) accept a `mode` parameter as a bitmask:
All material-removal macros (except drill/bore) take `mode` as the **first argument**:
| Bit | Value | Set (1) | Clear (0) |
|-----|-------|---------|-----------|
@@ -17,16 +19,17 @@ Default mode (0) = climb, one-way, helix entry, inside.
## Global Named Parameters
These optional globals configure macro behavior when set before calling:
| Parameter | Description | Required? |
|-----------|-------------|-----------|
| `#<_z_top>` | Top of material / start Z height | **Required** |
| `#<_z_bot>` | Final cut depth | **Required** |
| `#<_z_clearance>` | Safe Z retract height | Optional, falls back to `#<_z_top>` |
| `#<_rampang>` | Helix entry angle in degrees | Optional, defaults to 5.0 |
| `#<_stepover>` | Stepover distance | Optional, defaults to 40% of tool diameter |
| 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 |
Tool diameter is read automatically from `#5410` (the built-in LinuxCNC parameter for the current tool's diameter from the tool table). A tool must be loaded (`T M6 G43`) before calling any material-removal macro.
A negative `fincut` value causes macros to rough only, leaving material for a separate finishing pass.
A negative `fincut` value causes macros to rough only, leaving that amount of material for a separate finishing pass.
## M-Codes (Shell Scripts)
@@ -36,192 +39,117 @@ 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.
## Utility Subroutines
### z_home - Rapid to Machine Z0
Rapids the quill to machine Z=0 (fully up) using G53 to bypass all offsets.
```
o<z_home> call
```
## Drilling Subroutines
### drill.ngc - Peck Drill
Fully automatic drilling with optional peck cycle.
### drill - Peck Drill
```
o<drill> call [x][y] [ztop][zbot] [peck]
o<drill> call [x][y] [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. Retracts to Z Top between pecks with 0.020" rapid-approach gap.
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.
### drill_man - Manual Drill
```
o<drill_man> call [x][y]
```
Calls M102 to disable Z-axis, then M0 pause.
Calls M102 to disable Z, then M0 pause. No Z globals needed.
### 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.
### drill_retr - Semi-Manual Drill with Retract
```
o<drill_retr> call [x][y] [z_clearance]
o<drill_retr> call [x][y]
```
## Material Removal Subroutines
### pocket_circ.ngc - Circular Pocket
Cuts a circular pocket using an outward spiral from center.
### pocket_circ - Circular Pocket
```
o<pocket_circ> call [x][y] [diameter] [ztop][zbot] [fincut] [mode]
o<pocket_circ> call [mode] [x][y] [diameter] [fincut]
```
| # | 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.
### pocket_rect - Rectangular Pocket (Zigzag)
```
o<pocket_rect> call [x1][y1] [x2][y2] [zstart][zend] [fincut] [mode]
o<pocket_rect> call [mode] [x1][y1] [x2][y2] [fincut]
```
| # | 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 |
Zigzag along the long axis, stepping by `#<_stepover>`. Perimeter cleanup pass at the end.
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).
### frame_rect - Rectangular Frame
```
o<frame_rect> call [x1][y1] [x2][y2] [ztop][zbot] [mode] [radius]
o<frame_rect> call [mode] [x1][y1] [x2][y2] [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).
### frame_circ - Circular Frame
```
o<frame_circ> call [x][y] [diameter] [ztop][zbot] [fincut] [mode]
o<frame_circ> call [mode] [x][y] [diameter] [fincut]
```
| # | 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.
### slot - Slot / Obround
```
o<slot> call [x1][y1] [x2][y2] [width] [ztop][zbot] [fincut] [mode]
o<slot> call [mode] [x1][y1] [x2][y2] [width] [fincut]
```
| # | 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.
### bore - Helical Bore
```
o<bore> call [x][y] [d] [zstart][zend] [stepdown]
o<bore> call [x][y] [d] [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 |
No mode arg. Uses `#<_z_top>`, `#<_z_bot>`, and `#5410`.
Spirals down in full-circle passes, then does a partial-arc cleanup and spring pass at final depth. Returns to center and Z0.
### poly_frame - Polygon Perimeter
```
o<poly_frame> call [mode] [x][y] [n_sides] [apothem] [rotation] [fincut]
```
Apothem = flat-to-flat / 2. Rotation in degrees (0 = first vertex on +X, CCW positive).
### poly_pocket - Polygon Pocket
```
o<poly_pocket> call [mode] [x][y] [n_sides] [apothem] [rotation] [fincut]
```
## Typical Program Header
```
#<_z_clearance> = 0.0
```gcode
#<_z_clearance> = 0.2
#<_rampang> = 5.0
#<_z_top> = 0.05
#<_z_bot> = -0.25
G10 L1 P1 Z0.0 R0.25 ; set tool P1 offset and radius
T1 ; select tool
M06 ; manual toolchange
G10 L1 P1 Z0.0 R0.125 ; set tool 1 offset and 1/4" radius
T1 M6 ; load tool (sets #5410 = 0.250)
G43 ; activate TLO
M101 ; enable z-axis
G90 ; absolute coordinates
G54 ; fixture #1
M101 ; enable z-axis
G90 ; absolute coordinates
G54 ; fixture #1
F5.0 ; feedrate
F5.0 ; feedrate
o<pocket_circ> call [0] [0][0] [1.0] [0]
```
## Known Bugs
## Known Bugs & Limitations
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.
1. **Some combinations of values cause hangs.** LinuxCNC has no stall/timeout detection; a macro stuck in an infinite loop hangs the whole machine. Iteration limits have been added to pocket_circ's spiral loop as a safety measure.
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)
2. **Slot arc directions may be wrong under some combinations** — inverted arc ends seen under certain mode/geometry combinations.