Bill of Materials (BOM) handling in uEDA

There are a number of reasons why one may want to have a BOM for a board design:

* To have a list of all components outside of schematic drawing files
* To have a list of PCB land patterns for pre-layout (see prelayout.txt)
* For purchasing or other part procurement
* For handing to assemblers (those who populate the parts on the board)
* For quick reference

Although one is often tempted to get away with keeping the "BOM" information in
his head, a formal BOM is a good thing to have.

OK, so we are going to have a BOM.  But what exactly is the BOM in precise
terms, and what is its format?  uEDA provides several different facilities for
BOM handling.

The MCL

Whether or not you are interested in any of the other BOM formats, you have to
have the MCL.  It is a critical part of the design source code in the uEDA flow
model.  It's a human-created and human-edited text file described in great
detail in mcldoc.txt.

Having a simple and intuitive text-based format, MCL can be readily viewed and
printed.  As it contains the complete information about all components in the
design, i.e., all BOM information, it is in itself a type of BOM.  It is in a
way "the ultimate BOM".  There are, however, a few situations in which other
BOM formats are desirable.

Procurement BOM

You write the MCL for your design.  For each component you enter all the
attributes that you may need for procurent: manufacturer,
manufacturer_part_number, vendor, vendor_part_number, etc.  But now it's
actually time to order the parts.  What quantity of what part numbers do you
order?  All necessary information is in the MCL, but it isn't at all obvious
for filling out order forms.  One really needs a distilled BOM for procurement.

The ueda-mkbom utility generates a procurement-oriented BOM from the MCL.
First it reads the MCL and makes note of all components that have been reduced
to parts.  (Components that haven't been reduced to parts are ignored, though
the user can request that a warning be issued.  You need to reduce all
components to parts for this function to be useful, see mcldoc.txt for the
details.)  All multiple instances of each part are tallied together.
Finally, output is emitted which is centered around parts with a quantity for
each, rather than around reference designators.  (A list of refdes'ed components
using each part can optionally be emitted.)  Each entry is given a heading and
usually some comment lines based on part attributes from the MCL which are
deemed relevant to the procurement BOM.  See mcldoc.txt for the details.

One can generate procurement BOMs for different population options, see below.

The procurement BOM generated by ueda-mkbom is plain text formatted on the
assumption of 80 columns of fixed character spacing.  It is thus suitable for
both online viewing and printing.

Short BOM

For purposes other than procurement of parts, component reference designators
do matter, and a BOM organised and sorted by the component refdes is the right
format.  MCL is such a format, and oftentimes it serves quite well.

Sometimes however, it is desirable to have a "short BOM" that is ordered by
the component refdes like the MCL, but follows a tabular format with one line
per component and with columns corresponding to a few attributes deemed most
useful.

The ueda-shortbom utility generates such a "short BOM" with 4 columns: refdes,
manufacturer, part number and description.  The manufacturer and description
columns are taken from the identically named MCL attributes; the part number
column is taken from the manufacturer_part_number= attribute if one is defined,
otherwise the device= attribute is used instead.  If neither attribute is
defined, the string "unknown" is substituted.  The same holds for the
manufacturer column.  The description column is left blank if no description=
attribute is defined.

The intent is that the MCL would be used directly only by the board designer
himself, who would of course be intimately familiar with the UNIX environment,
the workings of uEDA and its file formats, and the way his particular MCL is
structured, whereas the short BOM would be given to lab technicians and others
who are not UNIX-based intellectual creators.

ueda-shortbom can generate plain text output that is directly usable for viewing
and printing in a fixed character spacing environment, but it usually ends up
needing more than 80 characters per line and thus a pain to work with.
ueda-shortbom can also produce output with columns separated by ASCII tab
characters irrespective of field widths; such output is useful for post-
processing.  UNIX tbl(1) and troff(1) can be used to produce a very pretty
hard copy (PostScript) version of the short BOM.

Assembly BOM

An assembly BOM is exactly the same as the short BOM described above, but has
one difference: if a component is to be socketed, the information put in the
corresponding columns of the assembly BOM is that for the socket part, rather
than for the component to be pushed into the socket.  The assembly BOM is thus
exactly what you need to give to those who will be stuffing parts on your board
and running it through the reflow oven.

An assembly BOM is generated by the ueda-shortbom utility with the -a option.
Since one would need to generate different assembly BOMs for different
population options (assuming that the document is intended for those who will
follow it blindly), ueda-shortbom supports population options as well.
See the ueda-shortbom(1) man page for details.

If your design uses no socketed parts and no population options, the short BOM
and the assembly BOM would be identical.

Population options

uEDA supports designs with population options, i.e., ones in which some
components may or may not be populated as a manufacturing option.  They are
described in this document because the BOM is really the only part of the uEDA
flow for which population options matter.  The PCB obviously has to have
footprints for all components that may ever be populated on it and the
schematics normally show the interconnections for all possible components as
well.  The BOM is the only part that is made in multiple versions for different
population options.

In order to support population options, each component in the design (i.e., in
the MCL) is assigned to a numbered population group.  Population groups are
identified by integers and a component is assigned to a given population group
via the population_option= attribute in the MCL.  Components without this
attribute are assigned to population group 0, the default.

When generating a BOM for a given population option, specify the list of
population groups to be included (see ueda-mkbom(1) and ueda-shortbom(1)).
The default population option consists of population group 0, i.e., running
ueda-mkbom or ueda-shortbom without any options counts only those components
which do not have a population_option= attribute.