enginehall 2.0.0__py3-none-any.whl

pcba/parsers/kicad/kicad_cli.py

@@ -0,0 +1,190 @@
+"""Run KiCad's own checks through `kicad-cli`, when it is installed.
+
+`kicad-cli` is optional. Without it, ERC, DRC and the netlist cross-check are reported as not
+checked, never as passed. With it, the review runs:
+
+- `sch erc --format json --severity-all`: KiCad's electrical rules check,
+- `pcb drc --format json --severity-all --schematic-parity`: KiCad's design rules check plus
+  the schematic-to-board parity check,
+- `sch export netlist --format kicadsexpr`: KiCad's netlist, compared with the engine's own
+  connectivity so that a disagreement shows up as a finding instead of a silent wrong answer.
+
+kicad-cli writes `<project>.kicad_prl` (local settings) next to the project file it opens. A
+review must not change the project, so kicad-cli never sees the project folder itself: it runs on
+a temporary mirror in which the KiCad files (`.kicad_pro`, `.kicad_prl`, `.kicad_sch`, `.kicad_pcb`,
+`.kicad_dru`, the library tables) are copies and every other entry is a link, so project-relative
+libraries and models still resolve. Libraries referenced outside the project folder may not, which
+shows up as KiCad's library-configuration messages, reported as information.
+
+The `PCBA_KICAD_CLI` environment variable names the executable, or switches the tool off with
+`off` (the test suite does that, so its exact counts do not depend on the machine).
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from pcba.parsers.kicad.sexpr import SexprError, load
+
+ENVIRONMENT = "PCBA_KICAD_CLI"
+TIMEOUT_S = 300
+_OFF = {"off", "0", "none", "no", "false", ""}
+
+
+def candidates() -> list[str]:
+    """Where KiCad installs its command-line tool on each OS."""
+    home = Path.home()
+    out = [
+        "/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli",
+        str(home / "Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"),
+        "/usr/bin/kicad-cli",
+        "/usr/local/bin/kicad-cli",
+    ]
+    if sys.platform == "win32":
+        for base in (os.environ.get("ProgramFiles", r"C:\Program Files"), os.environ.get("LOCALAPPDATA", "")):
+            if base:
+                out += sorted(glob.glob(os.path.join(base, "KiCad", "*", "bin", "kicad-cli.exe")), reverse=True)
+                out += sorted(glob.glob(os.path.join(base, "Programs", "KiCad", "*", "bin", "kicad-cli.exe")),
+                              reverse=True)
+    return out
+
+
+def find() -> tuple[Path | None, str]:
+    """(executable, how it was found or why not)."""
+    configured = os.environ.get(ENVIRONMENT)
+    if configured is not None:
+        if configured.strip().lower() in _OFF:
+            return None, f"switched off by {ENVIRONMENT}"
+        path = Path(configured).expanduser()
+        if path.is_file():
+            return path, f"{ENVIRONMENT}"
+        return None, f"{ENVIRONMENT} names {configured}, which does not exist"
+    found = shutil.which("kicad-cli")
+    if found:
+        return Path(found), "PATH"
+    for candidate in candidates():
+        if Path(candidate).is_file():
+            return Path(candidate), "default install location"
+    return None, "kicad-cli not found (install KiCad, or set PCBA_KICAD_CLI to its path)"
+
+
+def _run(arguments: list[str], cwd: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(arguments, cwd=cwd, capture_output=True, text=True, timeout=TIMEOUT_S,
+                          errors="replace", check=False)
+
+
+def version(cli: Path) -> str | None:
+    try:
+        done = _run([str(cli), "version"], Path(tempfile.gettempdir()))
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    text = done.stdout.strip().splitlines()
+    return text[-1] if text else None
+
+
+def _report(cli: Path, arguments: list[str], suffix: str) -> dict:
+    """Run one kicad-cli report into a temporary file; {"ran": bool, "reason"|"report"}."""
+    with tempfile.TemporaryDirectory(prefix="pcba-kicad-") as tmp:
+        out = Path(tmp) / f"report{suffix}"
+        try:
+            done = _run([str(cli), *arguments, "-o", str(out)], Path(tmp))
+        except subprocess.TimeoutExpired:
+            return {"ran": False, "reason": f"kicad-cli timed out after {TIMEOUT_S} s"}
+        except OSError as exc:
+            return {"ran": False, "reason": f"kicad-cli could not start: {exc}"}
+        if not out.is_file():
+            detail = (done.stderr or done.stdout).strip().splitlines()
+            useful = [line for line in detail if "Fontconfig" not in line]
+            return {"ran": False, "reason": f"kicad-cli exited {done.returncode} without a report"
+                    + (f": {useful[-1]}" if useful else "")}
+        if suffix == ".json":
+            try:
+                return {"ran": True, "report": json.loads(out.read_text(encoding="utf-8"))}
+            except (OSError, ValueError) as exc:
+                return {"ran": False, "reason": f"kicad-cli wrote an unreadable report: {exc}"}
+        try:
+            return {"ran": True, "report": netlist_nodes(out)}
+        except (OSError, SexprError) as exc:
+            return {"ran": False, "reason": f"kicad-cli wrote an unreadable netlist: {exc}"}
+
+
+def netlist_nodes(path: Path) -> dict[str, list[list[str]]]:
+    """A `kicadsexpr` netlist as {net name: [[ref, pin], ...]}."""
+    root = load(path)
+    out: dict[str, list[list[str]]] = {}
+    nets = root.child("nets")
+    for net in nets.children("net") if nets is not None else ():
+        name = net.value("name") or ""
+        out[name] = [[node.value("ref") or "", node.value("pin") or ""] for node in net.children("node")]
+    return out
+
+
+COPIED_SUFFIXES = (".kicad_pro", ".kicad_prl", ".kicad_sch", ".kicad_pcb", ".kicad_dru")
+COPIED_NAMES = ("sym-lib-table", "fp-lib-table")
+# Linked without looking inside: searching them for sheets would crawl a whole repository.
+LINKED_DIRECTORIES = frozenset({"node_modules", "build", "dist", "venv", "__pycache__"})
+
+
+def mirror(folder: Path, target: Path) -> None:
+    """Copy the KiCad files of `folder` into `target` and link everything else."""
+    for entry in sorted(folder.iterdir()):
+        destination = target / entry.name
+        if entry.is_file() and (entry.suffix in COPIED_SUFFIXES or entry.name in COPIED_NAMES):
+            shutil.copy2(entry, destination)
+        elif entry.is_dir() and entry.name not in LINKED_DIRECTORIES and not entry.name.startswith(".") \
+                and any(entry.rglob("*.kicad_sch")):
+            # Sheets in a subfolder: copy the subfolder's KiCad files the same way.
+            destination.mkdir()
+            mirror(entry, destination)
+        else:
+            try:
+                destination.symlink_to(entry.resolve(), target_is_directory=entry.is_dir())
+            except OSError:
+                continue   # no link permission (Windows): models and libraries may then be missing
+
+
+def run_all(schematic: Path | None, board: Path | None) -> dict[str, dict]:
+    """ERC, netlist and DRC for one project, each {"ran": ..., "tool": ..., ...}."""
+    cli, how = find()
+    results: dict[str, dict] = {}
+    if cli is None:
+        for name in ("erc", "netlist", "drc"):
+            results[name] = {"ran": False, "reason": how}
+        return results
+    anchor = schematic or board
+    with tempfile.TemporaryDirectory(prefix="pcba-kicad-project-") as tmp:
+        try:
+            mirror(anchor.parent, Path(tmp))
+        except OSError as exc:
+            for name in ("erc", "netlist", "drc"):
+                results[name] = {"ran": False, "reason": f"cannot mirror the project for kicad-cli: {exc}"}
+            return results
+        return _run_all(cli, how, Path(tmp) / schematic.name if schematic else None,
+                        Path(tmp) / board.relative_to(anchor.parent) if board else None)
+
+
+def _run_all(cli: Path, how: str, schematic: Path | None, board: Path | None) -> dict[str, dict]:
+    results: dict[str, dict] = {}
+    tool = {"tool": "kicad-cli", "path": str(cli), "found_by": how, "version": version(cli)}
+    if schematic is not None:
+        results["erc"] = {**tool, **_report(cli, ["sch", "erc", "--format", "json", "--severity-all",
+                                                  str(schematic)], ".json")}
+        results["netlist"] = {**tool, **_report(cli, ["sch", "export", "netlist", "--format", "kicadsexpr",
+                                                      str(schematic)], ".net")}
+    else:
+        results["erc"] = results["netlist"] = {"ran": False, "reason": "no schematic"}
+    if board is not None:
+        arguments = ["pcb", "drc", "--format", "json", "--severity-all"]
+        if schematic is not None:
+            arguments.append("--schematic-parity")
+        results["drc"] = {**tool, **_report(cli, [*arguments, str(board)], ".json")}
+    else:
+        results["drc"] = {"ran": False, "reason": "no board"}
+    return results

pcba/parsers/kicad/pinmap.py

@@ -0,0 +1,90 @@
+"""Map a KiCad schematic onto the MCU pin map the STM32 cross-domain rules read.
+
+The rules compare one MCU's pins with the `.ioc` and the firmware. For a KiCad project the pins
+come from the connectivity the reader built from wire geometry; the net name a pin carries is
+the label a designer gave its net (without the sheet path), so `/Sensors/I2C1_SDA` compares as
+`I2C1_SDA`, exactly as an Altium net label would. An unnamed net reached through one resistor
+takes the name on the far side, marked as a series-resistor inference; several names there are
+ambiguous; none leaves the pin unnamed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pcba.model.design import Component, Schematic
+from pcba.model.pinmap import Pin, Resolution, SchematicPinMap
+from pcba.parsers.kicad.schematic import KicadError
+
+
+def _part_name(component: Component, hint: str) -> str | None:
+    for candidate in (component.value, component.lib_id.split(":")[-1]):
+        if candidate.upper().startswith(hint.upper()) and len(candidate) > len(hint):
+            return candidate
+    return None
+
+
+def detect_parts(schematic: Schematic, hint: str = "STM32") -> list[tuple[str, str]]:
+    """Distinct MCU part names and the sheet each is first drawn on."""
+    found: dict[str, str] = {}
+    for component in schematic.components.values():
+        name = _part_name(component, hint)
+        if name and not component.power:
+            found.setdefault(name, component.sheet_file)
+    return sorted(found.items())
+
+
+def detect_part(schematic: Schematic, hint: str = "STM32") -> str | None:
+    parts = detect_parts(schematic, hint)
+    return parts[0][0] if parts else None
+
+
+def _is_resistor(component: Component) -> bool:
+    lib = component.lib_id.split(":")[-1]
+    return (len({p.number for p in component.pins}) == 2
+            and (re.fullmatch(r"R(_.*)?|R_Small.*|Resistor.*", lib, re.I) is not None
+                 or re.fullmatch(r"R\d+", component.ref) is not None))
+
+
+def extract(schematic: Schematic, part: str, component: str | None = None) -> SchematicPinMap:
+    family = re.match(r"^([A-Za-z]+\d*)", part or "")
+    if not family:
+        raise KicadError(f"cannot derive an MCU family from part {part!r}; pass --part")
+    hint = family.group(1)
+    candidates = [c for c in schematic.components.values()
+                  if not c.power and _part_name(c, hint) and (component is None or c.ref == component)]
+    exact = [c for c in candidates if _part_name(c, hint).upper() == part.upper()]
+    chosen = exact or candidates
+    if not chosen:
+        raise KicadError(f"no symbol of {part} in the KiCad schematic"
+                         + ("; check --schematic-component" if component else ""))
+    refs = sorted({c.ref for c in chosen})
+    if len(refs) > 1:
+        raise KicadError("several MCU instances found (" + ", ".join(refs)
+                         + "); select one with --schematic-component")
+    mcu = chosen[0]
+    pin_map = SchematicPinMap(part=part, source=schematic.root_file)
+    for pin in sorted(mcu.pins, key=lambda p: p.number):
+        net = schematic.net_of(mcu.ref, pin.number)
+        name, how = (net.label, Resolution.DIRECT) if net and net.label else (None, Resolution.NONE)
+        if net and not name:
+            reachable = []
+            for other in net.parts:
+                owner = schematic.components.get(other.ref)
+                if owner is None or other.ref == mcu.ref or not _is_resistor(owner):
+                    continue
+                for far in owner.pins:
+                    far_net = schematic.net_of(owner.ref, far.number)
+                    if far.number != other.number and far_net and far_net.label:
+                        reachable.append(far_net.label)
+            reachable = sorted(set(reachable))
+            if len(reachable) == 1:
+                name, how = reachable[0], Resolution.SERIES_R
+            elif reachable:
+                name, how = "(" + " / ".join(reachable) + ")", Resolution.AMBIGUOUS
+        connected = bool(net and (len(net.pins) > 1 or net.labels))
+        pin_map.pins[pin.number] = Pin(
+            name=pin.name or pin.number, package_pin=pin.number, net=name, resolution=how,
+            sheet=pin.sheet_file, component=mcu.ref, connected=connected,
+        )
+    return pin_map