Facere/FacereDataset
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

tools/epro2/kicad: hierarchical export + global_label + 5-Voltage power ports

Browse Source 
Three coupled changes so kicad-cli sch erc runs at the project level
(across all sheets of one schematic) instead of single-sheet:

1. (label) → (global_label (shape passive)). EPRO2 nets are
   project-global by construction (named rails span every page in the
   SCH and physically wire across PCBs); KiCad's local label is sheet-
   scoped and triggers `label_dangling` for any name not duplicated on
   the same page.

2. New root_sch_writer that groups SCH_PAGE docs by their parent SCH
   (META.schematic), emits one root .kicad_sch per group with one
   (sheet ...) entry per child, and threads the root-assigned uuid back
   into each child's (sheet_instances) so KiCad can bind them.
   --all-sch now defaults to this; --flat falls back to one-file-per-page.

3. EPRO2's "5-Voltage" placeholder COMPONENT (partId
   pid8a0e77bacb214e, 365 instances on ESP-VoCat) is the editor's power
   port. The rail name lives in the placement's `Global Net Name` ATTR,
   not in the PART. We now emit a (global_label "<rail>") at the
   placement coords whenever that attr is set (101/365 of them on
   ESP-VoCat — the rest are unconfigured drafts).

ESP-VoCat 5 hierarchical roots: 2325 → 2265 violations. Modest because
5 of 6 SCHs are single-page (no cross-sheet nets to resolve), and the
one 4-page schematic (CoreBoard) shares only a handful of names across
sheets — most net names are de-facto sheet-local. The remaining ~190
pin_not_connected are dominated by 0402-style passives whose pin tip
lies on a wire's interior, not at an endpoint; KiCad needs an explicit
(junction) at those points and we don't yet emit one. Marked as the
next follow-up in log.md.

47 → 52 unit tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Knowit
2026-04-29 00:05:47 +08:00
parent 54f0173947
commit ff5553fb06
6 changed files with 479 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files

155
tools/epro2/kicad/__main__.py
View File

