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