enginehall 2.0.0__py3-none-any.whl

pcba/rules/kicad_common.py

@@ -0,0 +1,167 @@
+"""Shared reading of a KiCad design for the KiCad rules: part classes, rails, locations.
+
+Classification is by reference prefix first (R, C, L, FB, D, Q, U, J, TP ...), then by library
+symbol: the prefix is what a designer controls and checks, the symbol name varies by library.
+Rail voltages come from `pcba-requirements.toml` when declared, otherwise from the net name
+(`+3V3`); a finding that rests on a name-derived voltage says so and is marked heuristic.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pcba.model.design import Component, Design, Net, Schematic, SchLabel, SchPin
+from pcba.model.finding import Detector, Evidence, Location
+from pcba.model.pinmap import Project
+from pcba.requirements import Rail, Requirements, is_ground
+
+_PREFIX = re.compile(r"^#?([A-Za-z]+)")
+
+
+def design(project: Project) -> Design | None:
+    return project.design
+
+
+def schematic(project: Project) -> Schematic | None:
+    return project.design.schematic if project.design else None
+
+
+def requirements(project: Project) -> Requirements:
+    return project.design.requirements if project.design and project.design.requirements else Requirements()
+
+
+def prefix(ref: str) -> str:
+    match = _PREFIX.match(ref or "")
+    return match.group(1).upper() if match else ""
+
+
+def pin_numbers(component: Component) -> set[str]:
+    return {p.number for p in component.pins}
+
+
+def classify(component: Component) -> str:
+    """power | net_tie | test_point | capacitor | resistor | inductor | ferrite | fuse | jumper |
+    diode | connector | transistor | crystal | mechanical | ic | other."""
+    if component.power or component.ref.startswith("#"):
+        return "power"
+    lib = component.lib_id.upper()
+    name = lib.split(":")[-1]
+    first = prefix(component.ref)
+    if "NETTIE" in lib or first == "NT":
+        return "net_tie"
+    if "TESTPOINT" in lib or first == "TP":
+        return "test_point"
+    if first == "FB" or "FERRITE" in lib:
+        return "ferrite"
+    if first in ("JP", "SJ") or "JUMPER" in lib or "SOLDERJUMPER" in lib:
+        return "jumper"
+    by_prefix = {"C": "capacitor", "R": "resistor", "L": "inductor", "F": "fuse", "D": "diode", "LED": "diode",
+                 "J": "connector", "P": "connector", "CN": "connector", "X": "connector", "CON": "connector",
+                 "Q": "transistor", "T": "transistor", "Y": "crystal", "MH": "mechanical", "H": "mechanical",
+                 "U": "ic", "IC": "ic"}
+    if first in by_prefix:
+        return by_prefix[first]
+    if re.match(r"^(C|CP|C_.*|CP_.*|C_POLARIZED.*)$", name):
+        return "capacitor"
+    if re.match(r"^(R|R_.*)$", name):
+        return "resistor"
+    if lib.startswith("CONNECTOR"):
+        return "connector"
+    if sum(p.type == "power_in" for p in component.pins) and len(pin_numbers(component)) > 2:
+        return "ic"
+    return "other"
+
+
+def parts(project: Project, *kinds: str) -> list[Component]:
+    sch = schematic(project)
+    if sch is None:
+        return []
+    return [c for c in sch.components.values() if not c.power and (not kinds or classify(c) in kinds)]
+
+
+def is_ground_net(net: Net | None) -> bool:
+    return bool(net and (is_ground(net.label) or is_ground(net.name)))
+
+
+def rail(project: Project, net: Net | None) -> Rail | None:
+    if net is None:
+        return None
+    return requirements(project).rail(net.name, net.label)
+
+
+def is_supply_rail(project: Project, net: Net | None) -> bool:
+    """A named, non-ground supply: a power-symbol net, a declared rail, a voltage name, or a net
+    driven by a power output pin."""
+    if net is None or is_ground_net(net):
+        return False
+    known = rail(project, net)
+    if known is not None and known.voltage != 0:
+        return True
+    return net.power or any(p.type == "power_out" for p in net.pins if not p.ref.startswith("#"))
+
+
+def other_nets(sch: Schematic, component: Component, number: str) -> list[Net]:
+    """The nets on the other pins of a part (for a two-pin part: the far side)."""
+    out = []
+    for pin in component.pins:
+        if pin.number != number:
+            net = sch.net_of(component.ref, pin.number)
+            if net is not None and net not in out:
+                out.append(net)
+    return out
+
+
+def net_display(net: Net) -> str:
+    return net.label or net.name
+
+
+def sheet_of(sheet_path: str) -> str | None:
+    return None if sheet_path in ("/", "") else sheet_path
+
+
+def at_component(project: Project, component: Component, pin: str | None = None, key: str | None = None) -> Location:
+    return Location(artifact=project.relative(component.sheet_file), sheet=sheet_of(component.sheet_path),
+                    component=component.ref, pin=pin, line=component.line or None, key=key)
+
+
+def at_pin(project: Project, pin: SchPin, key: str | None = None) -> Location:
+    return Location(artifact=project.relative(pin.sheet_file), sheet=sheet_of(pin.sheet_path),
+                    component=pin.ref, pin=pin.number, line=pin.line or None, key=key)
+
+
+def at_label(project: Project, label: SchLabel, key: str | None = None) -> Location:
+    return Location(artifact=project.relative(label.sheet_file), sheet=sheet_of(label.sheet_path),
+                    line=label.line or None, key=key)
+
+
+def at_net(project: Project, net: Net, key: str | None = None) -> Location:
+    """A net is shown where its first part pin is, or its first label."""
+    if net.parts:
+        return at_pin(project, net.parts[0], key=key or net_display(net))
+    if net.labels:
+        return at_label(project, net.labels[0], key=key or net_display(net))
+    sch = schematic(project)
+    return Location(artifact=project.relative(sch.root_file) if sch else ".", key=key or net_display(net))
+
+
+def rail_evidence(project: Project, net: Net, known: Rail) -> Evidence:
+    sch = schematic(project)
+    if known.source == "requirements":
+        req = requirements(project)
+        source = project.relative(req.path) if req.path else "pcba-requirements.toml"
+        span = f" ({known.low:g} to {known.high:g} V)" if known.low != known.high else ""
+        return Evidence(kind="rail_voltage", value=f"rail {known.name} = {known.voltage:g} V{span}", source=source)
+    return Evidence(kind="rail_voltage",
+                    value=f"net {net_display(net)!r} read as {known.voltage:g} V from its name",
+                    source=project.relative(sch.root_file) if sch else None)
+
+
+def detector_for(*rails: Rail | None) -> tuple[Detector, float]:
+    """Deterministic when every voltage was declared; heuristic when one came from a net name."""
+    if any(r is not None and r.source != "requirements" for r in rails):
+        return Detector.HEURISTIC, 0.9
+    return Detector.DETERMINISTIC, 1.0
+
+
+def pin_label(pin: SchPin) -> str:
+    return f"{pin.ref}.{pin.number}" + (f" ({pin.name})" if pin.name else "")