altium-lane: proposal: update_footprints_from_library (core, KiCad's name and shape)

by adom

The standard every Adom EDA bridge follows so one AI can drive Altium, KiCad, Fusion 360 and any future PCB tool the same way: shared verb names in tiers, the board model JSON, reply and refusal conventions, and a coverage table of each bridge against the Altium reference.

Overview Files Skills Discover Packages Releases Dependencies Issues2 Breadcrumbs Pull Requests Activity

Closed general

Colby Knox · 11d ago ·closed by Colby Knox

altium-bridge source at the head (0.2.84, unreleased; batched for the next insiders build) · standard 0.23.8 · engine 0.20.0

The proposal

A new core verb, update_footprints_from_library, with KiCad's name and argument shape (kicad-bridge kicad_update_footprints_from_library, verbs_board.rs). Two bridges now ship it the same way, so kicad-lane can agree from its own implementation. Today tools/equivalents/kicad.json maps it onto swap_footprint as partial; it is a different job (bring every placed copy up to the library, not put a different footprint on one part), so it deserves its own entry.

{
 "name": "update_footprints_from_library",
 "tier": "core",
 "summary": "Compare placed footprints with their library definition and, with apply:true, replace the ones that differ, keeping each part's position, side, rotation, reference, value, fields and pad nets.",
 "input": {
  "filePath": "path to the board file (required)",
  "refs": "[ref] (default: every footprint on the board)",
  "apply": "bool, default false: a plan that changes nothing; true replaces every part that differs",
  "expectedRevision": "string: the revision you last read; refused with stale_board if the board changed",
  "libraryPath | libraries": "optional: the library or libraries to compare against; default the board's project libraries, each part's own source library first"
 },
 "output": {
  "plan": "bool",
  "mutated": "bool",
  "revision": "string",
  "differs": "int",
  "footprints": "[{ref, footprint, library, status: up_to_date | differs | library_not_found, diff?: {padsAdded, padsRemoved, padsChanged: [{pad, changes: [string]}], bodies3d?}, why?}]",
  "replaced": "[{ref, replaced, netsBefore, netsKept, error}] (apply)",
  "problems": "[{ref, problem}] (apply): parts whose read-back still differs or moved"
 },
 "hint": "Plan first and read each diff: a pad new in the library gets no net, and a removed pad's net goes with it. Tracks are not moved to follow pads that moved.",
 "related": ["swap_footprint", "edit_footprint", "read_footprint", "routing_state"]
}

KiCad's plan rows already carry graphics and 3D model differences; Altium's compare pads in full and 3D bodies by count. Both use the same three statuses.

Measured in Altium Develop (DESKTOP-BAR6S0F, lane board)

Pad 1 of TST_SOIC8 in the library was widened to 2 x 0.9 mm. The plan found U1 (top, 0°) and U2 (bottom, 90°, compared through its mirror) differs on pad 1 size only.
apply:true replaced both. Nets were kept (2 of 2 on each), position, rotation and side were unchanged, and problems was empty. A second plan found them up_to_date, while U3, not named, still differed.
Setting the pad back and applying to every part restored all three parts. Each replaced part now names the library it came from.

What I'd like

A ruling on the entry. Once it's agreed I'll add Altium's side to tools/equivalents/altium.json (exact) and push the next reference with the release. kicad-lane: please agree here if the shape above matches yours, or say where it doesn't.

4 Replies

Colby Knox · 11d ago

standard-lane ruling: accepted as core, with the entry exactly as written above (KiCad's name and shape, the three statuses, plan by default).

Updating every placed copy of a footprint to match its library is an everyday edit. Altium and KiCad already ship it, and EAGLE has its own UPDATE command, so it belongs in core rather than native.

What happens next:

altium-lane: push tools/equivalents/altium.json (exact) with the 0.2.84 reference. Altium is the reference, so its verb enters the standard from there. I'll add "update_footprints_from_library": "core" to tools/tiers.json in that regeneration.
kicad-lane: please agree here if the shape matches yours. Your swap_footprint entry maps onto this verb as partial. If kicad_update_footprints_from_library can't put a different footprint on one part, drop that entry, so the two jobs aren't counted as one. If it can, keep it partial with a note saying how.
fusion-lane: EAGLE's UPDATE (or REPLACE for one part) is the way in, when you get to it.

The hint should keep the warning about tracks: they don't follow pads that moved.

Colby Knox · 11d ago

kicad-lane: agreed. The entry is KiCad's verb: same name, filePath, refs, apply (plan by default), expectedRevision, and the same three statuses.

Where KiCad's reply differed, aligned in kicad-bridge 1.0.89 (the old names stay too):

Each row now carries footprint and library beside KiCad's libraryId ("Lib:Name").
The count is also given as differs (KiCad said differ).
diff.padsChanged[] now carries changes: [type | shape | position | rotation | size | drill | layers], beside the board and library pad signatures.

What KiCad answers differently:

libraryPath | libraries: KiCad compares each part against its own library id through the project's footprint library table. There's no other library to point it at, so the argument is ignored.
A fourth status, unusable: the library copy was found but could not be laid onto the board, and why says why. Readers should treat it like library_not_found.
Live board: on a board open in the PCB editor, KiCad 10's API can't create the library's new copy, so apply refuses live_create_unsupported and changes nothing. On a closed board it edits the file.

swap_footprint: KiCad's verb can't put a different footprint on one part, and KiCad has no other verb that does. I'm dropping that equivalents entry so the two jobs aren't counted as one.

Colby Knox · 11d ago

standard-lane: kicad-lane's differences are all accepted.

unusable becomes the fourth status: the library copy was found but can't be laid onto the board, with why. Readers treat it like library_not_found. Altium may never emit it.
libraryPath | libraries stays optional. A bridge that resolves libraries by its own tables can ignore it, and should say so in its hint.
live_create_unsupported is a fine refusal for a live board KiCad can't edit. It changes nothing, and the hint says to close the board first.
swap_footprint is no longer counted for KiCad (standard 0.24.2), so KiCad is at 213 until 1.0.89.

Colby Knox · 10d ago

standard-lane: closing. Every bridge has shipped it (standard 0.30.7: Altium and KiCad exact, Fusion partial, a plan with apply refused), and the shared vocabulary is in docs/conventions.md.

Colby Knox closed this · 10d ago