traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/design/spec.py

@@ -0,0 +1,462 @@
+"""Circuit-as-code: a YAML/JSON description of parts and their connections.
+
+Example::
+
+    name: led_indicator
+    board: {width: 30, height: 20}
+    parts:
+      - ref: J1
+        symbol: Connector_Generic:Conn_01x02
+        footprint: Connector_PinHeader_2.54mm:PinHeader_1x02_P2.54mm_Vertical
+        value: PWR
+        pins: {1: VIN, 2: GND}
+      - ref: R1
+        symbol: Device:R
+        value: 1k
+        footprint: Resistor_SMD:R_0603_1608Metric
+        pins: {1: VIN, 2: LED_A}
+      - ref: D1
+        symbol: Device:LED
+        footprint: LED_SMD:LED_0603_1608Metric
+        pins: {A: LED_A, K: GND}
+    power_nets: [VIN, GND]
+
+Pins are matched by number first, then by pin name. Connections may also be
+listed per net under ``nets: {NET: [R1.1, D1.A]}``.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+
+from traceforge.design.constraints import ConstraintError, RuleAreaSpec
+from traceforge.design.constraints import validate as _validate_constraints
+from traceforge.design.outline import (
+    CastellatedSpec,
+    FiducialSpec,
+    MountingSpec,
+    OutlineSpec,
+    PanelSpec,
+    ToolingSpec,
+    bbox_size,
+    check_outline,
+)
+
+_REF_RE = re.compile(r"^[A-Za-z]+[A-Za-z_]*\d+$")
+_NET_RE = re.compile(r"^[^\s\"(){}]+$")
+
+
+class BoardSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    width: float | None = Field(default=None, gt=0, description="Board width in mm")
+    height: float | None = Field(default=None, gt=0, description="Board height in mm")
+    layers: int = Field(default=2, description="Copper layers (2, 4, 6 or 8)")
+    thickness: float = Field(default=1.6, gt=0)
+    origin: tuple[float, float] = (100.0, 100.0)
+    margin: float = Field(default=3.0, ge=0, description="Clearance from parts to board edge")
+    corner_radius: float = Field(default=0.0, ge=0)
+    ground_plane: str | None = Field(
+        default="GND",
+        description="net joined by a bottom-layer pour when routing (null: route as tracks)",
+    )
+    mounting_holes: float | None = Field(
+        default=None, description="Drill diameter for 4 corner holes"
+    )
+
+    outline: OutlineSpec | None = Field(
+        default=None, description="non-rectangular outline, cut-outs and slots (design/outline.py)"
+    )
+    mounting: MountingSpec | None = Field(
+        default=None, description="mounting-hole pattern (board-only, not in the schematic)"
+    )
+    fiducials: FiducialSpec | None = None
+    tooling_holes: ToolingSpec | None = None
+    castellated: list[CastellatedSpec] = Field(
+        default_factory=list, description="half-cut plated holes along an edge"
+    )
+    panel: PanelSpec | None = Field(
+        default=None, description="panel of copies: tabs or V-score, rails (written as *_panel)"
+    )
+
+    @field_validator("layers")
+    @classmethod
+    def _layers(cls, value: int) -> int:
+        if value not in (2, 4, 6, 8):
+            raise ValueError("layers must be 2, 4, 6 or 8")
+        return value
+
+    @model_validator(mode="after")
+    def _outline_size(self) -> BoardSpec:
+        if self.outline is not None:
+            w, h = bbox_size(self.outline, self.width, self.height)
+            if self.outline.shape in ("round", "polygon"):
+                self.width, self.height = w, h
+            check_outline(w, h, self.outline, self.corner_radius)
+        return self
+
+
+class PartSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    ref: str
+    symbol: str = Field(description="KiCad symbol id, e.g. Device:R")
+    footprint: str | None = Field(default=None, description="KiCad footprint id")
+    value: str | None = None
+    pins: dict[str, str] = Field(default_factory=dict, description="pin number or name -> net")
+    nc: list[str] = Field(default_factory=list, description="pins intentionally left unconnected")
+    fields: dict[str, str] = Field(default_factory=dict, description="extra fields, e.g. LCSC, MPN")
+    dnp: bool = False
+    at: tuple[float, float] | None = Field(
+        default=None, description="PCB position (mm, board origin)"
+    )
+    rotation: float = Field(
+        default=0.0,
+        description="orientation as KiCad's footprint properties show it; for a bottom part it "
+        "is the orientation of the turned-over footprint (the placement file converts it)",
+    )
+    side: Literal["top", "bottom"] = Field(
+        default="top", description="board side the footprint is placed on"
+    )
+    decoupling: Literal["same", "opposite"] = Field(
+        default="same",
+        description="where this part's decoupling capacitors go: next to it, or on the "
+        "other side of the board (a capacitor's own side overrides this)",
+    )
+    group: str | None = Field(default=None, description="placement cluster name")
+    description: str | None = None
+    sheet: str | None = Field(default=None, description="schematic sheet this part is drawn on")
+
+    @field_validator("ref")
+    @classmethod
+    def _ref(cls, value: str) -> str:
+        if not _REF_RE.match(value):
+            raise ValueError(f"reference {value!r} must be letters followed by a number, e.g. R1")
+        return value
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def _value(cls, value: Any) -> Any:
+        return None if value is None else str(value)
+
+    @field_validator("fields", mode="before")
+    @classmethod
+    def _fields(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            return {str(k): str(v) for k, v in value.items()}
+        return value
+
+    @field_validator("pins", mode="before")
+    @classmethod
+    def _pins(cls, value: Any) -> Any:
+        if isinstance(value, dict):
+            return {str(k): str(v) for k, v in value.items()}
+        return value
+
+    @field_validator("nc", mode="before")
+    @classmethod
+    def _nc(cls, value: Any) -> Any:
+        if isinstance(value, list):
+            return [str(v) for v in value]
+        return value
+
+
+class RulesSpec(BaseModel):
+    """Board-wide design rules finer (or coarser) than the fab profile's defaults."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    clearance: float | None = Field(
+        default=None,
+        gt=0,
+        description="default copper clearance, mm; never below the fab's minimum "
+        "(fine-pitch QFN and BGA fan-out needs about 0.15)",
+    )
+    track_width: float | None = Field(default=None, gt=0, description="default track width, mm")
+
+
+class LengthGroupSpec(BaseModel):
+    """Nets whose routed lengths must agree (byte lanes, address buses, pairs of a lane)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="group name, e.g. DQ_LANE0")
+    nets: list[str] = Field(
+        min_length=2, description="nets of the group; a pair's two nets count as one member"
+    )
+    tolerance: float = Field(default=0.5, ge=0, description="allowed length spread, mm")
+
+
+class DiffPairSpec(BaseModel):
+    """Two nets routed as a coupled pair (constant gap, matched length)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    nets: tuple[str, str] = Field(description="positive and negative net, e.g. [USB_DP, USB_DM]")
+    impedance: float | None = Field(
+        default=None, gt=0, description="differential impedance target in ohms (USB: 90)"
+    )
+    width: float | None = Field(default=None, gt=0, description="track width, mm")
+    gap: float | None = Field(default=None, gt=0, description="edge-to-edge gap, mm")
+    tolerance: float = Field(default=0.1, ge=0, description="allowed length skew, mm")
+    drc_skew: bool = Field(
+        default=False,
+        description="also write a KiCad skew rule (needs net names KiCad pairs: X+/X-, XP/XN)",
+    )
+
+
+class DielectricSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    thickness: float = Field(gt=0, description="mm")
+    er: float = Field(default=4.4, ge=1, description="relative permittivity")
+    kind: str = Field(default="prepreg", pattern="^(core|prepreg)$")
+    material: str = "FR4"
+    loss_tangent: float = Field(default=0.02, ge=0)
+
+
+class PlaneNetSpec(BaseModel):
+    """One net of a split plane: the region it fills, or None to derive it from its pads."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    net: str
+    region: list[float] | None = Field(
+        default=None,
+        min_length=4,
+        max_length=4,
+        description="[x0, y0, x1, y1] in mm from the board's top-left corner",
+    )
+
+
+class StackupSpec(BaseModel):
+    """Layer roles, copper weights and dielectrics of a multi-layer board.
+
+    ``preset`` (jlc-2, jlc-4, jlc-6, jlc-8) gives typical JLCPCB values; anything else given here
+    overrides it. The fab's own stackup is authoritative, copy its numbers in before ordering.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    preset: str | None = Field(default=None, description="jlc-2 | jlc-4 | jlc-6 | jlc-8")
+    roles: list[str] | None = Field(
+        default=None, description="signal or plane per copper layer, top to bottom"
+    )
+    planes: dict[str, str | list[str | PlaneNetSpec]] = Field(
+        default_factory=dict,
+        description=(
+            "plane layer -> net poured on it, e.g. {In1.Cu: GND}; a list of nets splits the layer "
+            "(the first fills the board, the others take regions around their pads, or the given "
+            "region): {In2.Cu: [+3V3, +1V1]}"
+        ),
+    )
+    copper_oz: list[float] | None = Field(
+        default=None, description="copper weight per layer in ounces (1 oz = 35 um)"
+    )
+    dielectrics: list[DielectricSpec] | None = Field(
+        default=None, description="gap between each neighbouring copper pair, top to bottom"
+    )
+
+    @field_validator("roles")
+    @classmethod
+    def _roles(cls, value: list[str] | None) -> list[str] | None:
+        if value is not None and any(r not in ("signal", "plane") for r in value):
+            raise ValueError("roles must be signal or plane")
+        return value
+
+    def resolve(self, layers: int):
+        """The :class:`~traceforge.kicad.stackup.Stackup` for a board of ``layers`` layers."""
+        from dataclasses import replace
+
+        from traceforge.kicad import stackup as st
+
+        base = st.preset(self.preset or f"jlc-{layers}")
+        if base.count != layers:
+            raise ValueError(f"stackup preset {base.name} has {base.count} layers, board {layers}")
+        copper = list(base.copper)
+        if self.roles is not None:
+            if len(self.roles) != layers:
+                raise ValueError(f"stackup roles lists {len(self.roles)} layers, board {layers}")
+            copper = [replace(c, role=r) for c, r in zip(copper, self.roles)]
+        if self.copper_oz is not None:
+            if len(self.copper_oz) != layers:
+                raise ValueError(f"copper_oz lists {len(self.copper_oz)} layers, board {layers}")
+            copper = [
+                replace(c, thickness=round(oz * 0.035, 4)) for c, oz in zip(copper, self.copper_oz)
+            ]
+        gaps = list(base.dielectrics)
+        if self.dielectrics is not None:
+            if len(self.dielectrics) != layers - 1:
+                raise ValueError(
+                    f"stackup needs {layers - 1} dielectrics, got {len(self.dielectrics)}"
+                )
+            gaps = [
+                st.Dielectric(d.thickness, d.er, d.kind, d.material, d.loss_tangent)
+                for d in self.dielectrics
+            ]
+        stack = replace(base, copper=tuple(copper), dielectrics=tuple(gaps))
+        return stack.with_planes(self.planes) if self.planes else stack
+
+
+class DesignSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    description: str | None = None
+    board: BoardSpec = Field(default_factory=BoardSpec)
+    parts: list[PartSpec]
+    nets: dict[str, list[str]] = Field(default_factory=dict, description="NET: [REF.PIN, ...]")
+    power_nets: list[str] = Field(default_factory=list, description="nets that get a PWR_FLAG")
+    net_classes: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="class name -> {nets, track_width, clearance, via_diameter, via_drill, "
+        "min_track_width, min_via_diameter, min_via_drill, edge_clearance, layers}",
+    )
+    rule_areas: list[RuleAreaSpec] = Field(
+        default_factory=list,
+        description="keep-outs and rule areas: {name, rect | polygon, layers, keepout, clearance, "
+        "max_track_width}",
+    )
+    diff_pairs: list[DiffPairSpec] = Field(
+        default_factory=list,
+        description="differential pairs; nets named X+/X-, X_P/X_N or USB_DP/USB_DM are "
+        "paired automatically at 90 ohms",
+    )
+    rules: RulesSpec | None = Field(
+        default=None, description="board-wide clearance and track width (default: the fab's)"
+    )
+    length_groups: list[LengthGroupSpec] = Field(
+        default_factory=list,
+        description="length-matching groups: {name, nets, tolerance}; the router serpentines "
+        "the shorter members and reports the spread",
+    )
+    sheets: list[str] = Field(
+        default_factory=list,
+        description="schematic sheet names; splits the design (see part.sheet)",
+    )
+    rev: str | None = Field(default=None, description="revision in the schematic title block")
+    date: str | None = Field(default=None, description="date in the title block (default: today)")
+    stackup: StackupSpec | None = Field(
+        default=None,
+        description="layer roles, copper weights and dielectrics (4+ layers get the JLCPCB "
+        "preset for their layer count when omitted)",
+    )
+    fab: str = "jlcpcb"
+    kicad_version: int | str | None = Field(
+        default=None,
+        description="KiCad file format to write: 7, 8, 9, 10, or auto (the installed KiCad)",
+    )
+
+    @field_validator("name")
+    @classmethod
+    def _name(cls, value: str) -> str:
+        if not re.match(r"^[A-Za-z0-9_.-]+$", value):
+            raise ValueError("name may only contain letters, digits, '_', '-' and '.'")
+        return value
+
+    @model_validator(mode="after")
+    def _merge(self) -> DesignSpec:
+        refs = [p.ref for p in self.parts]
+        duplicates = sorted({r for r in refs if refs.count(r) > 1})
+        if duplicates:
+            raise ValueError(f"duplicate references: {duplicates}")
+        by_ref = {p.ref: p for p in self.parts}
+        for net, members in self.nets.items():
+            for member in members:
+                ref, dot, pin = str(member).partition(".")
+                if not dot or not pin:
+                    raise ValueError(f"net {net}: {member!r} must look like REF.PIN")
+                if ref not in by_ref:
+                    raise ValueError(f"net {net}: unknown part {ref!r}")
+                existing = by_ref[ref].pins.get(pin)
+                if existing and existing != net:
+                    raise ValueError(f"{ref}.{pin} is on both {existing!r} and {net!r}")
+                by_ref[ref].pins[pin] = net
+        for part in self.parts:
+            for pin, net in part.pins.items():
+                if not _NET_RE.match(net):
+                    raise ValueError(f"{part.ref}.{pin}: invalid net name {net!r}")
+        return self
+
+    @model_validator(mode="after")
+    def _stackup(self) -> DesignSpec:
+        if self.stackup is not None:
+            self.stackup.resolve(self.board.layers)  # raises on a mismatch
+        return self
+
+    @model_validator(mode="after")
+    def _constraints(self) -> DesignSpec:
+        try:
+            _validate_constraints(self)
+        except ConstraintError as exc:
+            raise ValueError(str(exc)) from exc
+        return self
+
+    def stackup_model(self):
+        """The resolved stackup; None for a plain 2-layer board without a ``stackup`` block."""
+        if self.stackup is None and self.board.layers == 2:
+            return None
+        return (self.stackup or StackupSpec()).resolve(self.board.layers)
+
+    def all_nets(self) -> dict[str, list[tuple[str, str]]]:
+        result: dict[str, list[tuple[str, str]]] = {}
+        for part in self.parts:
+            for pin, net in part.pins.items():
+                result.setdefault(net, []).append((part.ref, pin))
+        return dict(sorted(result.items()))
+
+
+class SpecError(ValueError):
+    """A design spec that cannot be read or does not validate (the message says where and why)."""
+
+
+def _validation_message(path: Path, exc: ValidationError) -> str:
+    lines = []
+    for item in exc.errors():
+        where = ".".join(str(part) for part in item.get("loc", ()))
+        msg = str(item.get("msg", "")).removeprefix("Value error, ")
+        lines.append(f"  {where}: {msg}" if where else f"  {msg}")
+    return (
+        f"{path}: invalid design spec ({len(lines)} problem{'s' if len(lines) != 1 else ''}):\n"
+        + "\n".join(lines)
+    )
+
+
+def load_spec(path: str | Path) -> DesignSpec:
+    """Read and validate a spec (.yaml/.yml/.json); raises SpecError with a readable message."""
+    import json
+
+    path = Path(path)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise SpecError(f"design spec not found: {path}") from None
+    except (OSError, UnicodeDecodeError) as exc:
+        raise SpecError(f"cannot read {path}: {exc}") from exc
+    try:
+        if path.suffix.lower() in {".yaml", ".yml"}:
+            data = yaml.safe_load(text)
+        else:
+            data = json.loads(text)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" at line {mark.line + 1}, column {mark.column + 1}" if mark else ""
+        problem = getattr(exc, "problem", None) or str(exc).splitlines()[0]
+        raise SpecError(f"{path}: not valid YAML{where}: {problem}") from None
+    except json.JSONDecodeError as exc:
+        raise SpecError(f"{path}: not valid JSON at line {exc.lineno}: {exc.msg}") from None
+    if not isinstance(data, dict):
+        raise SpecError(f"{path}: a design spec is a mapping with name, board and parts")
+    try:
+        return DesignSpec.model_validate(data)
+    except ValidationError as exc:
+        raise SpecError(_validation_message(path, exc)) from None
+
+
+def spec_schema() -> dict[str, Any]:
+    return DesignSpec.model_json_schema()