Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
7315b96d0This 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.