eda-tools/old-boom/README

The BOM processing system
=========================

The BOM processing system takes a bill of material generated by
KiCad and converts it in various steps into a "shopping list"
that can be used to order from various providers.


Introduction
============

The following sections describe how to use the basic elements of
the BOM processing system.


A simple BOM translation
------------------------

KiCad identifies components by a so-called component reference,
e.g., R1001, U5, etc. In addition to this, each component can have
various parameters, such as a "value", its footprint, and further
user-defined items. These parameters can be shown in the schematics
(e.g., the value usually is) or they can be hidden (e.g., the
footprint).

At the end of the process, we want a "shopping list" that can be
used to order items or to find them in an inventory or catalog.
Components in the shopping list are identified by a part number.

...
- BOM
- inventory
- ID matching


Equivalences
------------

A single component can be associated with multiple part numbers.
For example, a chip its manufacturer calls "XYZ-R1" may be listed in
a distributor's catalog with a completely different order number,
such as "20-1234-8". The BOM processing system therefore
distinguishes multiple so-called name spaces. A name space is
identified by a (unique) name and a part number is generally
qualified by the name of the name space.

E.g., if the manufacturer is called "ACME" and the distributor of
electronical components calls itself "DIST-EL", the part in our
example may have the equivalent names "ACME XYZ-R1" and "DIST-EL
20-1234-8".

...
- revise .inv

example.equ:

#INV
DIST-EL 20-1234-8
#EQU
ACME XYZ-R1 DIST-EL 20-1234-8


Adding stock and cost
---------------------

- .inv, more fields
- quanta

Substituting component names
----------------------------

- intro to .sub
- ad-hoc fixes


Selecting characteristics
-------------------------

- .sub
- .chr
- <rel><number><multiplier><unit> syntax
...


Generating characteristics
--------------------------

- .gen


Advanced topics
===============

- generating .inv files
- different presentations (e.g., CT, TR, ...)
- component substitution (one-way equivalence)
- problem reports
- hiding known problems (while sourcing)


File formats
============

The BOM processing system uses a large number of different files to
store information retrieved from the BOM, inventories, intermediate
results, etc. The following sections describe the various formats.


Part characteristics (.chr)
---------------------------

A part characteristics file lists the parameters of components.
This information is then matched with the parameters specified in
the schematics.

The part characteristics file begins with a line containing only
#CHR

After this, each line contains the manufacturer (namespace), the
part number, and a list of parameter=value entries. Fields are
separated by spaces.

Long lines can be wrapped by indenting the continuation lines.

