How to Use PCB2GCode for CNC Milling: Complete Setup and Configuration Guide

After years of using GUI-based CAM software for PCB milling, I finally made the switch to pcb2gcode. The learning curve was steeper than clicking through FlatCAM’s interface, but the payoff has been substantial. Once configured, I can convert Gerber files to G-Code with a single command, and the output is consistently clean. This guide covers everything from installation to advanced features like Voronoi regions and autolevelling.

What Is PCB2GCode and Why Use It?

PCB2GCode is a command-line tool that converts Gerber and Excellon files into G-Code for CNC milling machines. Unlike GUI-based alternatives, pcb2gcode stores all your settings in a configuration file called “millproject” that you can version control, share between projects, and tweak without clicking through menus repeatedly.

The software handles three main operations: isolation routing (cutting around traces to separate them electrically), drilling holes for through-hole components and vias, and cutting the board outline to release it from the stock material. For each operation, it generates a separate G-Code file optimized for the task.

Key Advantages Over GUI Alternatives

The command-line approach offers several practical benefits for regular PCB milling work. You can automate the entire conversion process with shell scripts, integrate it into your design workflow with KiCad or Eagle, and maintain consistent settings across multiple projects. The millproject file becomes your documented record of exactly what parameters produced a successful board.

PCB2GCode also includes an integrated autoleveller that compensates for uneven board surfaces, a common problem with budget CNC machines and DIY setups. The Voronoi region feature reduces milling time significantly by only removing copper where electrical isolation is actually needed.

Installing PCB2GCode on Different Platforms

Installation varies by operating system, but all platforms can run pcb2gcode effectively once set up.

Linux Installation

On Debian and Ubuntu systems, pcb2gcode is available in the repositories, though the packaged version may be outdated. For the latest features, building from source is recommended:

bash

sudo apt-get install build-essential automake autoconf autoconf-archive libtool libboost-program-options-dev libgtkmm-2.4-dev gerbv git librsvg2-devgit clone https://github.com/pcb2gcode/pcb2gcode.gitcd pcb2gcodeautoreconf -fvi./configuremakesudo make install

For Arch Linux users, both stable and git versions are available through the AUR.

macOS Installation

The easiest path on macOS is through Homebrew. Open Terminal and run:

bash

brew install pcb2gcode

This installs pcb2gcode along with all required dependencies automatically.

Windows Installation

Windows binaries are sometimes available on the GitHub releases page, though they may lag behind the current version. For reliable Windows installation, building with MSYS2 works well. Download MSYS2, then install the required packages and compile from source following the instructions in the project’s README.

Understanding the Millproject Configuration File

The heart of pcb2gcode is the millproject file. This plain text configuration stores all your parameters, and pcb2gcode automatically reads it when run from the same directory. Creating a well-tuned millproject eliminates repetitive command-line typing and ensures consistent results.

Basic Millproject Structure

Here is a complete millproject template with explanations:

# Units and output formatmetric=truemetricoutput=truezero-start=true# Safety heightszsafe=2.0zchange=10.0# Input files (uncomment and modify for your project)#back=board-B_Cu.gbr#drill=board.drl#outline=board-Edge_Cuts.gbr# Isolation milling parameterszwork=-0.1mill-feed=400mill-speed=10000mill-diameters=0.2isolation-width=0.5extra-passes=1# Drilling parameterszdrill=-2.0drill-feed=100drill-speed=10000# Board cutout parameterszcut=-1.8cutter-diameter=1.0cut-feed=100cut-speed=10000cut-infeed=0.5# Output optimizationoptimise=true

Lines starting with # are comments. Options are specified as name=value pairs without the double dashes used on the command line.

PCB Design Considerations for CNC Milling

Designing boards intended for CNC milling requires different thinking than boards destined for commercial fabrication. The tolerances and constraints are quite different.

Trace Width and Spacing

Commercial fabs routinely handle 0.15mm (6 mil) traces and spacing. Desktop CNC machines struggle with anything below 0.25mm. Design with generous 0.4mm or wider traces wherever possible. This provides margin for bit wear, machine imprecision, and variations in copper thickness.

