bom — Skillopedia

BOM Management BOM data lives in KiCad schematic symbol properties as the single source of truth. This skill orchestrates the full lifecycle: analyze the schematic, search distributors, validate parts, write properties back, export tracking CSVs, and generate order files. Related Skills | Skill | Purpose | |-------|---------| | | Read/analyze schematics, PCB, footprints | | | Search DigiKey, download datasheets (primary prototype source) | | | Search Mouser (secondary prototype source) | | | Search LCSC (production/JLCPCB parts) | | | Search Newark/Farnell/element14 (international) | | | PCB…

, value):\n return \"digikey\"\n\n # LCSC: C followed by 3-8 digits (exactly)\n if re.match(r'^C\\d{3,8}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, value):\n return \"lcsc\"\n\n # Mouser: 2-3 digit numeric prefix + hyphen + alphanumeric manufacturer PN\n if re.match(r'^\\d{2,3}-[A-Za-z0-9]', value):\n return \"mouser\"\n\n return None\n\n\n# ---------------------------------------------------------------------------\n# Convention detection\n# ---------------------------------------------------------------------------\n\ndef detect_convention(\n all_symbols: list[dict],\n) -> dict:\n \"\"\"Detect the project's BOM field naming convention.\n\n Returns a dict describing which field names are used, how they map to\n canonical names, and which distributor appears to be preferred.\n \"\"\"\n # Count occurrences of each property name across all symbols\n field_counts: Counter[str] = Counter()\n populated_counts: dict[str, int] = {} # canonical -> count of non-empty values\n\n # Also detect \"Supplier N\" / \"Supplier N Part #\" pattern (KiCad field names)\n # Maps the value inside the Supplier field to canonical distributor names\n _SUPPLIER_NAME_MAP = {\n \"digikey\": \"digikey\", \"digi-key\": \"digikey\",\n \"mouser\": \"mouser\",\n \"lcsc\": \"lcsc\", \"jlcpcb\": \"lcsc\",\n \"newark\": \"element14\", \"farnell\": \"element14\", \"element14\": \"element14\",\n \"arrow\": \"arrow\",\n }\n # Track KiCad \"Supplier N\" slot mappings: slot_number -> (name_field, pn_field, canonical)\n supplier_slots: dict[int, dict] = {} # \"supplier\" here refers to KiCad field names\n\n for sym in all_symbols:\n for name, value in sym[\"raw_properties\"].items():\n if name in STANDARD_FIELDS:\n continue\n field_counts[name] += 1\n canonical = _ALIAS_LOOKUP.get(name) or _ALIAS_LOOKUP.get(name.upper())\n if canonical and value.strip():\n populated_counts[canonical] = populated_counts.get(canonical, 0) + 1\n\n # Detect KiCad \"Supplier N\" field pattern\n sup_match = re.match(r'^Supplier\\s+(\\d+)

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, name, re.IGNORECASE)\n if sup_match and value.strip():\n slot = int(sup_match.group(1))\n dist_name = value.strip().lower()\n canonical_sup = _SUPPLIER_NAME_MAP.get(dist_name)\n if canonical_sup and slot not in supplier_slots:\n supplier_slots[slot] = {\n \"name_field\": name,\n \"canonical\": canonical_sup,\n }\n\n # Detect KiCad \"Supplier N Part #\" or \"Supplier N Part Number\" field\n sup_pn_match = re.match(\n r'^Supplier\\s+(\\d+)\\s+Part\\s*(?:#|Number|No\\.?)

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, name, re.IGNORECASE\n )\n if sup_pn_match:\n slot = int(sup_pn_match.group(1))\n if slot in supplier_slots:\n supplier_slots[slot][\"pn_field\"] = name\n # Count this as a populated distributor field\n can = supplier_slots[slot][\"canonical\"]\n if value.strip():\n populated_counts[can] = populated_counts.get(can, 0) + 1\n\n # Build field mapping: canonical -> actual field name used in this project\n field_mapping: dict[str, str] = {}\n for name in field_counts:\n canonical = _ALIAS_LOOKUP.get(name) or _ALIAS_LOOKUP.get(name.upper())\n if canonical:\n # If multiple aliases map to same canonical, pick the most common\n if canonical not in field_mapping or field_counts[name] > field_counts.get(field_mapping[canonical], 0):\n field_mapping[canonical] = name\n\n # Add KiCad supplier slot mappings (only if not already mapped by direct field names)\n for slot_info in supplier_slots.values():\n can = slot_info[\"canonical\"]\n if can not in field_mapping and \"pn_field\" in slot_info:\n field_mapping[can] = slot_info[\"pn_field\"]\n\n # Determine preferred distributor by populated count\n distributor_counts = {\n k: v for k, v in populated_counts.items()\n if k in (\"digikey\", \"mouser\", \"lcsc\", \"element14\")\n }\n preferred_distributor = None\n if distributor_counts:\n preferred_distributor = max(distributor_counts, key=distributor_counts.get)\n\n # Check if field names are already canonical\n names_canonical = all(\n field_mapping.get(c) == CANONICAL_NAMES.get(c)\n for c in field_mapping\n if c in CANONICAL_NAMES\n )\n\n # What fields should be suggested for new parts\n # Always include MPN + Manufacturer, plus whatever distributors the project uses\n suggested = [\"MPN\", \"Manufacturer\"]\n for dist in (\"digikey\", \"mouser\", \"lcsc\", \"element14\"):\n if dist in field_mapping:\n suggested.append(field_mapping[dist])\n elif dist == preferred_distributor:\n suggested.append(CANONICAL_NAMES[dist])\n\n return {\n \"field_mapping\": field_mapping, # canonical -> actual field name\n \"field_counts\": dict(field_counts), # actual field name -> symbol count\n \"populated_counts\": populated_counts, # canonical -> non-empty count\n \"preferred_distributor\": preferred_distributor,\n \"names_canonical\": names_canonical,\n \"suggested_fields\": suggested,\n }\n\n\n# ---------------------------------------------------------------------------\n# BOM grouping\n# ---------------------------------------------------------------------------\n\ndef generate_bom(symbols: list[dict], convention: dict,\n group_by: str = 'value+footprint') -> list[dict]:\n \"\"\"Group symbols into BOM lines and identify gaps.\"\"\"\n groups: dict[tuple, dict] = {}\n seen_refs = set()\n\n field_map = convention[\"field_mapping\"]\n\n for sym in symbols:\n ref = sym[\"reference\"]\n comp_type = sym[\"type\"]\n\n # Skip power symbols and non-BOM components\n if comp_type == \"power_symbol\" or not sym[\"in_bom\"]:\n continue\n if ref in seen_refs:\n continue\n seen_refs.add(ref)\n\n props = sym[\"raw_properties\"]\n\n # Extract canonical field values using the project's actual field names\n def get_canonical(canonical_name: str) -> str:\n actual_name = field_map.get(canonical_name)\n if actual_name:\n return props.get(actual_name, \"\").strip()\n # Try all known aliases as fallback\n for alias in FIELD_ALIASES.get(canonical_name, []):\n val = props.get(alias, \"\").strip()\n if val:\n return val\n return \"\"\n\n mpn = get_canonical(\"mpn\")\n manufacturer = get_canonical(\"manufacturer\")\n digikey = get_canonical(\"digikey\")\n mouser = get_canonical(\"mouser\")\n lcsc = get_canonical(\"lcsc\")\n element14 = get_canonical(\"element14\")\n datasheet = props.get(\"Datasheet\", \"\").strip()\n description = props.get(\"Description\", \"\").strip()\n value = props.get(\"Value\", \"\").strip()\n footprint = props.get(\"Footprint\", \"\").strip()\n\n # Extract BOM comments — freeform per-component notes\n bom_comment = \"\"\n for field_name in _BOM_COMMENT_NAMES:\n val = props.get(field_name, \"\").strip()\n if val:\n bom_comment = val\n break\n\n if group_by == 'mpn':\n group_key = (mpn,) if mpn else (value, footprint, mpn)\n elif group_by == 'value':\n group_key = (value,)\n else: # 'value+footprint' — current default\n group_key = (value, footprint, mpn)\n\n if group_key not in groups:\n groups[group_key] = {\n \"value\": value,\n \"footprint\": footprint,\n \"mpn\": mpn,\n \"manufacturer\": manufacturer,\n \"digikey\": digikey,\n \"mouser\": mouser,\n \"lcsc\": lcsc,\n \"element14\": element14,\n \"datasheet\": datasheet,\n \"description\": description,\n \"bom_comments\": [],\n \"references\": [],\n \"quantity\": 0,\n \"dnp\": sym[\"dnp\"],\n \"type\": comp_type,\n }\n if bom_comment and bom_comment not in groups[group_key][\"bom_comments\"]:\n groups[group_key][\"bom_comments\"].append(bom_comment)\n\n groups[group_key][\"references\"].append(ref)\n groups[group_key][\"quantity\"] += 1\n\n # Sort by first reference\n bom = sorted(\n groups.values(),\n key=lambda g: _ref_sort_key(g[\"references\"][0]) if g[\"references\"] else (\"\", 0),\n )\n\n # Identify gaps for each BOM line\n for entry in bom:\n entry[\"gaps\"] = _find_gaps(entry, convention)\n\n return bom\n\n\ndef _ref_sort_key(ref: str) -> tuple[str, int]:\n \"\"\"Sort reference designators naturally: C1, C2, C10, R1, U1.\"\"\"\n match = re.match(r'^([A-Za-z]+)(\\d+)

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

, ref)\n if match:\n return (match.group(1), int(match.group(2)))\n return (ref, 0)\n\n\ndef _find_gaps(entry: dict, convention: dict) -> list[str]:\n \"\"\"Identify which fields are missing that should be populated.\"\"\"\n gaps = []\n comp_type = entry[\"type\"]\n\n # Skip gap analysis for test points, mounting holes, etc.\n if comp_type in (\"test_point\", \"mounting_hole\", \"power_symbol\"):\n return gaps\n if entry[\"dnp\"]:\n return gaps\n\n # MPN should always be present for real components\n if not entry[\"mpn\"]:\n gaps.append(\"mpn\")\n\n # Manufacturer is strongly recommended alongside MPN\n if entry[\"mpn\"] and not entry[\"manufacturer\"]:\n gaps.append(\"manufacturer\")\n\n # Datasheet URL should be present for anything with an MPN\n ds = entry[\"datasheet\"]\n if entry[\"mpn\"] and (not ds or ds == \"~\" or \"://\" not in ds):\n gaps.append(\"datasheet\")\n\n # Check distributor fields that this project uses\n field_map = convention[\"field_mapping\"]\n for dist in (\"digikey\", \"mouser\", \"lcsc\", \"element14\"):\n if dist in field_map and not entry.get(dist):\n gaps.append(dist)\n\n return gaps\n\n\n# ---------------------------------------------------------------------------\n# Full analysis\n# ---------------------------------------------------------------------------\n\ndef parse_schematic_file(filepath: Path) -> tuple[list[dict], str]:\n \"\"\"Parse a single .kicad_sch file and return (symbols, text).\"\"\"\n text = filepath.read_text(encoding=\"utf-8\")\n raw_symbols = extract_placed_symbols(text)\n\n symbols = []\n for start, end, block in raw_symbols:\n props = extract_properties(block)\n ref = props.get(\"Reference\", \"\")\n comp_type = classify_reference(ref)\n\n symbols.append({\n \"reference\": ref,\n \"type\": comp_type,\n \"in_bom\": is_in_bom(block),\n \"dnp\": is_dnp(block, props),\n \"raw_properties\": props,\n \"source_file\": str(filepath),\n })\n\n return symbols, text\n\n\ndef analyze(\n input_path: Path,\n recursive: bool = False,\n group_by: str = 'value+footprint',\n) -> dict:\n \"\"\"Analyze a KiCad schematic and return full BOM report.\"\"\"\n files_to_parse = [input_path]\n\n if recursive:\n # Discover all sub-sheets recursively\n visited = set()\n queue = [input_path]\n while queue:\n current = queue.pop(0)\n if current in visited:\n continue\n visited.add(current)\n text = current.read_text(encoding=\"utf-8\")\n sub_sheets = find_sub_sheets(text, current.parent)\n for ss in sub_sheets:\n if ss not in visited:\n queue.append(ss)\n files_to_parse.append(ss)\n\n # Parse all files\n all_symbols = []\n for fp in files_to_parse:\n syms, _ = parse_schematic_file(fp)\n all_symbols.extend(syms)\n\n # Detect convention\n convention = detect_convention(all_symbols)\n\n # Generate BOM\n bom = generate_bom(all_symbols, convention, group_by=group_by)\n\n # Compute stats\n real_parts = [e for e in bom if e[\"type\"] not in (\"power_symbol\", \"test_point\", \"mounting_hole\")]\n dnp_parts = [e for e in real_parts if e[\"dnp\"]]\n active_parts = [e for e in real_parts if not e[\"dnp\"]]\n\n stats = {\n \"schematic_files\": [str(f) for f in files_to_parse],\n \"total_bom_lines\": len(real_parts),\n \"total_components\": sum(e[\"quantity\"] for e in real_parts),\n \"dnp_lines\": len(dnp_parts),\n \"active_lines\": len(active_parts),\n \"active_components\": sum(e[\"quantity\"] for e in active_parts),\n \"with_mpn\": sum(1 for e in active_parts if e[\"mpn\"]),\n \"without_mpn\": sum(1 for e in active_parts if not e[\"mpn\"]),\n \"with_datasheet\": sum(1 for e in active_parts if e[\"datasheet\"] and e[\"datasheet\"] != \"~\" and \"://\" in e[\"datasheet\"]),\n \"without_datasheet\": sum(1 for e in active_parts if not e[\"datasheet\"] or e[\"datasheet\"] == \"~\" or \"://\" not in e[\"datasheet\"]),\n }\n for dist in (\"digikey\", \"mouser\", \"lcsc\", \"element14\"):\n stats[f\"with_{dist}\"] = sum(1 for e in active_parts if e.get(dist))\n stats[f\"without_{dist}\"] = sum(1 for e in active_parts if not e.get(dist))\n\n # Detect any unrecognized PNs in generic fields\n unrecognized_fields: dict[str, list[str]] = {}\n for sym in all_symbols:\n for name, value in sym[\"raw_properties\"].items():\n if name in STANDARD_FIELDS or name in DNP_FIELDS or name in BOM_COMMENT_FIELDS:\n continue\n canonical = _ALIAS_LOOKUP.get(name) or _ALIAS_LOOKUP.get(name.upper())\n if not canonical and value.strip():\n guess = classify_pn_by_pattern(value)\n if guess:\n unrecognized_fields.setdefault(name, []).append(\n f\"{value} (looks like {guess})\"\n )\n\n return {\n \"schematic\": str(input_path),\n \"convention\": {\n \"field_mapping\": convention[\"field_mapping\"],\n \"populated_counts\": convention[\"populated_counts\"],\n \"preferred_distributor\": convention[\"preferred_distributor\"],\n \"names_canonical\": convention[\"names_canonical\"],\n \"suggested_fields\": convention[\"suggested_fields\"],\n },\n \"stats\": stats,\n \"bom\": bom,\n \"unrecognized_fields\": unrecognized_fields if unrecognized_fields else None,\n }\n\n\n# ---------------------------------------------------------------------------\n# Output formatting\n# ---------------------------------------------------------------------------\n\ndef format_human(report: dict, gaps_only: bool = False) -> str:\n \"\"\"Format report as human-readable text.\"\"\"\n lines = []\n conv = report[\"convention\"]\n stats = report[\"stats\"]\n\n lines.append(f\"BOM Analysis: {report['schematic']}\")\n lines.append(\"=\" * 60)\n\n # Convention\n lines.append(f\"\\nConvention:\")\n fm = conv[\"field_mapping\"]\n if fm:\n for canonical, actual in sorted(fm.items()):\n marker = \" (canonical)\" if actual == CANONICAL_NAMES.get(canonical) else f\" -> {canonical}\"\n lines.append(f\" {actual}{marker}\")\n else:\n lines.append(\" No BOM fields detected — this project has no part number tracking yet.\")\n\n if conv[\"preferred_distributor\"]:\n lines.append(f\" Preferred distributor: {conv['preferred_distributor']}\")\n\n # Stats\n lines.append(f\"\\nStats:\")\n lines.append(f\" BOM lines (active): {stats['active_lines']} ({stats['active_components']} components)\")\n lines.append(f\" DNP: {stats['dnp_lines']}\")\n lines.append(f\" With MPN: {stats['with_mpn']}/{stats['active_lines']}\")\n lines.append(f\" With datasheet URL: {stats['with_datasheet']}/{stats['active_lines']}\")\n for dist in (\"digikey\", \"mouser\", \"lcsc\", \"element14\"):\n w = stats.get(f\"with_{dist}\", 0)\n if w > 0 or dist in fm:\n lines.append(f\" With {dist}: {w}/{stats['active_lines']}\")\n\n # BOM table\n bom = report[\"bom\"]\n if gaps_only:\n bom = [e for e in bom if e.get(\"gaps\")]\n\n if bom:\n lines.append(f\"\\n{'Gaps' if gaps_only else 'BOM'}:\")\n lines.append(f\" {'Ref':\u003c12} {'Qty':>3} {'Value':\u003c20} {'MPN':\u003c30} {'Gaps'}\")\n lines.append(f\" {'-'*12} {'-'*3} {'-'*20} {'-'*30} {'-'*20}\")\n for entry in bom:\n if entry[\"type\"] in (\"power_symbol\",):\n continue\n refs = \",\".join(entry[\"references\"][:5])\n if len(entry[\"references\"]) > 5:\n refs += f\"...(+{len(entry['references'])-5})\"\n gaps_str = \", \".join(entry.get(\"gaps\", []))\n if entry[\"dnp\"]:\n gaps_str = \"DNP\"\n line = (\n f\" {refs:\u003c12} {entry['quantity']:>3} {entry['value']:\u003c20} \"\n f\"{entry['mpn'] or '(none)':\u003c30} {gaps_str}\"\n )\n bom_comments = entry.get(\"bom_comments\", [])\n if bom_comments:\n line += f\" [{'; '.join(bom_comments)}]\"\n lines.append(line)\n\n # Unrecognized fields\n if report.get(\"unrecognized_fields\"):\n lines.append(f\"\\nUnrecognized fields with part-number-like values:\")\n for name, examples in report[\"unrecognized_fields\"].items():\n lines.append(f\" '{name}': {examples[0]}\")\n\n return \"\\n\".join(lines)\n\n\n# ---------------------------------------------------------------------------\n# CSV export / merge\n# ---------------------------------------------------------------------------\n\nimport csv\n\n# Base columns (always present) and distributor column pairs (conditional)\n_CSV_BASE_COLUMNS = [\n \"Reference\", \"Qty\", \"Value\", \"Footprint\", \"MPN\", \"Manufacturer\",\n]\n_CSV_TAIL_COLUMNS = [\n \"Chosen_Distributor\", \"Datasheet\", \"Validated\", \"DNP\", \"Notes\",\n]\n\n# Map canonical distributor names to CSV column name pairs (PN, Stock)\n_DIST_CSV_MAP = {\n \"digikey\": (\"DigiKey\", \"DK_Stock\"),\n \"mouser\": (\"Mouser\", \"MO_Stock\"),\n \"lcsc\": (\"LCSC\", \"LC_Stock\"),\n \"element14\": (\"element14\", \"E14_Stock\"),\n}\n\n# Canonical ordering for distributor columns\n_DIST_ORDER = [\"digikey\", \"mouser\", \"lcsc\", \"element14\"]\n\n\ndef _build_csv_columns(active_distributors: list[str]) -> list[str]:\n \"\"\"Build the CSV column list including only the distributors the project uses.\"\"\"\n cols = list(_CSV_BASE_COLUMNS)\n for dist in _DIST_ORDER:\n if dist in active_distributors:\n pn_col, stock_col = _DIST_CSV_MAP[dist]\n cols.extend([pn_col, stock_col])\n cols.extend(_CSV_TAIL_COLUMNS)\n return cols\n\n\ndef _detect_active_distributors(report: dict) -> list[str]:\n \"\"\"Determine which distributors are actively used in a project.\n\n A distributor is active if:\n - The schematic has any parts with that distributor's PN populated, OR\n - The convention detected a field mapping for that distributor\n \"\"\"\n active = []\n convention = report.get(\"convention\", {})\n field_mapping = convention.get(\"field_mapping\", {})\n stats = report.get(\"stats\", {})\n\n for dist in _DIST_ORDER:\n has_mapping = dist in field_mapping\n has_parts = stats.get(f\"with_{dist}\", 0) > 0\n if has_mapping or has_parts:\n active.append(dist)\n return active\n\n\ndef _short_footprint(fp: str) -> str:\n \"\"\"Shorten a KiCad footprint path for display: 'Resistor_SMD:R_0805_2012Metric' -> '0805'.\"\"\"\n if not fp:\n return \"\"\n # Extract the part after the colon\n if \":\" in fp:\n fp = fp.split(\":\", 1)[1]\n # Try to extract the package size (e.g., 0402, 0805, SOT-23, QFN-24)\n m = re.search(r'(\\d{4})_\\d{4}Metric', fp)\n if m:\n return m.group(1)\n # Return the whole name minus common prefixes\n for prefix in (\"R_\", \"C_\", \"L_\", \"D_\"):\n if fp.startswith(prefix):\n fp = fp[len(prefix):]\n return fp\n\n\ndef load_existing_csv(csv_path: Path) -> dict[str, dict]:\n \"\"\"Load an existing BOM CSV and index by MPN (or Reference as fallback).\n\n Returns {key: row_dict} where key is MPN if available, else Reference.\n \"\"\"\n if not csv_path.exists():\n return {}\n\n rows = {}\n with open(csv_path, newline=\"\", encoding=\"utf-8\") as f:\n reader = csv.DictReader(f)\n for row in reader:\n # Use MPN as key if available, else first reference\n key = row.get(\"MPN\", \"\").strip()\n if not key:\n key = row.get(\"Reference\", \"\").strip().split(\",\")[0]\n if key:\n rows[key] = dict(row)\n return rows\n\n\ndef export_csv(report: dict, output_path: Path, extra_distributors: list[str] | None = None) -> dict:\n \"\"\"Export BOM to a tracking CSV, merging with existing data if present.\n\n Preserves user-edited columns (Chosen_Distributor, Validated, Notes, stock\n counts) from an existing CSV while updating schematic-derived columns.\n Only includes distributor columns for distributors the project actually uses,\n plus any explicitly requested via extra_distributors.\n \"\"\"\n bom = report[\"bom\"]\n\n # Determine which suppliers this project uses\n active_distributors = _detect_active_distributors(report)\n # Add explicitly requested suppliers\n if extra_distributors:\n for s in extra_distributors:\n if s in _DIST_CSV_MAP and s not in active_distributors:\n active_distributors.append(s)\n csv_columns = _build_csv_columns(active_distributors)\n\n # Load existing CSV data to preserve user edits\n existing = load_existing_csv(output_path)\n\n # If an existing CSV has extra distributor columns (user added one manually),\n # include those too so we don't drop data\n if existing:\n sample = next(iter(existing.values()), {})\n for dist in _DIST_ORDER:\n if dist not in active_distributors:\n pn_col, stock_col = _DIST_CSV_MAP[dist]\n if sample.get(pn_col) or sample.get(stock_col):\n active_distributors.append(dist)\n csv_columns = _build_csv_columns(active_distributors)\n\n # User-managed columns (preserved from existing CSV)\n user_columns = {\"Chosen_Distributor\", \"Validated\", \"Notes\"}\n for dist in active_distributors:\n user_columns.add(_DIST_CSV_MAP[dist][1]) # stock columns\n\n rows = []\n for entry in bom:\n if entry[\"type\"] in (\"power_symbol\",):\n continue\n\n refs = \",\".join(entry[\"references\"])\n mpn = entry[\"mpn\"]\n fp_short = _short_footprint(entry[\"footprint\"])\n ds = entry[\"datasheet\"] if entry[\"datasheet\"] != \"~\" else \"\"\n\n # Seed Notes from schematic BOM comments (user CSV edits take priority in merge below)\n bom_comments = \"; \".join(entry.get(\"bom_comments\", []))\n\n row = {\n \"Reference\": refs,\n \"Qty\": str(entry[\"quantity\"]),\n \"Value\": entry[\"value\"],\n \"Footprint\": fp_short,\n \"MPN\": mpn,\n \"Manufacturer\": entry[\"manufacturer\"],\n \"Datasheet\": ds,\n \"DNP\": \"yes\" if entry[\"dnp\"] else \"\",\n \"Notes\": bom_comments,\n }\n\n # Only add distributor PN columns for active distributors\n for dist in active_distributors:\n pn_col = _DIST_CSV_MAP[dist][0]\n row[pn_col] = entry.get(dist, \"\")\n\n # Merge with existing data — preserve user-managed columns\n existing_row = existing.get(mpn) if mpn else None\n if not existing_row:\n # Try matching by first reference\n first_ref = entry[\"references\"][0] if entry[\"references\"] else \"\"\n for erow in existing.values():\n if first_ref and first_ref in erow.get(\"Reference\", \"\").split(\",\"):\n existing_row = erow\n break\n\n if existing_row:\n for col in user_columns:\n if col in existing_row and existing_row[col]:\n row[col] = existing_row[col]\n # Also preserve distributor PNs from CSV if schematic has none\n for dist in active_distributors:\n dist_col = _DIST_CSV_MAP[dist][0]\n if not row.get(dist_col) and existing_row.get(dist_col):\n row[dist_col] = existing_row[dist_col]\n\n # Fill missing columns with empty strings\n for col in csv_columns:\n row.setdefault(col, \"\")\n\n rows.append(row)\n\n # Write CSV\n output_path.parent.mkdir(parents=True, exist_ok=True)\n with open(output_path, \"w\", newline=\"\", encoding=\"utf-8\") as f:\n writer = csv.DictWriter(f, fieldnames=csv_columns, extrasaction=\"ignore\")\n writer.writeheader()\n writer.writerows(rows)\n\n active_rows = [r for r in rows if r.get(\"DNP\") != \"yes\"]\n return {\n \"output\": str(output_path),\n \"total_lines\": len(rows),\n \"active_lines\": len(active_rows),\n \"active_distributors\": active_distributors,\n \"merged_from_existing\": sum(1 for _ in existing) if existing else 0,\n }\n\n\n# ---------------------------------------------------------------------------\n# Order file generation\n# ---------------------------------------------------------------------------\n\n# Distributor name normalization — map user-entered Chosen_Distributor values to canonical names\n_DISTRIBUTOR_NORMALIZE = {\n \"digikey\": \"digikey\", \"digi-key\": \"digikey\", \"dk\": \"digikey\",\n \"mouser\": \"mouser\", \"mo\": \"mouser\",\n \"lcsc\": \"lcsc\", \"jlcpcb\": \"lcsc\", \"jlc\": \"lcsc\",\n \"newark\": \"element14\", \"farnell\": \"element14\", \"element14\": \"element14\", \"e14\": \"element14\",\n}\n\n\ndef _normalize_distributor(name: str) -> str:\n \"\"\"Normalize a distributor name to canonical form.\"\"\"\n return _DISTRIBUTOR_NORMALIZE.get(name.strip().lower(), name.strip().lower())\n\n\ndef _split_comma_field(value: str) -> list[str]:\n \"\"\"Split a comma-separated field, stripping whitespace. Returns [''] for empty.\"\"\"\n if not value or not value.strip():\n return []\n return [v.strip() for v in value.split(\",\") if v.strip()]\n\n\ndef _write_digikey_order(f, lines: list[dict], split_log: list[str]) -> None:\n \"\"\"Write DigiKey bulk-add paste format: qty, DK_PN, customer_reference.\"\"\"\n for line in lines:\n refs_safe = line['refs'].replace(\",\", \"/\")\n f.write(f\"{line['qty']}, {line['pn']}, {refs_safe}\\n\")\n if line[\"split\"]:\n split_log.append(f\" {line['refs']}: split — {line['pn']} (qty {line['qty']})\")\n\n\ndef _write_mouser_order(f, lines: list[dict], split_log: list[str]) -> None:\n \"\"\"Write Mouser part list import format: Mouser_PN|qty.\"\"\"\n for line in lines:\n f.write(f\"{line['pn']}|{line['qty']}\\n\")\n if line[\"split\"]:\n split_log.append(f\" {line['refs']}: split — {line['pn']} (qty {line['qty']})\")\n\n\ndef _write_lcsc_order(f, lines: list[dict], split_log: list[str]) -> None:\n \"\"\"Write JLCPCB/LCSC BOM CSV format: Comment,Designator,Footprint,LCSC Part #.\"\"\"\n writer = csv.writer(f)\n writer.writerow([\"Comment\", \"Designator\", \"Footprint\", \"LCSC Part #\"])\n for line in lines:\n writer.writerow([line[\"value\"], line[\"refs\"], line[\"footprint\"], line[\"pn\"]])\n if line[\"split\"]:\n split_log.append(f\" {line['refs']}: split — {line['pn']} ({line['value']})\")\n\n\ndef _write_element14_order(f, lines: list[dict], split_log: list[str]) -> None:\n \"\"\"Write Newark quick order format: PN, qty.\"\"\"\n for line in lines:\n f.write(f\"{line['pn']}, {line['qty']}\\n\")\n if line[\"split\"]:\n split_log.append(f\" {line['refs']}: split — {line['pn']} (qty {line['qty']})\")\n\n\ndef generate_order_files(\n csv_path: Path,\n output_dir: Path,\n boards: int = 1,\n spares: int = 0,\n distributor_filter: str | None = None,\n) -> dict:\n \"\"\"Read a BOM tracking CSV and generate per-distributor order files.\n\n Args:\n csv_path: Path to BOM tracking CSV\n output_dir: Directory for output order files\n boards: Number of boards being assembled (multiplies all quantities)\n spares: Extra components per line (added after board multiplication)\n distributor_filter: If set, auto-assign this distributor for all parts that\n have a PN for it, ignoring the Chosen_Distributor column.\n\n Returns a summary dict with per-distributor stats and any errors.\n \"\"\"\n if not csv_path.exists():\n return {\"error\": f\"BOM CSV not found: {csv_path}\"}\n\n # Read the BOM CSV\n with open(csv_path, newline=\"\", encoding=\"utf-8\") as f:\n reader = csv.DictReader(f)\n rows = list(reader)\n\n # Distributor PN column mapping: canonical name -> CSV column name\n distributor_pn_col = {\n \"digikey\": \"DigiKey\",\n \"mouser\": \"Mouser\",\n \"lcsc\": \"LCSC\",\n \"element14\": \"element14\",\n }\n\n # Collect order lines per distributor\n orders: dict[str, list[dict]] = {} # distributor -> [order_line, ...]\n errors = []\n skipped_dnp = []\n skipped_no_distributor = []\n\n for row in rows:\n refs = row.get(\"Reference\", \"\").strip()\n qty_str = row.get(\"Qty\", \"1\").strip()\n qty_per_board = int(qty_str) if qty_str.isdigit() else 1\n qty = qty_per_board * boards + spares\n\n # Skip DNP\n if row.get(\"DNP\", \"\").strip().lower() in (\"yes\", \"true\", \"1\", \"dnp\"):\n skipped_dnp.append(refs)\n continue\n\n # Determine distributor: use filter override if set, else Chosen_Distributor\n if distributor_filter:\n distributor = _normalize_distributor(distributor_filter)\n pn_col = distributor_pn_col.get(distributor)\n if not pn_col:\n errors.append(f\"Unknown distributor filter: '{distributor_filter}'\")\n break\n pn_raw = row.get(pn_col, \"\").strip()\n if not pn_raw:\n skipped_no_distributor.append(refs)\n continue\n else:\n chosen = row.get(\"Chosen_Distributor\", \"\").strip()\n if not chosen:\n skipped_no_distributor.append(refs)\n continue\n\n distributor = _normalize_distributor(chosen)\n pn_col = distributor_pn_col.get(distributor)\n if not pn_col:\n errors.append(f\"{refs}: unknown distributor '{chosen}'\")\n continue\n\n pn_raw = row.get(pn_col, \"\").strip()\n value = row.get(\"Value\", \"\").strip()\n footprint = row.get(\"Footprint\", \"\").strip()\n mpn = row.get(\"MPN\", \"\").strip()\n\n # Split comma-separated PNs (accessory/cable bundled with main part)\n pns = _split_comma_field(pn_raw)\n mpns = _split_comma_field(mpn)\n\n if not pns:\n label = distributor_filter if distributor_filter else row.get(\"Chosen_Distributor\", \"\").strip()\n errors.append(f\"{refs}: distributor is '{label}' but {pn_col} column is empty\")\n continue\n\n for i, pn in enumerate(pns):\n line_mpn = mpns[i] if i \u003c len(mpns) else (mpns[0] if mpns else \"\")\n order_line = {\n \"pn\": pn,\n \"qty\": qty,\n \"refs\": refs,\n \"value\": value,\n \"footprint\": footprint,\n \"mpn\": line_mpn,\n \"split\": len(pns) > 1,\n }\n orders.setdefault(distributor, []).append(order_line)\n\n # Generate output files\n output_dir.mkdir(parents=True, exist_ok=True)\n files_written = {}\n split_log = []\n\n _distributor_writers = {\n \"digikey\": _write_digikey_order,\n \"mouser\": _write_mouser_order,\n \"lcsc\": _write_lcsc_order,\n \"element14\": _write_element14_order,\n }\n\n for distributor, lines in orders.items():\n writer_fn = _distributor_writers.get(distributor)\n if not writer_fn:\n errors.append(f\"No order format defined for distributor '{distributor}', skipping\")\n continue\n\n filename = f\"order_{distributor}.csv\"\n filepath = output_dir / filename\n\n with open(filepath, \"w\", newline=\"\", encoding=\"utf-8\") as f:\n writer_fn(f, lines, split_log)\n\n total_components = sum(l[\"qty\"] for l in lines)\n files_written[distributor] = {\n \"file\": str(filepath),\n \"lines\": len(lines),\n \"components\": total_components,\n }\n\n return {\n \"orders\": files_written,\n \"errors\": errors,\n \"skipped_dnp\": skipped_dnp,\n \"skipped_no_distributor\": skipped_no_distributor,\n \"split_log\": split_log,\n \"boards\": boards,\n \"spares\": spares,\n \"distributor_filter\": distributor_filter,\n }\n\n\ndef format_order_summary(result: dict) -> str:\n \"\"\"Format order generation results for human display.\"\"\"\n lines = []\n\n if \"error\" in result:\n return f\"Error: {result['error']}\"\n\n boards = result.get(\"boards\", 1)\n spares = result.get(\"spares\", 0)\n if boards > 1 or spares > 0:\n qty_desc = f\"{boards} board{'s' if boards != 1 else ''}\"\n if spares > 0:\n qty_desc += f\" + {spares} spare{'s' if spares != 1 else ''}/line\"\n lines.append(f\"Quantity: {qty_desc}\")\n lines.append(\"\")\n\n if result.get(\"distributor_filter\"):\n lines.append(f\"Distributor filter: {result['distributor_filter']} (auto-selected from PN columns)\")\n lines.append(\"\")\n\n orders = result.get(\"orders\", {})\n if orders:\n lines.append(\"Order files generated:\")\n for dist, info in orders.items():\n label = {\"digikey\": \"DigiKey\", \"mouser\": \"Mouser\", \"lcsc\": \"LCSC\", \"element14\": \"Newark/element14\"}.get(dist, dist)\n lines.append(f\" {label:\u003c20} {info['lines']:>3} lines, {info['components']:>4} components → {info['file']}\")\n else:\n lines.append(\"No order files generated.\")\n\n if result.get(\"split_log\"):\n lines.append(\"\\nSplit entries (multi-part BOM lines):\")\n lines.extend(result[\"split_log\"])\n\n if result.get(\"skipped_dnp\"):\n lines.append(f\"\\nDNP (excluded): {', '.join(result['skipped_dnp'])}\")\n\n if result.get(\"skipped_no_distributor\"):\n lines.append(f\"\\nNo distributor chosen: {', '.join(result['skipped_no_distributor'])}\")\n\n if result.get(\"errors\"):\n lines.append(\"\\nErrors:\")\n for err in result[\"errors\"]:\n lines.append(f\" ✗ {err}\")\n\n return \"\\n\".join(lines)\n\n\n# ---------------------------------------------------------------------------\n# CLI\n# ---------------------------------------------------------------------------\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Analyze KiCad schematic BOM properties and manage BOM files\"\n )\n subparsers = parser.add_subparsers(dest=\"command\")\n\n # analyze subcommand\n p_analyze = subparsers.add_parser(\"analyze\", help=\"Analyze schematic BOM properties\")\n p_analyze.add_argument(\"schematic\", type=Path, help=\"Path to .kicad_sch file\")\n p_analyze.add_argument(\"--json\", action=\"store_true\", help=\"Output as JSON\")\n p_analyze.add_argument(\"--gaps-only\", action=\"store_true\", help=\"Show only parts with missing fields\")\n p_analyze.add_argument(\"--recursive\", action=\"store_true\", help=\"Include hierarchical sub-sheets\")\n\n # export subcommand\n p_export = subparsers.add_parser(\"export\", help=\"Export BOM tracking CSV\")\n p_export.add_argument(\"schematic\", type=Path, help=\"Path to .kicad_sch file\")\n p_export.add_argument(\"-o\", \"--output\", type=Path, required=True, help=\"Output CSV path\")\n p_export.add_argument(\"--recursive\", action=\"store_true\", help=\"Include hierarchical sub-sheets\")\n p_export.add_argument(\"--add-distributor\", action=\"append\", default=[],\n help=\"Add distributor columns even if not detected (e.g., --add-distributor mouser)\")\n\n # order subcommand\n p_order = subparsers.add_parser(\"order\", help=\"Generate per-distributor order files from BOM CSV\")\n p_order.add_argument(\"csv\", type=Path, help=\"Path to BOM tracking CSV\")\n p_order.add_argument(\"-o\", \"--output-dir\", type=Path, default=None,\n help=\"Output directory for order files (default: orders/ next to CSV)\")\n p_order.add_argument(\"--boards\", type=int, default=1,\n help=\"Number of boards (multiplies all quantities, default: 1)\")\n p_order.add_argument(\"--spares\", type=int, default=0,\n help=\"Extra components per line (added after board multiplication, default: 0)\")\n p_order.add_argument(\"--distributor\", type=str, default=None,\n help=\"Auto-select distributor for all parts that have its PN (bypasses Chosen_Distributor)\")\n p_order.add_argument(\"--json\", action=\"store_true\", help=\"Output result as JSON\")\n\n # Backwards compat: if first arg is a .kicad_sch file with no subcommand, assume \"analyze\"\n if len(sys.argv) > 1 and sys.argv[1].endswith(\".kicad_sch\"):\n sys.argv.insert(1, \"analyze\")\n\n args = parser.parse_args()\n\n # Load project config for BOM preferences\n bom_config: dict = {}\n preferred_suppliers_cfg: list = []\n try:\n from project_config import load_config, get_preferred_suppliers\n sch_dir = str(getattr(args, 'schematic', Path('.')).parent)\n cfg = load_config(sch_dir)\n bom_config = cfg.get('bom', {})\n preferred_suppliers_cfg = get_preferred_suppliers(cfg)\n except (ImportError, Exception):\n pass\n\n if args.command is None:\n parser.print_help()\n sys.exit(1)\n\n if args.command == \"order\":\n # Order subcommand takes a CSV, not a schematic\n if not args.csv.exists():\n print(f\"Error: {args.csv} not found\", file=sys.stderr)\n sys.exit(1)\n output_dir = args.output_dir or (args.csv.parent / \"orders\")\n result = generate_order_files(\n args.csv, output_dir,\n boards=args.boards,\n spares=args.spares,\n distributor_filter=args.distributor,\n )\n if args.json:\n json.dump(result, sys.stdout, indent=2)\n print()\n else:\n print(format_order_summary(result), file=sys.stderr)\n else:\n # analyze and export both need a schematic\n if not args.schematic.exists():\n print(f\"Error: {args.schematic} not found\", file=sys.stderr)\n sys.exit(1)\n if args.schematic.suffix != \".kicad_sch\":\n print(f\"Error: expected a .kicad_sch file, got {args.schematic.suffix}\", file=sys.stderr)\n sys.exit(1)\n\n if args.command == \"analyze\":\n group_by = bom_config.get('group_by', 'value+footprint')\n report = analyze(args.schematic, recursive=args.recursive,\n group_by=group_by)\n # Config override: preferred_suppliers takes precedence\n if preferred_suppliers_cfg:\n report['convention']['preferred_distributor'] = (\n preferred_suppliers_cfg[0])\n report['convention']['preferred_suppliers'] = (\n preferred_suppliers_cfg)\n if args.json:\n json.dump(report, sys.stdout, indent=2)\n print()\n else:\n print(format_human(report, gaps_only=args.gaps_only))\n\n elif args.command == \"export\":\n group_by = bom_config.get('group_by', 'value+footprint')\n report = analyze(args.schematic, recursive=args.recursive,\n group_by=group_by)\n extra_distributors = [_normalize_distributor(s)\n for s in args.add_distributor]\n # Config-preferred suppliers always get CSV columns\n for s in preferred_suppliers_cfg:\n ns = _normalize_distributor(s)\n if ns not in extra_distributors:\n extra_distributors.append(ns)\n result = export_csv(report, args.output, extra_distributors=extra_distributors)\n print(f\"Exported {result['total_lines']} BOM lines to {result['output']}\", file=sys.stderr)\n dist_names = [_DIST_CSV_MAP[s][0] for s in result.get(\"active_distributors\", []) if s in _DIST_CSV_MAP]\n if dist_names:\n print(f\" Distributors: {', '.join(dist_names)}\", file=sys.stderr)\n if result[\"merged_from_existing\"]:\n print(f\" Merged with {result['merged_from_existing']} existing rows (preserved stock/distributor/notes)\", file=sys.stderr)\n print(f\" Active: {result['active_lines']}, DNP: {result['total_lines'] - result['active_lines']}\", file=sys.stderr)\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":48836,"content_sha256":"e5a4d0da8d1c62976afd5ddfb6211d7ef841277d32df954e343f409171250a6e"},{"filename":"scripts/edit_properties.py","content":"#!/usr/bin/env python3\n\"\"\"Edit KiCad schematic symbol properties — add or update BOM fields.\n\nReads a .kicad_sch file, applies property updates to symbols identified by\nreference designator, and writes the modified file back.\n\nUpdates are provided as JSON, either from a file or stdin.\n\nUsage:\n # Apply updates from a JSON file\n python3 edit_properties.py path/to/schematic.kicad_sch --updates updates.json\n\n # Pipe updates from stdin\n echo '{\"R1\": {\"MPN\": \"RC0805FR-0710KL\"}}' | python3 edit_properties.py schematic.kicad_sch\n\n # Create a backup before writing\n python3 edit_properties.py schematic.kicad_sch --updates updates.json --backup\n\n # Dry run — show what would change without writing\n python3 edit_properties.py schematic.kicad_sch --updates updates.json --dry-run\n\nUpdate JSON format:\n {\n \"R1\": {\n \"MPN\": \"RC0805FR-0710KL\",\n \"Manufacturer\": \"Yageo\",\n \"DigiKey\": \"311-10.0KCRCT-ND\"\n },\n \"C1\": {\n \"MPN\": \"GRM155R71C104KA88D\",\n \"Datasheet\": \"https://example.com/datasheet.pdf\"\n }\n }\n\nEach key is a reference designator. The value is a dict of property name -> value.\nProperties that already exist are updated; new properties are added (hidden).\nTo clear a property value, set it to an empty string \"\".\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport re\nimport shutil\nimport sys\nfrom datetime import datetime\nfrom pathlib import Path\n\nfrom kicad_sexp import escape_kicad_string, find_matching_paren\n\n\n# ---------------------------------------------------------------------------\n# Symbol finder\n# ---------------------------------------------------------------------------\n\ndef find_placed_symbols(text: str) -> list[tuple[int, int, str]]:\n \"\"\"Find all placed symbol blocks and their positions in the text.\n\n Returns list of (start_pos, end_pos, reference) tuples.\n \"\"\"\n symbols = []\n\n # Skip past lib_symbols section\n lib_match = re.search(r'\\(lib_symbols\\b', text)\n search_start = 0\n if lib_match:\n lib_end = find_matching_paren(text, lib_match.start())\n search_start = lib_end + 1\n\n # Find placed symbols\n pattern = re.compile(r'\\(symbol\\s*\\n?\\s*\\(lib_id\\s+')\n for match in pattern.finditer(text, search_start):\n sym_start = match.start()\n sym_end = find_matching_paren(text, sym_start)\n block = text[sym_start:sym_end + 1]\n\n # Extract reference\n ref_match = re.search(\n r'\\(property\\s+\"Reference\"\\s+\"((?:[^\"\\\\]|\\\\.)*)\"', block\n )\n ref = ref_match.group(1) if ref_match else \"\"\n symbols.append((sym_start, sym_end, ref))\n\n return symbols\n\n\n# ---------------------------------------------------------------------------\n# Property editor\n# ---------------------------------------------------------------------------\n\ndef find_property_in_block(text: str, sym_start: int, sym_end: int, prop_name: str) -> tuple[int, int] | None:\n \"\"\"Find a property entry within a symbol block.\n\n Returns (start, end) positions of the entire (property ...) block, or None.\n \"\"\"\n block = text[sym_start:sym_end + 1]\n escaped_name = re.escape(prop_name)\n pattern = re.compile(rf'\\(property\\s+\"{escaped_name}\"\\s+\"')\n\n match = pattern.search(block)\n if not match:\n return None\n\n prop_start = sym_start + match.start()\n prop_end = find_matching_paren(text, prop_start)\n return (prop_start, prop_end)\n\n\ndef find_last_property_end(text: str, sym_start: int, sym_end: int) -> int:\n \"\"\"Find the end position of the last property block in a symbol.\n\n Returns the position right after the closing paren of the last property.\n \"\"\"\n block = text[sym_start:sym_end + 1]\n last_prop_end = sym_start # fallback\n\n for match in re.finditer(r'\\(property\\s+\"', block):\n prop_start = sym_start + match.start()\n prop_end = find_matching_paren(text, prop_start)\n if prop_end > last_prop_end:\n last_prop_end = prop_end\n\n return last_prop_end\n\n\ndef detect_indentation(text: str, sym_start: int, sym_end: int) -> str:\n \"\"\"Detect the indentation used for properties in this symbol.\"\"\"\n block = text[sym_start:sym_end + 1]\n match = re.search(r'\\n(\\s+)\\(property\\s+\"', block)\n if match:\n return match.group(1)\n return \"\\t\\t\" # default to 2 tabs\n\n\ndef build_new_property(\n prop_name: str,\n prop_value: str,\n indent: str,\n) -> str:\n \"\"\"Build a new (property ...) block for insertion.\"\"\"\n escaped_value = escape_kicad_string(prop_value)\n inner = indent + \"\\t\"\n return (\n f'\\n{indent}(property \"{prop_name}\" \"{escaped_value}\" (at 0 0 0)\\n'\n f'{inner}(effects\\n'\n f'{inner}\\t(font\\n'\n f'{inner}\\t\\t(size 1.27 1.27)\\n'\n f'{inner}\\t)\\n'\n f'{inner}\\t(hide yes)\\n'\n f'{inner})\\n'\n f'{indent})'\n )\n\n\ndef update_property_value(\n text: str,\n prop_start: int,\n prop_end: int,\n prop_name: str,\n new_value: str,\n) -> str:\n \"\"\"Replace the value of an existing property, preserving all formatting.\"\"\"\n old_block = text[prop_start:prop_end + 1]\n escaped_value = escape_kicad_string(new_value)\n\n # Replace just the value string after the property name\n escaped_name = re.escape(prop_name)\n new_block = re.sub(\n rf'(\\(property\\s+\"{escaped_name}\"\\s+)\"(?:[^\"\\\\]|\\\\.)*\"',\n rf'\\1\"{escaped_value}\"',\n old_block,\n count=1,\n )\n\n return text[:prop_start] + new_block + text[prop_end + 1:]\n\n\n# ---------------------------------------------------------------------------\n# Main edit logic\n# ---------------------------------------------------------------------------\n\ndef apply_updates(\n text: str,\n updates: dict[str, dict[str, str]],\n dry_run: bool = False,\n) -> tuple[str, list[dict]]:\n \"\"\"Apply property updates to schematic text.\n\n Args:\n text: Full .kicad_sch file contents\n updates: {reference: {prop_name: value, ...}, ...}\n dry_run: If True, compute changes but don't modify text\n\n Returns:\n (modified_text, change_log)\n \"\"\"\n change_log = []\n\n # Find all placed symbols\n symbols = find_placed_symbols(text)\n ref_to_symbols = {}\n for start, end, ref in symbols:\n ref_to_symbols.setdefault(ref, []).append((start, end))\n\n # Check for missing references\n for ref in updates:\n if ref not in ref_to_symbols:\n change_log.append({\n \"reference\": ref,\n \"action\": \"error\",\n \"message\": f\"Reference '{ref}' not found in schematic\",\n })\n\n # Apply updates in reverse file order so positions don't shift\n # for changes we haven't made yet\n all_edits = [] # (position, reference, prop_name, action, old_value, new_value)\n\n for ref, props in updates.items():\n if ref not in ref_to_symbols:\n continue\n\n # A reference can appear multiple times (multi-unit symbols).\n # Update all instances.\n for sym_start, sym_end in ref_to_symbols[ref]:\n indent = detect_indentation(text, sym_start, sym_end)\n\n for prop_name, new_value in props.items():\n existing = find_property_in_block(text, sym_start, sym_end, prop_name)\n\n if existing:\n prop_start, prop_end = existing\n # Extract current value\n old_block = text[prop_start:prop_end + 1]\n old_match = re.search(\n rf'\\(property\\s+\"{re.escape(prop_name)}\"\\s+\"((?:[^\"\\\\]|\\\\.)*)\"',\n old_block,\n )\n old_value = old_match.group(1) if old_match else \"\"\n\n if old_value == new_value:\n change_log.append({\n \"reference\": ref,\n \"property\": prop_name,\n \"action\": \"unchanged\",\n \"value\": new_value,\n })\n continue\n\n all_edits.append({\n \"type\": \"update\",\n \"position\": prop_start,\n \"sym_start\": sym_start,\n \"sym_end\": sym_end,\n \"prop_start\": prop_start,\n \"prop_end\": prop_end,\n \"prop_name\": prop_name,\n \"old_value\": old_value,\n \"new_value\": new_value,\n \"reference\": ref,\n })\n else:\n # New property — insert after last existing property\n insert_pos = find_last_property_end(text, sym_start, sym_end)\n all_edits.append({\n \"type\": \"insert\",\n \"position\": insert_pos,\n \"insert_after\": insert_pos,\n \"prop_name\": prop_name,\n \"new_value\": new_value,\n \"reference\": ref,\n \"indent\": indent,\n })\n\n if dry_run:\n for edit in all_edits:\n change_log.append({\n \"reference\": edit[\"reference\"],\n \"property\": edit[\"prop_name\"],\n \"action\": \"would_\" + edit[\"type\"],\n \"old_value\": edit.get(\"old_value\", \"(new)\"),\n \"new_value\": edit[\"new_value\"],\n })\n return text, change_log\n\n # Apply edits in reverse position order so earlier edits don't\n # invalidate later positions. For multiple inserts in the same symbol,\n # they all share the same insert_after position (end of last property),\n # so reverse order stacks them correctly. Updates within the same symbol\n # are safe because each update preserves the block length of other\n # properties. Mixing updates + inserts in the same symbol works because\n # inserts go after all properties (higher position) and are applied first.\n all_edits.sort(key=lambda e: e[\"position\"], reverse=True)\n\n for edit in all_edits:\n if edit[\"type\"] == \"update\":\n text = update_property_value(\n text,\n edit[\"prop_start\"],\n edit[\"prop_end\"],\n edit[\"prop_name\"],\n edit[\"new_value\"],\n )\n change_log.append({\n \"reference\": edit[\"reference\"],\n \"property\": edit[\"prop_name\"],\n \"action\": \"updated\",\n \"old_value\": edit[\"old_value\"],\n \"new_value\": edit[\"new_value\"],\n })\n elif edit[\"type\"] == \"insert\":\n new_prop = build_new_property(\n edit[\"prop_name\"],\n edit[\"new_value\"],\n edit[\"indent\"],\n )\n pos = edit[\"insert_after\"] + 1\n text = text[:pos] + new_prop + text[pos:]\n change_log.append({\n \"reference\": edit[\"reference\"],\n \"property\": edit[\"prop_name\"],\n \"action\": \"added\",\n \"new_value\": edit[\"new_value\"],\n })\n\n return text, change_log\n\n\n# ---------------------------------------------------------------------------\n# CLI\n# ---------------------------------------------------------------------------\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Edit KiCad schematic symbol properties\"\n )\n parser.add_argument(\"schematic\", type=Path, help=\"Path to .kicad_sch file\")\n parser.add_argument(\n \"--updates\", type=Path,\n help=\"Path to JSON file with updates (or pipe via stdin)\",\n )\n parser.add_argument(\n \"--backup\", action=\"store_true\",\n help=\"Create a .bak backup file before writing changes\",\n )\n parser.add_argument(\n \"--dry-run\", action=\"store_true\",\n help=\"Show what would change without writing\",\n )\n args = parser.parse_args()\n\n if not args.schematic.exists():\n print(f\"Error: {args.schematic} not found\", file=sys.stderr)\n sys.exit(1)\n\n # Check for KiCad lock file — indicates schematic is open in KiCad\n lock_path = args.schematic.parent / f\"{args.schematic.name}.lck\"\n if lock_path.exists() and not args.dry_run:\n print(\n f\"WARNING: KiCad lock file detected ({lock_path.name}).\\n\"\n f\"The schematic appears to be open in KiCad. Changes will be\\n\"\n f\"written to disk, but KiCad won't see them until you close and\\n\"\n f\"reopen the schematic (File > Open Recent). If you save from\\n\"\n f\"KiCad without reopening first, KiCad will overwrite these changes.\",\n file=sys.stderr,\n )\n\n # Read updates\n if args.updates:\n updates = json.loads(args.updates.read_text())\n elif not sys.stdin.isatty():\n updates = json.load(sys.stdin)\n else:\n print(\"Error: provide updates via --updates file or stdin\", file=sys.stderr)\n sys.exit(1)\n\n if not isinstance(updates, dict):\n print(\"Error: updates must be a JSON object {reference: {prop: value}}\", file=sys.stderr)\n sys.exit(1)\n\n # Read schematic\n text = args.schematic.read_text(encoding=\"utf-8\")\n\n # Apply updates\n modified_text, change_log = apply_updates(text, updates, dry_run=args.dry_run)\n\n # Report changes\n actions = {}\n for entry in change_log:\n action = entry[\"action\"]\n actions[action] = actions.get(action, 0) + 1\n if action == \"error\":\n print(f\" ERROR: {entry['message']}\", file=sys.stderr)\n elif action in (\"updated\", \"would_update\"):\n print(\n f\" {entry['reference']}.{entry['property']}: \"\n f\"'{entry['old_value']}' -> '{entry['new_value']}'\",\n file=sys.stderr,\n )\n elif action in (\"added\", \"would_insert\"):\n print(\n f\" {entry['reference']}.{entry['property']}: \"\n f\"(new) = '{entry['new_value']}'\",\n file=sys.stderr,\n )\n\n total_changes = actions.get(\"updated\", 0) + actions.get(\"added\", 0)\n total_would = actions.get(\"would_update\", 0) + actions.get(\"would_insert\", 0)\n\n if args.dry_run:\n print(f\"\\nDry run: {total_would} changes would be made.\", file=sys.stderr)\n # Output the change log as JSON for programmatic use\n json.dump(change_log, sys.stdout, indent=2)\n print()\n return\n\n if total_changes == 0:\n print(\"No changes needed.\", file=sys.stderr)\n return\n\n # Create backup if requested\n if args.backup:\n timestamp = datetime.now().strftime(\"%Y%m%d_%H%M%S\")\n backup_path = args.schematic.with_suffix(f\".{timestamp}.bak\")\n shutil.copy2(args.schematic, backup_path)\n print(f\"Backup: {backup_path}\", file=sys.stderr)\n\n # Write modified file\n args.schematic.write_text(modified_text, encoding=\"utf-8\")\n print(\n f\"\\nDone: {total_changes} properties changed \"\n f\"({actions.get('updated', 0)} updated, {actions.get('added', 0)} added).\",\n file=sys.stderr,\n )\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":15259,"content_sha256":"48d9fe68f57e2faa469685e6fc7a1b48311e084fcd95955f8c5de511210ec4bc"},{"filename":"scripts/kicad_sexp.py","content":"\"\"\"Shared utilities for parsing KiCad S-expression (.kicad_sch) files.\n\nProvides low-level helpers used by bom_manager.py, edit_properties.py,\nand sync_datasheet_urls.py.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport re\nfrom pathlib import Path\n\n\ndef find_matching_paren(text: str, start: int) -> int:\n \"\"\"Find the index of the closing paren matching the open paren at `start`.\n\n Raises ValueError if the parentheses are unbalanced (truncated or\n corrupted file).\n \"\"\"\n depth = 1\n i = start + 1\n in_string = False\n while i \u003c len(text) and depth > 0:\n c = text[i]\n if in_string:\n if c == '\\\\':\n i += 2\n continue\n elif c == '\"':\n in_string = False\n else:\n if c == '\"':\n in_string = True\n elif c == '(':\n depth += 1\n elif c == ')':\n depth -= 1\n i += 1\n if depth > 0:\n raise ValueError(\n f\"Unbalanced parentheses at position {start} \"\n f\"(reached end of text with depth {depth})\"\n )\n return i - 1\n\n\ndef escape_kicad_string(s: str) -> str:\n \"\"\"Escape a string for use in a KiCad S-expression property value.\"\"\"\n return s.replace('\\\\', '\\\\\\\\').replace('\"', '\\\\\"')\n\n\ndef find_sub_sheets(text: str, base_dir: Path) -> list[Path]:\n \"\"\"Find hierarchical sub-sheet files referenced in a .kicad_sch.\"\"\"\n sheets = []\n for match in re.finditer(r'\\(sheet\\b', text):\n sheet_start = match.start()\n sheet_end = find_matching_paren(text, sheet_start)\n block = text[sheet_start:sheet_end + 1]\n file_match = re.search(\n r'\\(property\\s+\"Sheetfile\"\\s+\"((?:[^\"\\\\]|\\\\.)*)\"', block\n )\n if file_match:\n filepath = base_dir / file_match.group(1)\n if filepath.exists():\n sheets.append(filepath)\n return sheets\n\n\ndef collect_schematic_files(root: Path, recursive: bool) -> list[Path]:\n \"\"\"Collect root schematic and optionally all sub-sheets recursively.\"\"\"\n files = [root.resolve()]\n if not recursive:\n return files\n\n visited = {root.resolve()}\n queue = [root.resolve()]\n while queue:\n current = queue.pop(0)\n text = current.read_text(encoding=\"utf-8\")\n for sub in find_sub_sheets(text, current.parent):\n sub = sub.resolve()\n if sub not in visited:\n visited.add(sub)\n files.append(sub)\n queue.append(sub)\n return files\n","content_type":"text/x-python; charset=utf-8","language":"python","size":2555,"content_sha256":"7e26a3468be23844cbddb05f92f645642cd358bb0f820713f56dd0fe694a7812"},{"filename":"scripts/sync_datasheet_urls.py","content":"#!/usr/bin/env python3\n\"\"\"Sync datasheet URLs from datasheets/manifest.json back into KiCad schematic properties.\n\nAfter running datasheet sync scripts (DigiKey, LCSC, element14), this script\nreads the datasheets/manifest.json file (legacy name index.json still supported)\nand writes the discovered datasheet URLs back into the schematic's Datasheet\nproperties.\n\nOpportunistic: only fills in missing/empty URLs by default. Warns about\nmismatched URLs without overwriting unless --overwrite is specified.\n\nUsage:\n # Preview changes (dry run)\n python3 sync_datasheet_urls.py path/to/schematic.kicad_sch --dry-run\n\n # Apply — fill empty Datasheet fields, warn about mismatches\n python3 sync_datasheet_urls.py path/to/schematic.kicad_sch\n\n # Also overwrite mismatched URLs (after reviewing warnings)\n python3 sync_datasheet_urls.py path/to/schematic.kicad_sch --overwrite\n\n # Recursive (include sub-sheets)\n python3 sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive\n\n # Custom datasheets directory\n python3 sync_datasheet_urls.py path/to/schematic.kicad_sch --datasheets ./datasheets\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport re\nimport sys\nfrom pathlib import Path\nfrom urllib.parse import urlparse\n\nsys.path.insert(0, str(Path(__file__).parent))\nfrom edit_properties import apply_updates\nfrom kicad_sexp import collect_schematic_files, find_matching_paren\n\n\n# ---------------------------------------------------------------------------\n# URL helpers\n# ---------------------------------------------------------------------------\n\ndef is_empty_datasheet(value: str) -> bool:\n \"\"\"Return True if the Datasheet property is effectively empty.\"\"\"\n v = value.strip()\n return not v or v == \"~\"\n\n\ndef normalize_url(url: str) -> str:\n \"\"\"Normalize a URL for comparison purposes.\"\"\"\n url = url.strip().rstrip(\"/\")\n parsed = urlparse(url)\n # Normalize scheme to https for comparison\n scheme = \"https\" if parsed.scheme in (\"http\", \"https\") else parsed.scheme\n # Lowercase the netloc (domain)\n netloc = parsed.netloc.lower()\n # Keep path and query as-is (case-sensitive on most servers, query\n # params like ?v=2 can distinguish datasheet versions)\n path = parsed.path.rstrip(\"/\")\n result = f\"{scheme}://{netloc}{path}\"\n if parsed.query:\n result += f\"?{parsed.query}\"\n return result\n\n\ndef urls_match(a: str, b: str) -> bool:\n \"\"\"Compare two URLs, ignoring trivial differences.\"\"\"\n return normalize_url(a) == normalize_url(b)\n\n\n# ---------------------------------------------------------------------------\n# Schematic parsing (lightweight — only extracts Reference + Datasheet)\n# ---------------------------------------------------------------------------\n\ndef extract_ref_datasheets(text: str) -> dict[str, str]:\n \"\"\"Extract {reference: datasheet_url} from placed symbols in a schematic.\"\"\"\n result = {}\n\n # Skip lib_symbols section\n lib_match = re.search(r'\\(lib_symbols\\b', text)\n search_start = 0\n if lib_match:\n lib_end = find_matching_paren(text, lib_match.start())\n search_start = lib_end + 1\n\n # Find placed symbols\n pattern = re.compile(r'\\(symbol\\s*\\n?\\s*\\(lib_id\\s+')\n for match in pattern.finditer(text, search_start):\n sym_start = match.start()\n sym_end = find_matching_paren(text, sym_start)\n block = text[sym_start:sym_end + 1]\n\n ref_match = re.search(\n r'\\(property\\s+\"Reference\"\\s+\"((?:[^\"\\\\]|\\\\.)*)\"', block\n )\n if not ref_match:\n continue\n ref = ref_match.group(1)\n if ref.startswith(\"#\"):\n continue\n\n ds_match = re.search(\n r'\\(property\\s+\"Datasheet\"\\s+\"((?:[^\"\\\\]|\\\\.)*)\"', block\n )\n ds = ds_match.group(1) if ds_match else \"\"\n result[ref] = ds\n\n return result\n\n\n# ---------------------------------------------------------------------------\n# Index loading\n# ---------------------------------------------------------------------------\n\ndef build_ref_url_map(index: dict) -> dict[str, dict]:\n \"\"\"Build {reference: {url, mpn, source, verification}} from index.json.\n\n Only includes parts with status=ok and a valid datasheet_url.\n Skips parts flagged as wrong datasheets by the verification step.\n \"\"\"\n ref_map = {}\n for part_key, entry in index.get(\"parts\", {}).items():\n if entry.get(\"status\") != \"ok\":\n continue\n url = entry.get(\"datasheet_url\", \"\").strip()\n if not url:\n continue\n # Don't propagate URLs that verification flagged as wrong\n if entry.get(\"verification\") == \"wrong\":\n continue\n for ref in entry.get(\"references\", []):\n ref_map[ref] = {\n \"url\": url,\n \"mpn\": part_key,\n \"source\": entry.get(\"source\", \"\"),\n \"verification\": entry.get(\"verification\", \"\"),\n }\n return ref_map\n\n\n# ---------------------------------------------------------------------------\n# Main sync logic\n# ---------------------------------------------------------------------------\n\ndef sync_datasheet_urls(\n schematic_path: str,\n datasheets_dir: str | None = None,\n recursive: bool = False,\n overwrite: bool = False,\n dry_run: bool = False,\n backup: bool = False,\n) -> dict:\n \"\"\"Sync datasheet URLs from index.json into schematic Datasheet properties.\n\n Returns summary dict with counts and mismatch details.\n \"\"\"\n schematic_path = Path(schematic_path).resolve()\n if not schematic_path.exists():\n print(f\"Error: {schematic_path} not found\", file=sys.stderr)\n return {\"error\": \"schematic not found\"}\n\n # Find datasheets directory\n if datasheets_dir:\n ds_dir = Path(datasheets_dir).resolve()\n else:\n ds_dir = schematic_path.parent / \"datasheets\"\n if not ds_dir.exists():\n print(f\"Error: datasheets directory not found at {ds_dir}\", file=sys.stderr)\n print(\" Run a datasheet sync first (DigiKey, LCSC, or element14).\", file=sys.stderr)\n return {\"error\": \"no datasheets directory\"}\n\n index_path = ds_dir / \"manifest.json\"\n if not index_path.exists():\n index_path = ds_dir / \"index.json\"\n if not index_path.exists():\n print(f\"Error: {ds_dir / 'manifest.json'} not found\", file=sys.stderr)\n print(\" Run a datasheet sync first to generate the manifest.\", file=sys.stderr)\n return {\"error\": \"no manifest\"}\n\n with open(index_path, \"r\") as f:\n index = json.load(f)\n\n # Build ref→url mapping from manifest\n ref_url_map = build_ref_url_map(index)\n if not ref_url_map:\n print(\"No datasheet URLs available in manifest (no parts with status=ok).\",\n file=sys.stderr)\n return {\"error\": \"no urls in manifest\"}\n\n # Collect schematic files\n sch_files = collect_schematic_files(schematic_path, recursive)\n print(f\"Processing {len(sch_files)} schematic file(s)...\", file=sys.stderr)\n\n # Track results\n total_filled = 0\n total_skipped = 0\n total_already_correct = 0\n total_mismatched = 0\n total_overwritten = 0\n mismatches = []\n fills = []\n files_modified = 0\n\n for sch_file in sch_files:\n text = sch_file.read_text(encoding=\"utf-8\")\n current = extract_ref_datasheets(text)\n\n updates = {}\n for ref, current_ds in current.items():\n if ref not in ref_url_map:\n total_skipped += 1\n continue\n\n info = ref_url_map[ref]\n new_url = info[\"url\"]\n\n if is_empty_datasheet(current_ds):\n # Fill in the missing URL\n updates[ref] = {\"Datasheet\": new_url}\n fills.append({\n \"reference\": ref,\n \"mpn\": info[\"mpn\"],\n \"url\": new_url,\n \"file\": sch_file.name,\n })\n total_filled += 1\n elif urls_match(current_ds, new_url):\n total_already_correct += 1\n else:\n # Mismatch — current URL differs from index URL\n mismatches.append({\n \"reference\": ref,\n \"mpn\": info[\"mpn\"],\n \"current\": current_ds,\n \"index\": new_url,\n \"source\": info[\"source\"],\n \"file\": sch_file.name,\n })\n total_mismatched += 1\n if overwrite:\n updates[ref] = {\"Datasheet\": new_url}\n total_overwritten += 1\n\n if not updates:\n continue\n\n if dry_run:\n for ref, props in sorted(updates.items()):\n info = ref_url_map[ref]\n action = \"overwrite\" if ref in [m[\"reference\"] for m in mismatches] else \"fill\"\n print(f\" [{sch_file.name}] {ref} ({info['mpn']}): \"\n f\"would {action} Datasheet\", file=sys.stderr)\n else:\n modified_text, change_log = apply_updates(text, updates)\n\n # Backup if requested\n if backup:\n from datetime import datetime\n import shutil\n timestamp = datetime.now().strftime(\"%Y%m%d_%H%M%S\")\n backup_path = sch_file.with_suffix(f\".{timestamp}.bak\")\n shutil.copy2(sch_file, backup_path)\n print(f\" Backup: {backup_path}\", file=sys.stderr)\n\n sch_file.write_text(modified_text, encoding=\"utf-8\")\n files_modified += 1\n\n # Report fills\n if fills:\n label = \"Would fill\" if dry_run else \"Filled\"\n print(f\"\\n{label} {len(fills)} empty Datasheet field(s):\", file=sys.stderr)\n for f in fills:\n print(f\" {f['reference']} ({f['mpn']}): {f['url'][:80]}\",\n file=sys.stderr)\n\n # Report mismatches\n if mismatches:\n print(f\"\\nMismatched datasheet URLs ({len(mismatches)}):\", file=sys.stderr)\n for m in mismatches:\n if overwrite:\n action = \"OVERWRITTEN\" if not dry_run else \"would overwrite\"\n else:\n action = \"kept existing (use --overwrite to replace)\"\n print(f\" {m['reference']} ({m['mpn']}) [{m['file']}]:\", file=sys.stderr)\n print(f\" Schematic: {m['current']}\", file=sys.stderr)\n print(f\" Index: {m['index']} (from {m['source']})\", file=sys.stderr)\n print(f\" Action: {action}\", file=sys.stderr)\n\n # Summary\n summary = {\n \"filled\": total_filled,\n \"already_correct\": total_already_correct,\n \"mismatched\": total_mismatched,\n \"overwritten\": total_overwritten,\n \"skipped_no_index_entry\": total_skipped,\n \"files_modified\": files_modified if not dry_run else 0,\n \"mismatches\": mismatches,\n }\n\n if dry_run:\n changes = total_filled + total_overwritten\n print(f\"\\nDry run: {changes} change(s) would be made.\", file=sys.stderr)\n else:\n changes = total_filled + total_overwritten\n if changes:\n print(f\"\\nDone: {changes} Datasheet properties updated across \"\n f\"{files_modified} file(s).\", file=sys.stderr)\n else:\n print(\"\\nNo changes needed.\", file=sys.stderr)\n\n if total_already_correct:\n print(f\"Already correct: {total_already_correct}\", file=sys.stderr)\n\n # Lock file warning (same as edit_properties.py)\n if not dry_run and files_modified:\n for sch_file in sch_files:\n lock_path = sch_file.parent / f\"{sch_file.name}.lck\"\n if lock_path.exists():\n print(\n f\"\\nWARNING: KiCad lock file detected for {sch_file.name}.\\n\"\n f\"Close and reopen the schematic (File > Open Recent) to see changes.\\n\"\n f\"Don't save from KiCad first — it will overwrite these changes.\",\n file=sys.stderr,\n )\n break # One warning is enough\n\n return summary\n\n\n# ---------------------------------------------------------------------------\n# CLI\n# ---------------------------------------------------------------------------\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Sync datasheet URLs from index.json into KiCad schematic Datasheet properties\",\n )\n parser.add_argument(\n \"schematic\",\n help=\"Path to root .kicad_sch file\",\n )\n parser.add_argument(\n \"--datasheets\", \"-d\",\n help=\"Path to datasheets directory (default: datasheets/ next to schematic)\",\n )\n parser.add_argument(\n \"--recursive\", \"-r\", action=\"store_true\",\n help=\"Include hierarchical sub-sheets\",\n )\n parser.add_argument(\n \"--overwrite\", action=\"store_true\",\n help=\"Overwrite mismatched Datasheet URLs (default: warn only)\",\n )\n parser.add_argument(\n \"--dry-run\", action=\"store_true\",\n help=\"Show what would change without modifying files\",\n )\n parser.add_argument(\n \"--backup\", action=\"store_true\",\n help=\"Create .bak backup files before writing (default: no backup, use git)\",\n )\n parser.add_argument(\n \"--json\", action=\"store_true\",\n help=\"Output summary as JSON to stdout\",\n )\n args = parser.parse_args()\n\n result = sync_datasheet_urls(\n schematic_path=args.schematic,\n datasheets_dir=args.datasheets,\n recursive=args.recursive,\n overwrite=args.overwrite,\n dry_run=args.dry_run,\n backup=args.backup,\n )\n\n if args.json:\n json.dump(result, sys.stdout, indent=2)\n print()\n\n if \"error\" in result:\n sys.exit(1)\n if result.get(\"mismatched\", 0) > 0 and not args.overwrite:\n sys.exit(2) # Signal mismatches need attention\n sys.exit(0)\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":13934,"content_sha256":"e97f61e1ceea6c21a9bea84d3ac834d2a13d849530f6942e633176d3821abac7"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"BOM Management","type":"text"}]},{"type":"paragraph","content":[{"text":"BOM data lives in ","type":"text"},{"text":"KiCad schematic symbol properties","type":"text","marks":[{"type":"strong"}]},{"text":" as the single source of truth. This skill orchestrates the full lifecycle: analyze the schematic, search distributors, validate parts, write properties back, export tracking CSVs, and generate order files.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Related Skills","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skill","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"kicad","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Read/analyze schematics, PCB, footprints","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"digikey","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Search DigiKey, download datasheets (primary prototype source)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"mouser","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Search Mouser (secondary prototype source)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"lcsc","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Search LCSC (production/JLCPCB parts)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"element14","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Search Newark/Farnell/element14 (international)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"jlcpcb","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PCB fabrication & assembly ordering","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"pcbway","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Alternative PCB fab & assembly","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Scripts","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"\u003cskill-path>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to reference the BOM skill directory.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Analyze schematic (JSON output, recursive sub-sheets)\npython3 \u003cskill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive\n\n# Export BOM tracking CSV (creates new or merges with existing)\npython3 \u003cskill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive\n\n# Generate per-distributor order files (5 boards + 2 spares/line)\npython3 \u003cskill-path>/scripts/bom_manager.py order bom/bom.csv --boards 5 --spares 2\n\n# Quick single-distributor order (bypasses Chosen_Distributor column)\npython3 \u003cskill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey\n\n# Write properties to schematic (dry-run first, then apply)\necho '{\"R1\": {\"MPN\": \"RC0805FR-0710KL\", \"Manufacturer\": \"Yageo\"}}' \\\n | python3 \u003cskill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch --dry-run\n\n# Sync datasheet URLs from manifest.json back into schematic Datasheet properties\npython3 \u003cskill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive --dry-run","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip steps that don't apply. Common shortcuts:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Add Mouser PNs\"","type":"text","marks":[{"type":"strong"}]},{"text":" — search Mouser by MPN for each part → validate → write to schematic → update CSV","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Fill in the gaps\"","type":"text","marks":[{"type":"strong"}]},{"text":" — run analyzer with ","type":"text"},{"text":"--gaps-only","type":"text","marks":[{"type":"code_inline"}]},{"text":", address each missing field","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Update datasheet URLs\"","type":"text","marks":[{"type":"strong"}]},{"text":" — run ","type":"text"},{"text":"sync_datasheet_urls.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" to backfill empty Datasheet fields from the datasheets manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Prepare for production\"","type":"text","marks":[{"type":"strong"}]},{"text":" — ensure every part has an LCSC number, check stock, set Chosen_Distributor to LCSC","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Understand the Project","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cskill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive","type":"text"}]},{"type":"paragraph","content":[{"text":"The output tells you the project's field naming convention, which distributors are populated, what's missing, and the preferred distributor. Also look for an existing BOM tracking CSV in the project directory or ","type":"text"},{"text":"bom/","type":"text","marks":[{"type":"code_inline"}]},{"text":" folder.","type":"text"}]},{"type":"paragraph","content":[{"text":"The script covers common patterns, but some projects use internal key systems or parametric fields. See ","type":"text"},{"text":"references/part-number-conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full catalog. Read the schematic if something seems off.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Sync Datasheets","type":"text"}]},{"type":"paragraph","content":[{"text":"Do this immediately.","type":"text","marks":[{"type":"strong"}]},{"text":" Datasheets are essential context for validation and part selection. Run the preferred distributor's sync first; if some fail, try others — they share the same ","type":"text"},{"text":"datasheets/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory and skip already-downloaded parts.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cdigikey-skill-path>/scripts/sync_datasheets_digikey.py path/to/schematic.kicad_sch --recursive\npython3 \u003clcsc-skill-path>/scripts/sync_datasheets_lcsc.py path/to/schematic.kicad_sch --recursive\npython3 \u003celement14-skill-path>/scripts/sync_datasheets_element14.py path/to/schematic.kicad_sch --recursive","type":"text"}]},{"type":"paragraph","content":[{"text":"DigiKey is best (direct PDF URLs). element14 is reliable (no bot protection). LCSC works for LCSC-only parts. Mouser is a last resort (often blocks downloads).","type":"text"}]},{"type":"paragraph","content":[{"text":"Tell the user where datasheets are","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g., ","type":"text"},{"text":"hardware/\u003cproject>/datasheets/","type":"text","marks":[{"type":"code_inline"}]},{"text":"). They'll reference them often.","type":"text"}]},{"type":"paragraph","content":[{"text":"Cross-revision projects:","type":"text","marks":[{"type":"strong"}]},{"text":" Use a single shared datasheets directory at the project level rather than per-revision. The same MPN's datasheet doesn't change between revisions.","type":"text"}]},{"type":"paragraph","content":[{"text":"Re-sync after writing new MPNs (Step 5) — the scripts are idempotent. Then backfill Datasheet URLs into the schematic:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cskill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive","type":"text"}]},{"type":"paragraph","content":[{"text":"This reads ","type":"text"},{"text":"datasheets/manifest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (legacy name ","type":"text"},{"text":"index.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" still supported) and writes discovered datasheet URLs into empty schematic ","type":"text"},{"text":"Datasheet","type":"text","marks":[{"type":"code_inline"}]},{"text":" properties. Opportunistic — only fills blanks. If a schematic already has a different URL, it warns about the mismatch without overwriting (use ","type":"text"},{"text":"--overwrite","type":"text","marks":[{"type":"code_inline"}]},{"text":" to replace). Run with ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" first to preview.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Gather Part Information","type":"text"}]},{"type":"paragraph","content":[{"text":"Watch for comma-separated MPNs.","type":"text","marks":[{"type":"strong"}]},{"text":" Some symbols track multiple physical parts (e.g., battery holder + clip). Split on commas and search each MPN independently — searching the combined string matches the wrong product.","type":"text"}]},{"type":"paragraph","content":[{"text":"Search strategy based on what's available:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Has MPN → search distributors by MPN to get their PNs and stock","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Has distributor PN but no MPN → search that distributor, get MPN, then search others","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Has only Value + Footprint → search by description (e.g., \"100nF 0402 X7R 16V\")","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use the project's preferred distributor first, then alternates. Prototype: DigiKey primary, Mouser secondary. Production: LCSC.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Validate Matches","type":"text"}]},{"type":"paragraph","content":[{"text":"Don't assume existing PNs are correct","type":"text","marks":[{"type":"strong"}]},{"text":" — distributor PNs go stale (discontinued, renumbered). Verify existing PNs resolve against the API. If a PN returns 404, flag it for replacement.","type":"text"}]},{"type":"paragraph","content":[{"text":"For every match, verify:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Package","type":"text","marks":[{"type":"strong"}]},{"text":" matches the schematic footprint (see cross-reference table below)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Specs","type":"text","marks":[{"type":"strong"}]},{"text":" match (capacitance, resistance, voltage, tolerance)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Description","type":"text","marks":[{"type":"strong"}]},{"text":" makes sense (a resistor ref should get a resistor)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lifecycle","type":"text","marks":[{"type":"strong"}]},{"text":" — not obsolete or EOL","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Datasheet URL","type":"text","marks":[{"type":"strong"}]},{"text":" is a direct PDF link (not a product page)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If ambiguous, ask the user. A wrong part is worse than a missing part.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 5: Update the Schematic","type":"text"}]},{"type":"paragraph","content":[{"text":"KiCad coexistence.","type":"text","marks":[{"type":"strong"}]},{"text":" The script detects KiCad's lock file and warns but proceeds. KiCad doesn't auto-detect external changes — it keeps its in-memory copy. If KiCad is open, tell the user: ","type":"text"},{"text":"\"Close and reopen the schematic (File → Open Recent) to see the changes. Don't save from KiCad first.\"","type":"text","marks":[{"type":"em"}]}]},{"type":"paragraph","content":[{"text":"If unsaved KiCad work exists, ask them to save first (Ctrl+S), then run the script, then reopen.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"echo '{\"R1\": {\"MPN\": \"RC0805FR-0710KL\", \"Manufacturer\": \"Yageo\", \"DigiKey\": \"311-10.0KCRCT-ND\"}}' \\\n | python3 \u003cskill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch","type":"text"}]},{"type":"paragraph","content":[{"text":"Backups:","type":"text","marks":[{"type":"strong"}]},{"text":" By default, no ","type":"text"},{"text":".bak","type":"text","marks":[{"type":"code_inline"}]},{"text":" file is created (git tracks changes). Pass ","type":"text"},{"text":"--backup","type":"text","marks":[{"type":"code_inline"}]},{"text":" if the schematic is not in a git repo or has uncommitted changes the user wants to preserve.","type":"text"}]},{"type":"paragraph","content":[{"text":"Respect the project's convention.","type":"text","marks":[{"type":"strong"}]},{"text":" Write to ","type":"text"},{"text":"\"Digi-Key_PN\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" if that's what exists, not ","type":"text"},{"text":"\"DigiKey\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". Use canonical names only for new projects.","type":"text"}]},{"type":"paragraph","content":[{"text":"Always write Manufacturer alongside MPN","type":"text","marks":[{"type":"strong"}]},{"text":" — every API returns it, it's free data.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 6: Update the BOM Tracking CSV","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"python3 \u003cskill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive","type":"text"}]},{"type":"paragraph","content":[{"text":"CSV columns are dynamic — only distributors the project uses get columns. Base columns: Reference, Qty, Value, Footprint, MPN, Manufacturer. Each active distributor gets a PN column + stock column. Tail columns: Chosen_Distributor, Datasheet, Validated, DNP, Notes.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Notes","type":"text","marks":[{"type":"strong"}]},{"text":" column is seeded from schematic ","type":"text"},{"text":"BOM Comments","type":"text","marks":[{"type":"code_inline"}]},{"text":" properties (or aliases like ","type":"text"},{"text":"Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Remarks","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Ordering Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.) on first export. On re-export, user edits in the CSV take priority — existing Notes values are preserved and schematic-sourced comments won't overwrite them.","type":"text"}]},{"type":"paragraph","content":[{"text":"Merge behavior:","type":"text","marks":[{"type":"strong"}]},{"text":" Re-exporting preserves user-managed columns (stock, Chosen_Distributor, Validated, Notes) while updating schematic-derived columns.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 7: Check Stock","type":"text"}]},{"type":"paragraph","content":[{"text":"For each part with a distributor PN, query current stock via the corresponding distributor skill. Update stock columns in the CSV. Stock data goes stale — note the date and re-check before ordering.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the chosen distributor is out of stock, flag it and suggest the alternate.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 8: Set Chosen Distributor","type":"text"}]},{"type":"paragraph","content":[{"text":"Factors: stock availability, price at order qty, minimum order/multiples, lead time, shipping consolidation (fewer distributors = fewer shipments).","type":"text"}]},{"type":"paragraph","content":[{"text":"For prototypes, consolidate to 1-2 distributors (DigiKey + Mouser). For production, LCSC/JLCPCB is cheapest.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 9: Re-Sync Datasheets & URLs","type":"text"}]},{"type":"paragraph","content":[{"text":"Re-run Step 2 (download + URL backfill) to pick up parts added in Steps 3-5. Fast — already-downloaded files are skipped.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 10: Validate Datasheets Against Design","type":"text"}]},{"type":"paragraph","content":[{"text":"Read downloaded datasheets and verify parts are functionally correct for the circuit. This catches wrong-part-number errors that Step 4 might miss.","type":"text"}]},{"type":"paragraph","content":[{"text":"What to check by type:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Passives","type":"text","marks":[{"type":"strong"}]},{"text":" — voltage rating vs rail voltage, temperature coefficient, power dissipation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Regulators","type":"text","marks":[{"type":"strong"}]},{"text":" — Vin range, Vout, max current, quiescent current","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCUs/ICs","type":"text","marks":[{"type":"strong"}]},{"text":" — supply voltage, I/O levels, peripherals, pinout","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Connectors","type":"text","marks":[{"type":"strong"}]},{"text":" — pin count, pitch, current/voltage rating","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MOSFETs","type":"text","marks":[{"type":"strong"}]},{"text":" — Vds, Rds(on), gate threshold, thermal dissipation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Diodes","type":"text","marks":[{"type":"strong"}]},{"text":" — Vf, Vr, current rating, recovery time","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For large BOMs (50+ parts), focus on power components, critical signal paths, and anything the user flagged. Commodity passives usually don't need deep review.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 11: Generate Order Files","type":"text"}]},{"type":"paragraph","content":[{"text":"Ask how many boards","type":"text","marks":[{"type":"strong"}]},{"text":" if not already known — this sets the ","type":"text"},{"text":"--boards","type":"text","marks":[{"type":"code_inline"}]},{"text":" multiplier.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pre-flight:","type":"text","marks":[{"type":"strong"}]},{"text":" verify no gaps, CSV is current, Chosen_Distributor is set (or use ","type":"text"},{"text":"--distributor","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag), stock is fresh.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Using Chosen_Distributor column, 5 boards + 2 spares\npython3 \u003cskill-path>/scripts/bom_manager.py order bom/bom.csv -o bom/orders/ --boards 5 --spares 2\n\n# Or quick single-distributor order\npython3 \u003cskill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey","type":"text"}]},{"type":"paragraph","content":[{"text":"--boards","type":"text","marks":[{"type":"code_inline"}]},{"text":" multiplies all quantities. ","type":"text"},{"text":"--spares","type":"text","marks":[{"type":"code_inline"}]},{"text":" adds a flat extra per line after multiplication. ","type":"text"},{"text":"--distributor","type":"text","marks":[{"type":"code_inline"}]},{"text":" bypasses Chosen_Distributor — generates an order for all parts with that distributor's PN.","type":"text"}]},{"type":"paragraph","content":[{"text":"Comma-separated PNs (accessories) are auto-split into separate order lines. DNP parts excluded. The script produces one file per distributor in the correct upload format (see ","type":"text"},{"text":"references/ordering-and-fabrication.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for format details).","type":"text"}]},{"type":"paragraph","content":[{"text":"Present the order summary and let the user review/edit before ordering.","type":"text"}]},{"type":"paragraph","content":[{"text":"Cost estimate:","type":"text","marks":[{"type":"strong"}]},{"text":" After generating order files, query pricing from distributor APIs at the order quantity and present a total per distributor. See ","type":"text"},{"text":"references/ordering-and-fabrication.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the cost summary template.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"BOM Corner Cases & Per-Component Notes","type":"text"}]},{"type":"paragraph","content":[{"text":"Real projects have BOM quirks that don't fit neatly into standard fields. These are the things that get lost between design and ordering — a connector that's only for prototyping, a cable shared between two boards, a part that needs to be ordered from a specific vendor lot. ","type":"text"},{"text":"Actively look for these","type":"text","marks":[{"type":"strong"}]},{"text":" during BOM analysis; don't wait for the user to mention them.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"BOM Comments Field","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"BOM Comments","type":"text","marks":[{"type":"code_inline"}]},{"text":" symbol property (canonical name) captures per-component freeform notes. It flows into the ","type":"text"},{"text":"Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":" column in the exported CSV. The script recognizes many aliases: ","type":"text"},{"text":"BOM Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Ordering Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Assembly Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Notes","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Remarks","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Comment","type":"text","marks":[{"type":"code_inline"}]},{"text":", and underscore/space variants.","type":"text"}]},{"type":"paragraph","content":[{"text":"When to suggest adding BOM Comments:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component is prototype-only (DNP in production, or vice versa)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component has ordering constraints (minimum order qty, long lead time, specific vendor lot)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component is shared with another board (ribbon cables, mating connectors, shared harnesses)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component has assembly notes (orientation matters, hand-solder only, apply after reflow)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component has substitution rules (acceptable alternates, pin-compatible swaps)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Component has conditional population (different value for different product variants/SKUs)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example values:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"\"Proto only — DNP in production\"\n\"Shares ribbon cable with power board — don't double-order\"\n\"Must be Murata GRM series, no substitution (validated for EMI)\"\n\"Hand-solder after reflow — temperature sensitive\"\n\"Order 10% extra — fragile QFN rework difficult\"\n\"Use 10K for rev A, 4.7K for rev B\"\n\"Mating connector: Molex 39-01-2040 on cable side\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Where Else to Look for BOM Quirks","type":"text"}]},{"type":"paragraph","content":[{"text":"The schematic symbol property is the best place for per-component notes, but projects scatter this information everywhere. Check all of these:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Schematic text annotations","type":"text","marks":[{"type":"strong"}]},{"text":" — free text placed on the schematic sheet. The ","type":"text"},{"text":"kicad","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill's analyzer extracts these as ","type":"text"},{"text":"text_annotations","type":"text","marks":[{"type":"code_inline"}]},{"text":". Look for notes near components about ordering, assembly, or variants.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Title block comments","type":"text","marks":[{"type":"strong"}]},{"text":" — the title block has numbered comment fields. Sometimes used for board-level BOM notes (\"All passives 0402 unless marked\", \"Order from DigiKey for proto\").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project README / docs","type":"text","marks":[{"type":"strong"}]},{"text":" — look for ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"bom/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", or any text file mentioning parts, ordering, or assembly. These often contain the highest-level BOM decisions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Existing BOM CSV Notes column","type":"text","marks":[{"type":"strong"}]},{"text":" — if a ","type":"text"},{"text":"bom.csv","type":"text","marks":[{"type":"code_inline"}]},{"text":" already exists, read the Notes column. The user may have added notes there that aren't in the schematic.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Project-level config","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":".kicad-happy.json","type":"text","marks":[{"type":"code_inline"}]},{"text":") — ","type":"text"},{"text":"preferred_suppliers","type":"text","marks":[{"type":"code_inline"}]},{"text":" sets sourcing priority, ","type":"text"},{"text":"bom","type":"text","marks":[{"type":"code_inline"}]},{"text":" section sets field naming and grouping conventions. See ","type":"text"},{"text":"skills/kicad/references/config-reference.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the full schema.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Schematic symbol Description field","type":"text","marks":[{"type":"strong"}]},{"text":" — sometimes used for assembly notes rather than part description (e.g., \"100nF bypass - place close to U3 pin 4\").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"KiCad custom fields with non-standard names","type":"text","marks":[{"type":"strong"}]},{"text":" — fields like ","type":"text"},{"text":"Assembly","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Order","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Variant","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Config","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"SKU","type":"text","marks":[{"type":"code_inline"}]},{"text":" may contain BOM-relevant info. The analyzer flags these as ","type":"text"},{"text":"unrecognized_fields","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DNP with context","type":"text","marks":[{"type":"strong"}]},{"text":" — a DNP component may need a note about ","type":"text"},{"text":"why","type":"text","marks":[{"type":"em"}]},{"text":" it's DNP and ","type":"text"},{"text":"when","type":"text","marks":[{"type":"em"}]},{"text":" to populate it. KiCad's DNP flag is boolean — the reason belongs in BOM Comments.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Multi-Board / System-Level BOM Concerns","type":"text"}]},{"type":"paragraph","content":[{"text":"When a project has multiple boards (e.g., main board + daughter board, or sender + receiver):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shared cables/connectors","type":"text","marks":[{"type":"strong"}]},{"text":" — document on both boards which connector mates with which, and note \"don't double-order\" on cables shared between boards","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shared power supplies","type":"text","marks":[{"type":"strong"}]},{"text":" — if boards share a PSU, document which board's BOM includes it","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Common parts across boards","type":"text","marks":[{"type":"strong"}]},{"text":" — when ordering, consolidate quantities across boards. Note in each board's BOM which parts are shared","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Board-specific variants","type":"text","marks":[{"type":"strong"}]},{"text":" — if the same PCB is used with different stuffing options (e.g., different resistor values for different output voltages), use BOM Comments to document the variant rules","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Non-BOM Items","type":"text"}]},{"type":"paragraph","content":[{"text":"Some project-specific items aren't on the schematic but need ordering alongside the BOM. Commonly forgotten:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mating connectors & cables","type":"text","marks":[{"type":"strong"}]},{"text":" — if the schematic has a connector, the other half needs ordering too (board-to-board, ribbon cables, wire harnesses)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stencil","type":"text","marks":[{"type":"strong"}]},{"text":" — order a framed stencil with the PCBs (~$7 from JLCPCB/PCBWay)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Programming/debug adapter","type":"text","marks":[{"type":"strong"}]},{"text":" — Tag-Connect cable, SWD ribbon, specific USB cable for the board's debug connector","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Antenna cables","type":"text","marks":[{"type":"strong"}]},{"text":" — U.FL to SMA pigtails if the board has an RF connector","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mounting hardware","type":"text","marks":[{"type":"strong"}]},{"text":" — standoffs, screws, nuts specific to the enclosure","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Thermal management","type":"text","marks":[{"type":"strong"}]},{"text":" — heat sinks, thermal pads for specific components","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Track these as rows in the BOM CSV with ","type":"text"},{"text":"Reference","type":"text","marks":[{"type":"code_inline"}]},{"text":" = ","type":"text"},{"text":"--","type":"text","marks":[{"type":"code_inline"}]},{"text":" and a Note, or in a separate ","type":"text"},{"text":"bom/non-bom-items.csv","type":"text","marks":[{"type":"code_inline"}]},{"text":". Mention them separately in cost estimates.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Presenting BOM Comments","type":"text"}]},{"type":"paragraph","content":[{"text":"When generating reports or order summaries, ","type":"text"},{"text":"always surface BOM comments prominently","type":"text","marks":[{"type":"strong"}]},{"text":" — they're the designer's voice about exceptions and gotchas. Don't bury them. In the order summary, list any component with a BOM comment separately after the main table so the user sees them before clicking \"order.\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Package/Footprint Cross-Reference","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Imperial","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Metric","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"KiCad Footprint","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0201","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0603","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"R_0201_0603Metric","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0402","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1005","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"R_0402_1005Metric","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0603","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1608","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"R_0603_1608Metric","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"0805","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2012","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"R_0805_2012Metric","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1206","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"3216","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"R_1206_3216Metric","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Replace ","type":"text"},{"text":"R_","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"C_","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"L_","type":"text","marks":[{"type":"code_inline"}]},{"text":" as appropriate. Prefix with ","type":"text"},{"text":"Resistor_SMD:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Capacitor_SMD:","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"BOM Diffing","type":"text"}]},{"type":"paragraph","content":[{"text":"When the schematic changes between revisions, compare the old and new BOM to identify added, removed, and changed parts. Highlight which new parts need sourcing.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Interactive BOM (ibom)","type":"text"}]},{"type":"paragraph","content":[{"text":"Generates an HTML page showing component locations on the PCB — essential for hand-assembly.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"pip install InteractiveHtmlBom\ngenerate_interactive_bom board.kicad_pcb \\\n --dest-dir bom/ --name-format \"%f_ibom_%r\" \\\n --extra-fields \"MPN,Manufacturer,DigiKey,Mouser,LCSC\" \\\n --group-fields \"Value,Footprint,MPN\" \\\n --checkboxes \"Sourced,Placed\" --dnp-field \"DNP\" --no-browser","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference Files","type":"text"}]},{"type":"paragraph","content":[{"text":"Read these when you need detailed lookup data:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/kicad-fields.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — field definitions, aliases, S-expression format, part number patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/ordering-and-fabrication.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — distributor paste formats, gerber export, CPL, cost templates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/part-number-conventions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — detailed analysis of naming patterns across 56+ real projects","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Production Readiness Checklist","type":"text"}]},{"type":"checkbox_list","attrs":{"id":null},"content":[{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"All parts have MPN and LCSC numbers (for JLCPCB) or MPN (for PCBWay)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"No obsolete or EOL parts","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Stock verified, basic vs extended parts identified","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"BOM and CPL exported in correct format","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Gerbers exported and verified","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Design rules meet manufacturer minimums (see ","type":"text"},{"text":"jlcpcb","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"pcbway","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill)","type":"text"}]}]},{"type":"checkbox_item","attrs":{"checked":false},"content":[{"type":"paragraph","content":[{"text":"Prototype fully tested","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Generated Files & Cleanup","type":"text"}]},{"type":"paragraph","content":[{"text":"The BOM and distributor skills create files in the project tree. Know what they are so you can clean up or ","type":"text"},{"text":".gitignore","type":"text","marks":[{"type":"code_inline"}]},{"text":" them.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Files created in the project directory","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File/Dir","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Created By","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Keep in git?","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"datasheets/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"DigiKey, LCSC, element14, Mouser sync scripts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Downloaded PDF datasheets","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — large binaries, re-downloadable","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"datasheets/manifest.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Datasheet sync scripts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tracks download status per MPN (legacy name: ","type":"text"},{"text":"index.json","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — regenerated by sync","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bom/bom.csv","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bom_manager.py export","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"BOM tracking spreadsheet","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes — user-curated data","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bom/orders/*.csv","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"bom_manager.py order","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Per-distributor order upload files","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — regenerated before each order","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"*.YYYYMMDD_HHMMSS.bak","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"edit_properties.py --backup","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Schematic backup before edits","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — use git instead","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"kicad","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill also creates analyzer JSON and design review markdown reports with user-chosen filenames — see its \"Generated Files\" section for tracking and cleanup guidance.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Temporary files (outside project)","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"File","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Location","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Purpose","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"digikey_token_cache.json","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"System temp dir","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OAuth token cache (9-min TTL, mode 0600)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"manifest.tmp","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"datasheets/","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Atomic write staging — renamed to ","type":"text"},{"text":"manifest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", never persists","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cleanup commands","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Remove downloaded datasheets (re-downloadable)\nrm -rf datasheets/\n\n# Remove order files (regenerate before ordering)\nrm -rf bom/orders/\n\n# Remove schematic backups\nrm -f *.bak\n\n# Remove KiCad analyzer/report files (filenames vary — check project instructions file)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Suggested .gitignore additions","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"gitignore"},"content":[{"text":"# BOM skill working files\ndatasheets/\nbom/orders/\n*.bak","type":"text"}]},{"type":"paragraph","content":[{"text":"Keep ","type":"text"},{"text":"bom/bom.csv","type":"text","marks":[{"type":"code_inline"}]},{"text":" tracked — it contains user-curated data (Chosen_Distributor, Validated, Notes) that can't be regenerated from the schematic alone.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Tips","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MPN is the universal key","type":"text","marks":[{"type":"strong"}]},{"text":" — populate it first, enables cross-referencing everything","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Schematic is source of truth","type":"text","marks":[{"type":"strong"}]},{"text":" — all BOM data in symbol properties, exported as needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DigiKey first, Mouser second","type":"text","marks":[{"type":"strong"}]},{"text":" for prototyping; LCSC for production","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CSV round-trip","type":"text","marks":[{"type":"strong"}]},{"text":" — Edit Symbol Fields > Export/Import CSV for bulk updates","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Field Name Templates","type":"text","marks":[{"type":"strong"}]},{"text":" (KiCad 9+) — pre-define MPN, Manufacturer, LCSC, DigiKey, Mouser","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"DigiKey token reuse","type":"text","marks":[{"type":"strong"}]},{"text":" — cached to temp file with 9-minute TTL; no need to re-auth per call","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Second source","type":"text","marks":[{"type":"strong"}]},{"text":" — use ","type":"text"},{"text":"AltMPN","type":"text","marks":[{"type":"code_inline"}]},{"text":" field for critical parts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Price at target qty","type":"text","marks":[{"type":"strong"}]},{"text":" — prototype pricing != production pricing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BOM Comments","type":"text","marks":[{"type":"strong"}]},{"text":" — use the ","type":"text"},{"text":"BOM Comments","type":"text","marks":[{"type":"code_inline"}]},{"text":" symbol property for ordering/assembly quirks that don't fit in standard fields. Flows into CSV Notes column. Check schematic text annotations, README, and existing CSV notes for scattered BOM info too.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"bom","author":"@skillopedia","source":{"stars":464,"repo_name":"kicad-happy","origin_url":"https://github.com/aklofas/kicad-happy/blob/HEAD/skills/bom/SKILL.md","repo_owner":"aklofas","body_sha256":"4a3e59f6d43336178d23a403e962195c06bae2e7d5b38906ef0826b203a5a367","cluster_key":"aff237bfc34445be9c0a6cbe67ec86267cceaeb48dee0f0bd800b7e6dcc3cfd9","clean_bundle":{"format":"clean-skill-bundle-v1","source":"aklofas/kicad-happy/skills/bom/SKILL.md","attachments":[{"id":"d687b965-d93f-5291-ac56-cf4f4b79456b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d687b965-d93f-5291-ac56-cf4f4b79456b/attachment.md","path":"references/kicad-fields.md","size":3308,"sha256":"277fe657a971484903220671d1a16c6e2fa19922e627797be9f4042b5a04c52b","contentType":"text/markdown; charset=utf-8"},{"id":"5711fab6-ee32-5ca0-932b-42496b2d79fe","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/5711fab6-ee32-5ca0-932b-42496b2d79fe/attachment.md","path":"references/ordering-and-fabrication.md","size":4207,"sha256":"db8cf5fc59a794465b309fea727a46b1fe591c4bc9b9f4d4e574f2dc280ee8ee","contentType":"text/markdown; charset=utf-8"},{"id":"00bbe293-8366-5d89-a6f1-de73cb9b9c00","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/00bbe293-8366-5d89-a6f1-de73cb9b9c00/attachment.md","path":"references/part-number-conventions.md","size":18940,"sha256":"df6d8ce303adbaf41a16b7c28568443fec755aea60f893ef0b0f1cf8f037e01e","contentType":"text/markdown; charset=utf-8"},{"id":"86096bee-06c1-5174-bbe4-23d371da580d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/86096bee-06c1-5174-bbe4-23d371da580d/attachment.py","path":"scripts/bom_manager.py","size":48836,"sha256":"e5a4d0da8d1c62976afd5ddfb6211d7ef841277d32df954e343f409171250a6e","contentType":"text/x-python; charset=utf-8"},{"id":"9f459023-f18e-523d-879d-e53a45668556","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9f459023-f18e-523d-879d-e53a45668556/attachment.py","path":"scripts/edit_properties.py","size":15259,"sha256":"48d9fe68f57e2faa469685e6fc7a1b48311e084fcd95955f8c5de511210ec4bc","contentType":"text/x-python; charset=utf-8"},{"id":"52ef8452-4ff4-5b5a-9d37-f955b16a1e93","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/52ef8452-4ff4-5b5a-9d37-f955b16a1e93/attachment.py","path":"scripts/kicad_sexp.py","size":2555,"sha256":"7e26a3468be23844cbddb05f92f645642cd358bb0f820713f56dd0fe694a7812","contentType":"text/x-python; charset=utf-8"},{"id":"a5032cd7-29d8-512f-b499-d0079d724b58","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a5032cd7-29d8-512f-b499-d0079d724b58/attachment.py","path":"scripts/sync_datasheet_urls.py","size":13934,"sha256":"e97f61e1ceea6c21a9bea84d3ac834d2a13d849530f6942e633176d3821abac7","contentType":"text/x-python; charset=utf-8"}],"bundle_sha256":"aad7e96a25a283e9447b4321528ef48aed12156c7afb252a49264567bf571c62","attachment_count":7,"text_attachments":7,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/bom/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"web-development","import_tag":"clean-skills-v1","description":"BOM (Bill of Materials) management for electronics projects — the primary orchestrator skill that coordinates DigiKey, Mouser, LCSC, element14, JLCPCB, PCBWay, and KiCad skills into a unified workflow. Create, update, and maintain BOMs with part numbers, costs, quantities stored as KiCad symbol properties. ALWAYS trigger this skill for any task involving component sourcing, pricing, ordering, distributor searches, BOM export, or fabrication preparation — even if the user names a specific distributor or fab house (e.g. \"search DigiKey for...\", \"generate JLCPCB BOM\", \"order from Mouser\"). This skill decides which distributor/fab skills to invoke and in what order. Also trigger on phrases like \"what parts do I need\", \"order components\", \"how much will this cost\", \"export for JLCPCB\", \"find parts for this board\", \"cost estimate\", \"compare pricing\", or \"check stock\"."}},"renderedAt":1782986917393}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.