← Commit history
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."