gerbmerge/doc/cfgfile.html

442 lines
24 KiB
HTML

<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>GerbMerge -- A Gerber-file merging program -- The Configuration File</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000c0" VLINK="#8f008f">
<!-- -->
<P><FONT SIZE="+2">GerbMerge -- The Configuration File</FONT></P>
<BLOCKQUOTE>
<P><A HREF="http://ruggedcircuits.com/gerbmerge"><FONT
SIZE="-1">Rugged Circuits LLC</FONT></A><FONT SIZE="-1"></FONT></P>
</BLOCKQUOTE>
<P><HR ALIGN=LEFT><TABLE WIDTH="100%" BORDER="0" CELLSPACING="2"
CELLPADDING="0">
<TR>
<TD><A HREF="index.html">Top-Level</A> | The Configuration File | <A HREF="layoutfile.html">The Layout File</A> | <A HREF="autosearch.html">Automatic Placement</A></TD>
</TR>
<TR>
<TD>&nbsp;</TD>
</TR>
<TR>
<TD>
<FONT SIZE="-1"><A HREF="#Parameters">Operating Parameters</A> | <A HREF="#Jobs">Job Descriptions</A> |
<A HREF="#Syntax">Syntax Notes</A></TD>
</TR>
</TABLE><HR ALIGN=LEFT></P>
<H2>Introduction</H2>
<P>The configuration file tells GerbMerge things like:
<UL>
<LI><P>How much space to leave between jobs in the final panel</LI>
<LI><P>Whether or not to draw cut lines or crop marks, and on which layers</LI>
<LI><P>Whether or not to generate a fabrication drawing</LI>
<LI><P>The job names and files to be panelized</LI>
<LI><P>The output file names</LI>
</UL>
<P>Note that the configuration file does not specify layout of jobs on the
panel. This layout is described by the <A HREF="layoutfile.html">layout file</A>.
The layout of jobs on the panel may also be constructed automatically using
the <A HREF="autosearch.html">automatic placement</A> mode of operation.
<P><H2>Help!</H2>
<P>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.
<P>Don't panic. Start with a <A HREF="layout2.cfg">sample configuration file</A> and
modify it for your own jobs. The comments in the sample file will guide you through the
process.
<P><A NAME="Syntax"></A>
<H2>Syntax Notes</H2>
<P>The configuration file is a plain text file that can be created with any
text editor. It is parsed using Python's
<A HREF="http://docs.python.org/lib/module-ConfigParser.html"><TT>ConfigParser</TT></A> module.
See the documentation for this module for a full description of supported syntax.
<P>Note that comments in this file begin with a <TT>'#'</TT> 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:
<PRE>
# 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
</PRE>
<P>The configuration file has a standard "INI-style" syntax comprising:
<UL>
<LI><I>Sections</I> delimited by section names in square brackets (e.g., <TT>[Options]</TT>)
<LI><I>Assignments</I> of the form '<TT>Name = Value</TT>'
</UL>
<P>The configuration file parser supports variable substitution. You can specify a common
pathname prefix, for example, and substitute it in subsequent assignments, like this:
<PRE>
[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
</PRE>
<HR>
<P><B>NOTE:</B> the parser converts all names you assign to into <B>lowercase letters only</B>.
<HR>
<P>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 <TT>[DEFAULT]</TT> are visible in all
sections. For example:
<PRE>
[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
</PRE>
<P>Have a look at the sample configuration files <A HREF="layout1.cfg"><TT>layout1.cfg</TT></A>
and <A HREF="layout2.cfg"><TT>layout2.cfg</TT></A> for a quick overview of this file's syntax.
<P><A NAME="Parameters"></A>
<H2>Operating Parameters</H2>
<P>The first section of the configuration file is called <TT>[Options]</TT>.
This section specifies operating parameters for the job.
<P>The following optional parameters are supported:
<DL>
<A NAME="ToolList"><DT><B>Tool List</B></DT></A>
<DD><TT>ToolList = /home/user/eagle/toollist.drl</TT>
<P><B>NOTE:</B>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!
<P>This parameter sets the default tool list (or &quot;drill rack&quot;) 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).
<P>As of Eagle version 4.11r2, tool sizes are embedded in the Excellon file, like this:
<PRE>
...
T01C0.032
T02C0.045
T03C0.115
...
</PRE>
<P>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:
<PRE>
T01 0.032in
T02 0.045in
T03 0.115in
</PRE>
<P>Suffixes of 'mm' and 'mil' may be used instead of 'in' to indicate millimetres and mils.
<P>Note that Eagle's CAM Processor uses two different forms of Excellon output
devices, <TT>EXCELLON</TT> in which tool sizes are embedded in the drill file,
and <TT>EXCELLON_RACK</TT> 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 <TT>ToolList</TT> option and
set it to the drill rack you specified for the <TT>EXCELLON_RACK</TT> device.
</DD>
<A NAME="ExcellonDecimals"><DT><B>Excellon Decimals</B></DT></A>
<DD><TT>ExcellonDecimals = 4</TT>
<P>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 <TT>M.N</TT> where there are <TT>M</TT> digits
before the decimal point and <TT>N</TT> digits after. The default number of decimal digits
is 4, hence a 2.4 integer format, so that the drill instruction <TT>X12300Y9400</TT> means to drill at (1.23", 0.94").
In 2.3 format (with <TT>ExcellonDecimals=3</TT>) the above would appear as
<TT>X1230Y940</TT>. 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.
<P>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.</DD>
<P>Note that each job may have its own <TT>ExcellonDecimals</TT> setting (see <A HREF="#LocalExcellonDecimals">below</A>) to override this global
setting.
<P>Finally, note that the <TT>ExcellonDecimals</TT> option applies to the expected format for
the <B>input</B> Excellon files, i.e., the drill files that GerbMerge reads in. The <A HREF="#ExcellonLeadingZeros">
<TT>ExcellonLeadingZeros</TT></A> option below applies to the <B>output</B> Excellon file generated by GerbMerge.
<A NAME="CutLineLayers"><DT><B>Cut Line Layers</B></DT></A>
<DD><TT>CutLineLayers = *toplayer,*bottomlayer</TT>
<P>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.
<P>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.
<P>Note that <B>layer names must be written in lowercase letters</B>, even if they are defined with
uppercase letters. Also note that all layer names except the board outline layer will begin
with an asterisk '<B>*</B>'.</DD>
<P>This parameter may be omitted, or be set to <TT>None</TT> to indicate that no cut lines should
be drawn.</DD>
<A NAME="CropMarkLayers"><DT><B>Crop Mark Layers</B></DT></A>
<DD><TT>CropMarkLayers = *toplayer,*bottomlayer</TT>
<P>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.
<P>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.
<P>Note that <B>layer names must be written in lowercase letters</B>, even if they are defined with
uppercase letters. Also note that all layer names except the board outline layer will begin
with an asterisk '<B>*</B>'.
<P>This parameter may be omitted, or be set to <TT>None</TT> to indicate that no crop marks should
be drawn.</DD>
<A NAME="FabricationDrawingFile"><DT><B>Fabrication Drawing File</B></DT></A>
<DD><TT>FabricationDrawingFile = fabdwg.ger</TT>
<P>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.
<P>The Fabrication Drawing Text option below allows you add user-defined text
to this drawing.
<P>Note that for generating a fabrication drawing, no more
than 26 drill tools can appear in the merged output.</DD>
<A NAME="FabricationDrawingText"><DT><B>Fabrication Drawing Text</B></DT></A>
<DD><TT>FabricationDrawingText = project/fabdwg.txt</TT>
<P>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.</DD>
<A NAME="ExcellonLeadingZeros"><DT><B>ExcellonLeadingZeros</B></DT></A>
<DD><TT>ExcellonLeadingZeros = 0</TT>
<P>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:
<PRE> X12300Y45600
</PRE>Without leading-zero suppression (i.e., with <TT>ExcellonLeadingZeros=1</TT>) it would appear as:
<PRE> X012300Y045600
</PRE><P>Not using leading-zero suppression may make it easier for some
Gerber viewers to properly interpret the Excellon file. Try setting
<TT>ExcellonLeadingZeros=1</TT> if your drills appear in completely the
wrong locations when viewing your merged output files in a Gerber
viewer.</DD>
<P>Finally, note that the <TT>ExcellonLeadingZeros</TT> option applies to the format for
the <B>output</B> Excellon file as generated by GerbMerge. The <A HREF="#ExcellonDecimals">
<TT>ExcellonDecimals</TT></A> option described above applies to the <B>input</B> Excellon files read
in by GerbMerge.
<A NAME="OutlineLayerFile"><DT><B>Outline Layer File</B></DT></A>
<DD><TT>OutlineLayerFile = project.oln</TT>
<P>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.
<P>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.</DD>
<A NAME="ScoringFile"><DT><B>Scoring File</B></DT></A>
<DD><TT>ScoringFile = project.sco</TT>
<P>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.</DD>
<A NAME="PanelWidthHeight"><DT><B>Panel Width/Height</B></DT></A>
<DD><TT>PanelWidth = 12.6</TT><BR>
<TT>PanelHeight = 7.8</TT>
<P>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.
<P>For <A HREF="autosearch.html">automatic placement</A>, the panel size defined by these settings
constraint the random placements such that only placements that would fit on the panel are considered.</DD>
<A NAME="Margins"><DT><B>Margins</B></DT></A>
<DD><TT>LeftMargin = 0.1</TT><BR>
<TT>RightMargin = 0.1</TT><BR>
<TT>TopMargin = 0.1</TT><BR>
<TT>BottomMargin = 0.1</TT>
<P>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
<A HREF="#CropMarkLayers">CropMarkLayers</A> above) or use an <A HREF="#OutlineLayerFile">outline layer</A>.
<A NAME="JobSpacing"><DT><B>Job Spacing</B></DT></A>
<DD><TT>XSpacing = 0.125</TT><BR>
<TT>YSpacing = 0.125</TT>
<P>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 &quot;tweak&quot;
a panel to exactly fit some dimensions.</DD>
<A NAME="CutLineWidth"><DT><B>Cut Line Width</B></DT></A>
<DD><TT>CutLineWidth = 0.01</TT>
<P>This optional parameter (in inches) indicates the width of the line used to draw cut lines. If not
specified, the default is 0.01".</DD>
<A NAME="CropMarkWidth"><DT><B>Crop Mark Width</B></DT></A>
<DD><TT>CropMarkWidth = 0.01</TT>
<P>This optional parameter (in inches) indicates the width of the line used to draw crop marks. If not
specified, the default is 0.01".</DD>
<A NAME="AllowMissingLayers"><DT><B>Allow Missing Layers</B></DT></A>
<DD><TT>AllowMissingLayers = 0</TT>
<P>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.
<P>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 <TT>AllowMissingLayers</TT> to 1 allows you to panelize such
job mixtures. Take care, however, to <A HREF="index.html#Verifying">inspect the output carefully</A>
in this case to catch layer-name surprises.</DD>
<A NAME="DrillClusterTolerance"><DT><B>DrillClusterTolerance</B></DT></A>
<DD><TT>DrillClusterTolerance = 0</TT>
<P>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 <TT>DrillClusterTolerance</TT> 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 <TT>DrillClusterTolerance</TT> from the
drill tool size generated by clustering.
<P>Setting <TT>DrillClusterTolerance</TT> to 0 (the default) disables clustering.</DD>
<A NAME="MinimumFeatureSize"><DT><B>MinimumFeatureSize</B></DT></A>
<DD><TT>MinimumFeatureSize = None</TT>
<P>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:
<PRE> MinimumFeatureSize = *topsilkscreen,0.008,*bottomsilkscreen,0.008</PRE></DD>
<A NAME="FiducialPoints"><DT><B>FiducialPoints</B></DT></A>
<DD><TT>FiducialPoints = None</TT>
<P>Use this option to automatically add fiducials (little round markers used to aid
in automatic component placement) to your final panel. This makes the most sense when
you leave some <A HREF="#Margins">margins</A> around your panel and place the fiducials on the margins.
<P>The parameter to this option is a list of X,Y points at which to draw fiducials, relative to the
edges of the final panel. Positive values are relative to the lower-left, while negative values are
relative to the upper-right. For example:
<PRE> FiducialPoints = 0.125,0.125,-0.1,-0.1</PRE>
would place one fiducial at (0.125,0.125) relative to the lower-left, and another fiducial
a distance of (0.1,0.1) from the top-right of the final panel. To place a fiducial at the top-left
of the final panel:
<PRE> FiducialPoints = 0.125,-0.125</PRE>
The <A HREF="#FiducialCopperDiameter"><TT>FiducialCopperDiameter</TT></A> and <A HREF="#FiducialMaskDiameter"><TT>FiducialMaskDiameter</TT></A> options control the appearance of the fiducials.</DD>
<P>
<A NAME="FiducialCopperDiameter"><DT><B>FiducialCopperDiameter</B></DT></A>
<DD><TT>FiducialCopperDiameter = 0.08</TT>
<P>This option sets the diameter of fiducials in inches. See the <A HREF="#FiducialPoints"><TT>FiducialPoints</TT></A> configuration option for more information.</DD>
<A NAME="FiducialMaskDiameter"><DT><B>FiducialMaskDiameter</B></DT></A>
<DD><TT>FiducialMaskDiameter = 0.32</TT>
<P>This option sets the diameter of the soldermask opening around fiducials in inches. See the <A HREF="#FiducialPoints"><TT>FiducialPoints</TT></A> configuration option for more information.</DD>
</DL>
<P><A NAME="Jobs"></A>
<H2>Job Descriptions</H2>
<P>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:
<UL>
<LI><P>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.
<LI><P>Each job must have at least a 'boardoutline' and 'drills' layer, specifying the Gerber
board outline and Excellon drills layer, respectively.
<LI><P>Each job may have an optional 'toollist' file specifying the tool list (or &quot;drill rack&quot;)
in effect for this job only. This setting overrides the global <TT>ToolList</TT> option, described above.
If the Excellon file for the job has embedded tool sizes, this option is ignored.
<LI><P>All layer names other than 'boardoutline' and 'drills' must begin with an asterisk '*'
character.
</UL>
<P>Consider the following example:
<PRE>
[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
</PRE>
<P>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.
<P>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 '*'.
<P>Make good use of variable substitutions (see the sample <A HREF="layout1.cfg"><TT>layout1.cfg</TT></A>
and <A HREF="layout2.cfg"><TT>layout2.cfg</TT></A> files) to avoid
typing the same pathname over and over.
<P>In addition to specifying board layers, each job description can also have job-specific
parameter assignments:
<DL>
<DT><B>Repeat</B></DT>
<DD><TT>Repeat = 3</TT>
<P>This option is only used for <A HREF="autosearch.html">automatic placement</A> 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.
<A NAME="LocalExcellonDecimals"><DT><B>ExcellonDecimals</B></DT></A>
<DD><TT>ExcellonDecimals = 3</TT>
<P>This option overrides the global <A HREF="#ExcellonDecimals"><TT>ExcellonDecimals</TT></A> setting in the
<TT>[Options]</TT> 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 <TT>ExcellonDecimals</TT> setting is applied.
</DL>
<P><A NAME="MergeOutputFiles"></A>
<H2>Merge Output Files</H2>
<P>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 <TT>[MergeOutputFiles]</TT> section of the
configuration file.
<P>This section contains assignments of file names to layer names. The layer names must be the
same as the ones specified in the <A HREF="#Jobs"><TT>[Jobs]</TT></A> section of the configuration file.
All layer names must begin with an asterisk '<B>*</B>' except for the following four reserved layer names:
<UL><LI><TT>BoardOutline</TT></LI>
<LI><TT>Drills</TT></LI>
<LI><TT>Placement</TT></LI>
<LI><TT>ToolList</TT></LI>
</UL>
<P>The first two reserved layer names are actual layers, while
<TT>Placement</TT> refers to the placement file generated by GerbMerge
containing positions of jobs on the final panel, and <TT>ToolList</TT> refers
to the combined tool list file generated by GerbMerge.
<P> 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.
<P>Here is an example:
<PRE>
[MergeOutputFiles]
Prefix = job1
BoardOutline = %(prefix)s.bor
Drills = %(prefix)s.xln
*topcopper = %(prefix)s.cmp
*bottomcopper = %(prefix)s.sol
</PRE>
<P>If an assignment to a layer name is missing, GerbMerge will create the file <TT>merged.layername.ger</TT> where
'<TT>layername</TT>' is the layer name. Default values for the four reserved names are <TT>merged.boardoutline.ger</TT>
for the <TT>BoardOutline</TT> layer, <TT>merged.drills.xln</TT> for the <TT>Drills</TT> layer, <TT>merged.placement.txt</TT> for the <TT>Placement</TT> file, and <TT>merged.toollist.drl</TT> for the <TT>ToolList</TT> combined tool list file.
<HR ALIGN=LEFT>
<P><CENTER><FONT SIZE="-1">&COPY; 2003-2011, Copyright by <A HREF="http://ruggedcircuits.com">Rugged Circuits LLC</A>; All Rights Reserved. mailto: <A HREF="mailto:support@ruggedcircuits.com?subject=GerbMerge">support@ruggedcircuits.com</A></FONT></CENTER>
</BODY>
</HTML>