Sync

The SyncOperations module handles synchronization between schematic and PCB.

board = kicad.get_board()
sync = board.sync

Update from Schematic

update_from_schematic()

Updates the PCB from the schematic netlist.

result = board.sync.update_from_schematic()

print(f"Added: {len(result.added)} footprints")
print(f"Removed: {len(result.removed)} footprints")
print(f"Changed: {len(result.changed)} footprints")

update_from_schematic_with_options(**options)

Updates with specific options.

result = board.sync.update_from_schematic_with_options(
    delete_extra_footprints=False,
    delete_single_pad_nets=True,
    replace_footprints=False,
    update_footprint_links=True
)

Checking Sync Status

check_sync()

Checks if the PCB is in sync with the schematic.

status = board.sync.check_sync()

if status.is_synced:
    print("PCB is up to date")
else:
    print(f"Changes pending: {len(status.changes)}")
    for change in status.changes:
        print(f"  {change.type}: {change.description}")

Update Result

The update returns a PCBUpdateResult object:

class PCBUpdateResult:
    added: List[str]        # Footprint references added
    removed: List[str]      # Footprint references removed
    changed: List[str]      # Footprint references changed
    errors: List[str]       # Any errors that occurred
    warnings: List[str]     # Any warnings

Change Types

PCBUpdateChange

class PCBUpdateChange:
    type: str           # "add", "remove", "change"
    reference: str      # Component reference
    description: str    # Human-readable description
    old_value: str      # Previous value (for changes)
    new_value: str      # New value (for changes)

Example: Update and Report

from kipy import KiCad

kicad = KiCad()
board = kicad.get_board()

# Check current sync status
status = board.sync.check_sync()

if not status.is_synced:
    print("PCB needs update from schematic")
    print(f"Pending changes: {len(status.changes)}")

    for change in status.changes:
        if change.type == "add":
            print(f"  ADD: {change.reference}")
        elif change.type == "remove":
            print(f"  REMOVE: {change.reference}")
        elif change.type == "change":
            print(f"  CHANGE: {change.reference} - {change.description}")

    # Perform update
    result = board.sync.update_from_schematic()

    print("\nUpdate complete:")
    print(f"  Added {len(result.added)} footprints")
    print(f"  Removed {len(result.removed)} footprints")
    print(f"  Changed {len(result.changed)} footprints")

    if result.errors:
        print("\nErrors:")
        for error in result.errors:
            print(f"  {error}")

    if result.warnings:
        print("\nWarnings:")
        for warning in result.warnings:
            print(f"  {warning}")
else:
    print("PCB is already in sync with schematic")

Example: Selective Update

# Check what would change
status = board.sync.check_sync()

# Filter to only additions
new_components = [c for c in status.changes if c.type == "add"]

if new_components:
    print(f"Will add {len(new_components)} new footprints")

    # Proceed with update, but keep extra footprints
    result = board.sync.update_from_schematic_with_options(
        delete_extra_footprints=False  # Keep manually placed footprints
    )

Example: Position New Footprints

from kipy.geometry import Vector2

# Update from schematic
result = board.sync.update_from_schematic()

# Position newly added footprints
if result.added:
    print(f"Positioning {len(result.added)} new footprints...")

    # Find clear area for new components
    start_x = 150
    start_y = 50
    spacing = 10

    for i, ref in enumerate(result.added):
        fp_id = board.footprints.find_by_reference(ref)
        if fp_id:
            x = start_x + (i % 5) * spacing
            y = start_y + (i // 5) * spacing
            board.footprints.move(fp_id, Vector2.from_xy_mm(x, y))
            print(f"  Placed {ref} at ({x}, {y})")

Sync Workflow

Typical sync workflow:

  1. Make changes in schematic
  2. Save schematic
  3. Check sync status in PCB
  4. Review pending changes
  5. Update PCB from schematic
  6. Position new footprints
  7. Update routing as needed
# Complete workflow
board = kicad.get_board()

# 1. Check status
status = board.sync.check_sync()

if not status.is_synced:
    # 2. Review changes
    print("Changes to apply:")
    for change in status.changes:
        print(f"  {change.type}: {change.reference}")

    # 3. Update
    result = board.sync.update_from_schematic()

    # 4. Save
    board.document.save()

    print("Sync complete")