The spacing between traces matters even more than trace width. Set your design rules to at least 0.4mm clearance, preferably 0.5mm. With a typical V-bit creating 0.2mm cuts, this leaves room for the isolation path plus some safety margin.

Component Selection

Through-hole components with 2.54mm pitch work perfectly with milled boards. Surface-mount parts are achievable but require more care. SOIC packages with 1.27mm pitch work well. Anything finer than 0.65mm pitch pushes the limits of typical desktop mills.

Avoid QFN and BGA packages entirely for milled prototypes. The tolerances required are beyond what home milling achieves reliably.

Use Wide Pads

Increase pad sizes beyond the minimum required for your components. Larger pads are easier to solder and more forgiving of registration errors between the copper and drill operations. A component with 0.8mm holes works fine with 1.6mm or larger pads.

Ground Planes and Copper Pours

Large copper areas require extensive milling to isolate, wearing out your bit and extending job time dramatically. Consider using hatched fills instead of solid pours, or simply avoid copper pours on milled boards. If you need a ground plane, use Voronoi mode which handles this more efficiently.

Essential Parameters Explained

Getting the parameters right determines whether your board mills successfully or becomes scrap. Here are the critical settings organized by function.

Milling Parameters

Parameter	Description	Typical Value
zwork	Depth of isolation cut below surface	-0.05 to -0.15 mm
mill-feed	Horizontal feed rate during milling	200-600 mm/min
mill-speed	Spindle RPM for milling	8000-30000
mill-diameters	Effective cutting width of V-bit	0.1-0.3 mm
isolation-width	Total width of isolation gap	0.3-0.8 mm
extra-passes	Additional passes for wider isolation	0-3

The mill-diameters value deserves special attention. For V-bits, this is not the diameter of the bit itself but the effective cutting width at your specified zwork depth. A 60-degree V-bit cutting at 0.1mm depth creates an approximately 0.28mm wide cut. Calculate this based on your bit geometry.

Drilling Parameters

Parameter	Description	Typical Value
zdrill	Drilling depth below surface	-1.8 to -2.5 mm
drill-feed	Plunge feed rate	50-200 mm/min
drill-speed	Spindle RPM for drilling	8000-20000
onedrill	Use single drill for all holes	true/false
milldrill	Mill holes instead of drilling	true/false

Setting onedrill=true combines all holes into one operation, useful when you want to avoid tool changes. The milldrill option uses an end mill to create holes by helical milling, handy when you lack proper drill bits.

Cutting Parameters

Parameter	Description	Typical Value
zcut	Final cutting depth	-(board thickness + 0.2mm)
cutter-diameter	Diameter of cutout end mill	1.0-2.0 mm
cut-feed	Horizontal feed during cutout	50-150 mm/min
cut-infeed	Depth per cutting pass	0.3-0.8 mm
bridges	Number of holding tabs	2-4
bridgesnum	Alternative tab specification	2-4

The cut-infeed parameter controls how deep each pass goes. Multiple shallow passes are gentler on small end mills than plunging through in one shot.

Step-by-Step Workflow

Let me walk through the complete process from design files to G-Code.

Step 1: Export Gerber Files from Your PCB Software

In KiCad, go to File, then Fabrication Outputs, then Gerbers. Select the copper layer (B_Cu for single-sided boards), edge cuts, and generate. Then export the drill file separately as Excellon format.

Name your files consistently. KiCad typically produces files like project-B_Cu.gbr for the bottom copper and project.drl for drilling.

Step 2: Create Your Millproject File

In the same directory as your Gerber files, create a file named exactly “millproject” (no extension). Add your parameters, specifying the input files:

metric=truemetricoutput=truezero-start=trueback=myboard-B_Cu.gbrdrill=myboard.drloutline=myboard-Edge_Cuts.gbrzsafe=2.0zchange=10.0zwork=-0.08mill-feed=400mill-speed=12000mill-diameters=0.2isolation-width=0.4zdrill=-2.0drill-feed=100drill-speed=10000zcut=-1.8cutter-diameter=1.5cut-feed=80cut-speed=10000cut-infeed=0.5bridges=2

Step 3: Run PCB2GCode

Open a terminal in your project directory and run:

bash

pcb2gcode

