ProjekinAja. Embedded Systems Stage 5 · PCB Design Lesson 5.3
● Stage 5 · Lesson 5.3

Symbols, Footprints, and the Lie in Every Library

A library footprint is someone else's reading of a datasheet. Check it as if they were tired when they made it.

⏱ ~24 min read 🧠 Physical correctness 🛠 KiCad footprint editor

🎯 By the end you'll understand

Why a symbol's pin numbers, not its pin names, are what the board is built from, and how to verify them against a datasheet pinout in five minutes. Every layer of a footprint — pads, courtyard, fab outline, silkscreen, mask and paste — and the specific way each one fails on the bench: shorts, tombstones, parts that will not insert, parts mounted backwards. What IPC-7351's three density levels trade off. How to run a project library so that every pattern on Beacon has been checked and signed. And the three Beacon parts whose footprints need more than a glance — including the LED footprint whose pin-1 mark sent Rev A's LEDs out rotated.

KEY INSIGHTThe netlist connects pin numbers to pad numbers, and nothing checks either against the part

Every one of twenty-five boards had the LED rotated. The footprint had been "checked": pads measured, pitch measured, courtyard present. Nobody had checked which corner the footprint called pin 1.

Here is what a schematic-to-board flow actually transmits. The symbol for the LED has four pins numbered 1 to 4, with names like VDD and DIN. The footprint has four pads numbered 1 to 4. When you update the board from the schematic, KiCad connects the net on symbol pin 3 to footprint pad 3. That is the entire contract. Whether symbol pin 3 is really the part's GND, whether footprint pad 3 sits where the part's GND terminal lands, and whether the footprint's idea of "pin 1 corner" matches the part's — none of that is checked by any tool, because no tool has read the datasheet. A library author did, once, possibly for a different package variant, possibly at 2 a.m.

That is the lie in the title. Not malice: every library footprint is an interpretation, and interpretations drift from their source. The datasheet gets a revision, the package variant is different from the one the author drew, the pin-1 convention for a four-pad LED is ambiguous, and the KiCad Library Convention's rules for where to put the pin-1 marker are applied inconsistently by hundreds of contributors. The professional response is neither to trust libraries nor to redraw everything, but to copy, verify against the datasheet, and sign — every part, every revision.

🔑 Hold onto this

Two checks catch almost everything: pin number to function on the symbol against the datasheet's pin table, and pad number to physical position, including pin 1's corner on the footprint against the datasheet's package drawing, viewed from the top. A third — opening the 3D viewer and looking at the model on the pads — catches most of what the first two miss, at the cost of ninety seconds.

HOW IT WORKSSymbols: pin numbers are the contract, pin names are the comments

