Root/
| 1 | The BOM processing system |
| 2 | ========================= |
| 3 | |
| 4 | The BOM processing system takes a bill of material generated by |
| 5 | KiCad and converts it in various steps into a "shopping list" |
| 6 | that can be used to order from various providers. |
| 7 | |
| 8 | |
| 9 | Introduction |
| 10 | ============ |
| 11 | |
| 12 | The following sections describe how to use the basic elements of |
| 13 | the BOM processing system. |
| 14 | |
| 15 | |
| 16 | A simple BOM translation |
| 17 | ------------------------ |
| 18 | |
| 19 | KiCad identifies components by a so-called component reference, |
| 20 | e.g., R1001, U5, etc. In addition to this, each component can have |
| 21 | various parameters, such as a "value", its footprint, and further |
| 22 | user-defined items. These parameters can be shown in the schematics |
| 23 | (e.g., the value usually is) or they can be hidden (e.g., the |
| 24 | footprint). |
| 25 | |
| 26 | At the end of the process, we want a "shopping list" that can be |
| 27 | used to order items or to find them in an inventory or catalog. |
| 28 | Components in the shopping list are identified by a part number. |
| 29 | |
| 30 | ... |
| 31 | - BOM |
| 32 | - inventory |
| 33 | - ID matching |
| 34 | |
| 35 | |
| 36 | Equivalences |
| 37 | ------------ |
| 38 | |
| 39 | A single component can be associated with multiple part numbers. |
| 40 | For example, a chip its manufacturer calls "XYZ-R1" may be listed in |
| 41 | a distributor's catalog with a completely different order number, |
| 42 | such as "20-1234-8". The BOM processing system therefore |
| 43 | distinguishes multiple so-called name spaces. A name space is |
| 44 | identified by a (unique) name and a part number is generally |
| 45 | qualified by the name of the name space. |
| 46 | |
| 47 | E.g., if the manufacturer is called "ACME" and the distributor of |
| 48 | electronical components calls itself "DIST-EL", the part in our |
| 49 | example may have the equivalent names "ACME XYZ-R1" and "DIST-EL |
| 50 | 20-1234-8". |
| 51 | |
| 52 | ... |
| 53 | - revise .inv |
| 54 | |
| 55 | example.equ: |
| 56 | |
| 57 | #INV |
| 58 | DIST-EL 20-1234-8 |
| 59 | #EQU |
| 60 | ACME XYZ-R1 DIST-EL 20-1234-8 |
| 61 | |
| 62 | |
| 63 | Adding stock and cost |
| 64 | --------------------- |
| 65 | |
| 66 | - .inv, more fields |
| 67 | - quanta |
| 68 | |
| 69 | Substituting component names |
| 70 | ---------------------------- |
| 71 | |
| 72 | - intro to .sub |
| 73 | - ad-hoc fixes |
| 74 | |
| 75 | |
| 76 | Selecting characteristics |
| 77 | ------------------------- |
| 78 | |
| 79 | - .sub |
| 80 | - .chr |
| 81 | - <rel><number><multiplier><unit> syntax |
| 82 | ... |
| 83 | |
| 84 | |
| 85 | Generating characteristics |
| 86 | -------------------------- |
| 87 | |
| 88 | - .gen |
| 89 | |
| 90 | |
| 91 | Advanced topics |
| 92 | =============== |
| 93 | |
| 94 | - generating .inv files |
| 95 | - different presentations (e.g., CT, TR, ...) |
| 96 | - component substitution (one-way equivalence) |
| 97 | - problem reports |
| 98 | - hiding known problems (while sourcing) |
| 99 | |
| 100 | |
| 101 | File formats |
| 102 | ============ |
| 103 | |
| 104 | The BOM processing system uses a large number of different files to |
| 105 | store information retrieved from the BOM, inventories, intermediate |
| 106 | results, etc. The following sections describe the various formats. |
| 107 | |
| 108 | |
| 109 | Part characteristics (.chr) |
| 110 | --------------------------- |
| 111 | |
| 112 | A part characteristics file lists the parameters of components. |
| 113 | This information is then matched with the parameters specified in |
| 114 | the schematics. |
| 115 | |
| 116 | The part characteristics file begins with a line containing only |
| 117 | #CHR |
| 118 | |
| 119 | After this, each line contains the manufacturer (namespace), the |
| 120 | part number, and a list of parameter=value entries. Fields are |
| 121 | separated by spaces. |
| 122 | |
| 123 | Long lines can be wrapped by indenting the continuation lines. |
| 124 | |
| 125 | Blank lines and comments (#) are ignored. |
| 126 | |
| 127 | |
| 128 | Substitutions (.sub) |
| 129 | -------------------- |
| 130 | |
| 131 | A substitutions file specifies rules for translating component |
| 132 | parameters in schematics to part characteristics. |
| 133 | |
| 134 | A substitution rule consists of zero or more conditions and zero or |
| 135 | more assignments. The conditions are of the form field=pattern. The |
| 136 | field can be a per-component fields KiCad provides or any parameter |
| 137 | set by substitutions. |
| 138 | |
| 139 | KiCad fields are named as follows: |
| 140 | |
| 141 | KiCad field Field name |
| 142 | ----------- ---------- |
| 143 | Reference REF (*) |
| 144 | Value VAL |
| 145 | Footprint FP |
| 146 | Field1 F1 |
| 147 | ... ... |
| 148 | |
| 149 | (*) As a shortcut, REF= can be omitted. |
| 150 | |
| 151 | Note that fields with a user-defined name currently still only appear |
| 152 | as F1, F2, etc. |
| 153 | |
| 154 | The special field name FN can be used to look for a match in all of |
| 155 | F1, F2, ... This way, it's sufficient to use a consistent syntax for |
| 156 | additional parameters, without having to assign also a fixed location |
| 157 | for them. If more than one field matches, the first match is taken. |
| 158 | |
| 159 | Field names are case-insensitive. |
| 160 | |
| 161 | The pattern is uses a notation similar to filename globbing. There |
| 162 | are the following special constructs: |
| 163 | |
| 164 | - * matches a string of any length |
| 165 | - ? matches a single character |
| 166 | - (...) matches the pattern between the parentheses and records the |
| 167 | string matched |
| 168 | - $X marks a value in nXn notation, e.g., 4u7 or 100R. Such values |
| 169 | are converted to SI-like notation. |
| 170 | |
| 171 | A rule is applied when all conditions are fulfilled. In this case, |
| 172 | assignments of the form field=value are executed. Strings obtained |
| 173 | in the match can be included in a value as follows: |
| 174 | |
| 175 | - $field and ${field} are replaced by the respective field |
| 176 | - $field:n and ${field:n} are replaced by the n-th (...) pattern in |
| 177 | the match of the respective field |
| 178 | |
| 179 | If a rule ends with an exclamation mark, the substitution process stops |
| 180 | after the rule is applied. Otherwise, further rules are processed. |
| 181 | |
| 182 | Examples: |
| 183 | |
| 184 | R* val=$R -> R=$val |
| 185 | |
| 186 | This rule translates the values of all resistors to SI notation. |
| 187 | |
| 188 | D* FN=(*)Vdc -> T=TSV Vdc=FN:1 |
| 189 | |
| 190 | This rule sets the parameters T and Vdc for Zeners acting as TSVs. |
| 191 | |
| 192 | If a set of rules has a common set of conditions or assignments, the |
| 193 | more compact block notation can be used instead of repeating them for |
| 194 | each rule: |
| 195 | |
| 196 | common-conditions -> common-assignments { |
| 197 | rule-specific-conditions -> rule-specific-assignments |
| 198 | ... |
| 199 | } |
| 200 | |
| 201 | Rules in a block only match if both the common and the rule-specific |
| 202 | conditions are met. Then the common and the rule-specific assignments |
| 203 | are performed. If a condition or an assignment appears both in the |
| 204 | common and the rule-specific part, only the latter is used. |
| 205 | |
| 206 | Long lines can be wrapped by indenting the continuation lines. Note |
| 207 | that { and ! are also considered to be part of the same line as the |
| 208 | rest of the rule. In particular, the following construct wouldn't |
| 209 | work: |
| 210 | |
| 211 | X=Y |
| 212 | { |
| 213 | ... |
| 214 | } |
| 215 | |
| 216 | With proper indentation, this would: |
| 217 | |
| 218 | X=Y |
| 219 | { |
| 220 | ... |
| 221 | } |
| 222 | |
| 223 | |
| 224 | Characteristics generation (.gen) |
| 225 | --------------------------------- |
| 226 | |
| 227 | The substitution mechanism can also be used to automatically generate |
| 228 | characteristics from part numbers, e.g., for resistors or capacitors. |
| 229 | |
| 230 | .gen files are exactly .sub files, with the exception that the only |
| 231 | field used is the REF field and that it contains the part number. |
| 232 | |
| 233 | Once the rule set has been processed, all fields (except REF) whose |
| 234 | name doesn't begin with an underscore are placed in the characteristics |
| 235 | entry as parameters. |
| 236 | |
| 237 | An entry is only produced if the rule set is explicitly terminated. |
| 238 | |
| 239 | |
| 240 | Parts list (.par) |
| 241 | ------------------ |
| 242 | |
| 243 | A parts file lists the parts that are suitable for a given BOM item. |
| 244 | The file begins with a line containing only |
| 245 | #PAR |
| 246 | |
| 247 | After this, each line contains the component reference, a space, and |
| 248 | then one or more namespace part-number groups, separated by spaces as |
| 249 | well. |
| 250 | |
| 251 | Blank lines and comments (#) are ignored. |
| 252 | |
| 253 | |
| 254 | Order list (.ord) |
| 255 | ----------------- |
| 256 | |
| 257 | An order file lists the quantities to order from inventories, along |
| 258 | with the cost and the component references the item is used for. The |
| 259 | file begins with a line containing only |
| 260 | #ORD |
| 261 | |
| 262 | After this, each line contains the supplier (namespace), the part |
| 263 | number, the number of items to order, the currency code, the cost, |
| 264 | and one or more component references. |
| 265 | |
| 266 | Blank lines and comments (#) are ignored. |
| 267 | |
| 268 | |
| 269 | Equivalence (.equ) |
| 270 | ------------------ |
| 271 | |
| 272 | Equivalence files establish equivalences between parts numbers in the |
| 273 | same or in different name spaces. An equivalence file begins with a |
| 274 | line containing only |
| 275 | #EQU |
| 276 | |
| 277 | After this, each line consists of the following four space-separated |
| 278 | fields: |
| 279 | |
| 280 | namespace-1 part-number-1 namespace-2 part-number-2 |
| 281 | |
| 282 | Blank lines and comments (#) are ignored. |
| 283 | |
| 284 | |
| 285 | Inventory (.inv) |
| 286 | ---------------- |
| 287 | |
| 288 | Inventory files list inventory and component cost. An inventory file |
| 289 | begins with a line containing only |
| 290 | #INV |
| 291 | |
| 292 | After this, each line contains the namespace and the part number, |
| 293 | followed by the number of items in stock, the currency code, and one |
| 294 | or more pricing entries. |
| 295 | |
| 296 | Each pricing entry consists of two fields: the number of items in an |
| 297 | order, and the per item price at that quantity. A sequence of |
| 298 | increasing order sizes indicates that they are quanta. A sequence of |
| 299 | decreasing order sizes indicates that smaller quanta are possible |
| 300 | after a previous larger threshold has been met. |
| 301 | |
| 302 | Example: |
| 303 | |
| 304 | ... USD 1 0.5 10 0.4 100 0.2 |
| 305 | |
| 306 | Means that an order of at least 170 units would be made either as |
| 307 | 2 * 100 units, costing USD 40, or as 1 * 100 + 7 * 10 units, costing |
| 308 | USD 20 + USD 28 = USD 48. |
| 309 | |
| 310 | If the entry is |
| 311 | |
| 312 | ... USD 1 0.5 10 0.4 100 0.2 1 0.2 |
| 313 | |
| 314 | Then the USD 0.2 per unit cost would apply to any any quantity of at |
| 315 | least 100 units. So a 170 units order would cost USD 34. |
| 316 | |
| 317 | Blank lines and comments (#) are ignored. |
| 318 | |
| 319 | The number of items in stock and the pricing data can be omitted. We |
| 320 | call this "virtual inventory". In this case, the numer of items in |
| 321 | stock and the price default to large numbers (e.g., 999999). Virtual |
| 322 | inventory is used to suppress warnings for parts that have not been |
| 323 | sourced yet, but where sourcing is in progress. |
| 324 | |
| 325 | |
| 326 | Description (.dsc) |
| 327 | ------------------ |
| 328 | |
| 329 | A description file contains plain text descriptions of parts. The file |
| 330 | begins with a like containing only |
| 331 | #DSC |
| 332 | |
| 333 | Each line contains the name space, a space, the part number, another |
| 334 | space, and the description. The description can contain any printable |
| 335 | character and ends with a newline. |
| 336 | |
| 337 | Blank lines and comments (#) are ignored. |
| 338 |
Branches:
master
