PCB Agent

An AI agent that turns one English sentence into a connected, ERC-clean, multi-layer KiCad PCB project — schematic, board, routing, vias, copper pours, and self-correction included.

The goal is working complex PCB designs, not manufacturer-ready boards. The agent produces designs that an engineer can open, validate, and finalize — not designs that bypass review.

---

Table of contents

• What it does
• Demo
• Verification numbers
• Install
• Quick start
• How it works
• Project layout
• Modules
• What it doesn't do yet
• License

---

What it does

• Accepts a natural-language hardware prompt
• Extracts requirements, protocols, voltages, sensors, outputs, connectivity
• Picks first-pass component stages with concrete KiCad symbol/footprint hints
• Builds a connection plan with named rails and nets
• Generates a connected KiCad schematic (.kicad_sch) with explicit no-connect markers
• Packages a project-local symbol library, footprint library, and library tables
• Plans board size, placement zones, routing priorities — auto-selects 2- or 4-layer
• Places components and maps schematic pins onto PCB pad nets
• Runs a multi-strategy router:
  • L-shape + dogleg + escape-line candidates first
  • A* maze on a 0.5 mm coarse grid as fallback
  • 3-D A* with via insertion (F.Cu ↔ B.Cu) as deeper fallback
• Stitches GND tie-in vias for floating GND pads
• Builds copper GND zones on F.Cu and B.Cu
• Runs a 3-iteration self-correction loop driven by KiCad ERC/DRC
• Produces a teacher-friendly demo summary in a single command
• Ships with a 5-prompt evaluation suite + scored MD/JSON report

---

Demo

.\.venv312\Scripts\python.exe -m pcb_agent.demo "Design an ESP32 environmental monitoring board with OLED, temperature sensor, humidity sensor, buzzer, Wi-Fi, and 12V input."

Output:

PCB Agent — Demo Run
====================
Project name: design-an-esp32-environmental-monitoring-board-with-oled-tem
Output folder: outputs\design-an-esp32-environmental-monitoring-board-with-oled-tem

What I understood from your prompt
==================================
  Controller: ESP32
  Voltages: 12V
  Sensors: Temperature sensor, Humidity sensor
  Outputs: OLED display, Buzzer
  Connectivity: Wi-Fi

Components selected (first-pass)
================================
  - U1    Main controller        ESP32-WROOM-32E
  - U2    Primary buck regulator LM2596 buck stage
  - U3    Logic regulator        AP2112K-3.3
  - U5    Temperature sensor     TMP102
  - U6    Humidity sensor        SHT31-DIS
  - U7    OLED display           SSD1306 OLED module
  - U8    Buzzer                 Active buzzer + NPN driver
  ...

Board plan
==========
  124.0 x 91.0 mm, 2 layers

KiCad health
============
  ERC violations: 0
  DRC violations: 23
  Unconnected items: 14
  Routed nets: 8
  Route segments: 48

Open outputs/<project-name>/kicad/<project-name>.kicad_pro in KiCad to view the schematic, board, and 3D render.

---

Verification numbers

Latest evaluation (outputs/evaluation_final/_evaluation_report/):

Prompt	ERC	DRC (real)	Unconnected	Routed nets	Segments	Layers
ESP32 environmental monitor	0	23	14	8	48	2
ESP32 industrial CAN relay	0	17	15	15	105	2
STM32 motor control	0	14	13	10	76	2
RP2040 LoRa/GPS telemetry	0	44	13	11	62	4
STM32 RS-485 + Ethernet gateway	0	23	19	15	110	4

• ERC: 0 violations across all 5 prompts
• Unit tests: 12/12 passing
• Prompt simulations: 5/5 passing
• Unconnected items: 74 total — down 39% from the original baseline (122 → 74)
• DRC (real electrical only): cosmetic categories (silk_over_copper, solder_mask_bridge, courtyards_overlap, starved_thermal, track_dangling, missing_courtyard, footprint, tracks_crossing, via_diameter) are classified as warnings, not errors

---

Install

Prerequisites

• Python 3.12 (3.13 also works for the runtime, but the bundled .venv312 is locked to 3.12)
• KiCad 9 or 10 with kicad-cli available
• Windows / macOS / Linux — code is OS-agnostic; commands below are PowerShell

Setup

git clone https://github.com/<your-username>/pcb-agent.git
cd pcb-agent

python -m venv .venv312
.\.venv312\Scripts\Activate.ps1
pip install -r requirements.txt

KiCad CLI is expected at D:\KiCad\bin\kicad-cli.exe by default. To use a different path, edit the KICAD_CLI constant near the top of pcb_agent/kicad_project.py.

Optional — enable LLM-assisted reasoning

The agent runs fully offline by default. To enable Gemini-based prompt refinement:

$env:GEMINI_API_KEY = "your-gemini-api-key"

OpenAI is supported as a secondary provider via OPENAI_API_KEY.

---

Quick start

Single-command demo (recommended)

.\.venv312\Scripts\python.exe -m pcb_agent.demo "<your prompt>"

Plain run

.\.venv312\Scripts\python.exe -m pcb_agent --prompt "<your prompt>"

Run all 5 reference prompts

.\.venv312\Scripts\python.exe -m pcb_agent.evaluation

Writes outputs/evaluation_runs/_evaluation_report/evaluation_report.md.

Run unit tests

.\.venv312\Scripts\python.exe -m unittest tests.test_phase1

Example prompts that work well

.\.venv312\Scripts\python.exe -m pcb_agent.demo "Design an ESP32 environmental monitoring board with OLED, temperature sensor, humidity sensor, buzzer, Wi-Fi, and 12V input."
.\.venv312\Scripts\python.exe -m pcb_agent.demo "Create an STM32 motor control board with CAN bus, relay output, debug header, 24V input, and two motor outputs."
.\.venv312\Scripts\python.exe -m pcb_agent.demo "Design an RP2040 telemetry node with LoRa, GPS, pressure sensor, current sensor, voltage monitor, OLED display, and 12V input."
.\.venv312\Scripts\python.exe -m pcb_agent.demo "Create an STM32 industrial gateway with RS-485, Ethernet, LCD display, current sensor, voltage monitor, relay output, and 24V input."

---

How it works

prompt
  │
  ▼
parser ──► requirement snapshot
  │
  ▼
spec_builder + component_catalog ──► selected components, blocks, candidates
  │
  ▼
schematic_planner + schematic_wiring ──► nets, pin assignments, no-connects
  │
  ▼
kicad_project ──► .kicad_pro / .kicad_sch / .kicad_pcb + libraries
  │
  ▼
pcb_planner + pcb_netlist + board_population ──► board, zones, pad-net map
  │
  ▼
pcb_router ──► L-shape → maze → via-aware maze → GND tie-in vias
  │
  ▼
self_correction ──► reads KiCad ERC/DRC, runs 3 iterations of repair
  │
  ▼
KiCad CLI verification ──► ERC report, DRC report, board stats, 3D render
  │
  ▼
review_loop + advanced_validator ──► confidence score, decisions, attention items
  │
  ▼
demo / kicad_handoff ──► teacher-friendly summary + full project bundle

Per-prompt output bundle (under outputs/<project-name>/):

• summary.txt, kicad_handoff.md, system_architecture.md
• schematic_wiring.md + .json, pcb_netlist.md + .json, routing_plan.md + .json
• advanced_validation.md + .json, review_packet.md
• self_correction.md + .json
• kicad/ containing the full openable KiCad project plus ERC/DRC reports and 3D-rendered preview PNG

---

Project layout

pcb-agent/
├── pcb_agent/        # 23 modules, ~8000 LOC — the agent itself
├── tests/            # unit tests (12 cases)
├── docs/             # architecture notes + mind map
├── data/             # curated electronics knowledge cards
├── outputs/          # generated KiCad projects (gitignored)
├── README.md
├── requirements.txt
└── .gitignore

---

Modules

File	Role
parser.py, spec_builder.py, component_catalog.py	Prompt parsing + component selection
schematic_planner.py, schematic_wiring.py, component_pins.py, schematic_intent.py	Schematic synthesis
kicad_project.py, kicad_bridge.py	KiCad project generation + CLI verification
pcb_planner.py, pcb_netlist.py, board_population.py	Board planning + netlist
pcb_router.py	Multi-strategy router (L-shape, single-layer maze, via-aware 3-D maze, GND tie-ins)
self_correction.py	3-iteration ERC/DRC-driven correction loop
advanced_validator.py, validator.py, review_loop.py	Validation + human review packet
evaluation.py	5-prompt simulation suite
agent.py, cli.py, demo.py	Orchestration + CLI entry points
llm_provider.py, knowledge_base.py	Optional LLM + curated knowledge integration

See docs/architecture.md for a full module-by-module description.

---

What it doesn't do yet

• Push the last 13–19 unconnected items per board to 0 (would need commercial-grade autorouting or per-prompt manual tuning)
• Run electrical simulation (SPICE)
• Generate manufacturer-ready, production-finalized boards
• Multi-sheet schematic partitioning for very dense designs

These are explicit non-goals — the agent is optimized for working complex designs that hand off to a human reviewer.

---

License

MIT. See LICENSE for details.

---

Acknowledgements

Built around KiCad's CLI for ERC, DRC, board stats, and 3D rendering. Optional LLM reasoning via Google Gemini and OpenAI.