A KiCad symbol pin has a number (the string that maps to a footprint pad — usually "1", "2", but "A1", "EP", "PAD" are legal), a name (VDD, SDA, INT1 — for humans and for ERC's readability), and an electrical type (Lesson 5.2). The number is what matters for correctness. A symbol with SDA on pin 3 and SCL on pin 4, placed on a footprint drawn for a part whose SDA is on pad 4, produces a schematic that reads perfectly and a board with the bus swapped. ERC is happy, DRC is happy.

The verification is mechanical: open the datasheet's pin table, open the symbol in the Symbol Editor, and go down the list. Five minutes for an eight-pin part; fifteen for the ESP32-C3-MINI-1. Look for these specific traps:

💡 Symbol layout should follow function, not the package

A symbol that is a box with pins numbered around the perimeter in package order is easy to draw and miserable to read: power scattered, bus pins on opposite sides. Redraw it functionally — power top, ground bottom, inputs left, outputs right, I2C pins adjacent — and keep the numbers. The redraw is the moment you read every pin against the datasheet anyway. Two birds.

CORE CONCEPTAnatomy of a footprint, and how each layer fails

A footprint is a stack of layers, each with a purpose and a characteristic way of going wrong. Here they are in the order the assembler meets them.

One footprint, six layers (2.0 × 2.0 mm four-pad LED, illustrative geometry) F.Cu — pads 1 2 3 4 numbered · sized · pitched F.Mask — openings pad + expansion · dam between F.Paste — stencil usually = pad; reduced on big pads F.Fab + F.SilkS fab: true outline + pin-1 chamfer silk: outline + dot, never on a pad F.CrtYd body + pads + clearance DRC: courtyards must not overlap The pin-1 dot on silkscreen and the chamfer on F.Fab must agree with each other AND with the datasheet's top-view drawing — the CPL rotation is derived from this footprint's orientation.
Each layer is drawn separately and each can be wrong separately. The assembler's pick-and-place rotates the part according to the footprint's orientation as exported in the CPL; the assembler's inspector looks at the silkscreen dot. If the footprint's pin-1 corner does not match the part's, both of them do their job correctly and the LED is still backwards.
LayerWhat it definesHow it fails on the bench
Copper pads (F.Cu)Size, shape, pitch, numbering, hole for through-hole partsToo small: weak joint, no fillet. Too close: bridge. Wrong pitch: every other pin misses. Wrong hole: pin will not insert or rattles. Asymmetric pads on a two-terminal chip: tombstone — one end wets first and the surface tension stands the part up.
Solder mask (F.Mask)Opening around each pad (pad + expansion), the dam between padsDam thinner than the fab can make: the fab removes it, and adjacent pads share one opening — bridges under a fine-pitch part become likely.
Paste (F.Paste)Stencil aperturesFull paste on a large thermal pad floats the part on a bead of solder; its perimeter pins never touch. Reduce to ~50–70% coverage in a window pattern (the datasheet often specifies).
Fab (F.Fab)True body outline, pin-1 mark, reference for the CPLPin-1 mark on the wrong corner: the part is placed rotated on every board. The most expensive line in this table.
Silkscreen (F.SilkS)What the human sees: outline, pin-1 dot, polarity bandSilk over a pad is clipped by the fab (or wicks solder). Silk that disagrees with F.Fab makes the inspector "correct" a correctly placed part.
Courtyard (F.CrtYd)The exclusion box: body + pads + assembly clearanceToo small: parts collide, or a rework nozzle cannot reach. Missing: DRC's courtyard-overlap check is disabled for that part.
3D modelSTEP/WRL for the viewerNot a manufacturing layer — but the fastest way to see a rotated pin 1, a connector facing inwards, or a module hanging off the board.
📖 Tombstoning, mechanically

During reflow, molten solder's surface tension pulls each terminal toward the centre of its pad. On a two-terminal chip (0402, 0603) the two pulls cancel if both ends melt together and the pads are symmetric. If one pad is bigger, or connects to a wide copper pour without thermal relief so it heats slower, or has more paste, one end melts first, its pull is unopposed, and the part pivots up on the other end — a tombstone. The fix is a footprint fix (equal pads, equal paste) and a layout fix (thermal spokes into pours), and it is why "just make the ground pad bigger" is not free.

COMPARISONIPC-7351 density levels: how much pad is enough

IPC-7351 is the land-pattern standard most libraries follow. It derives pad dimensions from the component's terminal dimensions plus three margins — toe (outside the terminal), heel (under the body), and side — and it publishes three sets of margins:

LevelNameMarginsUse whenCost
AMost (maximum land protrusion)Largest toe/heel/sideHand assembly, rework-heavy prototypes, high-reliability with inspectionBoard area; bridging risk on fine pitch
BNominal (median)MedianOrdinary production; what KiCad's library and most fabs assume—
CLeast (minimum)SmallestDense boards with controlled process; phones, wearablesWeaker joints, no room for rework, needs a tuned reflow profile

Beacon at 35 × 25 mm is dense but not phone-dense, and it will be reworked on the bench. Nominal (B) is the right default — with one deliberate exception: the parts you know you will rework (the LED, the sensors) may get a Level-A toe so a hot-air nozzle and tweezers have something to work with. Level C anywhere on a first revision is a decision to spend rework time later to save area now; write down why.

SEE ITFootprint verifier

Three of Beacon's footprints, each compared against a reference drawn from its datasheet's package drawing. Adjust the footprint the way a library author might have, and the widget overlays the part and tells you what the board would do: short, tombstone or skew, refuse to insert, or mount backwards. The reference geometry is simplified for teaching — the checks are the real ones; the exact millimetres come from the datasheet you have open at the bench.

⚙ Interactive · Footprint verifier

Pick a part. Every control changes the footprint; the datasheet reference stays fixed. Simplified geometry, deterministic checks.

0.70 mm
0.90 mm
1.30 mm
1.10 mm
0.70 mm
1.20 mm
0.50 mm
60%
Verdict
—

Notice how the LED's worst outcome is produced by a control that does not change a single pad dimension. Every geometric check passes with pin 1 on the wrong corner; the footprint is "correct" by every measurement and the part is backwards. The JST connector's worst outcome — polarity — is the same kind of defect: not a millimetre, a meaning. Measure pads, yes; but the questions that cost respins are which corner and which pin.

IN PRACTICEManaging the project library: copy, verify, sign, never edit in place

Lesson 5.1 set the policy: every symbol and footprint on Beacon resolves to the project's own library. Here is the routine that makes it real, per part, in the order that catches the most for the least time:

1

Copy, don't reference

Find the symbol in the global library, then Save copy to library → beacon.kicad_sym. Same for the footprint into beacon.pretty. From now on the global copy is irrelevant to this board.

2

Symbol: pin table walk

Datasheet pin table on one screen, Symbol Editor on the other. Number → function → type, every pin. Fix names to match the datasheet's exactly (INT1, not INT) so a reviewer can grep.

3

Footprint: package drawing walk

Datasheet's recommended land pattern (if given) or package drawing, top view. Check pad count and numbering direction, pitch, pad size, pin-1 corner on F.Fab and F.SilkS, courtyard exists, paste on any large pad is reduced, mask expansion is default unless the datasheet says otherwise. Measure with the editor's ruler, not by eye.

4

3D model on the pads

Attach a STEP model (manufacturer's or KiCad's), open the 3D viewer, and look at the pin-1 mark on the model against the footprint's mark. Ninety seconds. This is the step that would have saved Rev A's LED.

5

Sign it

Add a Checked property: date, initials, datasheet revision and figure. A footprint without the property fails the Lesson 5.9 review by rule. Commit.

beacon.pretty/LED_WS2812B-2020.kicad_modexcerpt · KiCad 8 s-expression
(footprint "LED_WS2812B-2020" (version 20240108) (generator "pcbnew")
  (layer "F.Cu")
  (property "Reference" "REF**" (at 0 -2.2) (layer "F.SilkS") …)
  (property "Checked" "2026-08 LCL · datasheet pkg drawing, top view · pin 1 = corner with notch" …)
  (attr smd)
  ; F.Fab: true outline with pin-1 chamfer — the CPL rotation is derived from this orientation
  (fp_line (start -1.0 -0.7) (end -0.7 -1.0) (layer "F.Fab") (stroke (width 0.1)))
  ; F.SilkS: pin-1 dot OUTSIDE the courtyard corner, never on a pad
  (fp_circle (center -1.35 -1.35) (end -1.25 -1.35) (layer "F.SilkS") (stroke (width 0.15)) (fill solid))
  (fp_rect (start -1.25 -1.25) (end 1.25 1.25) (layer "F.CrtYd") (stroke (width 0.05)))
  (pad "1" smd rect (at -0.65 -0.55) (size 0.7 0.9) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "2" smd rect (at  0.65 -0.55) (size 0.7 0.9) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "3" smd rect (at  0.65  0.55) (size 0.7 0.9) (layers "F.Cu" "F.Paste" "F.Mask"))
  (pad "4" smd rect (at -0.65  0.55) (size 0.7 0.9) (layers "F.Cu" "F.Paste" "F.Mask"))
  (model "${KIPRJMOD}/lib/3d/WS2812B-2020.step" …)
)

Two things to notice in the file. The footprint is plain text — a reviewer can diff it, and git can show exactly which pad moved between Rev A and Rev B. And the pin-1 information lives in three places (the chamfer on F.Fab, the dot on F.SilkS, and pad "1"'s position), which must agree with each other and with the datasheet. The highlighted pad is the one whose position defines "pin 1 corner" for the placement file.

BEACONBeacon's parts that need a second look

Most of Beacon's passives and small ICs use KiCad's nominal-density patterns, copied and checked as above. Three parts need more, and one of them is the canon's Rev A defect.

🧪 ESP32-C3-MINI-1 — castellations, ground pads, and a keep-out that belongs in the footprint

The module's pads are castellated half-holes along three edges at fine pitch, plus a grid of ground pads under the body. Three checks: the base-board pads must extend outward past the module edge so a visible fillet forms on each half-hole (the datasheet's recommended footprint gives the length — and a fillet you can see is a joint you can inspect); the ground pads underneath get reduced paste so the module does not float on solder and lift its castellations off their pads; and the antenna region at the far end must have a keep-out on all copper layers — Beacon puts that keep-out inside the footprint as a rule area, so that whoever routes near the module later cannot forget it. Lesson 5.7 is about what happens when it is forgotten.

🧪 JST-PH 2.0 mm — pitch, hole, and a polarity nobody standardised

The battery lands on a 2-pin JST-PH: 2.0 mm pitch, through-hole pins in the datasheet's recommended 0.7 mm holes. The pitch trap is real — XH is 2.5 mm, ordinary headers are 2.54 mm, and a library search for "JST 2 pin" returns all three. The polarity trap is worse: JST defines pin numbers, not which pin is positive, and LiPo packs from different vendors arrive with the red wire on either pin. Beacon's footprint marks pin 1 as VBAT on the silkscreen, the schematic says so in a note, and the bring-up procedure in Stage 6 checks every pack before it is plugged in. The reverse-battery PMOS from Lesson 2.6 exists because this check will one day be skipped.

⚠ WS2812B-2020 — the pin-1 corner that sent Rev A's LEDs out rotated

The canon records it plainly: Rev A's LED footprint has pin 1 rotated. The pads were the right size, the right pitch, the right count. The pin-1 chamfer on F.Fab was drawn on the wrong corner — a four-pad square LED gives no geometric hint — and the CPL rotation, derived from that orientation, placed every LED turned. Whichever way a four-pad square is rotated, power and data pins land on each other's pads; at 180° the supply and ground swap outright. The review in Lesson 5.9 checked the schematic and the layout and never opened the 3D viewer on the LED; Lesson 6.1's bring-up finds an LED that does nothing and gets slightly warm. It is in the course because it is the most common footprint defect in the world, and because every check in this lesson would have caught it.

The remaining checks are quick but not skippable: the TPS62840's small leadless package (fine pitch, exposed pad — datasheet's land pattern, reduced paste), the MCP73831 in SOT-23-5 (pin numbering direction; the DFN variant's numbers differ), the SHT40's 1.5 × 1.5 mm DFN (tiny pads; Level-A toe for rework), the LIS2DH12 LGA-12 (pin-1 corner, no exposed pad), the DW01A SOT-23-6 and FS8205 TSSOP-8, the PRTR5V0U2X SOT-143B (an asymmetric package — the wide pin is the orientation key), the USB-C receptacle (SMD signal pads plus through-hole shell anchors, because a surface-mount-only shell is torn off by the third cable insertion), and the Tag-Connect TC2030 pattern, which must be taken from Tag-Connect's own library because its locating holes are the whole point.

WEAKNESSWhere footprints bite

✗ Trusting a "verified" tag from a parts-aggregator library

Downloadable symbol-and-footprint bundles from component search sites are convenient and often fine. They are also generated, sometimes from a different package variant, sometimes with pin 1 on the CAD tool's default corner rather than the datasheet's. The tag says a script ran, not that a human read the drawing. Treat them exactly like KiCad's global library: copy, verify, sign.

✗ Checking the footprint but not the CPL it produces

The fab's assembler places parts by the rotation in the placement file, and KiCad's rotation origin for a footprint follows the KiCad convention, which does not always match the assembler's zero-rotation convention for that package. JLCPCB, for one, publishes rotation corrections for common packages and shows a rendered preview of every placed part before you confirm the order. Look at the preview. A rotated LED is visible there, in colour, for free. It is the last gate before the bench.

✗ Enlarging pads "for easier soldering" on fine-pitch parts

Bigger pads under a hand-soldering iron are nice. Bigger pads under a 0.5 mm-pitch leadless package narrow the solder-mask dam between them below what the fab can make, so the fab merges the openings, and paste from adjacent apertures bridges during reflow. Level-A margins are for the toe, where there is room; the side margin on fine pitch is not yours to spend.

KEY INSIGHTHow this connects

With symbols and footprints verified, the netlist that crosses into the board editor is finally trustworthy. The next three lessons are about the board itself: what it is made of, where things go, and how the copper connects them.

GLOSSARYKey terms introduced

Pin number vs pin name
The number is the string that maps a symbol pin to a footprint pad and is what the board is built from; the name is documentation for humans and ERC.
Land pattern
The set of copper pads (with mask and paste) that a component's terminals solder to; the manufacturing core of a footprint.
Courtyard
The footprint's exclusion outline (body plus pads plus assembly clearance) used by DRC to prevent parts overlapping.
Tombstoning
A two-terminal chip standing on one end during reflow because one pad's solder melted first and its surface tension was unopposed; caused by asymmetric pads, paste, or thermal mass.
IPC-7351 density levels
Three standard margin sets for land patterns: A (Most), B (Nominal), C (Least); trading pad size against board density and rework-ability.
Solder-mask dam
The strip of mask left between adjacent pad openings; below the fab's minimum it is removed and the pads share an opening.
Castellation
A plated half-hole on a module's edge that solders to a base-board pad; the pad should extend past the edge so an inspectable fillet forms.
Checked property
Beacon's convention: a field on every project-library symbol and footprint recording date, initials, and the datasheet figure it was verified against.

ACTIVE RECALLCheck your understanding

Answer in your own words first, then reveal.

1A footprint's pads are the right size, pitch, and count. Name two ways it can still put the part on backwards, and the ninety-second check that catches both.›

First, the pin-1 mark (the F.Fab chamfer and silkscreen dot) is on a different corner from the datasheet's top-view drawing, so pad "1" is not where the part's pin 1 lands — the CPL rotation is derived from the footprint's orientation, and the assembler places the part rotated. Second, the footprint's pads are numbered in the opposite direction from the datasheet (clockwise vs anticlockwise from pin 1), so pin 1 is right and every other pin is mirrored. The check: attach the 3D model and look at it on the pads in the 3D viewer — the model's pin-1 mark and the footprint's must coincide, and for a connector the model shows which way the opening faces.

2Why does a large ground pad under a module get reduced paste, and what happens if it does not?›

The stencil deposits paste in proportion to aperture area. A large pad with full paste becomes a thick bead of molten solder at reflow; the module floats up on it, and the perimeter castellations — which have only a thin layer of paste each — lift off their pads and never wet. The result is a module with a perfect ground joint and open signal pins, which is maddening to diagnose because it looks soldered. Reduce the paste to a window pattern of roughly half to two-thirds coverage (the datasheet often specifies), so the module settles onto its perimeter pads.

3Beacon's JST-PH footprint is dimensionally perfect. What defect can still destroy the board, and which earlier design decision limits the damage?›

Polarity. JST defines the connector's pin numbers, not which pin carries positive; battery packs from different vendors arrive with the red wire on either pin. If a pack's polarity does not match the footprint's assignment (pin 1 = VBAT on Beacon), the board sees a reversed cell. The reverse-battery PMOS from Lesson 2.6 blocks reversed current so the charger, protection pair, and buck survive; without it the pack would drive the whole rail negative. The procedural defence is the silkscreen marking plus the Stage 6 bring-up rule that every pack is checked with a meter before it is plugged in.

4Why is editing a footprint in KiCad's global library "in place" the wrong fix, even when the edit is correct?›

Because the fix is then not part of the project. The board file embeds its own copy of each footprint, so the edit does nothing until footprints are updated from the library; a KiCad upgrade or a colleague's stock installation silently reverts the library; and nothing in the project's git history shows what changed, so the ordered Gerbers cannot be reproduced from source. The right fix is to copy the footprint into the project library, edit that copy, sign it with the Checked property, update footprints on the board from the project library, and commit — which makes the correction visible, reviewable, and permanent for this design.

Next: what the board is made of — layers, vias, and impedance →