Datasheet to symbol lib

PDF Datasheet to KiCad Symbol Library Conversion

Why this skill exists

Manually transcribing a datasheet's pin table straight into symbol text is where errors creep in silently: a dropped pin, a transposed pin number, a missed alternate function, an off-by-one in an auto-incrementing bus name. None of these throw an error in the jpd2spd | spd2csv | kipart pipeline — they just produce a wrong symbol that looks plausible. The core idea of this skill is: never go straight from "reading the PDF" to a symbol. Land the extraction in a structured, machine-checkable file first, verify it against the source, and let tools generate everything downstream.

That file is a JPD (JSON Part Description) — the JSON format kipart itself defines and consumes (see references/jpd_format.md). JPD is the single artifact you author by hand. jpd2spd generates the SPD from it, spd2csv generates the CSV, and kipart builds the .kicad_sym — so there is exactly one hand-made source of truth and no re-transcription step between "verified" and "built." A JSON object is also directly checkable by a script for missing pins, duplicate numbers, and count mismatches in a way hand-written symbol text is not.

The process has five phases. Do not skip or combine them, and do not skip the JPD file in Phase 2 even for a "simple" part — it's what makes Phase 5 verification possible instead of just re-reading your own work and confirming your own mistake.

Phase 1: Part Identification

Every distinct part number described in the datasheet must be identified before any pinout work begins.

Where to find part numbers (in priority order):

1. Ordering information table — usually near the front or back of the datasheet. Lists all available part numbers with package type, temperature range, packaging, etc.
2. Page headers/footers — some datasheets list the base part number at the top of each page.
3. Device naming/option section — explains the suffix convention (e.g., "LM358N = PDIP, LM358D = SOIC").
4. Package marking diagrams — show what's printed on each package variant.

What counts as a separate part:

• Different package types of the same function (e.g., SOIC-14 vs PDIP-14) — separate part objects, since pin arrangement and footprint differ.
• Functionally different parts (e.g., LM358N vs LM393N in the same datasheet).

What does not count as a separate part:

• Different temperature/grade variants that share the same pinout — these become Manf/other properties on a single part entry, not separate parts.

Output of Phase 1: A table of every part to create, each annotated with package type and expected pin count. Keep this table — it's the checklist Phase 5 verifies against, and it feeds the package and expected_pin_count helper fields on each JPD part.

Phase 2: Pinout Extraction into the JPD file

For each part, extract every pin's number, name, type, and alternate functions — but land the result in a JPD file (one part object per device) before anything downstream. This is the single biggest lever for accuracy on complex datasheets: a JSON structure can be programmatically checked for missing pins, duplicate numbers, and count mismatches; symbol text cannot. Read references/jpd_format.md for the exact schema.