The software reads your millproject file automatically and generates the G-Code files. By default, you get back.ngc for isolation routing, drill.ngc for drilling, and outline.ngc for the board cutout.

Step 4: Verify Output

Before sending to your machine, preview the G-Code in a simulator like Camotics or your CNC controller’s preview function. Look for complete isolation around traces, correct hole positions, and a sensible cutout path.

Advanced Features

Voronoi Region Milling

Standard isolation milling cuts a fixed-width path around each trace. Voronoi mode instead divides the entire copper surface into regions, milling only where necessary to separate adjacent traces. This dramatically reduces milling time on sparse boards.

Enable Voronoi with:

voronoi=true

Alternatively, set a very large offset value (like offset=50), and pcb2gcode automatically generates Voronoi-style regions. The result looks unusual but mills much faster and is easier on your bits.

Autoleveller for Uneven Surfaces

Budget CNC machines and copper-clad boards rarely provide a perfectly flat surface. The autoleveller feature probes a grid of points across your board, then adjusts Z coordinates in the G-Code to follow the measured surface.

Enable autolevelling with:

al-back=truesoftware=linuxcncal-x=5al-y=5al-probefeed=50

The software parameter must match your CNC controller because probing commands differ between LinuxCNC, Mach3, Mach4, and others. If using GRBL, you will need external autolevelling software like bCNC instead.

GRBL Compatibility

GRBL and similar lightweight controllers do not support the G81 canned drilling cycle. Add this option to generate compatible G-Code:

nog81=true

This replaces the compact G81 commands with explicit G0 and G1 moves. The output file becomes larger but works on any controller.

Common Problems and Solutions

Traces Not Fully Isolated

When traces remain connected after milling, the isolation width is insufficient. Increase mill-diameters to match your actual cut width, add extra-passes for wider gaps, or increase isolation-width directly.

Holes in Wrong Position

Coordinate misalignment between copper and drill files usually indicates a units mismatch or different origin points in your Gerber exports. Ensure all files use the same units (metric recommended) and origin. The zero-start=true option helps by resetting coordinates to start at (0,0).

Inconsistent Cut Depth

Uneven cutting depth across the board indicates a surface levelness problem. Either surface your spoilboard, implement autolevelling, or use double-sided tape with a thin superglue layer to bond the PCB flat against the bed.

G-Code Incompatible with Controller

If your CNC refuses to run the output, check for unsupported commands. Set nog81=true for GRBL compatibility. For metric output, ensure both metric=true and metricoutput=true are set. Some controllers need software=custom with additional probe settings.

Useful Resources and Downloads

Software Downloads

The pcb2gcode source code and releases are available at github.com/pcb2gcode/pcb2gcode with installation instructions for all platforms.

The pcb2gcodeGUI provides a graphical interface wrapper at github.com/pcb2gcode/pcb2gcodeGUI for those who prefer clicking over typing.

G-Code Senders

bCNC at github.com/vlachoudis/bCNC includes integrated autolevelling that works independently of pcb2gcode’s autoleveller, useful for GRBL users.

Universal G-Code Sender (UGS) at winder.github.io/ugs_website provides reliable streaming to GRBL controllers.

Simulation and Preview

Camotics at camotics.org offers free G-Code simulation for verifying your toolpaths before cutting.

Documentation

The complete pcb2gcode manual is available on the project wiki at github.com/pcb2gcode/pcb2gcode/wiki/Manual with all parameters documented.

The millproject_example file in the repository shows a working configuration you can adapt.

Recommended Millproject Configurations

Here are tested configurations for different scenarios:

Basic Single-Sided Board

metric=truemetricoutput=truezero-start=truezsafe=2.0zchange=10.0zwork=-0.08mill-feed=400mill-speed=10000mill-diameters=0.2isolation-width=0.4zdrill=-2.0drill-feed=100nog81=true

SMD Board with Fine Traces

metric=truemetricoutput=truezero-start=truezsafe=1.5zchange=10.0zwork=-0.05mill-feed=300mill-speed=15000mill-diameters=0.1isolation-width=0.3dpi=2000optimise=true

Quick Prototyping with Voronoi

