rescue files from svn.openmoko.org

2025-04-21 12:27:27 +03:00 · 2012-05-01 23:09:24 -03:00
parent 702343cabc
commit 881bf33be0
15 changed files with 2210 additions and 0 deletions
@@ -0,0 +1,337 @@
+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.