by barrett-land
Add any catalog component (resistor, capacitor, inductor, IC, connector, diode) to a user's Altium Designer library with its LCSC/JLCPCB part number attached, so JLCPCB BOM + pick-and-place exports carry it automatically. Drives Altium headlessly via the altium Adom Desktop bridge. Three paths: CREATE a library from a downloaded Altium .IntLib, APPEND a part into an existing library, or REUSE an existing symbol for a new value (clone + parametric footprint, no internet fetch). For Adom's own mac
← Commit history
Publish 1.0.0
6 files changed
+375
docs/hero.pngadded⋯ 1 unchanged line ⋯
install.shadded+5@@ -0,0 +1,5 @@+#!/bin/bash+set -euo pipefail+source "$(adompkg sh-helpers)"+# Skill install: symlink skills/altium-part-importer/ into ~/.claude/skills/altium-part-importer/+adompkg-link-skill altium-part-importer
package.jsonadded+40@@ -0,0 +1,40 @@+{+ "slug": "altium-part-importer",+ "version": "1.0.0",+ "type": "skill",+ "description": "Add any catalog component (resistor, capacitor, inductor, IC, connector, diode) to a user's Altium Designer library with its LCSC/JLCPCB part number attached, so JLCPCB BOM + pick-and-place exports carry it automatically. Drives Altium headlessly via the altium Adom Desktop bridge. Three paths: CREATE a library from a downloaded Altium .IntLib, APPEND a part into an existing library, or REUSE an existing symbol for a new value (clone + parametric footprint, no internet fetch). For Adom's own machine pins/contacts use adom-altium-library-importer instead.",+ "tags": ["skill","altium","lcsc","jlcpcb","library","footprint","symbol","component","bom"],+ "dependencies": {},+ "scripts": { "install": "./install.sh", "uninstall": "./uninstall.sh" },+ "needs_sudo": false,+ "discovery_pitch": "Add any catalog component to Altium Designer with its JLCPCB/LCSC part number attached — create a library, append to an existing one, or reuse a symbol for a new value. Headless via the altium bridge.",+ "discovery_triggers": [+ "add a part to Altium",+ "add a component to Altium",+ "add a resistor to Altium",+ "add a capacitor to Altium",+ "add an inductor to Altium",+ "add an IC to Altium",+ "add a chip to Altium",+ "add a connector to Altium",+ "import a footprint into Altium",+ "import a symbol into Altium",+ "add a part to my Altium library",+ "add the LCSC part number to Altium",+ "add a part to Altium for JLCPCB",+ "build out my Altium library",+ "add a component to Altium with its part number"+ ],+ "hero": {+ "headline": "Altium Part Importer",+ "subhead": "Add any component to Altium with its JLC/LCSC part number — create, append, or reuse. Headless.",+ "screenshot": "docs/hero.png"+ },+ "sample_prompts": [+ {"label": "Add a cap", "prompt": "add a 100nF 0402 capacitor to my Altium library with the JLC part number"},+ {"label": "Add an IC", "prompt": "add the STM32G031 to my Altium ICs library with its LCSC number"},+ {"label": "New value", "prompt": "add a 4.7k 0402 resistor by reusing my existing resistor symbol"},+ {"label": "Append", "prompt": "append this part into my existing Capacitors library"},+ {"label": "Survey", "prompt": "what Altium libraries do I already have?"}+ ]+}
skills/altium-part-importer/SKILL.mdadded+116@@ -0,0 +1,116 @@+---+name: altium-part-importer+description: Add any catalog component (resistor, capacitor, inductor, IC, connector, diode…) to a user's Altium Designer library with its LCSC/JLCPCB part number attached, so JLCPCB BOM + pick-and-place exports carry it automatically. Drives Altium headlessly via the `altium` Adom Desktop bridge (Altium has no CLI). Three paths: CREATE a library from a downloaded Altium .IntLib, APPEND a part into an existing library, or REUSE an existing symbol for a new value (clone + parametric footprint, no internet fetch). Use when the user wants to "add a part/component/resistor/capacitor/IC/chip to Altium", "import a footprint or symbol into Altium", "add a part to my Altium library with the JLC/LCSC number", or build out an Altium component library. For Adom's OWN machine pins/contacts use adom-altium-library-importer instead.+---++# altium-part-importer++Adds catalog components to a user's **Altium Designer** libraries with the **`LCSC Part #`**+parameter attached (so JLCPCB BOM/CPL round-trip with no remapping). Each part gets a+symbol, a footprint (with a 3D body), and the symbol→footprint link. Drives Altium via the+**`altium` Adom Desktop bridge** — Altium has no headless/CLI mode, so everything goes+through the bridge's DelphiScript verbs over `adom-desktop`.++> For installing **Adom's own machine-contact/pin libraries**, use the separate+> `adom-altium-library-importer` skill. THIS skill is the general "add any component" tool.++## Requirements++1. **Adom Desktop** connected (`adom-desktop ping`) + **Altium Designer open**.+2. The **`altium` bridge** installed (one time):+ ```bash+ adom-desktop bridge_install '{"manifestUrl":"https://wiki.adom.inc/download/barrett-land/adom-desktop-altium-bridge/0.0.33/altium-bridge-manifest.json"}'+ adom-desktop altium_ping '{}' # -> {"altiumInstalled": true, "version": "..."}+ ```++## FIRST: find the user's library — never blind-create++Before making any new library, **survey what the user already has**:+```bash+python import_part.py --list-libs+```+- **Libraries exist** → append into the right one, or create a new `<lib>` alongside them.+- **None found** → **ASK the user**: "Do you already have Altium libraries? Where?"+ - They point you somewhere → pass `--symdir/--fpdir`.+ - They have none → only then create one (pass `--new-library`).++`import_part.py` enforces this: it refuses to create a library in an empty location unless+`--new-library` is given. Default location is `%USERPROFILE%\Documents\Altium\Libraries\+{Symbols,Footprints}` (symbols and footprints split; the symbol→footprint link resolves by+footprint NAME across installed PcbLibs).++## The fast workflow — pick the cheapest path++Altium is GUI-only, so **speed = fewest round-trips**. In order of preference:++### A. REUSE (no fetch) — a new VALUE of a part type you already have+If the library already has, say, a resistor symbol, don't fetch — clone it and generate the+footprint parametrically. This is the fastest path (no download, no extract):+```bash+# footprint: 2 SMD pads in mils (0402 example), appended to the existing PcbLib+adom-desktop altium_build_footprint '{"footprint":"R0402","pcblib":"<...>\\Footprints\\Resistors.PcbLib","padcount":"2","pad0":"1,-20,0,23,25,0,1,rect","pad1":"1,20,0,23,25,0,2,rect"}'+adom-desktop altium_add_body '{"pcblib":"<...>\\Footprints\\Resistors.PcbLib","footprint":"R0402","bw_mil":"39","bh_mil":"20","h_mil":"16","so_mil":"1"}'+# symbol: clone an existing one (copies all pins+shapes), link to the new footprint+adom-desktop altium_clone_symbol '{"schlib":"<...>\\Symbols\\Resistors.SchLib","template":"R_10k_0603_1%","component":"R_1k_0402_1%","footprint":"R0402","designator":"R"}'+adom-desktop altium_add_component '{"schlib":"<...>\\Symbols\\Resistors.SchLib","component":"R_1k_0402_1%","lcsc":"C11702","mpn":"RC0402FR-071KL","value":"1k","package":"0402","description":"1k 1% 0.1W 0402 (RC0402FR-071KL)"}'+adom-desktop altium_set_visibility '{"schlib":"<...>\\Symbols\\Resistors.SchLib","component":"R_1k_0402_1%","visible":"Value"}'+```++### B. CREATE a new library from a real catalog part (.IntLib)+For a new part type with no symbol to reuse. Get an Altium `.IntLib` (SnapEDA "Download+Symbol and Footprint → Altium", or UltraLibrarian / manufacturer), then **one command**:+```bash+python import_part.py \+ --intlib "C:\\Users\\<you>\\Downloads\\CL05B104KO5NNNC.IntLib" \+ --lib Capacitors --name C_100nF_0402 --footprint C0402 \+ --lcsc C1525 --mpn CL05B104KO5NNNC --manufacturer Samsung --value 100nF \+ --package 0402 --designator "C?" --description "100nF X7R 0402 Ceramic Capacitor (CL05B104KO5NNNC)"+```+(creates the lib; add `--new-library` if no libraries exist yet, or `--overwrite` to replace).+Internally this is **one batched `import_part` round-trip** (extract → rename footprint →+params → rename symbol → link → save-as → install).++### C. APPEND a part into an EXISTING library+Same command **plus `--append`** — copies the part into an existing `<lib>` instead of+replacing it (cross-lib copy of the symbol + footprint):+```bash+python import_part.py --append --intlib "...\\STM32xx.IntLib" --lib ICs \+ --name STM32G031F8 --footprint TSSOP20 --lcsc C2040921 --mpn STM32G031F8P6 --designator "U?" ...+```++## Conventions (applied to every part)++| What | Value |+|---|---|+| JLC BOM key | parameter **`LCSC Part #`** = `Cxxxxx` (exact name → round-trips into the JLC BOM) |+| Identity params | `Manufacturer Part Number`, `Manufacturer`, `Value`, `Package` |+| Description | human text **with the MPN in it** |+| Schematic display | **only `Value`** visible (`altium_set_visibility`) |+| Designator | `R?`/`C?`/`U?`/… |++## `altium` bridge — verb reference++`altium_ping`/`altium_detect`; `altium_extract_intlib`; `altium_import_part` (batched create);+`altium_copy_sch_component` + `altium_copy_footprint` (append into existing lib);+`altium_build_footprint` (pads + STEP 3D) + `altium_add_body` (extruded 3D);+`altium_clone_symbol` (reuse a symbol for a new value); `altium_add_component` (LCSC + params);+`altium_set_visibility`; `altium_rename_component`/`altium_rename_footprint`;+`altium_install_library`/`altium_cleanup_libs`; `altium_close_doc`/`altium_read_params`/+`altium_list_symbols`/`altium_read_symbol`.++## Gotchas (hard-won — read these)++- **The bridge is single-threaded.** Fire **one** bridge call at a time. A slow save often+ reports `"Request timed out"` **but the work persisted** — never blindly retry; let the+ bridge drain (poll `altium_ping`) and **verify by read-back** (`altium_read_params` /+ `altium_list_symbols`). Firing several calls at once stacks slow saves and wedges the+ bridge; if it wedges, kill the bridge's python (port 8801) so it respawns and clear+ `C:\Users\Public\AdomAltium\{request.txt,response.json}`. `import_part.py` already paces+ + verifies for you.+- **Survey + ask before creating a library** (see above). No blind library creation.+- **Build bridge args with proper JSON** (the importer uses `json.dumps`) — bash string+ interpolation mangles Windows backslashes into "invalid escape".+- **Append footprint name collisions**: if the target PcbLib already has a footprint of the+ same name, Altium auto-dedups (`C0402_1`) which can mismatch the symbol link — for a new+ *value* of an existing package, prefer path A (reuse the existing footprint).+- **Symbol + footprint libraries must be registered together** (link resolves by footprint name).
skills/altium-part-importer/import_part.pyadded+210@@ -0,0 +1,210 @@+#!/usr/bin/env python3+"""import_part.py — add a catalog component (with its LCSC/JLCPCB part number) to a+user's Altium library, the fast way, via the `altium` Adom Desktop bridge.++THREE add paths (all drive the bridge; Altium has no headless mode, so speed = FEWER+round-trips):++ CREATE — make a new <lib>.SchLib/.PcbLib from a downloaded Altium .IntLib+ (one batched `import_part` round-trip: extract -> rename fp -> params ->+ rename symbol -> link -> install).+ APPEND — add the part into an EXISTING <lib> (cross-lib copy: copy_footprint ++ copy_sch_component), so a library accumulates parts instead of being+ replaced.+ (reuse) — for a NEW VALUE of an existing part type, prefer cloning the symbol you+ already have + generating the footprint parametrically — see SKILL.md+ (no .IntLib / no internet fetch needed).++LIBRARY-DISCOVERY RULE: before CREATING a brand-new library in an empty location, this+tool refuses unless --new-library is passed — so the agent first surveys existing libs+(`--list-libs`) and ASKS the user whether they already have libraries (and where),+creating new only on confirmation. Never blind-creates.++Usage:+ python import_part.py --list-libs+ python import_part.py --intlib "...\\X.IntLib" --lib Capacitors --name C_100nF_0402 \+ --footprint C0402 --lcsc C1525 --mpn ... --value 100nF --package 0402 \+ --designator "C?" --description "..." # CREATE (needs --new-library if no libs exist)+ ... same, plus --append # APPEND into existing Capacitors+"""+import argparse+import json+import ntpath+import subprocess+import sys+import time++LIB_SUBPATH = r"Documents\Altium\Libraries"+++def ad(verb, args=None):+ """Call an adom-desktop verb; unwrap {success,output}. Build args with json.dumps,+ never bash interpolation (bash mangles Windows backslashes)."""+ p = subprocess.run(["adom-desktop", verb, json.dumps(args or {})],+ capture_output=True, text=True)+ try:+ d = json.loads(p.stdout)+ except ValueError:+ return {"ok": False, "error": "non-json: " + (p.stdout or p.stderr)[:200]}+ if d.get("success") and isinstance(d.get("output"), str):+ try:+ return json.loads(d["output"])+ except ValueError:+ return d+ return d+++def win_userprofile():+ r = ad("shell_execute", {"command": "echo %USERPROFILE%"})+ for line in (r.get("stdout") or r.get("output") or "").splitlines():+ line = line.strip()+ if len(line) > 3 and line[1] == ":":+ return line+ return r"C:\Users\Public"+++def desk_listdir(folder, ext):+ r = ad("shell_execute", {"command": 'dir /b "%s\\*%s"' % (folder, ext)})+ out = (r.get("stdout") or r.get("output") or "")+ return [l.strip() for l in out.splitlines() if l.strip().lower().endswith(ext.lower())]+++def desk_exists(path):+ r = ad("shell_execute", {"command": 'if exist "%s" (echo YES) else (echo NO)' % path})+ return "YES" in (r.get("stdout") or r.get("output") or "")+++def is_transient(r):+ e = ((r or {}).get("error") or "").lower()+ return ("did not respond" in e) or ("failed to spawn" in e) or ("timed out" in e)+++def settle(label):+ """The bridge is single-threaded; a slow save can report a timeout while the work+ persisted. Wait for the bridge to drain so we don't stack calls."""+ print(" %s: timed out at relay (save usually persisted) — letting the bridge drain…" % label)+ for _ in range(10):+ time.sleep(6)+ if ad("altium_ping", {}).get("version"):+ return+++def main():+ ap = argparse.ArgumentParser(description="Add a catalog component to an Altium library (+LCSC).")+ ap.add_argument("--list-libs", action="store_true", help="list existing libraries in the default location and exit")+ ap.add_argument("--intlib", help="path to the downloaded Altium .IntLib on the desktop")+ ap.add_argument("--lib", help="target library base name (-> <lib>.SchLib/.PcbLib)")+ ap.add_argument("--name", help="friendly component name, e.g. C_100nF_0402")+ ap.add_argument("--footprint", help="friendly footprint name, e.g. C0402")+ ap.add_argument("--lcsc", help="LCSC part number, e.g. C1525")+ ap.add_argument("--mpn"); ap.add_argument("--manufacturer"); ap.add_argument("--value")+ ap.add_argument("--description"); ap.add_argument("--package")+ ap.add_argument("--designator", default="U?")+ ap.add_argument("--append", action="store_true", help="append into an EXISTING <lib> (don't create/replace)")+ ap.add_argument("--overwrite", action="store_true", help="replace <lib> if it exists (CREATE mode)")+ ap.add_argument("--new-library", action="store_true", help="confirm creating a new library when none exist yet")+ ap.add_argument("--symdir"); ap.add_argument("--fpdir")+ ap.add_argument("--visible", default="Value", help="schematic-visible params (default: Value)")+ a = ap.parse_args()++ if not ad("altium_ping", {}).get("version"):+ sys.exit("altium bridge not responding — Altium open + desktop connected? "+ "Install: adom-desktop bridge_install '{\"manifestUrl\":\"https://wiki.adom.inc/download/barrett-land/adom-desktop-altium-bridge/0.0.33/altium-bridge-manifest.json\"}'")++ base = ntpath.join(win_userprofile(), LIB_SUBPATH)+ symdir = a.symdir or ntpath.join(base, "Symbols")+ fpdir = a.fpdir or ntpath.join(base, "Footprints")+ existing = desk_listdir(symdir, ".SchLib")++ if a.list_libs:+ print("Symbols dir: %s" % symdir)+ for s in existing:+ print(" " + s + " -> " + str(ad("altium_list_symbols",+ {"schlib": ntpath.join(symdir, s)}).get("components")))+ if not existing:+ print(" (no .SchLib libraries found here)")+ return++ for req in ("intlib", "lib", "name", "footprint", "lcsc"):+ if not getattr(a, req):+ sys.exit("missing --%s" % req)++ tgt_sch = ntpath.join(symdir, a.lib + ".SchLib")+ tgt_pcb = ntpath.join(fpdir, a.lib + ".PcbLib")+ lib_exists = desk_exists(tgt_sch)++ # ---- library-discovery guardrail (don't blind-create) ----+ if not a.append and not lib_exists and not existing and not a.new_library:+ sys.exit("No Altium libraries found in %s.\n"+ " - If you ALREADY have libraries elsewhere, re-run with --symdir/--fpdir pointing there.\n"+ " - If you do NOT have any yet, confirm with --new-library to create '%s'." % (symdir, a.lib))+ if a.append and not lib_exists:+ sys.exit("--append given but '%s' doesn't exist at %s. Drop --append to create it." % (a.lib, tgt_sch))+ if not a.append and lib_exists and not a.overwrite:+ sys.exit("'%s' already exists. Use --append to add this part into it, or --overwrite to replace it." % a.lib)++ # ---- extract the IntLib (shared by create+append) ----+ print("1) extract_intlib")+ intdir = ntpath.dirname(a.intlib)+ extdir = ntpath.join(intdir, ntpath.splitext(ntpath.basename(a.intlib))[0])+ schs = pcbs = []+ for attempt in range(3):+ ad("altium_extract_intlib", {"intlib": a.intlib, "timeout": 150})+ time.sleep(1.5)+ schs = desk_listdir(extdir, ".SchLib"); pcbs = desk_listdir(extdir, ".PcbLib")+ if schs and pcbs:+ break+ print(" sources not on disk yet (%d/3) — retrying…" % (attempt + 1)); time.sleep(3)+ if not schs or not pcbs:+ sys.exit("could not find extracted sources in %s" % extdir)+ src_sch = ntpath.join(extdir, schs[0]); src_pcb = ntpath.join(extdir, pcbs[0])++ params = {"schlib": tgt_sch, "component": a.name, "lcsc": a.lcsc, "mpn": a.mpn,+ "manufacturer": a.manufacturer, "value": a.value, "description": a.description,+ "package": a.package}++ if a.append:+ print("2) APPEND into %s" % a.lib)+ if a.overwrite:+ ad("altium_close_doc", {"path": tgt_sch}); ad("altium_close_doc", {"path": tgt_pcb})+ r = ad("altium_copy_footprint", {"src": src_pcb, "dst": tgt_pcb, "newname": a.footprint, "timeout": 150})+ if is_transient(r): settle("copy_footprint")+ r = ad("altium_copy_sch_component", {"src": src_sch, "dst": tgt_sch, "newname": a.name,+ "footprint": a.footprint, "designator": a.designator, "timeout": 150})+ if is_transient(r): settle("copy_sch_component")+ print("3) attach LCSC + identity params")+ r = ad("altium_add_component", dict(params, timeout=120))+ if is_transient(r): settle("add_component")+ else:+ print("2) CREATE %s (batched single round-trip)" % a.lib)+ r = ad("altium_import_part", {+ "src_sch": src_sch, "src_pcb": src_pcb, "tgt_sch": tgt_sch, "tgt_pcb": tgt_pcb,+ "name": a.name, "footprint": a.footprint, "designator": a.designator,+ "lcsc": a.lcsc, "mpn": a.mpn, "manufacturer": a.manufacturer, "value": a.value,+ "description": a.description, "package": a.package, "timeout": 180})+ if is_transient(r): settle("import_part")++ print("4) value-only display + register")+ r = ad("altium_set_visibility", {"schlib": tgt_sch, "component": a.name, "visible": a.visible})+ if is_transient(r): settle("set_visibility")+ for lib in (tgt_pcb, tgt_sch):+ ad("altium_install_library", {"path": lib}); time.sleep(1)++ print("5) verify")+ comps = ad("altium_list_symbols", {"schlib": tgt_sch}).get("components") or []+ rp = ad("altium_read_params", {"schlib": tgt_sch, "component": a.name})+ p = rp.get("params", {}) if rp.get("ok") else {}+ ok = (a.name in comps) and (p.get("LCSC Part #") == a.lcsc)+ print(" %s.SchLib components: %s" % (a.lib, comps))+ for k in ("LCSC Part #", "Value", "Description"):+ if k in p:+ print(" %-14s = %s" % (k, p[k]))+ print("\n%s '%s' %s %s (footprint %s, LCSC %s)"+ % ("DONE." if ok else "CHECK:", a.name, "appended to" if a.append else "created in",+ a.lib, a.footprint, a.lcsc))+ if not ok:+ sys.exit("verification failed — inspect with altium_read_params")+++if __name__ == "__main__":+ main()
uninstall.shadded+4@@ -0,0 +1,4 @@+#!/bin/bash+set -euo pipefail+rm -rf "$HOME/.claude/skills/altium-part-importer"+echo "[altium-part-importer] skill removed."