soldermaskdocs

Symbols and pins

The design names every pin by what it does, such as VIN or SDA, and never by its number. This stage finds each part's symbol and turns every name into the pad it lands on.

A pin number from a language model is recall. It is sometimes wrong, and nothing downstream can catch it. So the model names pin functions, and symbols.py looks up the pads in the KiCad symbol library.

The library

WhatWhere
KiCad's legacy symbol library (kicad-symbols, .lib files), over 200 libraries.cache/kicad-symbols
An index of every DEF and ALIAS block, about 42 MB, so a lookup does not read the files.cache/symbol_index.json

soldermask setup fetches the library, and so does tools/fetch_symbols.py. No KiCad install is needed.

Without the library

A part whose own EasyEDA symbol can be fetched uses that instead. A part with neither gets the gap no KiCad symbol matches … (the library is absent), and the board names the missing library once.

Matching a part to a symbol

symbols.find(query, pin_count) matches a part number to a symbol:

  • An exact name match wins.
  • Otherwise the names must share a prefix of at least five characters.
  • A prefix match must have a pin count within two of the footprint's pads. A tab or a mounting pad is a normal shortfall.

ICs, transistors and similar parts are matched. Passives, connectors and switches have positional pins and need no symbol.

A part whose footprint comes from the vendor takes the vendor's own symbol first. That covers a FROM_PART module, a package this pipeline does not draw, and a connector whose vendor pads have names such as A1B12. On an IC or a module, KiCad's symbol for the exact part then lays its names on top.

When nothing matches, two fallbacks are tried in order. Each one is reported in the notes.

  1. A borrowed pinout. Symbols in the same package and with the same pin count vote on the pinout. It needs at least five voters, 90% agreement, and every wanted pin found. The note reads no symbol for 'X', so the pinout is taken from Y: 7 of 7 pin-compatible SOIC-8 parts … wire it this way. Assumed, not verified.
  2. The part's own symbol. EasyEDA's pinout for the exact LCSC part ordered.

With no symbol at all, the board carries a gap: no KiCad symbol matches 'X', pin functions cannot be verified.

Resolving a pin

symbols.resolve_pins(symbol, "VIN") maps a function name to its pads. It tries these rungs in order and stops at the first that answers:

RungWhat it acceptsExample
NameThe symbol's own pin name, in any caseVIN
AliasesCommon names for the same pin (symbols.ALIASES)VIN finds VI, IN, VCC, VDD, V+ or VBUS
Multiplexed nameThe first part of a vendor name that lists a pin's functionsGP4 finds GP4_SPI0RX_I2C0SDA_UART1TX
SpellingsInversion marks, dashes, separators and polarity signs~{RESET}, RESET#, nRESET and RESET_N are one pin
TokensOne name inside a decorated vendor name, split on / ( ) , and dashesPB0 finds (PCINT0/CLKO/ICP1)PB0

Four more sources of names sit around those rungs:

  • Units. On a multi-unit part, qualify the name with its unit: A.OUT, B.-. The same rungs then run on that unit.
  • Supplies. A supply name on several pads of one unit connects to all of them, with a note. GND on a DS3231M is nine pads. A motor driver's VS, VM and VMOT count as supplies, so VS on a TMC2209 is pads 22 and 28.
  • Datasheet names. Names from KiCad's symbol for the exact part, and from the part's datasheet, are laid on the vendor's symbol before the rungs run. So VREG_VIN finds the RP2040 pin its vendor symbol calls VREG_IN.
  • USB-C positions. On a connector, A4/B9 and the rest resolve through the standard's table (symbols.USB_C) to the signal the position carries.

When every rung fails, the last rung reads the datasheet's function text, then asks Jev.

A match through anything but the name adds a note saying which pin it landed on. A name is refused, with a note, when:

  • it is on several units and names no unit;
  • a signal name lands on two pads, so it is a choice;
  • nothing finds it.

A vendor symbol sometimes repeats a name on several pads. Then the first pad is wired, and a note names the others as left unconnected. Give each of the others by pad number:

  • on the same net, if the datasheet makes them one node, as a regulator's two VOUT pads are;
  • on its own net, if not, as an INA826's second RG pad is.

The resolver takes a pad number there on any net, because no name can reach that pad. A tie on the name's own net gets a note that it is right only if the datasheet makes the pads one node.

A token is at least two characters and not a bare number, so 1 cannot find A1B12.

Datasheet names

For a vendor symbol with four or more pins, datasheets.py fetches the part's datasheet from its listing. The design stage's model transcribes the pin table once. Every name the sheet gives a pin is then laid on the symbol under that number.

  • A name the symbol already uses for a different pin is not added. The sheet's GND alias on a VSS pin would otherwise tie two rails.
  • A pin the sheet and the symbol name differently gets a note, and both names answer.
  • A swap is a gap. The sheet's name for pin 3 is the symbol's name for pin 6, so both pads are held back from wiring.
  • A rail on several pins (GND, IOVDD, VBUS) is never a swap.
  • When most of a table is swapped, it is another package's table, and it is not held against the symbol.

The sheet cannot be read when the pinout is only a drawing, as on most two- and three-pin parts, or when the PDF is scanned.

Reading a sheet for the first time needs two things:

NeedsWithout it
pdftotext, from popplerThe sheet is fetched and not read, and the board says so in a note
A model callNothing is transcribed. The MCP server calls no model, so it reads only tables already cached.

A transcribed table is cached under .cache/datasheets/, so the next build reads it without a model.

On the 226 parts the replay orders, 543 pins were compared. 502 had the same name, 36 another spelling and 5 a different name. None was on a different pin.

Jev

The last rung is optional. It asks Jev, TypeSafe's closed-question model (jev.py), with the datasheet's table beside the symbol. It needs TYPESAFE_API_KEY. An answer at confidence 0.6 or more (jev.FLOOR) is taken with a note saying it is assumed, not verified. Below that, the refusal stands.

Pin numbers

A raw pin number on a part with a symbol is refused as unverifiable:

pin '3' given as a raw number for a part with a known pinout -- that is unverifiable. Symbol says pin 3 is 'VO'; use the function name instead

A number is accepted in these cases:

CaseWhy
The symbol's own name for the pin is that numberA passive has nothing else to call its ends
The symbol's name for the pin is the net it is onThe number is checked, not guessed
The pad is not on the symbolA tab or mounting pad, with a note
A connector or switchIts pins are positional
1 or 2 on a two-pad crystal, resistor, capacitor or inductorEither end is the same part
1 or 2 on a two-pad switch or connector whose footprint letters its pads A/BWith a note

A four-pad crystal's 2 is still refused: its pins 2 and 4 are ground.

Drawing the schematic

The same library supplies the schematic drawings.

  • symbols.graphics(name) parses a symbol's DRAW block into rectangles, polylines, arcs, text and pins, in KiCad mils with y up.
  • symbols.default_graphics(kind, …) picks a stock symbol for a part that has none.
PartStock symbol
ResistorDevice:R
CapacitorDevice:C, or C_Polarized for tantalum and electrolytic packages
InductorDevice:L
LEDDevice:LED
DiodeD_Schottky, D_Zener or D_TVS by value, else Device:D
CrystalDevice:Crystal, or Crystal_GND24 with four pins
SwitchSwitch:SW_Push
FuseDevice:Fuse
ConnectorConnector_Generic:Conn_01x0N

The board carries one symbol table, and each component holds a key into it. So ten resistors are one drawing.

On this page