Kicad

KiCad Open-Source ECAD AI Skill Guide (Claude)

Overview & Engine Architecture

KiCad is the premier open-source electronics design automation (EDA) suite for schematic capture, simulation, and multi-layer PCB layout. KiCad utilizes human-readable S-Expression (.kicad_sch, .kicad_pcb) file formats, features the advanced PNS Push & Shove Interactive Router, embeds the pcbnew Python API, and provides a powerful headless command-line interface (kicad-cli). Claude operates as a Principal PCB Hardware Design Engineer and Open-Source EDA Automation Specialist, specializing in kicad-cli CI/CD automated manufacturing pipelines, Pcbnew Python scripting, Custom Design Rules (.kicad_dru), and high-density BGA routing.

KiCad Architecture & Automation Stack

┌─────────────────────────────────────────────────────────────┐
│                 KiCad ECAD Suite Architecture               │
│                                                             │
│  Design Entry & Core Data Model (S-Expressions)             │
│  ├── Eeschema (Hierarchical Schematic Editor & ERC)         │
│  ├── Pcbnew (Multi-Layer Layout & PNS Push/Shove Router)    │
│  └── 3D Raytraced Ray-Caster (STEP / VRML Co-Design)        │
│                                                             │
│  Headless Automation & Scripting Layer                      │
│  ├── `kicad-cli` (Automated DRC/ERC, Gerber, Drill, STEP)   │
│  ├── `pcbnew` Native Python 3 Scripting API                 │
│  └── Custom Design Rule Language Parser (`.kicad_dru`)      │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. kicad-cli Headless CI/CD Pipelines: Author zero-touch shell scripts to run automated DRC/ERC, generate Gerber X2 files, create NC drill files, export Pick-and-Place POS files, and render 3D STEP models.
2. Pcbnew Python Scripting: Write Python 3 scripts utilizing the native pcbnew module (pcbnew.LoadBoard, board.GetTracks(), board.GetFootprints()) to automate layout modifications.
3. Custom Design Rule Formulation: Author KiCad 8/9 custom design rules (rule "BGA_Clearance") using S-expression pattern matching (condition "A.insideCourtyard('U1')").
4. Schematic & Hierarchical Netlist Triage: Troubleshoot hierarchical sheet label scope, global vs local net boundaries, and Electrical Rules Check (ERC) violations.

Production Python Automation: Headless PCB DRC & CAM Release Generator (pcbnew)

Save this script as kicad_cam_packager.py and run using KiCad's bundled Python interpreter:

"""
Automated KiCad 8/9 CAM Release & DRC Packager
Executes headless DRC, plots all Gerber layers, and generates NC Drill files.
"""

import sys
import os
import pcbnew

def generate_cam_outputs(pcb_path: str, output_dir: str):
    if not os.path.exists(pcb_path):
        print(f"Error: PCB file '{pcb_path}' not found.")
        return

    os.makedirs(output_dir, exist_ok=True)
    print(f"Loading PCB: {pcb_path}...")
    board = pcbnew.LoadBoard(pcb_path)

    # 1. Initialize Plot Controller
    pctl = pcbnew.PLOT_CONTROLLER(board)
    popt = pctl.GetPlotOptions()
    popt.SetOutputDirectory(output_dir)
    
    # Configure Standard Fabrication Plot Options
    popt.SetPlotFrameRef(False)
    popt.SetSketchPadOnFab(False)
    popt.SetPlotValue(True)
    popt.SetPlotReference(True)
    popt.SetPlotInvisibleText(False)
    popt.SetPlotViaOnMaskLayer(False)
    popt.SetUseAuxOrigin(True)
    popt.SetScale(1.0)
    popt.SetMirror(False)
    popt.SetSubtractMaskFromSilk(True)

    # 2. Plot Standard Production Gerber Layers
    plot_layers = [
        ("F_Cu", pcbnew.F_Cu, "Top Copper"),
        ("B_Cu", pcbnew.B_Cu, "Bottom Copper"),
        ("F_Mask", pcbnew.F_Mask, "Top Solder Mask"),
        ("B_Mask", pcbnew.B_Mask, "Bottom Solder Mask"),
        ("F_SilkS", pcbnew.F_SilkS, "Top Silkscreen"),
        ("B_SilkS", pcbnew.B_SilkS, "Bottom Silkscreen"),
        ("F_Paste", pcbnew.F_Paste, "Top Solder Paste"),
        ("B_Paste", pcbnew.B_Paste, "Bottom Solder Paste"),
        ("Edge_Cuts", pcbnew.Edge_Cuts, "Board Outline")
    ]

    for suffix, layer_id, desc in plot_layers:
        pctl.SetLayer(layer_id)
        pctl.OpenPlotfile(suffix, pcbnew.PLOT_FORMAT_GERBER, desc)
        pctl.PlotLayer()
        print(f"  • Plotted {desc} -> {suffix}.gbr")
    pctl.ClosePlot()

    # 3. Generate Excellon NC Drill Files
    print("Generating NC Drill and Map Files...")
    drill_writer = pcbnew.EXCELLON_WRITER(board)
    drill_writer.SetMapFileFormat(pcbnew.PLOT_FORMAT_GERBER)
    drill_writer.SetOptions(
        False, # aMirror
        True,  # aHeader
        board.GetDesignSettings().GetAuxOrigin(), # aOffset
        False  # aMerge_PTH_NPTH
    )
    drill_writer.SetFormat(True) # Metric units
    drill_writer.CreateDrillandMapFilesSet(output_dir, True, False)

    print(f"--- [CAM RELEASE PACKAGE GENERATED SUCCESSFULLY: {output_dir}] ---")

if __name__ == "__main__":
    if len(sys.argv) < 3:
        print("Usage: python kicad_cam_packager.py <board.kicad_pcb> <output_dir>")
        sys.exit(1)
    generate_cam_outputs(sys.argv[1], sys.argv[2])

Technical Troubleshooting Matrix

Command Line Syntax & kicad-cli Recipes

# 1. Run Automated DRC and Export JSON Report via kicad-cli
kicad-cli pcb drc --format json --output drc_report.json "C:\Hardware\board.kicad_pcb"

# 2. Export High-Resolution 3D STEP Enclosure Model
kicad-cli pcb export step --subst-models --output "C:\Mechanical\board.step" "C:\Hardware\board.kicad_pcb"

# 3. Export Complete Gerber Suite in a Single Command
kicad-cli pcb export gerbers -o "C:\Release\Gerbers" --no-x2 --use-drill-file-origin "C:\Hardware\board.kicad_pcb"

# 4. Generate Interactive BOM (ibom) for Assembly
generate_interactive_bom.py "C:\Hardware\board.kicad_pcb"

Essential File Locations

• Windows User Settings: %APPDATA%\kicad\8.0
• Linux User Settings: ~/.config/kicad/8.0
• macOS Preferences: ~/Library/Preferences/kicad/8.0

Agent Operational Directive

MANDATORY: For automated manufacturing CI/CD pipelines, leverage kicad-cli to execute DRC verification and export Gerber X2 and STEP packages. Always resolve ERC errors in Eeschema before pushing changes to Pcbnew.