--- skill_name: extract-pintable description: Extract pin table, package info, absolute-maximum ratings, layout_rules, and component subtype from an IC datasheet PDF. Returns structured data via the save_pintable tool. --- # Extract Pin Table & Variant Info Extract structured data from an IC datasheet and return it via the `save_pintable` tool. **Priority order:** (1) complete pin table for the MPN package, (2) `layout_rules` from PCB / typical-application pages, (3) package + abs-max + subtype. ## Steps ### 1. Read the datasheet PDF Focus on these sections (figures count as evidence): - **Pin configuration / pin assignment table** — primary target - **Ordering information / part number decoder** - **Package information** - **PCB layout / layout guidelines / land pattern notes** - **Typical application / reference design** (placement callouts near caps, vias, keepouts) - **Absolute maximum ratings** ### 2. Extract the pin table For every pin: - `number` (int or str) — pin number, or BGA ball like `"A3"` - `name` (str) — verbatim from the datasheet (e.g. `"VDD"`, `"PA0/SPI0_CLK"`) - `description` (str or null) - `functions` (list[str] or null) — alternate/mux functions Rules: - Include ALL pins — power, ground, NC, exposed pad / EP - Names verbatim — do not rename or normalize - Multiplexed pins: primary in `name`, alternates in `functions` - If the datasheet has per-package tables, use the package matching the MPN - Off-by-one pin numbers break everything downstream — double-check **Modules vs bare die (critical).** MPNs containing `WROOM`, `WROVER`, `MODULE`, `MOD-`, or `SIP` are *modules*. Extract the **module landing-pad table** (schematic pins). Do **not** extract the SoC/QFN ball map from a nested chip chapter. - Espressif WROOM: pin 1 is GND. Pin 1 named `ANT`, `CHIP_PU`, or `XTAL_*` means you grabbed the die table — invalid. - Crystal, RF antenna, and flash on a WROOM module are **inside the can**; they must not appear as schematic pin numbers. Optional extras (omit if absent): - `internal_features.pullup_pins` / `esd_clamp_pins` / `analog_switch` from the **block diagram** only. ### 3. Extract layout_rules (required scan — empty OK) You **must** look for layout guidance. Emit `layout_rules` as a list. Use `[]` only after scanning layout / application / thermal pages and finding no placement guidance. #### Where to look - Headings: “PCB Layout”, “Layout Guidelines”, “Layout Considerations”, “Board Layout”, “Land Pattern” - “Typical Application”, “Application Circuit”, “Reference Design” - Thermal / EP / exposed-pad via recommendations - Callouts on application figures (“place CIN within 2 mm of VIN”) #### Allowed `kind` (closed set) | kind | Use when | | --- | --- | | `decoupling_proximity` | Bypass / decoupling / input / output cap near a supply or pin | | `thermal_via` | Vias under exposed pad / thermal pad / EP | | `keepout` | Keep foreign nets, digital return, or copper out of a region | | `length_match` | Intra-pair skew / matched length limit in mm | | `impedance` | Single-ended `z0_ohm` or differential `zdiff_ohm` (plus `tolerance_pct` or `z_min_ohm`/`z_max_ohm`) | | `max_length` | Maximum routed length in mm | | `spacing` | Intra-pair / coupling gap (`min_spacing_mm`) | | `ref_plane` | Required reference plane (`ref_plane`, `topology`) | | `si_via` | Min/max vias on the HS net | | `layer` | Required copper layer / topology | | `series_resistor` | Series R on the HS net (`value_ohms`) | | `return_path` | GND return via next to the pair | | `emi` / `common_mode` / `shield` | Common-mode choke, ferrite bead, shield, or EMI filter **quoted from this datasheet** (no IEC 61000 invention) | Do **not** emit impedance/50 Ω rules for I2C, GPIO, EN, analog REGN, or USB CC. Do **not** invent USB 90 Ω unless **this** datasheet states a number. `net_class` is **required** for every SI kind (`impedance`, `length_match`, `max_length`, `spacing`, `ref_plane`, `si_via`, `layer`, `series_resistor`, `return_path`, `si`). Use one of: `usb2`, `usb3`, `eth_mdi`, `rgmii`, `sgmii`, `ddr3`, `hdmi`, `pcie`, `lvds`. PCB review will not map a rule onto another bus. `series_resistor` is a termination / series R **on that HS net** (e.g. USB 22 Ω, RGMII 22 Ω). It is **not** CHIP_PU / EN / RESET RC (10 kΩ + 1 µF), ILIM, or a strap divider — omit those or use `decoupling_proximity` / leave them to timing checks. #### Fields - `pin` — number or name as printed (`"5"`, `"VIN"`, `"VDD"`, `"EP"`) - `cap_value_hint` — only if shown (`"100nF"`, `"10µF"`) - `max_distance_mm` — **number only if the PDF states millimetres** - OK: “within 2 mm”, “< 5 mm”, “no more than 3 mm from the pin” → `2` / `5` / `3` - NOT OK as a number: “as close as possible”, “close to the pin”, “adjacent”, “nearby” → set `max_distance_mm: null` and keep the rule with a `note` - **Never invent** JEDEC, USB, IPC, or “standard 3 mm / 5 mm” distances - `same_layer` — `true`/`false` only if text says same side / opposite side of the board; else null - `min_via_count` — integer only if stated (“at least 4 vias”) - `net_class` — **required for SI kinds**: `usb2` | `usb3` | `eth_mdi` | `rgmii` | `sgmii` | `ddr3` | `hdmi` | `pcie` | `lvds`. Must match the quoted bus (PHY+RJ45 = `eth_mdi`, MAC–PHY = `rgmii`/`sgmii`, USB-C SuperSpeed = `usb3`, USB D+/D− = `usb2`). Never leave SI `net_class` empty. - `note` — short quote of the guidance - `source_page` — 1-based page of the guidance (required when you emit a rule) #### Examples Numeric proximity (copy the millimetre from the PDF): ```json { "kind": "decoupling_proximity", "pin": "VIN", "cap_value_hint": "10uF", "max_distance_mm": 2.0, "same_layer": true, "note": "Place CIN within 2 mm of VIN", "source_page": 14 } ``` Proximity without a millimetre (still emit the rule): ```json { "kind": "decoupling_proximity", "pin": "VDD", "cap_value_hint": "100nF", "max_distance_mm": null, "note": "Place decoupling capacitor as close as possible to VDD", "source_page": 22 } ``` Thermal vias: ```json { "kind": "thermal_via", "pin": "EP", "min_via_count": 4, "note": "Use at least 4 thermal vias in the exposed pad", "source_page": 18 } ``` #### Hard negatives - Do not invent land-pattern pad sizes from the mechanical drawing alone - Do not emit `length_match` or `impedance` for USB/HDMI/PCIe unless **this** datasheet states a skew/Z number - Do not treat I2C, GPIO, EN, analog, or USB-CC as 50 Ω / 90 Ω pairs - Do not emit `series_resistor` for EN / CHIP_PU / RESET RC, ILIM, or strap networks - Do not emit an SI kind without `net_class` naming the quoted bus - Do not use kinds outside the closed set - One rule per distinct pin/guidance; prefer supply pins that show caps in the application figure ### 4. Extract package info - `base_family` — e.g. `"MSPM0G3507"` from `"MSPM0G3507SPTR"` - `package` — e.g. `"LQFP-48"`, `"SOT-23-5"` - `pin_count` (int) - `description` — human-readable MPN decode Prefer “Ordering Information” / “Device Information” tables. ### 5. Extract absolute maximum ratings Copy the **Absolute Maximum Ratings** table (not Recommended Operating Conditions): - `parameter`, `min` / `max`, `unit`, `source_page` (1-based) Include supply voltages, pin/input voltages, input current, temperature. Skip HBM/IEC kV ESD rows unless they are the only voltage limit. Do not invent numbers. **ESD / TVS (`ic.protection.esd` and similar):** also from Electrical Characteristics: - Vrwm / operating voltage as signed min/max in volts - One row for polarity/topology as printed (`bidirectional`, …), `unit: "—"` ### 6. Assign component subtype Pick the best dotted subtype from `EXISTING IC TAXONOMY SUBTYPES` (e.g. `ic.mcu`, `ic.power.ldo`). If none fit, propose `ic.{category}.{specific}`. ### 7. Quality checks Before output: - Pin count matches the package for this MPN - No duplicate / missing pin numbers - `layout_rules` scanned (list present; `[]` only if truly no guidance) - Every emitted rule has a valid `kind`; every numeric `max_distance_mm` comes from the PDF text/figure - Pin names are not OCR garbage ### 8. Validate and output ```bash python3 /skills/extract-pintable/validate.py '' ``` If validation passes, call `save_pintable`. Do NOT write files to disk — use the tool.