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 - 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.