Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
# PCB Flow — Autonomous AI-Driven PCB Design (EasyEDA → KiCad)
[](https://github.com/NijoP/pcbflow/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](VALIDATION.md)
**Autonomous AI PCB design workflow — take a hardware project from requirements to
manufacturing-ready files, with the engineer in the loop.**
PCB Flow is an AI-assisted electronics engineering workspace for **automated PCB design**.
You bring the PCB and electronics knowledge; an AI assistant does the repetitive,
error-prone work — AI-driven **schematic generation, component placement, and routing**,
plus every design check — while **you make every engineering decision that matters.** It
works with **EasyEDA** and **KiCad** and any AI coding agent, and you never have to write
software.
> 👉 **New here? Start with the [handbook](handbook/README.md)** — a step-by-step guide
> for electronics engineers, from installing the tools to shipping a board.
---
## 1. What is this?
PCB Flow is a **workspace and a method**, not a program you run. You open it in a code
editor (VS Code), and an **AI assistant** reads the instructions in this repository and
helps you design a PCB — doing the busywork and the checking, and stopping to ask you
whenever a real engineering decision comes up.
**Why it was created:** PCB design is full of careful, repetitive, mistake-prone work —
every net wired, every pin checked, every part placed, every trace sized, every rule
verified. That work is perfect for a tireless assistant and wasteful for a skilled
engineer. PCB Flow hands it to an AI that follows a fixed set of engineering rules,
and keeps *you* as the decision-maker.
**What it solves:** drift between the spec and the board, layouts built on a wrong
schematic, boards lost because nobody saved them, and hours spent on mechanical work an
assistant could do — while never taking a safety, sizing, or ordering decision out of
your hands.
**Who it's for:** electronics engineers who know PCB design, schematics, BOMs, and
manufacturing — and who do **not** need to know programming, APIs, or automation.
## 2. Vision
**AI assists the engineer; it does not replace them.** The goal is to automate the
repetitive engineering work while keeping human judgment central. The AI is a fast,
disciplined junior engineer who has read every datasheet and never tires of checking
nets — but who always defers to you on the decisions that carry real risk. It never
sizes a power path below its limit, never signs off a design-rule check, and **never
orders a board.** As you build more boards, it gets smarter: every lesson learned on one
project is carried into the next.
## 3. High-level workflow
Twelve phases, each with a checkpoint. You never start a phase until the previous one is
confirmed correct.
```
Client requirement → Feasibility study → BOM planning → EasyEDA project →
AI-assisted schematic generation → Engineering review → Placement planning →
Automated component placement → KiCad export → AI-assisted routing →
Verification → Manufacturing
```
1. **Client requirement** — capture what the product must do.
2. **Feasibility study** — the AI checks technical feasibility, cost, power budget,
board size, and layer count with real math before any design starts.
3. **BOM planning** — build and validate the parts list (availability, cost, package,
electrical fit, second sources).
4. **EasyEDA project** — create the project, sheets, and stack-up.
5. **AI-assisted schematic generation** — the AI draws the schematic block by block,
wiring every net; you review and run Annotate.
6. **Engineering review** — the schematic is audited (shorts, floating pins, ERC, net
list match). Nothing proceeds until it's clean.
7. **Placement planning** — you define board size, shape, connectors, keep-outs, and
mounting; the AI builds a placement knowledge graph and a visual plan for approval.
8. **Automated component placement** — the AI places all parts and checks real spacing;
you approve the layout.
9. **KiCad export** — the placed board moves to KiCad (which is the routing engine) and
the import is verified faithful.
10. **AI-assisted routing** — the AI routes to IPC standards (widths, current, diff
pairs, return paths, EMI) and iterates until the design-rule check is clean.
11. **Verification** — a full review: DRC, ERC, manufacturing, silkscreen, assembly,
mechanical, BOM.
12. **Manufacturing** — the AI produces the factory files; **you place the order.**
Full detail per phase: [`workflow/`](workflow/) and the [handbook](handbook/README.md).
## 4. Repository overview
| Folder | What it's for |
|---|---|
| [`handbook/`](handbook/) | **Start here** — the step-by-step guide for engineers. |
| [`workflow/`](workflow/) | The 12 design phases, each with its checkpoint. |
| [`agents/`](agents/) | The "job descriptions" for the AI helpers (one per phase). |
| [`automation/`](automation/) | The tools the AI uses to drive EasyEDA and KiCad. *You don't touch these.* |
| [`knowledge/`](knowledge/) | The engineering rules and lessons the AI follows (IPC widths, design standards, learnings). |
| [`templates/`](templates/) | Blank forms you fill in for a new board (parts list, net list, rules). |
| [`projects/`](projects/) | **Your boards live here** — one folder per project, with all its files and outputs. |
| [`tools/`](tools/) | Reliability helpers: the environment check (`doctor`), logging, and recovery (opt-in). |
| [`reliability/`](reliability/) | How the workspace detects and recovers from problems + the [troubleshooting guide](reliability/TROUBLESHOOTING.md). |
| [`architecture/`](architecture/) | **Architecture audit & target design** — learnings from EasyEDA/KiCad, the tool-agnostic architecture, and the implementation roadmap. |
| [`docs/`](docs/) | Deep reference material. *Optional — for later, or for contributors.* |
Why the structure: the **method** (`workflow/`), the **workers** (`agents/`), the
**tools** (`automation/`, `tools/`), and the **knowledge** (`knowledge/`) are shared and
reused for every board; only the board itself lives in `projects/`. Full explanation:
[`ARCHITECTURE.md`](ARCHITECTURE.md).
## 5. Supported AI tools
PCB Flow is **AI-model-agnostic.** It works with any AI coding assistant that can read
Markdown instructions and run tools inside VS Code:
- **Claude Code** (Anthropic) — recommended
- **OpenAI Codex**
- **OpenCode**
- **Cursor**
- **Gemini CLI**
- …and future compatible AI coding agents.
The framework does not depend on a single AI provider. The instructions live in plain
Markdown (`CLAUDE.md`, `AGENTS.md`, `workflow/`), which any capable agent can follow.
## 6. Software requirements
| Tool | For | Required |
|---|---|---|
| **VS Code** | the workspace you open this in | yes |
| **An AI assistant** (any from §5) | the assistant that helps you | yes |
| **EasyEDA Pro** (free) | schematic + placement | yes (from phase 3) |
| **KiCad** (free) | routing + verification | yes (from phase 10) |
| **Git** | saves & publishes your work | yes |
| **Chrome** | so the AI can read your live EasyEDA board | yes (from phase 3) |
| **Python 3.9+** | runs the reliability helpers | yes |
| **Node.js 18+** | the EasyEDA Bridge + some automation scripts | when automation runs |
**Skills required:** electronics and PCB knowledge. **No programming required.**
> 💡 **EasyEDA transport.** The recommended way for the AI to drive EasyEDA is the official
> **Bridge** — install the `run-api-gateway` extension in EasyEDA Pro, tick *"allow external
> interaction"*, and run the bridge server (needs Node.js). Setup:
> [`automation/easyeda/README.md`](automation/easyeda/README.md). A raw Chrome-DevTools
> fallback (the CDP driver `automation/browser/cdp.py`, with `tools/launch_easyeda.py`
> launching a logged-in Chrome) is used automatically if the Bridge isn't running.
> 🖥️ **Platform setup:** **[Windows](handbook/windows-setup.md)** ·
> **[macOS](handbook/macos-setup.md)** · Linux (follow the handbook directly). On Windows use
> `python`/`py` and the `.py` tools instead of the `.sh` scripts.
## 7. Getting started
1. **Install the software** — [`handbook/02`](handbook/02-installing-tools.md).
2. **Clone this repository** and open the folder in VS Code
([`handbook/03`](handbook/03-vscode-and-ai.md)).
3. **Check your environment:** run `python3 tools/doctor.py` — it lists each tool with
✅ / ⚠️ / ❌ and tells you how to fix anything missing.
4. **See a worked example first** — [`projects/example-usb-c-3v3/`](projects/example-usb-c-3v3/)
is a complete reference board (USB-C → 3.3 V + status LED), reproducible **end to end with one
command** — netlist → ERC → board-matches-netlist → `kicad-cli` **DRC-clean** → gerbers:
```
make example # or: python3 tools/reproduce_example.py
```
5. **Create your first project** — [`handbook/04`](handbook/04-your-first-project.md):
```
cp -r projects/_template projects/my-board
```
Then tell your AI assistant: *"follow the workflow, start phase 1 for
projects/my-board — it's a [describe your product]."*
6. **Work the phases** — generate the schematic, review it, place, route, verify. The AI
runs the repetitive work; you approve the checkpoints.
That's it. From here you talk to the AI in plain English and it walks you through the
rest.
## 8. Placement → routing pipeline (codified rules, not vibes)
Placement and routing are driven by **codified rules with two human checkpoints** — copper is
never drawn or ordered without you.
**Placement — planned, then executed (EasyEDA).** `pcbflow place-plan` optimizes positions to
**minimize trace length** (HPWL), snaps decoupling caps to their IC, pins connectors to their
board edge, and renders a **visual map (SVG) you approve before anything is placed** (checkpoint
#1). The placement gate scores decap proximity (≤ 2 mm ok / 2–4 mm warn / > 4 mm fail),
connectors-on-edge, courtyard spacing, and keep-outs.
```bash
pcbflow place-plan netlist.enet --intent placement_intent.json --out plan.json --svg map.svg
```
**The routing rulebook (`routing_rules.json`).** The routing phase loads a rulebook every rule of
which **cites its source** (IPC-2152 / IPC-2221 §6 / JLCPCB). Trace widths are **derived from
current via IPC-2152** (JLCPCB 1 oz outer / 0.5 oz inner, ΔT = 10 °C default, per-project
override). **High-current nets (≥ 2.0 A or width > 1.0 mm) must be polygon pours**, not traces.
EMI rules cover return-path continuity and no-routing-over-plane-splits.
**The hard routing gate (KiCad) — machine-enforced.** Nothing releases fab files until all pass:
| Gate | Enforced by |
|---|---|
| ERC — 0 errors | `pcbflow` schematic gate |
| DRC — 0 errors | `kicad-cli` + the project ruleset |
| DFM — JLCPCB profile | `pcbflow dfm` |
| Silkscreen — 0 over-pad/via | `pcbflow` silk check (+ `kicad-cli`) |
| High-current nets on pours | `pcbflow route-check` |
```bash
pcbflow route-check netlist.enet board.kicad_pcb # pour / width / length / return-path + silk
pcbflow export my-board --approval approval.json # HARD-BLOCKED until every gate passes + you approve
```
`export` refuses fab output until the routing gate passes **and** you record approval (checkpoint
#2). Full electrical + integrity checks: `pcbflow hw` (see [`docs/HW_GAP_ANALYSIS.md`](docs/HW_GAP_ANALYSIS.md)).
## 9. Roadmap
- **✅ Built now:** the 12-phase workflow with **machine-computed gates** (each checkpoint runs
its real checks) and a **hard-blocked manufacturing export**; the AI agent roster; EasyEDA +
KiCad automation; a **harmonized findings schema** behind ERC / DFM / spacing; an **offline
KiCad reader + import-diff** that proves the board matches the netlist; a **reproducible
end-to-end worked example** (DRC-clean board + gerbers via `make example`); the engineering
knowledge base; a **known-good + known-bad fixture corpus**; **CI** on ubuntu/macOS/windows
with an ~89% coverage gate; and a reliability layer (environment check, auto-diagnosis, safe
retry, phantom-DRC guard, checkpoint/resume, cross-platform tools). Structured logging and the
self-healing recovery engine are built and unit-tested but **opt-in** — not yet wired into
every phase (see [`AUDIT.md`](AUDIT.md)).
- **🚧 In progress:** live-session validation of the EasyEDA Bridge/CDP transport and the
recovery strategies; macOS/Windows host validation — tracked in [`VALIDATION.md`](VALIDATION.md).
- **🔭 Planned:** a branded CLI, a source-of-truth linter, deeper KiCad routing
automation, more AI-agent adapters.
- **🧪 Research:** one-command "board recompile" from the knowledge layer; a
cross-project knowledge graph; more EDA backends.
Full detail: [`ROADMAP.md`](ROADMAP.md).
## 10. Notes
**Please read these — they set honest expectations.**
- **Human review is required.** The AI stops for your approval before drawing copper,
and always leaves safety-critical calls (power sizing, DRC sign-off) and the **fab
order** to you.
- **Known EasyEDA limitations:** script-drawn schematics are electrically correct but not
perfectly aligned (a cosmetic limitation; the audit guarantees the wiring). Copper
pours and routing can't be scripted in EasyEDA — which is why routing happens in KiCad.
- **Browser automation:** the AI reads your *live* EasyEDA board through Chrome; keep one
EasyEDA window open and signed in. Details:
[`reliability/TROUBLESHOOTING.md`](reliability/TROUBLESHOOTING.md).
- **Supported platforms:** developed and validated on **Linux**; cross-platform tooling
for **macOS/Windows** is built and unit-tested but still needs real-world validation on
those hosts.
- **Engineering assumptions:** DRC ground truth is always the board's own tool with its
own ruleset (never a bare board file); high-current paths use copper planes, not
traces; grounds return cleanly. These are enforced in
[`knowledge/design-standards.md`](knowledge/design-standards.md).
- **Recommended workflow:** one phase at a time, review each checkpoint, commit your work
as you go. The AI's reliability layer diagnoses common failures and walks you through
recovery in plain English.
- **If something breaks:** just tell the AI *"something went wrong — read the log and fix
it."* See [`reliability/TROUBLESHOOTING.md`](reliability/TROUBLESHOOTING.md).
## 11. Contributing
Contributions are welcome — from engineers and AI agents alike. In short: improve a
**phase** (`workflow/`), a **tool** (`automation/`, `tools/`), or the **knowledge**
(`knowledge/`); keep board-specific work inside `projects/`; every claim should trace to
a real artifact; prefer updating over duplicating. Full guide:
[`CONTRIBUTING.md`](CONTRIBUTING.md).
---
## Provenance & license
PCB Flow was extracted from a real ESP32 robotics board designed with EasyEDA Pro +
KiCad and an AI assistant, **including the honest record of what went wrong** — see
[`docs/13_LESSONS_LEARNED.md`](docs/13_LESSONS_LEARNED.md) and
[`knowledge/learning-db.md`](knowledge/learning-db.md). You inherit the solutions without
paying the tuition.
**Project files:** [`CHANGELOG.md`](CHANGELOG.md) · [`ROADMAP.md`](ROADMAP.md) ·
[`CONTRIBUTING.md`](CONTRIBUTING.md) · [`SECURITY.md`](SECURITY.md) ·
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) · [`architecture/`](architecture/README.md).
License: [MIT](LICENSE). Status: **v0.1.0 public Beta** — see
[`CHANGELOG.md`](CHANGELOG.md) for what's built and the known limitations.
7315b96d0This file is pinned to the selected release. Download the original to open it in your design tool.