Skip to content

Alternate part numbers live in the ERP BOM, not in the schematic

Status: approved by Angel, 2026-09-15. Rule text lives in SOP-001 step 5, SOP-008 steps 18–20, SOP-021 step 13. Pilot: Cow_Robot_Board, Robot Cow 4.0.1.

The rule

  • The schematic and the hw/<board>/<rev> tag describe function: value, footprint, tolerance, and one primary ERP part number in the IPN field (SOP-008).
  • Alternates (second sources, drop-in equivalents) are BOM substitutes on the assembly's BOM line in the ERP. InvenTree already has this: each BOM line can carry any number of substitute parts, and stock, builds and purchasing all honour them.
  • Adding, removing or reordering an alternate is an ERP-only change. No schematic edit, no tag, no revision bump. SOP-001 already says a revision bump is for fit, form or function only; an alternate by definition changes none of them.
  • If the "alternate" does change fit, form or function (different package, different spec), it is not an alternate: it is a design change and gets a revision (SOP-001 step 4).

What the fab receives

  • The fab pack's assembly/<board>-<rev>-bom.csv is the design BOM from KiCad (primary IPN per line).
  • A second file, <board>-<rev>-order-bom.csv, is the order BOM exported from the ERP: one row per BOM line with the primary part and every substitute (MPN, manufacturer, LCSC), so the fab may use any of them. This file is generated at order time by ~/.local/bin/erp-bom-export <assembly-IPN> (to be written), because CI cannot reach the ERP; it is added to the zip before upload (SOP-005).

Pilot: Robot Cow

Reality check before any of this can run on the Cow: - Robot Cow 4.0.1 is not in the ERP as an assembly; only Dashcam Drive (EE-A-0001) is. - The schematic has 235 symbols, 50 distinct values, only 11 with a manufacturer part number, and none of those 11 exist in the ERP yet. No symbol carries an IPN.

So the pilot is three steps, in order: 1. Create the assembly EE-A-0002 Robot Cow and its bare PCB EE-P-0002-A in the ERP (SOP-001, SOP-003), then parts for the 50 values with the Cow's actual MPNs (part-normalise, SOP-003). 2. Put the IPN on each symbol and import the BOM against the assembly (SOP-008 §6). 3. Add the first alternates as substitutes, run erp-bom-export, and check the order BOM reads the way a fab expects.

Step 1 is the bulk of the work and needs the real MPNs from the last Cow order (the JLCPCB order BOM in hardware/Robot Cow/production/) to avoid guessing.

Update — 2026-09-16: pilot board corrected to 004B

Angel corrected product.yml: the shipping Robot Cow is board hardware/Robot-Cow-004B (project Robot-Cow-004B.kicad_pcb/.kicad_sch), not hardware/Robot Cow 4.0.1 used above. Everything this pilot built — the ERP assembly/BOM for EE-A-0002-A, the schematic IPN properties, fab.yml, and the hw/<board>/<rev> release — moved to 004B. The BOM diff between the two boards (fitted, non-power symbols) was: 4.0.1-only D11/D12 (BAT54S), R25/R26 (33R) dropped; 004B-only C5/C6 (1u), D3/D4 (BAT54S), R7/R8 (10k), R10 (new 4.7K), R12 (new 220R), U7 (USBLC6-2SC6) added; D1 changed from a SOD-123 5.1V zener to a MiniMELF ZMM5V1 (new part); D13/D15 LED colours swapped (D13 now green, D15 now orange). See the Log in ~/Notes/projects/project-template.md for the exact ERP pks/IPNs and release details.

Update — 2026-09-28: generic passives carry no alternates and no IPN

The generic resistor and capacitor libraries in the KiCad repo (EmbeddedEra_Resistors_*, EmbeddedEra_Capacitors_*) first shipped with Alternate/Preferred fields on every symbol. That broke this rule, and their scale (~13,500 symbols against a four-digit part number) also rules out pre-assigning IPNs. Decided: the symbols carry function plus one primary manufacturer part and nothing else; the approved makers stay in scripting/generic_passives_avl.json as the data source; the ERP part (and its extra manufacturer parts) is created the first time a value is used on a board, then the IPN is written into that board's schematic, not the library. Procedure: SOP-008 steps 21 to 26 (draft 2.0). Tool still to build: kicad-erp-sync bom-resolve. Rollback tag in the KiCad repo: rollback/before-alternates-strip.