Python API

The Zeo Python API (kipy) provides Python bindings for controlling Zeo through its IPC API. This allows you to write scripts and tools that interact with a running Zeo session.

Kipy is a fork of kicad-python, expanded to be more feature-rich with additional schematic and PCB operations.

Installation

pip install kicad-python

Requirements

  • Zeo 10.0 or higher
  • Python 3.9+
  • Zeo must be running with the API server enabled (Preferences > Plugins)

Quick Start

from kipy import KiCad

# Connect to running Zeo instance
kicad = KiCad()

# Get the open schematic
sch = kicad.get_schematic()

# Place a resistor
from kipy.geometry import Vector2
pos = Vector2.from_xy_mm(50, 50)
r1 = sch.symbols.add("Device:R", pos)

# Get the open PCB
board = kicad.get_board()

# Run DRC
errors, warnings, exclusions = board.drc.run()
print(f"DRC: {len(errors)} errors, {len(warnings)} warnings")

Architecture

The API is organized into several main modules:

ModuleDescription
kipy.KiCadMain entry point for connecting to Zeo
kipy.schematicSchematic operations (symbols, wiring, ERC)
kipy.boardPCB operations (footprints, routing, DRC)
kipy.projectProject-level settings (net classes, text variables)
kipy.geometryGeometric types (Vector2, Box2)

Connection

The API connects to Zeo via IPC socket. By default, it reads from:

  • KICAD_API_SOCKET environment variable
  • Default platform path: /tmp/kicad/api.sock (Unix) or %TEMP%\kicad\api.sock (Windows)
# Custom socket path
kicad = KiCad(socket_path="ipc:///custom/path/api.sock")

# Custom timeout (default: 2000ms)
kicad = KiCad(timeout_ms=5000)

Error Handling

from kipy.errors import ApiError, ConnectionError

try:
    kicad = KiCad()
    board = kicad.get_board()
except ConnectionError:
    print("Could not connect to Zeo. Is it running?")
except ApiError as e:
    print(f"API error: {e}")

Next Steps