pcb2gcode man page
pcb2gcode — command-line tool for engraving PCBs using CNCs
This manual page documents briefly the pcb2gcode command.
pcb2gcode is a program that takes the files typically produced by PCB (printed circuit board) designing tools, in particular Gerber (RS-274X) and Excellon (an RS-274C variant) files as parsed by gerbv, and produces files that can be used to control a CNC (computer numerical control) milling machine. These files are in G code format (RS-274D/NGC) that can be read, for example, by the linuxcnc EMC2 system.
When these files are executed, an engraving bit is used to remove the surface from a copper covered circuit board, thus creating isolated areas. In another step, holes are drilled into the board at the appropriate positions, and it can be cut out in another step. (For each step, a separate output file is created.)
These programs follow the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.
Instead of passing all options on the command line, nearly all options can be stored in a file named millproject. There, options are given one per line as option=value pairs (without the two dashes), and can be separated by blank lines and commented (everything after a `#` character is treated as a comment). Options that don't take an argument (like --metric) are entered as option=true or option=1 there.
Unless configured otherwise, numeric values are in units of inch and inch/minute. When the --metric option is given, they are in mm and mm/minute.
- --front filename.gbr
Engrave the front side according to the given file (typically used in two-sided boards).
- --back filename.gbr
Engrave the back side according to the given file.
- --outline filename.gbr
Cut out the board to the shape exposed in the given file. Typically, there is only a polygon in this gerber file. Alternatively, this file can contain a closed line chain (see --fill-outline). This option is enabled by default, to disable it use --fill-outline=false
- --drill filename.cnc
Convert the given file (containing drill sizes and positions) to G-code.
- --preamble-text filename
gcode text preamble file, inserted at the very beginning as a comment. All the round parenthesis will be converted to angled parenthesis (due to gcode's comments limitations). You can use this to include the license header at the top of the gcode output files.
- --preamble filename.ngc
gcode preamble file, inserted at the very beginning
- --postamble filename.ngc
gcode postamble file, inserted before M9 and M2
- --tolerance unit
maximum deviation from toolpath
do not explicitly set G64 inside the output gcode. This option makes the gcode compatible with low-end cnc controllers (like grbl)
For every option --x that takes a filename, there is an --x-output option that specifies where the resulting G-code is saved, defaulting to x.gbr. Instead of giving each output file name, the --basename option can be used; the base name will be used as a prefix to the default output file names. You can also specify the output directory with --output-dir; if unspecified, the output files will be created in the current directory.
The parameters that define engraving are:
- --zwork unit
Z-coordinate at which engraving happens
- --zsafe unit
Z-coordinate for movements between engraving steps
- --mill-feed unit/minute
feed rate at which engraving takes place (horizontal speed)
- --mill-vertfeed unit/minute
vertical mill feed rate used at the start of each engraving path. If unspecified, --mill-feed/2 will be used.
- --mill-speed rpm
spindle speed during engraving (rounds per minute)
- --offset unit
distance by which the tool movement will be outset from the contours in the gerber file to be engraved. If you want to obtain a PCB as similar as possible to the original file, you should set this value to half of the tool diameter.
If this distance can't be satisfied because copper areas are too close, a warning will be printed and the line will be drawn between the areas. This behavior can be used to get voronoi-style (flood-filling) areas; simply set the offset to a large value (like 1 inch). When the vectorial mode is in use, --voronoi is preferred.
enable the voronoi mode (requires --vectorial). This option is more efficient than a large --offset value, and provides the same result.
- --extra-passes number
number of additional isolation passes For each extra pass, engraving is repeated with the offset width increased by half its original value, creating wider isolation areas. This option is ignored when --voronoi is in use.
The parameters that define drilling are:
- --zdrill unit
Z value down to which will be drilled
- --zchange unit
Z-coordinate for movements with the drill head
- --drill-feed unit/minute
feed rate for drilling (vertical speed)
- --drill-speed rpm
spindle speed during drilling (rounds per minute)
If --milldrill is given, the milling head will be used to drill the holes in the PCB. Holes up to the size of the milling head will be drilled regularly (possibly creating a bigger hole than intended), the other holes are created by moving the head in circles using the feed and infeed parameters used in cutting.
- --milldrill-diameter unit
diameter of milling head which is used with --milldrill; the default value is same as --cutter-diameter.
- --drill-side side
choose the drill side. Valid choices are front, back or auto (default). In auto mode the drill side is automatically chosen (always front unless only the back side is specified)
use only one drill bit size
replace G81 with G0+G1. This option makes the gcode compatible with low-end cnc controllers (like grbl), but also makes it bigger and less clean
do not explicitly set G91.1 (incremental arc mode distance) in drill headers. Some controllers (like Roland's) does not support G91.1 and they can wrongly interpret it as G91 (relative distance). Since the default mode is usually "incremental", you can safely remove G91.1 in most of the cases
Outline cutting takes another set of options:
- --cutter-diameter unit
amount by half of which the tool path is outset from the shape in the outline file
- --zcut unit
Z-coordinate indicating where the outline cutting ends
- --cut-feed unit/minute
feed rate at which outline cutting takes place (horizontal speed)
- --cut-vertfeed unit/minute
vertical cut feed rate used at the start of each cutting path. If unspecified, --cut-feed/2 will be used.
- --cut-speed rpm
spindle speed during outline cutting (rounds per minute)
- --cut-infeed unit
maximum Z distance that is cut away in a single pass (positive value; if less then zcut's value, there will be more than one pass)
If --fill-outline is given, it is assumed that the outline file contains not a polygon but a closed chain of lines. The board will be cut along the centres of these lines.
- --outline-width unit
thickness of the lines that form the outline (if --fill-outline is given); the default value is 0.15 mm/0.059 in.
- --cut-side side
choose the cut side. Valid choices are front, back or auto (default). In auto mode the cut side is automatically chosen (always front unless only the back side is specified)
- --bridges unit
add bridges with the given width to the outline cut. --bridgesnum bridges will be created for each outline closed line. This option requires --optimise
- --zbridges unit
bridges height (Z-coordinates while engraving bridges, default to zsafe)
- --bridgesnum number
sets the numer of bridges to be created (--bridgesnum bridges for each closed line)
The autoleveller feature allows you to mill your project on a surface that isn't at exactly the same height in every point. To use the autoleveller feature you need a probe tool connected to your machine. The autoleveller process is composed by two parts:
- Initial probing, where the machine "probes" a grid of points and save their heights. In order to save probing time, only the area where the PCB will be milled will be probed.
- Actual milling, identical to the standard process, but with an additional Z-correction (based on a bilinear interpolation of the probed points)
Unfortunately each control software (LinuxCNC, Mach3, ...) uses different gcodes for the probing, the parameters and the macros, therefore the output gcode won't be software-independent, and you have to choose the used software with the option --software. For compatibility reasons, the gcode generated with --software=Custom is much bigger than the gcode for a supported software.
enable the autoleveller for the front side
enable the autoleveller for the back side
- --al-x unit
the width of the probing on the X axis. Lower values increase the levelling precision but also increase the probing time (but not the milling time)
- --al-y unit
the width of the probing on the Y axis. Lower values increase the levelling precision but also increase the probing time (but not the milling time)
- --al-probefeed unit/second
probe speed on the Z axis. Higher values decrease the probing time but also increase the wear of the probing tool
- --al-probe-on command(s)
insert these commands at the start of the probing sequence, replacing the standard M0 command. You can use this argument to add a M64/M65 command (LinuxCNC) to automatically enable the probe tool. Use an at sign (@) to insert a newline
- --al-probe-off command(s)
insert these commands at the end of the probing sequence, replacing the standard M0 command. You can use this argument to add a M64/M65 command (LinuxCNC) to automatically disable the probe tool. Use an at sign (@) to insert a newline
- --al-probecode code
custom Z probe code. For example, LinuxCNC uses G38.2 while Mach3, Mach4 and TurboCNC use G31. If unspecified, G31 will be used. This option is relevant only when --software=custom
- --al-probevar number
custom Z probe result variable. For example, LinuxCNC and Mach4 use 5063 while Mach3 and TurboCNC use 2002. If unspecified, 2002 will be used. This option is relevant only when --software=custom
- --al-setzzero code
custom gcode for setting the current height as the zero of the Z axis. For example, LinuxCNC uses G10 L20 P0 Z0 while Mach3, Mach4 and TurboCNC use G92 Z0. If unspecified, G92 Z0 will be used. This option is relevant only when --software=custom
pcb2gcode can repeat the PCB in a tile-x times tile-y grid of identical PCBs. This feature can be activated by specifying the number of columns and rows with --tile-x and --tile-y. If you don't specify a software, or if you use --software=Custom, the resulting Gcode will be much bigger (about original_size * tile-x * tile-y).
- --tile-x columns
number of tiling columns. Default value is 1.
- --tile-y rows
number of tiling rows. Default value is 1.
These options govern the general behavior of pcb2gcode:
enable the EXPERIMENTAL vectorial core. This new core offers much better performances, higher precision, smaller output files and support for internal cutoffs (like thermal pads). When --vectorial is enabled, --dpi is ignored.
- --software software
specify the gcode interpreter software; currently supported programs are LinuxCNC, Mach3, Mach4 and custom. With custom you can specify al-probecode, al-probevar and al-setzzero, in order to generate gcode for an unsupported software.
optimise the output gcode with Douglas-Peucker, reducing its output size up to 95% (while accepting a very little loss of precision). This option is enabled by default, to disable it use --optimise=false
- --dpi dpi
resolution used internally (defaults to 1000). If the software freezes during the layer exporting, try to increase the dpi value. Sane values for dpi are 1000/2000 for through-hole PCBs and 2000/4000 dpi for SMT PCBs.
mirror operations on the back side along the Y axis instead of the board center, which is the default
use metric units for parameters. Does not affect output code
use metric units for output code
set the starting point of the project at (0,0). With this option, the projet will be between (0,0) and (max_x_value, max_y_value) (positive values)
do not create the output gcode files. You can use this to quickly convert the input files to png/svg
The only options that can't be used in the millproject file are the common ones and noconfigfile:
Disable the parsing of the millproject file. Use this option if you want to manually pass all the arguments as command line parameters
- -?, --help
Show summary of options.
- -v, --version
Show version of program.
For further information about pcb2gcode, see the project wiki.
pcb2gcode was written by Patrick Birnzain and Nicola Corna, loosely based on an earlier program of the same name by Jeff Prothero (Cynbe ru Taren), which in term was based even more loosely on Matthew Sager's gerber_to_gcode.
This manual page was written by chrysn <firstname.lastname@example.org> and Nicola Corna <email@example.com> for the Debian project (and may be used by others).