@@ -3,9 +3,14 @@
Usage:
uv run python -m tools.epro2.kicad <project_dir> --doc <sch_uuid> --out <dir>
uv run python -m tools.epro2.kicad <project_dir> --all-sch --out <dir>
uv run python -m tools.epro2.kicad <project_dir> --all-sch --flat --out <dir>
The ``--all-sch`` form converts every SCH_PAGE in the project, naming each
output by its document title (or doc_uuid prefix as fallback).
By default ``--all-sch`` produces a hierarchical project: pages are grouped
by their parent SCH (``META.schematic``) and each group gets a directory
with a root ``.kicad_sch`` plus its child pages. ``kicad-cli sch erc`` on
the root then resolves cross-page nets via ``(global_label)``. Pass
``--flat`` to fall back to one file per page in a single directory (the
old behaviour, still useful when you only care about a single page).
"""
from __future__ import annotations
@@ -16,7 +21,8 @@ import sys
from pathlib import Path
from ..project_relations import ProjectRelations
from ..replay import Project, replay_project
from ..replay import Document, Project, replay_project
from .root_sch_writer import ChildSheet, new_sheet_uuid, write_root_sheet
from .sch_writer import write_sch_page
@@ -28,12 +34,27 @@ def _safe_filename(s: str) -> str:
return s or "untitled"
def _convert_one(
def _page_title(doc: Document) -> str:
return (doc.objects.get("META") or {}).get("title") or doc.doc_uuid[:12]
def _print_stats(name: str) -> None:
stats = getattr(write_sch_page, "last_stats", None)
if stats:
print(
f" {name}: wires={stats.wires} symbols={stats.symbol_placements} "
f"text={stats.text} labels={stats.labels} skipped={stats.skipped} "
f"lib_emb={stats.lib_symbols_embedded} lib_miss={stats.lib_symbols_missing}"
)
def _convert_one_flat(
proj: Project,
doc_uuid: str,
out_dir: Path,
pr: ProjectRelations | None = None,
) -> Path:
"""Standalone single-page export — no hierarchy. Useful for inspecting one page."""
if doc_uuid not in proj.documents:
candidates = [u for u in proj.documents if u.startswith(doc_uuid)]
if len(candidates) != 1:
@@ -44,21 +65,96 @@ def _convert_one(
raise SystemExit(f"doc {doc_uuid} is {doc.doc_type!r}, not SCH_PAGE")
text = write_sch_page(doc, project_relations=pr)
title = (doc.objects.get("META") or {}).get("title") or doc_uuid[:12]
out_path = out_dir / f"{_safe_filename(title)}_{doc_uuid[:8]}.kicad_sch"
out_path = out_dir / f"{_safe_filename(_page_title(doc))}_{doc_uuid[:8]}.kicad_sch"
out_path.write_text(text, encoding="utf-8")
stats = getattr(write_sch_page, "last_stats", None)
if stats:
print(
f" {out_path.name}: wires={stats.wires} symbols={stats.symbol_placements} "
f"text={stats.text} labels={stats.labels} skipped={stats.skipped} "
f"lib_emb={stats.lib_symbols_embedded} lib_miss={stats.lib_symbols_missing}"
)
_print_stats(out_path.name)
return out_path
def _group_pages_by_sch(proj: Project) -> dict[str, list[str]]:
"""Group SCH_PAGE doc uuids by their parent SCH uuid (META.schematic).
Pages without a META.schematic land in the bucket keyed by their own
uuid (treated as a single-page schematic). Deleted SCHs (``DELETE_DOC``)
are skipped — their pages are dropped silently.
"""
deleted_schs = {
u for u, d in proj.documents.items()
if d.doc_type == "SCH" and (d.objects.get("DELETE_DOC") or {}).get("isDelete")
}
out: dict[str, list[str]] = {}
for u, d in proj.documents.items():
if d.doc_type != "SCH_PAGE":
continue
meta = d.objects.get("META") or {}
sch_uuid = str(meta.get("schematic") or u)
if sch_uuid in deleted_schs:
continue
out.setdefault(sch_uuid, []).append(u)
# Sort pages within each SCH by zIndex (the editor's tab order)
for sch_uuid, pages in out.items():
pages.sort(key=lambda u: (proj.documents[u].objects.get("META") or {}).get("zIndex") or 0)
return out
def _convert_hierarchical(
proj: Project,
out_dir: Path,
pr: ProjectRelations | None,
) -> int:
"""Emit one root + N children per SCH group. Returns root count."""
groups = _group_pages_by_sch(proj)
if not groups:
print("no SCH_PAGE docs in this project", file=sys.stderr)
return 0
root_count = 0
for sch_uuid, page_uuids in groups.items():
sch_doc = proj.documents.get(sch_uuid)
sch_title = (
(sch_doc.objects.get("META") or {}).get("title")
if sch_doc and sch_doc.doc_type == "SCH"
else None
) or _page_title(proj.documents[page_uuids[0]])
sch_dir = out_dir / _safe_filename(sch_title)
sch_dir.mkdir(parents=True, exist_ok=True)
print(f"Schematic '{sch_title}' ({len(page_uuids)} page(s)) → {sch_dir}")
# Pre-assign each child a uuid and a filename; the child page
# writer needs the uuid to declare its hierarchy path, and the
# root needs both to emit its (sheet ...) entries.
children: list[ChildSheet] = []
for page_uuid in page_uuids:
page_doc = proj.documents[page_uuid]
title = _page_title(page_doc)
children.append(ChildSheet(
filename=f"{_safe_filename(title)}_{page_uuid[:8]}.kicad_sch",
title=title,
sheet_uuid=new_sheet_uuid(),
))
for idx, (page_uuid, child) in enumerate(zip(page_uuids, children)):
page_doc = proj.documents[page_uuid]
text = write_sch_page(
page_doc,
project_relations=pr,
sheet_path=f"/{child.sheet_uuid}",
page_num=idx + 2, # root takes page 1
)
(sch_dir / child.filename).write_text(text, encoding="utf-8")
_print_stats(child.filename)
root_text = write_root_sheet(sch_title, children, project_name=_safe_filename(sch_title))
root_path = sch_dir / f"{_safe_filename(sch_title)}.kicad_sch"
root_path.write_text(root_text, encoding="utf-8")
print(f" ROOT: {root_path}")
root_count += 1
return root_count
def main(argv: list[str] | None = None) -> int:
ap = argparse.ArgumentParser(description="EPRO2 → KiCad schematic exporter (Phase 1)")
ap = argparse.ArgumentParser(description="EPRO2 → KiCad schematic exporter (Phase 3 hierarchical)")
ap.add_argument("project_dir", type=Path)
g = ap.add_mutually_exclusive_group(required=True)
g.add_argument("--doc", help="SCH_PAGE doc uuid (or unique prefix) to convert")
@@ -69,6 +165,11 @@ def main(argv: list[str] | None = None) -> int:
action="store_true",
help="skip lib_symbols generation (Phase 1 mode — placements only, red ?)",
)
ap.add_argument(
"--flat",
action="store_true",
help="emit one flat .kicad_sch per page (no hierarchy); only with --all-sch or --doc",
)
args = ap.parse_args(argv)
proj = replay_project(args.project_dir)
@@ -76,19 +177,23 @@ def main(argv: list[str] | None = None) -> int:
pr = None if args.no_lib_symbols else ProjectRelations.build(proj)
if args.doc:
_convert_one(proj, args.doc, args.out, pr=pr)
_convert_one_flat(proj, args.doc, args.out, pr=pr)
return 0
targets = [u for u, d in proj.documents.items() if d.doc_type == "SCH_PAGE"]
if not targets:
print("no SCH_PAGE docs in this project", file=sys.stderr)
return 1
print(f"Converting {len(targets)} SCH_PAGE docs → {args.out}")
for u in targets:
try:
_convert_one(proj, u, args.out, pr=pr)
except Exception as e: # noqa: BLE001
print(f" FAIL {u[:12]}: {e}", file=sys.stderr)
if args.flat:
targets = [u for u, d in proj.documents.items() if d.doc_type == "SCH_PAGE"]
if not targets:
print("no SCH_PAGE docs in this project", file=sys.stderr)
return 1
print(f"Flat mode: converting {len(targets)} SCH_PAGE docs → {args.out}")
for u in targets:
try:
_convert_one_flat(proj, u, args.out, pr=pr)
except Exception as e: # noqa: BLE001
print(f" FAIL {u[:12]}: {e}", file=sys.stderr)
return 0
_convert_hierarchical(proj, args.out, pr=pr)
return 0

125
tools/epro2/kicad/root_sch_writer.py Normal file
View File

@@ -0,0 +1,125 @@
"""Generate a root ``.kicad_sch`` that ties multiple SCH_PAGE files into one
hierarchical project.
EPRO2 multi-page schematics live as N standalone ``SCH_PAGE`` docs all
referencing the same ``SCH`` doc through ``META.schematic``. When we exported
each page as its own ``.kicad_sch`` and ran ``kicad-cli sch erc`` against it
in isolation, every cross-sheet net showed up as ``label_dangling`` /
``pin_not_connected`` because single-sheet ERC can't see the matching
endpoint on a sibling page.
Hierarchical mode fixes that:
- Root .kicad_sch carries one ``(sheet ...)`` block per child page,
each with a uuid the root assigns and a ``Sheetfile`` pointing at the
child filename in the same directory.
- Each child .kicad_sch declares its position in the hierarchy with
``(sheet_instances (path "/<assigned_uuid>" (page "<n>")))`` so KiCad
can bind it to the root.
- With both halves wired up, ``kicad-cli sch erc <root>`` walks the whole
project, resolving global_labels across pages.
Usage:
Build a list of (filename, page_title, assigned_uuid) tuples — one per
child — *before* writing the children, then pass it here to emit the
root. The same uuid you stored in this list goes into the child writer
via its ``sheet_path="/<uuid>"`` argument.
"""
from __future__ import annotations
import uuid as _uuid
from dataclasses import dataclass
from .sexpr import Sym, to_sexpr
KICAD_SCH_VERSION = 20231120
KICAD_GENERATOR = "facere-epro2"
@dataclass
class ChildSheet:
"""One child entry in a root sheet.
``filename`` is relative to the root .kicad_sch's directory.
``sheet_uuid`` is the uuid the root assigns to this child; the child's
own (sheet_instances) must echo it back as ``"/<sheet_uuid>"``.
"""
filename: str
title: str
sheet_uuid: str
def new_sheet_uuid() -> str:
return str(_uuid.uuid4())
def _font(size: float = 1.27) -> list:
return [Sym("effects"), [Sym("font"), [Sym("size"), size, size]],
[Sym("justify"), Sym("left"), Sym("bottom")]]
def _file_font(size: float = 1.27) -> list:
return [Sym("effects"), [Sym("font"), [Sym("size"), size, size]],
[Sym("justify"), Sym("left"), Sym("top")]]
def write_root_sheet(
title: str,
children: list[ChildSheet],
*,
project_name: str = "facere",
grid_origin_mm: tuple[float, float] = (38.1, 38.1),
box_size_mm: tuple[float, float] = (50.8, 25.4),
box_pitch_mm: tuple[float, float] = (63.5, 38.1),
columns: int = 3,
) -> str:
"""Render a root ``.kicad_sch`` listing ``children`` as ``(sheet ...)`` blocks.
The boxes are laid out on a simple ``columns``-wide grid so they don't
overlap on the canvas; visual layout is irrelevant to ERC but KiCad's
GUI needs non-zero positions/sizes for the sheet to be visible/editable.
"""
elements: list = []
bw, bh = box_size_mm
px, py = box_pitch_mm
ox, oy = grid_origin_mm
for idx, child in enumerate(children):
col = idx % columns
row = idx // columns
x = ox + col * px
y = oy + row * py
page_num = idx + 2 # root is page 1, children start at 2
elements.append([
Sym("sheet"),
[Sym("at"), x, y],
[Sym("size"), bw, bh],
[Sym("stroke"), [Sym("width"), 0.1524], [Sym("type"), Sym("solid")]],
[Sym("fill"), [Sym("color"), 0, 0, 0, 0.0]],
[Sym("uuid"), child.sheet_uuid],
[Sym("property"), "Sheetname", child.title,
[Sym("at"), x, y - 0.5, 0], _font()],
[Sym("property"), "Sheetfile", child.filename,
[Sym("at"), x, y + bh + 0.5, 0], _file_font()],
[Sym("instances"),
[Sym("project"), project_name,
[Sym("path"), "/", [Sym("page"), str(page_num)]]]],
])
sch: list = [
Sym("kicad_sch"),
[Sym("version"), KICAD_SCH_VERSION],
[Sym("generator"), KICAD_GENERATOR],
[Sym("uuid"), new_sheet_uuid()],
[Sym("paper"), "A4"],
[Sym("title_block"),
[Sym("title"), title],
[Sym("comment"), 1, f"hierarchical root for {len(children)} child sheet(s)"]],
[Sym("lib_symbols")],
*elements,
[Sym("sheet_instances"),
[Sym("path"), "/", [Sym("page"), "1"]]],
]
return to_sexpr(sch, pretty=True)

44
tools/epro2/kicad/sch_writer.py
View File

@@ -71,6 +71,8 @@ def write_sch_page(
title: str | None = None,
sheet_origin_mm: tuple[float, float] = (25.4, 25.4),
project_relations: ProjectRelations | None = None,
sheet_path: str = "/",
page_num: int = 1,
) -> str:
"""Render a single SCH_PAGE Document as kicad_sch text.
@@ -82,6 +84,16 @@ def write_sch_page(
hosting that PART; the body of the first matching SYMBOL is rendered via
:func:`sym_writer.write_lib_symbol`. If a partId can't be resolved, we
still emit the placement (KiCad shows a red ``?``).
``sheet_path`` and ``page_num`` describe this page's place in a
hierarchical project. For a standalone page, the defaults emit
``(sheet_instances (path "/" (page "1")))`` which KiCad reads as a
single-sheet project. When this page is included as a child of a root
schematic, pass ``sheet_path="/<assigned_child_uuid>"`` (the uuid the
root assigned to its ``(sheet ...)`` block for this child) and the
page index in the hierarchy (root=1, children=2..N). Without this the
KiCad hierarchy can't bind the child file to its root entry, and ERC
treats the child as a disconnected island.
"""
if doc.doc_type != "SCH_PAGE":
raise ValueError(f"expected SCH_PAGE doc, got {doc.doc_type!r}")
@@ -129,11 +141,19 @@ def write_sch_page(
net = wire_net_cache[wid]
if not net:
continue
# global_label, not local label: EPRO2 nets are project-wide
# (a "GND" net spans every page in the schematic and physically
# connects to GND wires on neighbour PCBs). KiCad's local (label)
# is sheet-scoped and triggers `label_dangling` whenever a name
# only appears on one sheet — exactly the case we hit on every
# cross-sheet net before. (global_label) is project-scoped and
# gets resolved by hierarchical ERC on the root sheet.
elements.append([
Sym("label"), str(net),
Sym("global_label"), str(net),
[Sym("shape"), Sym("passive")],
[Sym("at"), x1, y1, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]],
[Sym("justify"), Sym("left"), Sym("bottom")]],
[Sym("justify"), Sym("left")]],
[Sym("uuid"), _new_uuid()],
])
stats.labels += 1
@@ -178,6 +198,24 @@ def write_sch_page(
elements.append(sym_block)
stats.symbol_placements += 1
# Power-port instances: EPRO2 expresses things like VCC / GND / VBUS
# as a generic "5-Voltage" symbol whose net name is carried by the
# placement's `Global Net Name` ATTR (not by the underlying PART).
# Without a global_label at the pin tip, every such placement
# shows up as pin_not_connected even though it should anchor the
# pin to a global rail.
gnn = attrs.get("Global Net Name")
if gnn:
elements.append([
Sym("global_label"), str(gnn),
[Sym("shape"), Sym("passive")],
[Sym("at"), x, y, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]],
[Sym("justify"), Sym("left")]],
[Sym("uuid"), _new_uuid()],
])
stats.labels += 1
# 3. Text labels from TEXT objects (best-effort — only those with a non-empty value).
for oid, obj in doc.objects.items():
if obj.get("_type") != "TEXT":
@@ -219,7 +257,7 @@ def write_sch_page(
lib_symbols,
*elements,
[Sym("sheet_instances"),
[Sym("path"), "/", [Sym("page"), "1"]]],
[Sym("path"), sheet_path, [Sym("page"), str(page_num)]]],
]
# Stash stats on the function for tests / CLI to inspect.