Maker Pro
PCB

Catch BOM-to-Placement Mismatches Before PCB Assembly

DR
November 05, 2026 by Diana Ren
Share
banner

Build a local Python checker for normalized PCB BOM and placement CSV files. Detect missing, duplicate, DNP and unknown references using synthetic examples, with 13 automated tests. This checks reference consistency, not full DFM.

A small, local Python tool for checking reference-designator consistency between a normalized bill of materials (BOM) and a normalized component-placement file.

This is a reproducible software technique for a PCB assembly handoff. The example board data are synthetic: no physical board was fabricated or electrically tested for this tutorial. The tool and this tutorial were developed with AI assistance for AtlasPCB; the accompanying automated tests were actually run.

The problem this check addresses

When two release files come from different revisions, a populated BOM reference can be absent from the placement file. A reference intentionally marked “do not populate” can also remain in the placement file. This tool makes those inconsistencies visible before you hand the files to an assembler.

It does not decide which revision is correct. Resolve each finding against your controlled design files and the assembler's agreed instructions.

What you need

• A computer with Python 3.9 or later. The included validation run used Python 3.13.

• The files in this package. No third-party Python packages are required.

• Copies of your BOM and placement export. Keep the original exports unchanged.

The checker reads local CSV files; it does not upload files or connect to a manufacturing service.

1. Normalize two review copies

CAD and assembler CSV formats differ. This version deliberately uses a small, explicit schema rather than guessing your tool's column meanings. Adapt copies of your exports to these headers:

BOM

reference,populate
U1,yes
R1,yes
C1,yes
R2,no

Placement

reference,x_mm,y_mm,rotation_deg,side
U1,10,10,0,top
R1,14,10,90,top
C1,10,14,180,bottom

Rules:

• One reference per row. Split grouped BOM references such as R1,R2 into separate rows before using this checker.

• Required header names are exact and case-sensitive. Extra named columns are ignored.

• Use yes for populated components and no for do-not-populate components. Values are case-insensitive.

• References are stripped of surrounding whitespace and compared in uppercase. The supported reference syntax is an ASCII letter followed by ASCII letters, digits or underscores.

• Coordinates and rotation must be finite numbers. Negative coordinates are allowed. There is no coordinate, rotation, unit or origin conversion.

• Map the side explicitly to top or bottom. For example, F.Cu is rejected rather than silently interpreted.

• Save as UTF-8 CSV; a UTF-8 byte-order mark is accepted. Quoted CSV fields are supported.

• Blank data sets, duplicate headers and rows with the wrong number of cells are rejected.

This workflow assumes every populated BOM component belongs in the supplied placement file. If your assembler excludes hand-fitted or through-hole parts, agree on that scope and prepare a separate review set. Do not mark genuinely populated parts DNP simply to get a passing result.

2. Run the passing example

From the extracted package directory:

python3 check_handoff.py examples/bom.csv examples/placement_good.csv

On Windows, use py -3 instead of python3 if that is how Python is installed.

Expected output:

PASS: reference consistency only; 4 BOM references; 3 placement references
Not checked: units/origin correctness, rotation conventions, footprints, polarity, Gerbers, electrical design, or manufacturability.

R2 is marked no in the BOM and is absent from the placement file, which is consistent with this example's scope.

3. Find four deliberately inserted errors

The bad fixture duplicates U1, omits C1, adds DNP reference R2, and adds an unknown reference R99:

python3 check_handoff.py examples/bom.csv examples/placement_bad.csv

Expected output:

DNP_IN_PLACEMENT: R2
DUPLICATE_PLACEMENT: U1
MISSING_PLACEMENT: C1
NOT_IN_BOM: R99
FAIL: 4 issue(s); 4 unique BOM references; 4 unique placement references

Interpret each finding separately:

• DNP_IN_PLACEMENT: verify the intended population variant. Is the BOM's DNP flag correct, or should this placement row be removed?

• DUPLICATE_PLACEMENT: resolve the duplicate from the original CAD export. Do not choose one arbitrarily.

• MISSING_PLACEMENT: check whether the BOM and placement file came from the same revision and whether the part is inside the agreed assembly scope.

• NOT_IN_BOM: inspect for stale placement data or a BOM omission.

• DUPLICATE_BOM is also detected, including differently cased duplicates such as U1 and u1.

The program reports findings; it never rewrites either input file.

4. Make it a repeatable release step

Exit codes are:

• Exit 0: no reference-consistency findings in the supported scope.

• Exit 1: one or more consistency findings.

• Exit 2: input, schema, file or command-line error.

Run the checker on the exact review files associated with your release, and retain its output beside the release manifest. A clean result is one check in the release process, not permission to manufacture.

Run the regression tests:

python3 -m unittest -v test_check_handoff.py

On 2026-11-05, all 13 tests passed locally. They cover valid input and DNP exclusion; whitespace, case and UTF-8 BOM handling; missing, unknown and duplicate references; malformed headers, row widths and CSV quotes; invalid population flags, nonfinite coordinates and unsupported side labels; and CLI exit codes 0, 1 and 2.

5. Keep the human review

This checker cannot establish that a board is electrically correct or manufacturable. It does not parse Gerbers, inspect footprints, compare package names or manufacturer part numbers, check polarity, validate pin 1, evaluate clearances or thermal design, confirm coordinate origin, or interpret an assembler's rotation convention.

For example, a placement row with the correct reference but the wrong rotation can pass. Two wrong files containing identical reference sets can also pass. Inspect the exported geometry and assembly drawings, verify your component data, and resolve engineering questions with the manufacturer.

Attribution and files

Prepared for the hardware community by Diana Ren / AtlasPCB, with AI-assisted development and documentation. AtlasPCB is a PCB sourcing and supply-chain partner. The complete checker and synthetic fixtures are provided here; visiting a company website is not required to use them.

Project contact and organization: AtlasPCB

Package contents:

• check_handoff.py — standard-library command-line checker.

• test_check_handoff.py — reproducible regression tests.

• examples/ — synthetic passing and failing review files.

• validation-output.txt — output captured during the local validation run.

• LICENSE — MIT license for this package.

If adapting this for your CAD exporter, document that adapter's schema and test it separately; this release makes no claim of direct KiCad, Altium or Eagle export compatibility.

Author

DR
Diana Ren

Diana Ren at AtlasPCB, a PCB sourcing and supply-chain partner. Sharing reproducible PCB handoff tools. https://www.atlaspcb.com/

Related Content

Categories

Tags

Comments


You May Also Like