pcb2cnc

pcb2cnc is a Python CLI tool designed to orchestrate the conversion of PCB Gerber files into CNC compatible G-code. It serves as an intelligent wrapper and post-processor around pcb2gcode, automating tool selection, configuration generation, and G-code optimization. It is intended for use with the the Carbide3D Nomad series of desktop CNC mills, but may be usable with other CNC machines.

If you are milling custom PCBs on a CNC machine, this tool eliminates the manual tediousness of setting up pcb2gcode configurations, and ensures your feeds, speeds, and tool geometries are correctly calculated. Simply generate Gerber files using your favorite PCB design software, then use pcb2cnc to convert them to a single machine-ready G-code job.

Installation

First, make sure you have the following prerequisites installed:

• Python 3.13 or higher
• pcb2gcode available in your system's PATH

Then install the CLI by cloning the repository and making it executable:

git clone https://github.com/google/makerspace-pcb2cnc.git
cd pcb2cnc
chmod +x pcb2cnc.py

Configuration

pcb2cnc expects a configuration file in TOML format, named pcb2cnc.toml. It will search for it in the input directory first, alongside your Gerber files. If it's not present there, it will look in $XDG_CONFIG_HOME (~/.config by default), or if it's not found there, it will use a default configuration shipped with the tool. You can override this and use a specific config by passing the --config flag.

The default configuration that ships with pcb2cnc is suitable for Carbide3D Nomad machines, and includes the endmills, engravers, and drill bits in the Carbide3D ecosystem most commonly used for PCB milling. If you have additional bits you would like to use, or want to make changes to this configuration, see the full documentation of pcb2cnc.toml.

Usage

Run the pipeline

To generate configuration, run pcb2gcode, and post-process the output all in one step, use the run command. Point it to a directory containing your Gerber files:

./pcb2cnc.py run /path/to/gerber/dir \
    --output-back back.gcode \
    --copper-side back

Postprocess existing G-code

If you already have raw .ngc files generated by pcb2gcode in a directory, you can run the post-processing step directly to apply tool changes, safe feed rates, and cleanup:

./pcb2cnc.py postprocess /path/to/raw/gcode/dir \
    --output-front finalized_front.gcode \
    --output-back finalized_back.gcode \
    --copper-side front_and_back

Inspect the millproject configuration

To generate and print the millproject configuration that would be passed to pcb2gcode (based on your TOML configuration), use the millproject command:

./pcb2cnc.py millproject

You can write the millproject configuration to a file using shell redirection:

./pcb2cnc.py millproject > millproject

You can then use that configuration to run pcb2gcode manually, or load it into pcb2gcodeGUI for a more visual look at your project's generated G-code files.

Recommended Gerber settings

When exporting your Gerbers from your PCB design software, pcb2gcode, and thus pcb2cnc, expects your output to meet these requirements:

• Gerber files
  • X2 Gerber format
  • Each layer in a separate file, with only that layer's contents - do not plot the outline on copper layers
  • Layers other than top/bottom copper and board outline will be ignored
  • May use -{layername}.gbr file suffix, or Protel extensions (.gtl, .gbl, .gm1, etc.)
  • All Gerber files in one directory
• Drill files
  • Excellon format
  • .drl file extension
  • Saved in the same directory as the Gerber files
  • Plated and non-plated through holes in the same file
  • Same unit system and origin as Gerber files
  • No routing-mode (G01/02/03) commands - use G85 for slots
    • KiCad users: enable "Use alternate drill mode for oval holes"

How to contribute

If you'd like to contribute to pcb2cnc, please review CONTRIBUTING.md and then submit a pull request!

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Disclaimer

This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.