mirror of
git://projects.qi-hardware.com/eda-tools.git
synced 2024-11-05 17:47:11 +02:00
338 lines
9.2 KiB
Plaintext
338 lines
9.2 KiB
Plaintext
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.
|