GerbMerge -- The Configuration File
Andrew Sterian
Padnos College of Engineering and Computing
Grand Valley State University
| Top-Level | The Configuration File | The Layout File | Automatic Placement |
| Operating Parameters | Job Descriptions | Syntax Notes |
The configuration file tells GerbMerge things like:
How much space to leave between jobs in the final panel
Whether or not to draw cut lines or crop marks, and on which layers
Whether or not to generate a fabrication drawing
The job names and files to be panelized
The output file names
Note that the configuration file does not specify layout of jobs on the panel. This layout is described by the layout file. The layout of jobs on the panel may also be constructed automatically using the automatic placement mode of operation.
The rest of this document has a lot of information and it's easy to get overwhelmed. Users of GerbMerge complain that the configuration file is the biggest hurdle to overcome in using the program.
Don't panic. Start with a sample configuration file and modify it for your own jobs. The comments in the sample file will guide you through the process.
The configuration file is a plain text file that can be created with any text editor. It is parsed using Python's ConfigParser module. See the documentation for this module for a full description of supported syntax.
Note that comments in this file begin with a '#' character. Comments must occupy an entire line and must not have any characters before the '#' character, including blanks. Comments cannot be placed at the end of a line. For example:
# This is correct...a comment occupies the entire line
# Incorrect...comment preceded by blanks
PanelWidth = 10.5 # This is INCORRECT...a comment cannot be placed at the end of a line
The configuration file has a standard "INI-style" syntax comprising:
The configuration file parser supports variable substitution. You can specify a common pathname prefix, for example, and substitute it in subsequent assignments, like this:
[CPUBoard]
Prefix = /home/user/eagle/cpuboard
# Note the syntax '%(prefix)s' is a variable string substitution.
# Even though we said 'Prefix = ...' we use LOWERCASE 'prefix' in the actual substitution!
BoardOutline = %(prefix)s/cpu.bor
Drills = %(prefix)s/cpu.xln
NOTE: the parser converts all names you assign to into lowercase letters only.
In general, assignments are local to the section in which they reside, i.e., the names assigned to are not visible in the other sections. However, any assignments in the section named [DEFAULT] are visible in all sections. For example:
[DEFAULT]
EagleDir = /home/user/eagle
[CPUBoard]
Prefix = %(eagledir)s/cpuboard
BoardOutline = %(prefix)s/cpu.bor
Drills = %(prefix)s/cpu.xln
[IOBoard]
Prefix = %(eagledir)s/ioboard
BoardOutline = %(prefix)s/io.bor
Drills = %(prefix)s/io.xln
Have a look at the sample configuration files layout1.cfg and layout2.cfg for a quick overview of this file's syntax.
The first section of the configuration file is called [Options]. This section specifies operating parameters for the job.
The following optional parameters are supported:
NOTE:If you're using a recent version of Eagle or other modern PCB program, you can probably ignore this option. Try commenting it out and see what happens!
This parameter sets the default tool list (or "drill rack") in effect for jobs that (a) do not have embedded tool sizes in the Excellon file, and (b) do not have a tool list specified as part of the job description (see below).
As of Eagle version 4.11r2, tool sizes are embedded in the Excellon file, like this:
...
T01C0.032
T02C0.045
T03C0.115
...
For Excellon files with embedded tool sizes, no tool list file need be specified. Otherwise, a tool list file must be specified that contains something like:
T01 0.032in
T02 0.045in
T03 0.115in
Suffixes of 'mm' and 'mil' may be used instead of 'in' to indicate millimetres and mils.
Note that Eagle's CAM Processor uses two different forms of Excellon output devices, EXCELLON in which tool sizes are embedded in the drill file, and EXCELLON_RACK which requires an external tool list file, or drill rack. The latter may be desirable when you want to send your boards to a manufacturer with a limited set of drill sizes, or that charges by the number of different drill sizes used. In this case, do specify the ToolList option and set it to the drill rack you specified for the EXCELLON_RACK device.
This optional setting specifies the number of digits after the decimal point in the input Excellon drill files. These files contain (X,Y) drill locations specified as integers, but represent actual positions in the format M.N where there are M digits before the decimal point and N digits after. The default number of decimal digits is 4, hence a 2.4 integer format, so that the drill instruction X12300Y9400 means to drill at (1.23", 0.94"). In 2.3 format (with ExcellonDecimals=3) the above would appear as X1230Y940. Note that it is assumed that leading 0's are omitted, or else no zeroes are omitted. Omitted trailing 0's are not yet supported.
As of this writing, older Eagle versions use a 2.3 format (prior to version 4.11r12), more recent Eagle versions use a 2.4 format, while Orcad and PCB use 2.4.
Note that each job may have its own ExcellonDecimals setting (see below) to override this global setting.
Finally, note that the ExcellonDecimals option applies to the expected format for
the input Excellon files, i.e., the drill files that GerbMerge reads in. The
ExcellonLeadingZeros option below applies to the output Excellon file generated by GerbMerge.
This parameter indicates which, if any, layers are to have cut lines drawn on them. Cut lines define the rectangular extents of each individual job on the panel. They are intended to help you in cutting out the individual jobs from the panel.
The value of this parameter is a list of layer names, which are defined for each job (see below). Layer names may be separated with commas or semicolons.
Note that layer names must be written in lowercase letters, even if they are defined with uppercase letters. Also note that all layer names except the board outline layer will begin with an asterisk '*'.
This parameter may be omitted, or be set to None to indicate that no cut lines should
be drawn.
This parameter indicates which, if any, layers are to have crop marks drawn on them. Crop marks are small L-shaped marks at the four corners of the final panel. Some board manufacturers require crop marks to ensure registration and to unambiguously define the extents of the job.
The value of this parameter is a list of layer names, which are defined for each job (see below). Layer names may be separated with commas or semicolons.
Note that layer names must be written in lowercase letters, even if they are defined with uppercase letters. Also note that all layer names except the board outline layer will begin with an asterisk '*'.
This parameter may be omitted, or be set to None to indicate that no crop marks should be drawn.
This optional parameter may be set to a filename, to 'none', or omitted entirely. When a valid filename is specified, GerbMerge will generate a Gerber RS274X file containing a fabrication drawing for the entire project. The drawing contains a box for the outline of the entire panel, dimension arrows for the panel, drill symbols for each drill hit, a drill tool legend, and optional user text. Some board manufacturers require a fabrication drawing.
The Fabrication Drawing Text option below allows you add user-defined text to this drawing.
Note that for generating a fabrication drawing, no more than 26 drill tools can appear in the merged output.
This optional parameter may specify the name of a file containing plain text. Each line in the file is added to the fabrication drawing, if one is enabled.
This optional setting creates a merged Excellon output file with leading zeros. The default is to use leading-zero suppression. For example, with leading-zero suppression, a drill hit at location (1.23",4.56") would be written in the output Excellon file as:
X12300Y45600Without leading-zero suppression (i.e., with ExcellonLeadingZeros=1) it would appear as:
X012300Y045600
Not using leading-zero suppression may make it easier for some Gerber viewers to properly interpret the Excellon file. Try setting ExcellonLeadingZeros=1 if your drills appear in completely the wrong locations when viewing your merged output files in a Gerber viewer.
Finally, note that the ExcellonLeadingZeros option applies to the format for
the output Excellon file as generated by GerbMerge. The
ExcellonDecimals option described above applies to the input Excellon files read
in by GerbMerge.
This optional parameter indicates that an additional output file (Gerber layer) is to be generated containing a rectangle that is drawn around the edges of the final panelized job. The value of this parameter is the name of the file. If 'none' is specified or this option is omitted, no outline file is generated.
This outline layer is useful in circuit board milling for defining the path extents of a contour router bit so that the entire panel may be cut out by the mill.
This optional parameter indicates that an additional output file (Gerber layer) is to be generated containing scoring lines. These scoring lines describe the path for a scoring tool to make V-grooves in the board in between jobs, so that the jobs may be easily snapped apart. The value of this parameter is the name of the file. If 'none' is specified or this option is omitted, no scoring file is generated.
These parameters (in inches) set the dimensions of the board manufacturer's panels. An error message will be displayed if the panelized job exceeds these dimensions. You can change these settings to match the panel size of your board manufacturer, if you know it.
For automatic placement, the panel size defined by these settings constraint the random placements such that only placements that would fit on the panel are considered.
These four parameters set the amount of extra space to leave around the
edges of the panel to simplify tooling and handling. These margins are
specified in inches, and default to 0" if not specified. These spacings will
only be visible to the board manufacturer if you enable crop marks (see
CropMarkLayers above) or use an outline layer.
These parameters set the job-to-job spacing in horizontal (X) and vertical (Y) directions. The default spacing is 0.125 inches if these parameters are not specified. Normally, both parameters will have the same value, but different values can be used to "tweak" a panel to exactly fit some dimensions.
This optional parameter (in inches) indicates the width of the line used to draw cut lines. If not specified, the default is 0.01".
This optional parameter (in inches) indicates the width of the line used to draw crop marks. If not specified, the default is 0.01".
This parameter may be set to either 0 or 1. When set to 0, all jobs must have the same layer names. This is the most common case. This parameter guards against misspelling of layer names and having them mistakenly placed on a different layer.
Some jobs, however, will have fewer or more layers. For example, mixing jobs that do and do not have surface-mount components may mean that some jobs will have solder mask layers and some will not. Setting AllowMissingLayers to 1 allows you to panelize such job mixtures. Take care, however, to inspect the output carefully in this case to catch layer-name surprises.
This option is intended to reduce the number of drills in the output by eliminating drill sizes that are too close to make a difference. For example, it probably does not make sense to have two separate 0.031" and 0.0315" drills. The DrillClusterTolerance value specifies how much tolerance is allowed in drill sizes, in units of inches. Multiple drill tools that span twice this tolerance will be clustered into a single drill tool. For example, a set of 0.031", 0.0315", 0.032", and 0.034" drills will all be replaced by a single drill tool of diameter (0.031"+0.034")/2 = 0.0325". It is guaranteed that all original drill sizes will be no farther than DrillClusterTolerance from the drill tool size generated by clustering.
Setting DrillClusterTolerance to 0 (the default) disables clustering.
Use this option to automatically thicken features on particular layers. This is intended for thickening silkscreen to some minimum width. The value of this option must be a comma-separated list of layer names followed by minimum feature sizes (in inches) for that layer. Comment this out to disable thickening. Example usage is:
MinimumFeatureSize = *topsilkscreen,0.008,*bottomsilkscreen,0.008
Each input job is described in its own section. The job is described by providing file names for each layer. Layer names are up to you, but note the following:
Layer names may be specified with lowercase and uppercase letters, but are converted to all-lowercase by GerbMerge. Note that this applies to layer names, not filenames.
Each job must have at least a 'boardoutline' and 'drills' layer, specifying the Gerber board outline and Excellon drills layer, respectively.
Each job may have an optional 'toollist' file specifying the tool list (or "drill rack") in effect for this job only. This setting overrides the global ToolList option, described above. If the Excellon file for the job has embedded tool sizes, this option is ignored.
All layer names other than 'boardoutline' and 'drills' must begin with an asterisk '*' character.
Consider the following example:
[CPUBoard]
BoardOutline = /home/user/eagle/cpuboard/cpu.bor
Drills = /home/user/eagle/cpuboard/cpu.xln
ToolList = /home/user/eagle/cpuboard/tools.drl
*TopLayer = /home/user/eagle/cpuboard/cpu.cmp
*BottomLayer = /home/user/eagle/cpuboard/cpu.sol
*Silkscreen = /home/user/eagle/cpuboard/cpu.plc
Job names (in square brackets) are fairly arbitrary and need not correspond to any file names. They must, however, comprise only letters, digits, and the underscore character. Furthermore, job names must begin with a letter. Job names, unlike layer names, are case sensitive.
Each assignment statement assigns a file name to a layer name. As mentioned above, the layer names 'boardoutline' and 'drills' are reserved and required. The optional 'toollist' layer is not an actual layer but an assignment that indicates the tool list in effect for this job. All other layer names are up to you and must begin with an asterisk '*'.
Make good use of variable substitutions (see the sample layout1.cfg and layout2.cfg files) to avoid typing the same pathname over and over.
In addition to specifying board layers, each job description can also have job-specific parameter assignments:
This option is only used for automatic placement and indicates the number
of times this job is to appear in the final panel. For manual placement, this option is ignored. This option
may be left unspecified in which case a repeat count of 1 is assumed.
This option overrides the global ExcellonDecimals setting in the [Options] section for this job only. This allows jobs with different Excellon decimal formats to be panelized. This option may be left unspecified in which case the global ExcellonDecimals setting is applied.
GerbMerge combines data from multiple jobs grouped by layer. All of the "bottom copper" layers from all jobs, for example, will be combined into a single "bottom copper" file. The names of these combined output files can be set in the [MergeOutputFiles] section of the configuration file.
This section contains assignments of file names to layer names. The layer names must be the same as the ones specified in the [Jobs] section of the configuration file. All layer names must begin with an asterisk '*' except for the following four reserved layer names:
The first two reserved layer names are actual layers, while Placement refers to the placement file generated by GerbMerge containing positions of jobs on the final panel, and ToolList refers to the combined tool list file generated by GerbMerge.
Any assignment made in this section that does not begin with an asterisk or is not an assignment to one of the above four reserved names is considered a general variable assignment for future string substitution.
Here is an example:
[MergeOutputFiles] Prefix = job1 BoardOutline = %(prefix)s.bor Drills = %(prefix)s.xln *topcopper = %(prefix)s.cmp *bottomcopper = %(prefix)s.sol
If an assignment to a layer name is missing, GerbMerge will create the file merged.layername.ger where 'layername' is the layer name. Default values for the four reserved names are merged.boardoutline.ger for the BoardOutline layer, merged.drills.xln for the Drills layer, merged.placement.txt for the Placement file, and merged.toollist.drl for the ToolList combined tool list file.