GUIDE FOR USING AUTOLEVELLER WITH MACH3 USB
https://drive.google.com/file/d/1togonx ... drive_link
Table of Contents
I. Overview of AutoLeveller 2
II. Issues with Chinese Mach3 USB Controller Boards 3
III. Tested Solutions for Each Issue 3
1. Fixing Unstable G31 Execution in G-code 3
2. Fixing the Issue of Variables #2000, #2001, #2002 Not Updating 3
3. Fixing the Issue of X–Y–Z Triplet File Not Being Written 4
IV. Implementing the Complete Solutions in MACH3 4
1. Contents of Macro M2001.M1S 4
2. Contents of Macro M2002.M1S 5
3. Contents of Macro M2003.M1S 5
V. Configuring Operating Modes in AutoLeveller 6
1. Configuring Custom Controller Options 6
2. Configuring Z Initialisation Routine 6
VI. AutoLeveller Operating Procedure 8
1. Open the Original G-code File 8
2. Generate the Probe File G-code (PFG) 11
3. Load the PFG File into Mach3 11
4. Load the Probe Result into AutoLeveller and Generate Corrected G-code 12
VII. Conclusion 13
I. Overview of AutoLeveller
AutoLeveller is a software tool that assists in CNC height compensation based on the actual surface of the workpiece. A typical example is PCB milling calibration, where the surface height of a PCB is probed at multiple points to generate a height map. This height map is then used to modify the original G-code, compensating for surface height deviations and producing a new corrected G-code file.
Thanks to this process, it becomes possible to mill extremely fine and uniform traces on thin copper layers of PCBs.
• PCB milled without AutoLeveller: traces are uneven; some areas are too deep, some too shallow, and some areas do not fully remove the copper.
• PCB milled with AutoLeveller: traces are uniform, clean, and visually consistent.
PCB milled without AutoLeveller PCB milled with AutoLeveller
Figure 1. PCB milling with and without AutoLeveller
Detailed videos explaining how AutoLeveller works can be found here and here.
In general, AutoLeveller works perfectly with standard CNC controllers such as Mach3 LPT, LinuxCNC, and TurboCNC. However, when used with Chinese-made Mach3 USB controller boards, serious issues arise. This guide exists to address those issues.
Specifically, when used with Mach3, AutoLeveller relies on the G31 probing command. Unfortunately, G31 is often buggy on Chinese Mach3 USB controllers, resulting in unstable behavior or complete failure.
________________________________________
II. Issues with Chinese Mach3 USB Controller Boards
The following problems are commonly observed:
1. G31 runs correctly in MDI mode, but hangs or fails to complete when executed inside a G-code or script file together with other commands.
2. G31 does not update system variables #2000, #2001, and #2002, which should store the precise X, Y, and Z coordinates at the moment the probe is triggered.
3. According to Mach3 design, G31 should write the X–Y–Z triplet to a file opened by macro M40. However, in practice, the Mach3 USB plugin fails to write any data.
The file containing the X–Y–Z triplets is critical input data for AutoLeveller to generate the height map. Therefore, this issue is severe and must be addressed.
________________________________________
III. Tested Solutions for Each Issue
1. Fixing Unstable G31 Execution in G-code
An attempt was made to add delays before and after the G31 command using macros:
Sleep 500
While IsMoving()
Sleep 200
Wend
This code creates:
• A fixed delay
• A wait loop until all axes stop moving
However, in practice, G31 still behaved unpredictably.
The only reliable solution is to require manual user confirmation:
' Ask user to confirm axes are idle before starting G31
StartG31 = Question("Start G31?")
' Ask user to confirm G31 has completed before continuing
FinishG31 = Question("Finished G31?")
2. Fixing the Issue of Variables #2000, #2001, #2002 Not Updating
After G31 completes, manually update the variables using DRO values:
' G31 does not update variables 2000, 2001, and 2002
SetVar(2000, GetDro(0))
SetVar(2001, GetDro(1))
SetVar(2002, GetDro(2))
3. Fixing the Issue of X–Y–Z Triplet File Not Being Written
Instead of using the file opened by macro M40, a custom file is created and written manually:
' Read X, Y, Z values
x = GetDro(0)
y = GetDro(1)
z = GetDro(2)
' Open heightmap file and append data
Open "C:\heightmap.txt" For Append As #1
Write #1, x, y, z
Close #1
This file will be used directly by AutoLeveller instead of the default triplet file.
________________________________________
IV. Implementing the Complete Solutions in MACH3
Use Mach3’s built-in Script Editor or a standard text editor such as Notepad or Notepad++ to create the following macro files:
• M2001.m1s
• M2002.m1s
• M2003.m1s
Place them in the directory:
C:\Mach3\macros\Mach3Mill\
1. Contents of Macro M2001.M1S
'====================================================
' File location: C:\Mach3\macros\Mach3Mill\M2001.M1S
' M2001 - PRE PROBE ROUTINE
' Function:
' - Wait for axis stabilization
' - Require user confirmation before G31
'====================================================
Const DELAY_START = 500
Const DELAY_WAIT = 200
Sleep(DELAY_START)
While IsMoving()
Sleep(DELAY_WAIT)
Wend
StartG31 = Question("Start G31 probing now?")
2. Contents of Macro M2002.M1S
'====================================================
' File location: C:\Mach3\macros\Mach3Mill\M2002.M1S
' M2002 - POST PROBE ROUTINE
' Function:
' - Wait for G31 completion
' - Read X,Y,Z from DRO
' - Update variable #2002
' - Append data to heightmap file
'====================================================
Const DELAY_START = 500
Const DELAY_WAIT = 200
Const HEIGHTMAP_FILE = "G:\heightmap.txt"
Sleep(DELAY_START)
While IsMoving()
Sleep(DELAY_WAIT)
Wend
ProbeDone = Question("Finished G31 probing?")
Dim x, y, z
x = GetDro(0)
y = GetDro(1)
z = GetDro(2)
SetVar(2000, x)
SetVar(2001, y)
SetVar(2002, z)
Open HEIGHTMAP_FILE For Append As #1
Write #1, x, y, z
Close #1
3. Contents of Macro M2003.M1S
'====================================================
' File location: C:\Mach3\macros\Mach3Mill\M2003.M1S
' M2003 - INITIALIZE HEIGHTMAP FILE
' Function:
' - Wait for axis stabilization
' - Manual confirmation
' - Reset variable #2002
' - Create new heightmap file
'====================================================
Const DELAY_START = 500
Const DELAY_WAIT = 200
Const HEIGHTMAP_FILE = "C:\heightmap.txt"
Sleep(DELAY_START)
While IsMoving()
Sleep(DELAY_WAIT)
Wend
FinishG31 = Question("Initialize new heightmap file?")
SetVar(2000, GetDro(0))
SetVar(2001, GetDro(1))
SetVar(2002, GetDro(2))
Open HEIGHTMAP_FILE For Output As #1
Close #1
________________________________________
V. Configuring Operating Modes in AutoLeveller
This configuration only needs to be done once. AutoLeveller will remember the settings for future use.
________________________________________
1. Configuring Custom Controller Options
From the AutoLeveller menu:
• Select Options
• Select Custom Controller Options
Set:
• Pre-probe command: M2001
• Post-probe command: M2002
Figure 2. Configuration for user-defined custom controller options
________________________________________
2. Configuring Z Initialisation Routine
Z initialisation defines the probing initialization process and sets Z = 0 at the first probe point, which is then used as the reference for calculating surface deviations across the probing grid.
Steps:
1. In AutoLeveller, go to Options → Z initialisation routine
2. Enable Use default block and copy the default code
3. Enable Use custom block and paste the copied code
4. Replace M2002 with M2003
5. Click Apply to save
Repeat the same steps for both the PFG File and AL File tabs.
Enable Use default block and copy the default code Enable Use custom block and paste the copied code. Replace M2002 with M2003
Figure 3. Z initialisation configuration
________________________________________
VI. AutoLeveller Operating Procedure
1. Open the Original G-code File
The Original G-code File (OGF) is the file that needs height correction before actual milling.
In this example, the file is spindle.top.etchm3mm.tap.
This file is typically generated by PCB-to-G-code software such as:
• CopperCAM (commercial, paid or limited free version)
• FlatCAM (powerful and completely free)
Steps:
a. Click Load OGF in AutoLeveller
b. Select the original G-code file
c. When prompted to adjust the probing grid to the G-code extents, select YES
d. The screen displays the loaded G-code
a. Click Load OGF in AutoLeveller b. Select the original G-code file
c. When prompted to adjust the probing grid to the G-code extents, select YES d. The screen displays the loaded G-code
Figure 4. Opening the original G-code file
You may then adjust probing parameters if desired.
Figure 5. Adjust probing parameters if desired
________________________________________
AutoLeveller Parameter Descriptions
Controller
Select the appropriate controller:
• Mach3 → for Mach3 LPT systems
• Custom → for Mach3 USB controllers using this guide
Starting X / Starting Y
Starting coordinates of the probing grid
X Width / X Length
Dimensions of the probing area
XY feed
Feed rate for X–Y movement during probing (mm/min)
Z feed
Z-axis feed rate during probing (mm/min)
Probe depth
Maximum allowed Z probing depth.
For 3D probes, -1 mm is recommended to avoid probe damage.
Probe clearance
Height above the surface where slow probing begins
Point space
Distance between probing points
Probe safe height
Safe Z height for rapid movement between probe points
Total points / Points per row / Rows
Automatically calculated probing grid parameters
Figure 6. 3D probe
________________________________________
2. Generate the Probe File G-code (PFG)
After loading the OGF:
• Click GENERATE PFG
• Choose the save location and filename
• Example: PFG~100x80.nc
Figure 7. Generating the probe G-code file
________________________________________
3. Load the PFG File into Mach3
Load PFG~100x80.nc into Mach3.
Figure 8. Loading the PFG file into Mach3
Ensure the probe is functioning correctly before running the program.
Press Cycle Start to begin probing.
During execution, Mach3 will request manual confirmation:
• Before starting G31
• After completing G31
Although inconvenient, this method is reliable.
After completion, the file C:\heightmap.txt will be created, containing the surface height map.
Macros M40 and M41 are still present, so Mach3 may request a triplet file name, but this file is no longer used.
________________________________________
4. Load the Probe Result into AutoLeveller and Generate Corrected G-code
After probing:
• Go to File → Raw Probe File
• Select C:\heightmap.txt
AutoLeveller will use this file to generate the corrected G-code.
Figure 9. Actual surface height map
Click AutoLevel to generate the final corrected G-code file.
Use this file for actual CNC milling.
________________________________________
VII. Conclusion
This solution enables AutoLeveller to work reliably with Chinese Mach3 USB controller boards that have defective G31 behavior. Although manual confirmation before and after each G31 command is inconvenient, it ensures stable and accurate probing, allowing AutoLeveller to function correctly.
