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
| What | Where |
|---|---|
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.
- 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.
- 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:
| Rung | What it accepts | Example |
|---|---|---|
| Name | The symbol's own pin name, in any case | VIN |
| Aliases | Common names for the same pin (symbols.ALIASES) | VIN finds VI, IN, VCC, VDD, V+ or VBUS |
| Multiplexed name | The first part of a vendor name that lists a pin's functions | GP4 finds GP4_SPI0RX_I2C0SDA_UART1TX |
| Spellings | Inversion marks, dashes, separators and polarity signs | ~{RESET}, RESET#, nRESET and RESET_N are one pin |
| Tokens | One name inside a decorated vendor name, split on / ( ) , and dashes | PB0 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.
GNDon a DS3231M is nine pads. A motor driver'sVS,VMandVMOTcount as supplies, soVSon 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_VINfinds the RP2040 pin its vendor symbol callsVREG_IN. - USB-C positions. On a connector,
A4/B9and 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
VOUTpads are; - on its own net, if not, as an INA826's second
RGpad 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
GNDalias on aVSSpin 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:
| Needs | Without it |
|---|---|
pdftotext, from poppler | The sheet is fetched and not read, and the board says so in a note |
| A model call | Nothing 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:
| Case | Why |
|---|---|
| The symbol's own name for the pin is that number | A passive has nothing else to call its ends |
| The symbol's name for the pin is the net it is on | The number is checked, not guessed |
| The pad is not on the symbol | A tab or mounting pad, with a note |
| A connector or switch | Its pins are positional |
1 or 2 on a two-pad crystal, resistor, capacitor or inductor | Either end is the same part |
1 or 2 on a two-pad switch or connector whose footprint letters its pads A/B | With 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'sDRAWblock 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.
| Part | Stock symbol |
|---|---|
| Resistor | Device:R |
| Capacitor | Device:C, or C_Polarized for tantalum and electrolytic packages |
| Inductor | Device:L |
| LED | Device:LED |
| Diode | D_Schottky, D_Zener or D_TVS by value, else Device:D |
| Crystal | Device:Crystal, or Crystal_GND24 with four pins |
| Switch | Switch:SW_Push |
| Fuse | Device:Fuse |
| Connector | Connector_Generic:Conn_01x0N |
The board carries one symbol table, and each component holds a key into it. So ten resistors are one drawing.
Parts and packages
The parts stage turns each part the design describes into a real part you can order from JLCPCB, with a footprint to draw it. A part it cannot find is taken off the board and named in the gaps list.
Simulation
The simulation switches the board's rails on in ngspice and reads what every net settles to. It runs after the parts are resolved and before anything is placed.