metric=truemetricoutput=truezero-start=truezsafe=2.0zchange=10.0zwork=-0.08mill-feed=500mill-speed=12000mill-diameters=0.2voronoi=truepreserve-thermal-reliefs=truezdrill=-2.0onedrill=truenog81=true

Frequently Asked Questions

What is the difference between pcb2gcode and FlatCAM?

Both tools convert Gerber files to G-Code for PCB milling, but they take different approaches. FlatCAM provides a graphical interface where you configure each operation visually, while pcb2gcode uses a configuration file and command-line execution. FlatCAM is easier for beginners and occasional use. Pcb2gcode excels when you want automated, repeatable conversions or need to integrate G-Code generation into scripts and build systems.

How do I calculate mill-diameters for my V-bit?

The mill-diameters value represents the effective cutting width at your specified zwork depth, not the bit diameter. For a V-bit with angle θ and cutting depth d, the formula is: width = 2 × d × tan(θ/2). For a 60-degree bit at 0.1mm depth, this gives approximately 0.115mm. Add any tip flat width if your bit has one. Many users start with a value slightly larger than calculated and adjust based on actual results.

Can I use pcb2gcode with GRBL controllers?

Yes, but with some configuration. GRBL does not support the G81 canned drilling cycle, so you must add nog81=true to your millproject. GRBL also requires metric output, so include both metric=true and metricoutput=true. The built-in autoleveller does not work with GRBL because it uses controller-specific probing macros. For GRBL autolevelling, use external software like bCNC or Candle that processes the G-Code after pcb2gcode generates it.

What does the voronoi option actually do?

Standard isolation milling traces a fixed-width path around each copper feature. Voronoi mode instead calculates regions where each point on the board is closest to a particular copper feature, then mills only the boundaries between these regions. The result removes far less copper, reducing milling time and tool wear. The board looks different with large copper areas between traces, but electrically it functions identically.

How do I handle double-sided boards?

For double-sided boards, pcb2gcode generates separate G-Code files for the front and back copper layers. The challenge is alignment when you flip the board. Use the mirror-axis parameter to specify where the board flips. Drill alignment holes first, flip the board around the mirror axis, and use pins through the alignment holes to maintain registration. The drill-front option places drill coordinates relative to the front side, which some users find easier for alignment.

Tips from Experience

After milling dozens of boards with pcb2gcode, here are practical insights that the documentation does not emphasize.

Dial In Your Bit First

Before trusting any mill-diameters value, run a test cut on scrap copper-clad. Cut a single straight line at your intended zwork depth, measure the actual width with calipers or a microscope, and use that measured value. Bit tip shapes vary between manufacturers, and even stated angles can be off by several degrees.

Keep Multiple Millproject Templates

Rather than modifying one file constantly, maintain separate millproject templates for different scenarios. I keep one for quick prototypes with Voronoi, one for fine-pitch SMD work, and one for power boards with wide traces. Copy the appropriate template into each project directory and adjust only the file names.

Version Control Your Configuration

Since millproject is plain text, it belongs in git alongside your PCB design files. When a board mills perfectly, commit that configuration. When you experiment with new settings, you can always revert to what worked. This habit has saved me from recreating settings I had forgotten.

Test with Single Traces First

When bringing up a new machine or trying new parameters, do not run a full board immediately. Export a test Gerber with just a few traces and pads, convert it, and mill that first. You will waste less copper learning what parameters actually work for your setup.

Mind Your Spindle Runout

On budget machines, spindle runout effectively widens your cut. If your spindle has 0.05mm runout and you are cutting with a 0.1mm effective width, you might actually remove 0.15mm or more. This is another reason to measure actual cuts rather than trusting calculations.

Conclusion

PCB2GCode rewards the time invested in learning its configuration system. Once you have a working millproject file for your machine and typical board parameters, converting new designs becomes a single-command operation. The consistency and repeatability beat clicking through GUI dialogs, especially when you are iterating on a design and regenerating G-Code multiple times per day.

Start with a conservative configuration, verify the output in simulation, and adjust based on actual results. Keep notes in your millproject comments about what works for different scenarios. Over time, you will build a library of configurations that produce reliable boards with minimal fiddling.