circuit-synth/kicad-sch-api

Python library for reading and writing KiCAD schematic files
Generates valid .kicadsch files that open in KiCAD 7/8. Focus on exact format preservation and simple API design.
## Overview
Read and write KiCAD schematic files programmatically. This library parses and generates .kicadsch files with exact format preservation - output matches KiCAD's native formatting byte-for-byte.
## Core Features
Exact format preservation - Output matches KiCAD's native formatting byte-for-byte
Standalone library - No KiCAD installation required
Simple API - Object-oriented interface for components, wires, labels, and symbols
Tested compatibility - 70+ tests verify format preservation against KiCAD reference files
KiCAD library access - Read actual KiCAD symbol libraries for component validation
Connectivity analysis - Trace electrical connections through wires, labels, and hierarchy
Hierarchical design - Complete support for multi-sheet schematic projects
Component bounding boxes - Calculate precise component boundaries for layout algorithms
Wire routing - Manhattan-style orthogonal routing with basic obstacle avoidance
BOM property management - Audit, update, and transform component properties for manufacturing
MCP server - 15 tools for programmatic schematic manipulation via Model Context Protocol
## Quick Start
### Installation
bash
# Install from PyPI
pip install kicad-sch-api
# Or install from source
git clone https://github.com/circuit-synth/kicad-sch-api.git
cd kicad-sch-api
uv pip install -e .
### Basic Usage
python
import kicadschapi as ksa
# Create a new schematic
sch = ksa.createschematic("My Circuit")
# Add components with proper validation
resistor = sch.components.add(
libid="Device:R",
reference="R1",
value="10k",
position=(100.0, 100.0),
footprint="ResistorSMD:R06031608Metric"
# Add wires for connectivity
sch.wires.add(start=(100, 110), end=(150, 110))
# Pin-to-pin wiring
wireuuid = sch.addwirebetweenpins("R1", "2", "C1", "1")
# Add labels for nets
sch.addlabel("VCC", position=(125, 110))
# Save with exact format preservation
sch.save("mycircuit.kicadsch")
## ⚠️ Critical: KiCAD Coordinate System
Understanding this is CRITICAL for working with this library.
### The Two Coordinate Systems
KiCAD uses two different Y-axis conventions:
1. Symbol Space (library definitions): Normal Y-axis (+Y is UP, like math)
2. Schematic Space (placed components): Inverted Y-axis (+Y is DOWN, like graphics)
### The Transformation
When placing a symbol on a schematic, Y coordinates are negated:
python
# Symbol library (normal Y, +Y up):
Pin 1: (0, +3.81) # 3.81mm UPWARD in symbol
Pin 2: (0, -3.81) # 3.81mm DOWNWARD in symbol
# Component placed at (100, 100) in schematic (inverted Y, +Y down):
# Y is NEGATED during transformation:
Pin 1: (100, 100 + (-3.81)) = (100, 96.52) # LOWER Y = visually HIGHER
Pin 2: (100, 100 + (+3.81)) = (100, 103.81) # HIGHER Y = visually LOWER
### Visual Interpretation
In schematic space (inverted Y-axis):
Lower Y values = visually HIGHER on screen (top)
Higher Y values = visually LOWER on screen (bottom)
X-axis is normal (increases to the right)
### Grid Alignment
ALL positions MUST be grid-aligned:
Default grid: 1.27mm (50 mil)