Blank lines and comments (#) are ignored.


Substitutions (.sub)
--------------------

A substitutions file specifies rules for translating component
parameters in schematics to part characteristics.

A substitution rule consists of zero or more conditions and zero or
more assignments. The conditions are of the form field=pattern. The
field can be a per-component fields KiCad provides or any parameter
set by substitutions.

KiCad fields are named as follows:

KiCad field  Field name
-----------  ----------
Reference    REF (*)
Value        VAL
Footprint    FP           
Field1       F1
...          ...

(*) As a shortcut, REF= can be omitted.

Note that fields with a user-defined name currently still only appear
as F1, F2, etc.

The special field name FN can be used to look for a match in all of
F1, F2, ... This way, it's sufficient to use a consistent syntax for
additional parameters, without having to assign also a fixed location
for them. If more than one field matches, the first match is taken.

Field names are case-insensitive.

The pattern is uses a notation similar to filename globbing. There
are the following special constructs:

- * matches a string of any length
- ? matches a single character
- (...) matches the pattern between the parentheses and records the
  string matched
- $X marks a value in nXn notation, e.g., 4u7 or 100R. Such values
  are converted to SI-like notation.

A rule is applied when all conditions are fulfilled. In this case,
assignments of the form field=value are executed. Strings obtained
in the match can be included in a value as follows:

- $field and ${field} are replaced by the respective field
- $field:n and ${field:n} are replaced by the n-th (...) pattern in
  the match of the respective field

If a rule ends with an exclamation mark, the substitution process stops
after the rule is applied. Otherwise, further rules are processed.

Examples:

R* val=$R -> R=$val

This rule translates the values of all resistors to SI notation.

D* FN=(*)Vdc -> T=TSV Vdc=FN:1

This rule sets the parameters T and Vdc for Zeners acting as TSVs.

If a set of rules has a common set of conditions or assignments, the
more compact block notation can be used instead of repeating them for
each rule:

common-conditions -> common-assignments {
    rule-specific-conditions -> rule-specific-assignments
    ...
}

Rules in a block only match if both the common and the rule-specific
conditions are met. Then the common and the rule-specific assignments
are performed. If a condition or an assignment appears both in the
common and the rule-specific part, only the latter is used.

Long lines can be wrapped by indenting the continuation lines. Note
that { and ! are also considered to be part of the same line as the
rest of the rule. In particular, the following construct wouldn't
work:

X=Y
{
    ...
}

With proper indentation, this would:

X=Y
  {
    ...
}


Characteristics generation (.gen)
---------------------------------

The substitution mechanism can also be used to automatically generate
characteristics from part numbers, e.g., for resistors or capacitors.

.gen files are exactly .sub files, with the exception that the only
field used is the REF field and that it contains the part number.

Once the rule set has been processed, all fields (except REF) whose
name doesn't begin with an underscore are placed in the characteristics
entry as parameters.

An entry is only produced if the rule set is explicitly terminated.


Parts list (.par)
------------------

A parts file lists the parts that are suitable for a given BOM item.
The file begins with a line containing only
#PAR

After this, each line contains the component reference, a space, and
then one or more namespace part-number groups, separated by spaces as
well.

Blank lines and comments (#) are ignored.


Order list (.ord)
-----------------

An order file lists the quantities to order from inventories, along
with the cost and the component references the item is used for. The
file begins with a line containing only
#ORD

After this, each line contains the supplier (namespace), the part
number, the number of items to order, the currency code, the cost,
and one or more component references.

Blank lines and comments (#) are ignored.


Equivalence (.equ)
------------------

Equivalence files establish equivalences between parts numbers in the
same or in different name spaces. An equivalence file begins with a
line containing only
#EQU

After this, each line consists of the following four space-separated
fields:

namespace-1 part-number-1 namespace-2 part-number-2

Blank lines and comments (#) are ignored.


Inventory (.inv)
----------------

Inventory files list inventory and component cost. An inventory file
begins with a line containing only
#INV

After this, each line contains the namespace and the part number,
followed by the number of items in stock, the currency code, and one
or more pricing entries.

Each pricing entry consists of two fields: the number of items in an
order, and the per item price at that quantity. A sequence of
increasing order sizes indicates that they are quanta. A sequence of
decreasing order sizes indicates that smaller quanta are possible
after a previous larger threshold has been met.

Example:

... USD 1 0.5 10 0.4 100 0.2

Means that an order of at least 170 units would be made either as
2 * 100 units, costing USD 40, or as 1 * 100 + 7 * 10 units, costing
USD 20 + USD 28 = USD 48.

If the entry is

... USD 1 0.5 10 0.4 100 0.2 1 0.2

Then the USD 0.2 per unit cost would apply to any any quantity of at
least 100 units. So a 170 units order would cost USD 34.

Blank lines and comments (#) are ignored.

The number of items in stock and the pricing data can be omitted. We
call this "virtual inventory". In this case, the numer of items in
stock and the price default to large numbers (e.g., 999999). Virtual
inventory is used to suppress warnings for parts that have not been
sourced yet, but where sourcing is in progress.


Description (.dsc)
------------------

A description file contains plain text descriptions of parts. The file
begins with a like containing only
#DSC

Each line contains the name space, a space, the part number, another
space, and the description. The description can contain any printable
character and ends with a newline.

Blank lines and comments (#) are ignored.