Sources to cross-reference (use ALL available, don't rely on one):

1. Pin function table — the detailed table listing every pin with number, name, type, description. Primary source for names and types.
2. Pinout/package diagram — physical drawing showing pin locations. Primary source for side placement and for catching table errors.
3. Functional block diagram — clarifies signal direction when the type column is ambiguous or missing.

Tooling:

• Use pdfplumber (Python) to pull pin tables when they're machine-readable. Multi-page tables: scan every page, carry over column headers across page breaks — don't stop at the first page break.
• For the pinout diagram, view the rendered PDF page as an image (rasterize the page, then look at it directly) rather than relying only on extracted text — pin-number-to-side mapping lives in the drawing, not the table, and text extraction from diagrams is unreliable.
• If a pin table is scanned/image-based rather than text, rasterize and read it visually — don't attempt OCR-free guessing from surrounding text.

Table reading rules:

• Footnote markers: Strip (1), (2), [a], [b], *, † etc. from pin names. Read the footnote text — it sometimes changes the pin's type or adds a real alternate function, not just a caveat.
• Multi-page tables: Always scan ALL pages.
• Split columns: Some tables split pin numbers by package variant (e.g., "SOIC-8: pin 1, PDIP-14: pin 3"). Each column set is a separate part entry — extract each into its own JPD part object.
• NC pins: A "-" or blank in the pin number column means that function doesn't exist on that variant. Omit it from that part entirely — do not invent a pin number.
• Repeated pin names: Tables often group several physical pins under one name row (e.g., "GND" spanning 4 rows or one row with "7, 14, 21"). Put every pin number in the single object's numbers array (e.g. {"name": "gnd", "numbers": ["7","14","21"], "type": "power_in"}) — one object, many numbers, no increment. Never merge them into one number and never split a shared name into differently-named entries.

JPD shape (one file per datasheet; see references/jpd_format.md for the full schema). A pin's side is the array it lives in — there is no side field — and type/style are spelled in full (input, power_in, inverted…), never as SPD's short codes:

{
  "format": "jpd",
  "version": 1,
  "parts": [
    {
      "name": "74hc00",
      "package": "SOIC-14",
      "expected_pin_count": 14,
      "properties": { "Footprint": "soic-14" },
      "units": [
        {
          "name": "LOGIC",
          "left":  [ { "name": "a1", "numbers": ["1"], "type": "input" } ],
          "right": [ { "name": "y1", "numbers": ["3"], "type": "output" } ]
        },
        {
          "name": "PWR",
          "top":    [ { "name": "vcc", "numbers": ["14"], "type": "power_in" } ],
          "bottom": [ { "name": "gnd", "numbers": ["7"],  "type": "power_in" } ]
        }
      ]
    }
  ]
}

package and expected_pin_count are verification-only helper fields carried from the Phase 1 checklist; jpd2spd ignores them so Phase 5 can check the count mechanically. Attach alternate functions per Phase 3 below.

Phase 3: Alternate or Additional Pin Function Detection

Many datasheets define pins with multiple functions depending on operating mode. Do not omit alternate or additional functions — they're essential to the pin's real behavior.

Signs of alternate/additional functions:

• Slash notation in pin names (e.g., "MISO/SDI/SDO").
• An explicit "Alternate Function" column, or a separate alternate-function table cross-referenced by pin number.
• The same pin number appearing under two different names in different tables/modes.
• Text describing mode-dependent behavior ("When MODE=1, pin 12 acts as SDO; when MODE=0, it acts as SDI").

How to represent it: in the JPD, the main function is the pin object itself, and every additional function goes in that object's alternates array, each with its own name, type, and style (use the type and style of the main function if the alternate is not explicitly described). For example:

{ "name": "gpio12", "numbers": ["12"], "type": "bidirectional",
  "alternates": [
    { "name": "miso", "type": "input" },
    { "name": "sdo",  "type": "output" }
  ] }

The pin number appears once, on the parent object; alternates do not repeat it. jpd2spd turns this into the multiple same-numbered SPD lines described in references/jpd_format.md.

Effect upon symbol size: Alternate pin functions do not increase the size of the symbol. All alternate functions for a pin share the same position in the symbol, so a pin with six alternate functions uses only a single slot on the final symbol even though it carries six functions (one object plus five alternates) in the JPD.

Phase 4: Pin Placement

Decide physical vs. logical arrangement:

• Physical: use the pinout diagram — match the real package layout. Use this whenever a diagram exists; it's what makes the schematic symbol match the reader's mental model of the physical part.
• Logical: group by function (power together, IO bus together) and place by convention: inputs left, outputs right, power top, ground bottom, bidirectional/uncommitted/unspecified/unconnected either left or right. Insert a {"spacer": 1} object to separate groups on the same side. Use these guidelines when no diagram is available or when requested by the user.

If no diagram is provided:

• DIP packages: pin 1 at top-left, proceed downward for half the pins; remaining half proceeds upward from the bottom of the right side.
• Quad packages: start top-left corner, proceed down the left side, across the bottom, up the right side, across the top, back to start — pins split evenly across all four sides.
• BGA packages: arrange logically by function. If pin count is large, split into multiple unit blocks by function group (see "High pin-count parts" below) rather than one enormous unit.

Phase 5: Verification (mechanical, not just visual re-read)

Verify the JPD file before running the pipeline — catch problems while they're still cheap to fix. Because the JPD is valid JSON, a script can load it directly.

Run a verification script (do this with actual code, not by eyeballing) that, for every part, checks:

• Total physical pins == expected_pin_count. Count each pin object once per entry in its numbers array, across every side of every unit; alternates and spacers do not count.
• No duplicate pin numbers within a part unless the duplicate is a recorded alternates entry (same number, different function).
• No duplicate pin names within a part (auto-increment collisions are a common source of this — expand any increment: true object to the names it will generate and check those).
• Every type is one of the KiCad electrical types listed in references/jpd_format.md (input, output, power_in, …) and every style is one of the listed styles — do not invent values or use SPD's short codes; the reference is the sole source of truth.
• Every pin sits in a left/right/top/bottom array (a pin with no side is impossible to place).
• Power/ground pins are typed power_in (or power_out for regulator outputs), not left as passive or unspecified.
• The file parses as JSON and has format: "jpd" with a parts array.

Only after this script reports clean should you cross-reference by hand: compare the pin function table against the pinout diagram pin-by-pin for each part, and resolve any discrepancy by re-reading the datasheet rather than picking one source arbitrarily.

Sanity checks:

• Total pin count per part matches package type (e.g., TQFP-32 has exactly 32 pins across all its units).
• All pin names are cleaned of footnote markers and whitespace (underscores substituted).
• Every part number from the Phase 1 checklist has a corresponding part object in the JPD.

Building the library from the JPD

The verified JPD is the input; the tools do the rest. Nothing downstream is hand-authored.

1. Run the pipeline:

   jpd2spd -o - parts.jpd | spd2csv | kipart -w -o parts.kicad_sym
   

   jpd2spd -o - writes the generated SPD to stdout, spd2csv turns it into CSV, and kipart builds the .kicad_sym. (If you want to inspect the intermediate SPD, run jpd2spd parts.jpd on its own to write parts.spd.)
2. Confirm parts.kicad_sym contains exactly the expected number of symbols (one per part object), and spot-check pin counts on at least the largest and most complex parts.
3. If any errors are found, do not edit the SPD, CSV, or .kicad_sym directly — they are build products. Go back to parts.jpd, fix it there, and re-run the pipeline.
4. Retain the JPD file in version control — it is the authoritative record of what was extracted from the datasheet. The SPD/CSV/.kicad_sym can always be regenerated from it.

High pin-count parts (QFP-100+, BGA, MCUs)

These are where manual approaches break down fastest — treat them deliberately:

• Split into multiple units by function (e.g., PORTA, PORTB, PWR, JTAG) — separate objects in the part's units array — rather than one unit with 100+ pins on four sides. This also matches how such parts are normally symbolized in KiCad.
• Extract and verify one functional group (one unit) at a time in the JPD rather than the whole part in one pass — it's much easier to catch a missing pin in a 16-pin GPIO port than in a 144-pin flat list.
• For BGA parts with a grid pinout diagram (e.g., ball A1, A2, B1...), the ball grid location itself is not the symbol's side placement — group by function per the logical-arrangement rule above, and use the pin function table (not the ball map) as the primary source of pin identity.

Troubleshooting jpd2spd / spd2csv / kipart failures

• jpd2spd errors or produces no part: the JPD is malformed JSON or missing a required key (name, units, a pin's name/numbers). Validate the JSON and check it against references/jpd_format.md. A trailing comma or a numbers value that's a bare string instead of an array is common.
• Stray characters copied from PDF text (curly quotes, non-breaking spaces) — PDF-extracted names often carry these invisibly; they end up in pin names. Clean them in the JPD.
• Wrong pin count in output symbol: almost always a JPD problem, not a pipeline problem — re-run the Phase 5 verification script against the JPD rather than debugging the generated SPD or CSV.
• Auto-increment produced unexpected names: an object with increment: true numbers its name off the first entry across all of numbers. If you wanted several pins to share one name (power, ground), drop increment (or leave it false); if you wanted a bus, keep it. See references/jpd_format.md.
• Missing symbol for a part: check for a duplicate name (a second part with the same name), or a unit whose side arrays are all empty.

Gotchas

• Use spacers ({"spacer": N}) only for logical pin arrangement, between groups of different function. Never use spacers when doing physical (diagram-based) arrangement — the diagram's actual spacing isn't meaningful.
• Do not hide pins ("hidden": true) unless specifically requested.
• Pin names cannot include whitespace — replace with underscores.
• Do not omit alternate pin functions present in the datasheet. They belong in each pin's alternates array in the JPD.
• Do not assume pins are numbered sequentially in the pinout diagram — always cross-reference the pin function table to confirm numbers and names; diagrams are drawn for physical clarity, not numeric order.
• The JPD is the only file you edit. SPD, CSV, and .kicad_sym are generated — never hand-edit them, and never author SPD directly.