Symbols

The SymbolOperations module handles symbol placement and manipulation.

sch = kicad.get_schematic()
symbols = sch.symbols

Adding Symbols

add(lib_id, position, ...)

Places a symbol on the schematic.

from kipy.geometry import Vector2

pos = Vector2.from_xy_mm(50, 50)

# Basic placement
r1 = sch.symbols.add("Device:R", pos)

# With rotation (degrees)
r2 = sch.symbols.add("Device:R", pos, rotation=90)

# With reference designator
r3 = sch.symbols.add("Device:R", pos, reference="R10")

# With value
r4 = sch.symbols.add("Device:R", pos, value="10k")

Parameters:

  • lib_id (str): Library identifier (e.g., "Device:R", "Connector:Conn_01x04")
  • position (Vector2): Placement position
  • rotation (float): Rotation in degrees (0, 90, 180, 270)
  • mirror (bool): Mirror the symbol horizontally
  • reference (str): Reference designator override
  • value (str): Value field override
  • unit (int): Unit number for multi-unit symbols

Returns: Symbol ID (KIID)

Finding Symbols

find_by_reference(reference)

Finds a symbol by its reference designator.

symbol_id = sch.symbols.find_by_reference("R1")

get_all()

Returns all symbols on the current sheet.

symbols = sch.symbols.get_all()
for sym in symbols:
    print(f"{sym.reference}: {sym.lib_id}")

Symbol Properties

get_fields(symbol_id)

Gets all fields of a symbol.

fields = sch.symbols.get_fields(symbol_id)
for field in fields:
    print(f"{field.name}: {field.value}")

set_field(symbol_id, field_name, value)

Sets a field value.

sch.symbols.set_field(r1, "Value", "4.7k")
sch.symbols.set_field(r1, "Footprint", "Resistor_SMD:R_0603_1608Metric")

get_pins(symbol_id)

Gets all pins of a symbol.

pins = sch.symbols.get_pins(symbol_id)
for pin in pins:
    print(f"Pin {pin.number}: {pin.name} at {pin.position}")

Manipulating Symbols

move(symbol_id, position)

Moves a symbol to a new position.

new_pos = Vector2.from_xy_mm(100, 100)
sch.symbols.move(symbol_id, new_pos)

rotate(symbol_id, angle)

Rotates a symbol.

sch.symbols.rotate(symbol_id, 90)  # Rotate 90 degrees CW

mirror(symbol_id)

Mirrors a symbol horizontally.

sch.symbols.mirror(symbol_id)

duplicate(symbol_id, offset)

Duplicates a symbol.

offset = Vector2.from_xy_mm(25, 0)
new_id = sch.symbols.duplicate(symbol_id, offset)

delete(symbol_id)

Deletes a symbol.

sch.symbols.delete(symbol_id)

Example: Place Multiple Resistors

from kipy import KiCad
from kipy.geometry import Vector2

kicad = KiCad()
sch = kicad.get_schematic()

# Place a row of resistors
start_x = 50
y = 50
spacing = 25

resistors = []
for i in range(4):
    pos = Vector2.from_xy_mm(start_x + i * spacing, y)
    r = sch.symbols.add(
        "Device:R",
        pos,
        reference=f"R{i+1}",
        value="10k"
    )
    resistors.append(r)

print(f"Placed {len(resistors)} resistors")

Example: Edit Symbol Fields

# Find a symbol and update its fields
symbol_id = sch.symbols.find_by_reference("U1")

# Get current fields
fields = sch.symbols.get_fields(symbol_id)
for field in fields:
    print(f"{field.name}: {field.value}")

# Update value and footprint
sch.symbols.set_field(symbol_id, "Value", "ATmega328P")
sch.symbols.set_field(symbol_id, "Footprint", "Package_DIP:DIP-28_W7.62mm")