키캐드(KiCad) AI 설계 자동화 시스템 — 종합 가이드(갱신)

# 키캐드(KiCad) AI 설계 자동화 시스템 — 종합 가이드

> 문서 버전: 1.2 (2026-10-30)

> 대상 환경: Windows 11 · D:\AICAD 워크스페이스 · ZCode(Claude 계열 에이전트) + KiCad 10 + kicad-mcp-pro

> 이 문서는 실제 설치와 테스트를 **모두 수행하고 검증한 결과**를 기록한 것입니다.

**문서 버전 히스토리**

| 버전 | 날짜 | 주요 변경 내용 |

|---|---|---|

| 1.3 | 2026-10-30 | 9.2절 **"Illustrator/AutoCAD 도면 → PCB 자동 아트워킹"** 추가 — .ai/.dwg는 DXF(mm)로 받아 ezdxf 1.4.4 파싱 후 pcbnew 이식(외곽→Edge.Cuts, 텍스트·그래픽→실크, refdes 마커→풋프린트 자동 배치), 7장 자동배선으로 이어지는 아트워크 파이프라인 정리. 도구 제약 실측(kicad-cli·MCP·pcbnew 전부 DXF 그래픽 임포트 미지원) |

| 1.2 | 2026-10-30 | 도구 최신화 점검 — KiCad 10.0.7 업그레이드(per-user `/currentuser` 주의, 3.1절) · kicad-mcp-pro 4.4.0 확인(3.8절) · **FreeRouting 2.5.0 전환**: 포터블 JRE 25 설치(3.6절), 헤드리스 `--gui.enabled=false`, 넥다운 버그 완화 후 DRC 0 실측(7장), 트러블슈팅 4건 갱신(10장) |

| 1.1 | 2026-10-29 | 9장 OrCAD 가져오기 추가 — orcad2kicad 1.0.5 + 포터블 나이틀리로 OrCAD Capture(.dsn/.opj) 직접 변환 실전 검증, 통합 DSN 분리 절차(`split_boards.py`) 정리 |

| 1.0 | 2026-09-07 | 초판 — 시스템 구축(KiCad 10.0.6, kicad-mcp-pro 3.34.0, FreeRouting 1.9.0), 무간섭 웹 모니터, sample_board 배선·제조파일 검증 |

---

## 1. 시스템 개요

이 시스템은 **사용자가 자연어로 요청하면 AI가 회로도 작성 → ERC 검사 → PCB 부품 배치 → 자동배선 → DRC 검증 → 제조 파일 생성까지 전 과정을 수행**하고, 진행 상황은 **웹 모니터 페이지로 실시간 시청**할 수 있게 구성됩니다.

핵심 설계 원칙은 **"무간섭(Non-intrusive)"** 입니다:

- AI의 모든 작업은 백그라운드(파일 기반 + CLI)로 수행됩니다.

- 사용자의 **마우스·키보드·화면 포커스를 절대 가져가지 않습니다.**

- 설계 결과는 웹 모니터(자동 갱신 렌더 이미지)와 KiCad 파일로 확인합니다.

| 구성 요소 | 역할 | 버전/위치 |

|---|---|---|

| KiCad 본체 | EDA(회로도·PCB 편집기), kicad-cli, pcbnew 파이썬 모듈 | 10.0.7 (2026-10-30) |

| kicad-mcp-pro | AI↔KiCad 연결 MCP 서버 (289개 도구) | 4.4.0 (2026-10-30) |

| uv / uvx | MCP 서버 실행 런처 (Python) | uv 0.12.10 |

| FreeRouting | 자동배선 엔진 (Java) | 2.5.0 JAR + 포터블 JRE 25 (1.9.0 폴백) |

| 모니터 웹서버 | 설계 진행 실시간 시청 페이지 (자체 제작) | Python 표준 라이브러리 |

| ZCode | 에이전트 실행 환경 (MCP 자동 연결) | — |

---

## 2. 전체 아키텍처

```mermaid

flowchart LR

    subgraph 사용자["👤 사용자"]

        REQ["자연어 요청<br/>'ESP32 보드 만들어줘'"]

        WATCH["🌐 브라우저<br/>웹 모니터 시청"]

    end

    subgraph AGENT["🤖 ZCode 에이전트 (백그라운드, 무간섭)"]

        AI["AI 설계 판단"]

        MCP["kicad-mcp-pro<br/>(289개 도구)"]

        CLI["kicad-cli<br/>(ERC/DRC/렌더/제조파일)"]

        PY["KiCad 내장 Python<br/>pcbnew 모듈<br/>(배치·DSN/SES)"]

    end

    subgraph FILES["📁 설계 파일 (D:\AICAD)"]

        SCH[".kicad_sch 회로도"]

        PCB[".kicad_pcb 보드"]

        OUT["output/<br/>넷리스트·Gerber·BOM"]

        FRAMES["monitor/frames/<br/>SVG·PNG 렌더"]

    end

    subgraph KICADGUI["🖥 KiCad GUI (선택, 열어만 두는 용도)"]

        EE["회로도 편집기"]

        PCBV["PCB 편집기"]

        IPC["IPC API 서버<br/>(상태 읽기용)"]

    end

    REQ --> AI

    AI --> MCP

    AI --> CLI

    AI --> PY

    MCP -->|"파일 읽기/쓰기"| SCH

    MCP -->|"파일 읽기/쓰기"| PCB

    MCP -->|"IPC (열린 문서 상태 읽기)"| IPC

    PY --> PCB

    CLI --> OUT

    SCH --> FRAMES

    PCB --> FRAMES

    OUT --> FRAMES

    FRAMES -->|"2초 폴링"| WATCH

    OUT -.->|"▶ 열기 버튼"| KICADGUI

```

**동작 방식 요약:**

- **쓰기(설계)**: MCP 도구가 `.kicad_sch` / `.kicad_pcb` 파일을 직접 수정합니다. 열려 있는 KiCad 창에 즉시 반영되지는 않고, **파일 → 되돌리기(Revert)** 로 새로 불러와야 보입니다.

- **읽기(상태)**: KiCad GUI의 IPC API 서버가 켜져 있으면, 열려 있는 문서의 선택 상태·네트 등을 AI가 읽을 수 있습니다.

- **시청**: 각 단계가 끝날 때마다 SVG/PNG 렌더가 `monitor/frames/`에 갱신되고, 웹 모니터가 2초마다 자동으로 가져갑니다.

---

## 3. 설치 가이드

실제 수행한 설치 순서입니다. 새 PC에 재구축할 때 이 순서대로 하면 됩니다.

### 3.1 KiCad 10 설치 (winget)

```powershell

winget install --id KiCad.KiCad --exact --silent `

  --accept-package-agreements --accept-source-agreements

```

- 설치 위치: `C:\Users\js\AppData\Local\Programs\KiCad\10.0` (사용자 단위 설치)

- 확인: `kicad-cli version` → `10.0.7`

- ⚠️ 기존 설치 위에 덮어쓰기(업그레이드)할 때는 인스톨러를 **반드시 `/S /currentuser`로 실행** —

  플래그 없이 전역 설치하면 Program Files에 969MB 중복 설치됨 (2026-10-30 10.0.6→10.0.7 검증)

### 3.2 uv / uvx 설치 (MCP 서버 런처)

```powershell

python -m pip install --user uv

# 실행 파일 위치: C:\Users\js\AppData\Roaming\Python\Python311\Scripts\uvx.exe

```

### 3.3 kicad-mcp-pro 서버 (uvx가 자동 설치)

별도 설치 명령이 필요 없습니다. `uvx kicad-mcp-pro` 최초 실행 시 캐시에 설치됩니다(94개 패키지).

수동 테스트:

```powershell

uvx kicad-mcp-pro --version        # 4.4.0

uvx kicad-mcp-pro health           # kicad-cli 탐지 확인

```

### 3.4 KiCad IPC API 서버 활성화

`%APPDATA%\kicad\10.0\kicad_common.json`에서:

```json

"api": { "enable_server": true, ... }

```

→ 열려 있는 KiCad 문서의 상태를 AI가 읽을 수 있게 됩니다(61개 IPC 도구).

### 3.5 전역 라이브러리 테이블 초기화 (신규 설치 후 필수!)

KiCad를 GUI로 한 번도 실행하지 않으면 전역 심볼/풋프린트 테이블이 비어 있어

`"심볼 라이브러리 'Device'가 포함되어 있지 않음"` 경고가 납니다. 템플릿을 복사해서 해결:

```powershell

copy "C:\Users\js\AppData\Local\Programs\KiCad\10.0\share\kicad\template\sym-lib-table" "%APPDATA%\kicad\10.0\"

copy "C:\Users\js\AppData\Local\Programs\KiCad\10.0\share\kicad\template\fp-lib-table"  "%APPDATA%\kicad\10.0\"

```

### 3.6 FreeRouting 자동배선 엔진

**현재 구성 (2026-10-30 검증): v2.5.0 JAR + 포터블 JRE 25 — v1.9.0은 폴백**

```powershell

# 1) 배선 엔진 최신본 (tools\ 보관 — 참고용 설치 명령)

curl -L -o D:\AICAD\KICAD\tools\freerouting-2.5.0.jar `

  https://github.com/freerouting/freerouting/releases/download/v2.5.0/freerouting-2.5.0.jar

# 2) 포터블 JRE 25 (시스템 PATH·기존 Java 17 무영향 — 폴더 삭제로 완전 제거 가능)

curl -L -o D:\AICAD\KICAD\tools\temurin-25-jre.zip `

  "https://api.adoptium.net/v3/binary/latest/25/ga/windows/x64/jre/hotspot/normal/eclipse"

# tools\ 에 압축 해제 → tools\jdk-25.0.5+8-jre\ 생성

```

- **실행은 반드시 `tools\jdk-25.0.5+8-jre\bin\java.exe`를 직접 호출**한다 (시스템 `java`는 여전히 17).

  FreeRouting 공식 README의 Java 요구사항도 "version 25, Adoptium Temurin JRE"로 명시돼 있다.

- **네이티브 CLI 빌드(`freerouting-cli-2.5.0-windows-x64`)는 사용 금지** — `--help`는 되지만 실제 DSN

  로드에서 즉시 크래시(GraalVM native-image 직렬화 버그, 업스트림 결함). JAR 경로에서는 미재현.

⚠️ **v1.9.0 주의**: `java -jar freerouting-1.9.0.jar -h`처럼 실행하면 **GUI가 뜹니다.**

반드시 `-de 입력.dsn -do 출력.ses -quit` 형태로 실행하세요(→ 7장).

💡 **1.9.0 고정이었던 이유와 해소 (2026-09-07 → 2026-10-30 경과)**:

초기 2.x 대규모 재작성판에는 배선 품질 회귀이 실제로 있었다 — 2레이어 초과 보드 배선이 조용히 깨지는

버그(→v2.2.3 수정), v1.9의 정체(stagnation) 감지 누락·조기 완료 오판(→v2.2.4 수정), SMD fanout

사전패스 누락(→v2.3.0 복원). v2.4.1부터 PCBench(실제 보드 1,157개) 패리티 검증 체계를 갖췄고,

1.9.0을 고정한 마지막 실질 이유였던 **"v2.x가 Java 25 필요"는 2026-10-30 포터블 JRE 25 설치로 해소** —

sample_board end-to-end 실측으로 v2.5.0 전환을 확정했다(→ 7장).

### 3.7 ZCode MCP 등록

`D:\AICAD\KICAD\.zcode\config.json` (워크스페이스 스코프 — 세션 시작 시 자동 연결):

```json

{

  "mcp": {

    "servers": {

      "kicad": {

        "command": "C:\\Users\\js\\AppData\\Roaming\\Python\\Python311\\Scripts\\uvx.exe",

        "args": [

          "kicad-mcp-pro", "--transport", "stdio",

          "--profile", "full", "--mode", "write",

          "--project-dir", "D:\\AICAD",

          "--log-file", "D:\\AICAD\\.zcode\\kicad-mcp.log"

        ],

        "env": {

          "KICAD_MCP_KICAD_CLI": "C:\\Users\\js\\AppData\\Local\\Programs\\KiCad\\10.0\\bin\\kicad-cli.exe",

          "KICAD_CLI_PATH": "C:\\Users\\js\\AppData\\Local\\Programs\\KiCad\\10.0\\bin\\kicad-cli.exe",

          "KICAD_MCP_WORKSPACE_ROOT": "D:\\AICAD"

        }

      }

    }

  }

}

```

**프로필/모드 조합:**

| 옵션 | 의미 | 도구 수 |

|---|---|---|

| `--profile full` | 전체 도구 세트 | MCP에서 289개 노출 |

| `--mode write` | 파일 쓰기 허용 (회로도/PCB 편집) | — |

| `--mode experimental` | + 자동배선(FreeRouting)·라우팅 도구 | 336개 |

| 기본값(profile 미지정) | 읽기 전용 검토 24개 | 자동화엔 부적합 |

### 3.8 버전 확인·업데이트 (2026-09-07 확인)

| 구성 요소 | 설치 버전 | 최신 버전 | 자동 업데이트 |

|---|---|---|---|

| KiCad | **10.0.7** (2026-10-30 업그레이드, per-user) | 10.0.7 (kicad.org 공식 안정판) | ❌ 없음 — 수동 설치 (재설치 시 `/S /currentuser` 필수) |

| kicad-mcp-pro | **4.4.0** (2026-10-30 PyPI 확인) | 4.4.0 | ❌ 없음 — uvx가 첫 버전을 캐시에 고정 |

| FreeRouting | **2.5.0 JAR + 포터블 JRE 25** (2026-10-30 전환) | 2.5.0 (→ 3.6절) | ❌ 수동 다운로드 |

- **kicad-mcp-pro는 버전을 지정하지 않아도 자동 갱신되지 않는다.** `uvx kicad-mcp-pro`는 최초 실행 시

  받은 버전을 캐시에 고정하므로, 프로젝트 도중 도구 동작이 바뀌지 않는다는 장점이 있다.

- **MCP 최신화**: `uvx --refresh kicad-mcp-pro --help` 1회 실행으로 캐시를 갱신한 뒤 ZCode 세션을

  재시작한다. 더 엄격한 고정이 필요하면 config.json args에서 `kicad-mcp-pro@4.4.0`처럼 핀을 지정한다.

- **버전 확인 방법**: MCP 도구 `kicad_get_version` / `kicad_get_server_info` (IPC unavailable 표시는

  KiCad GUI가 꺼져 있을 때의 정상 상태다). MCP 최신 버전은 https://pypi.org/pypi/kicad-mcp-pro/json ,

  KiCad 최신은 https://www.kicad.org/download/windows/ 에서 확인.

---

## 4. 설정 파일 및 배포 위치

```mermaid

flowchart TD

    A["D:\AICAD\KICAD\ (KiCad 워크스페이스)"] --> B[".zcode\config.json<br/>ZCode MCP 등록 (세션 시작 시 자동 연결)"]

    A --> C["AGENTS.md<br/>AI 행동 규칙 (매 세션 자동 참조)"]

    A --> D["monitor\<br/>웹 모니터 (server.py, index.html, state.json, frames/)"]

    A --> E["sample_board\<br/>완성 샘플 (배선+제조파일)"]

    A --> F["demo_led\<br/>회로도 전용 데모 (PCB 빈 상태)"]

    A --> G["tools\<br/>freerouting-2.5.0.jar + jdk-25 JRE"]

    A --> H[".zcode\*.py<br/>검증/배치/렌더 스크립트"]

```

| 파일/폴더 | 설명 |

|---|---|

| `C:\Users\js\AppData\Local\Programs\KiCad\10.0\` | KiCad 본체, kicad-cli, 내장 Python(파이썬 pcbnew용) |

| `C:\Users\js\AppData\Roaming\kicad\10.0\` | KiCad 사용자 설정(IPC 서버 스위치, 라이브러리 테이블) |

| `C:\Users\js\.zcode\cli\config.json` | ZCode 사용자 전역 설정 (MCP는 워크스페이스 스코프 사용) |

| `D:\AICAD\.zcode\config.json` | ZCode 워크스페이스 MCP 등록 ★ |

| `D:\AICAD\AGENTS.md` | AI가 매 세션 읽는 프로젝트 규칙 ★ |

| `D:\AICAD\monitor\` | 웹 모니터 서버·페이지·프레임 ★ |

---

## 5. 사용 방법 (ZCode 세션)

### 5.1 세션 시작

1. ZCode에서 `D:\AICAD` 워크스페이스로 세션을 엽니다 → MCP `kicad` 자동 연결

2. 모니터 서버가 죽어 있으면 AI가 자동으로 띄웁니다(AGENTS.md 규칙)

3. **http://127.0.0.1:8765** 를 브라우저에 띄워두면 진행 상황을 실시간 시청 가능

### 5.2 요청 예시

| 요청 예시 | AI가 수행하는 것 |

|---|---|

| "12~24V 입력 + RS485 컨트롤러 보드 만들어줘" | 요구사항 정리 → 블록도 제시 → 회로도 작성 → ERC → 배치 → 배선 → DRC → 제조파일 |

| "sample_board 자동배선 해줘" | DSN 내보내기 → FreeRouting → SES 적용 → DRC → 렌더 갱신 |

| "이 데이터시트로 부품 만들어줘" | 치수/핀맵 추출 → 확인 요청 → 풋프린트/심볼 생성 |

| "Gerber 만들어줘" | Gerber 7종 + 드릴 + 발주용 zip 생성, 모니터 파일 목록 자동 추가 |

### 5.3 설계 워크플로 (전체)

```mermaid

flowchart TD

    A["1. 요구사항 정리"] --> B["2. 블록도 제시 → 사용자 승인"]

    B --> C["3. 부품 선정 (데이터시트/라이브러리)"]

    C --> D["4. 회로도 작성 (심볼+라벨+전원심볼)"]

    D --> E{"5. ERC 통과?"}

    E -->|실패| D

    E -->|PASS| F["6. 넷리스트 추출"]

    F --> G["7. 풋프린트 배치 + 보드 외곽선<br/>(pcbnew 스크립트)"]

    G --> H["8. 자동배선 (FreeRouting)"]

    H --> I{"9. DRC 통과?"}

    I -->|위반| H

    I -->|PASS| J["10. Gerber + 드릴 + BOM + 부착목록"]

    J --> K["11. 👤 사람 최종 검토 → 발주"]

```

### 5.4 사용자가 꼭 지켜야 할 규칙

1. **AI가 작업 중일 때 KiCad에서 저장(Ctrl+S) 금지** — AI가 쓴 파일을 옛 내용으로 덮어씁니다

2. 최신 결과를 KiCad에서 보려면 **파일 → 되돌리기(Revert)** 또는 창을 다시 열기

3. 제조 파일 발주는 **반드시 사람이 3D/패턴을 검토한 후** 진행

---

## 6. 웹 모니터 (실시간 설계 시청)

### 6.1 구성

```mermaid

flowchart LR

    subgraph 자동화["AI 자동화 (백그라운드)"]

        STEP["설계 단계 수행"] --> RENDER["렌더 생성 → frames/프로젝트/<br/>sch.svg / pcb.svg / pcb_top.svg<br/>pcb_bottom.svg / board3d*.png"]

        RENDER --> STATE["state.json 갱신<br/>(updated/active +<br/>projects.프로젝트별 상태)"]

    end

    subgraph 웹서버["monitor/server.py (:8765)"]

        SERVE["정적 파일 + JSON API"]

    end

    subgraph 브라우저["사용자 브라우저"]

        PAGE["index.html<br/>2초 폴링"]

    end

    STATE --> SERVE --> PAGE

    PAGE -->|"/files → 파일 목록"| SERVE

    PAGE -->|"/open → KiCad로 열기"| SERVE

```

- 주소: **http://127.0.0.1:8765** (내 PC에서만 접근)

- 실행: `monitor\start_monitor.bat`(권장 — 이미 실행 중이면 안내, 최소화된 콘솔 창이 서버 본체) /

  종료는 `stop_monitor.bat`. 부팅 시 자동 실행되지 않으므로 세션 시작 시 AI가 확인 후 띄운다

- 구성 파일: `monitor/index.html`(페이지), `monitor/server.py`(서버), `monitor/state.json`(상태),

  `monitor/frames/<프로젝트>/`(프로젝트별 렌더)

- 배치파일은 **CP949 인코딩 + CRLF**여야 한다. UTF-8로 쓰면 cmd 파싱이 깨진다 (2026-09-07 검증)

### 6.2 화면 구성

| 카드 | 내용 |

|---|---|

| **상단 프로젝트 탭** | 프로젝트(demo_led, sample_board…) 전환 — 탭에 따라 렌더·검증 상태·로그·파일 목록이 모두 함께 바뀜 (선택 탭은 localStorage 유지) |

| 📄 회로도 | 회로도 SVG (부품·라벨·전원심볼) |

| 🟩 PCB 2D | 배치+배선 전체 뷰 |

| 🟫 Top / Bottom 구리 패턴 | 앞면/뒷면(좌우반전) 동선 패턴 |

| 🧊 3D 미리보기 | 아이소메트릭 / Top / Bottom 3종 |

| 📂 생성 파일 | 워크스페이스 파일 자동 스캔 + **▶ KiCad로 열기** 버튼 + 경로 복사 (선택 프로젝트의 파일만 표시) |

| 검증 상태·로그 | ERC/DRC 결과, 단계별 로그 (프로젝트별 관리) |

표시 방식(2026-09-07): 렌더는 기본(라이트) 테마로 생성하고 페이지 CSS가 `invert(0.85)+hue-rotate(180)`

필터로 다크 모드처럼 표시한다. 3D PNG는 투명 배경이라 어두운 회색 캔버스가 비친다. kicad-cli `--theme`

다크 테마명은 내장 테마라 인식되지 않고 라이트로 폴백되므로 사용하지 않는다. 렌더가 없는 항목은 플레이스홀더.

### 6.3 API (서버 엔드포인트)

| 엔드포인트 | 인증 | 기능 |

|---|---|---|

| `GET /` , `/state.json` , `/frames/*` | 불필요 | 페이지·상태·렌더 서빙 |

| `GET /token` | — | 열기 버튼용 토큰 발급 |

| `GET /files?token=...` | 토큰 필요 | KiCad 파일/산출물 자동 스캔 |

| `GET /open?token=...&path=...` | 토큰 필요 | **Windows 기본 연결(KiCad)로 파일 실행** |

보안: 127.0.0.1 바인딩(외부 접근 불가) + 토큰 + `D:\AICAD` 내부 경로만 허용. 악성 웹사이트가

브라우저를 통해 몰래 파일을 열어주는 것을 토큰이 차단합니다.

### 6.4 파일 열기 버튼 동작 원리

브라우저 보안상 웹페이지가 로컬 프로그램을 직접 실행할 수는 없지만, **로컬에서 돌아가는 모니터

서버의 `/open` 엔드포인트가 `os.startfile()`로 Windows 기본 연결 프로그램을 호출**합니다.

`.kicad_pro` → KiCad 프로젝트, `.kicad_sch` → 회로도 편집기, `.kicad_pcb` → PCB 편집기, `.pdf` → PDF 뷰어.

---

## 7. 자동배선 파이프라인 (FreeRouting)

> 배선 전 준비(보드 외곽·실크 텍스트·배치 참조 도면)를 DXF에서 가져와야 할 때는 **9.2절** 참조.

```mermaid

sequenceDiagram

    participant AI as AI (ZCode)

    participant KP as KiCad 내장 Python (pcbnew)

    participant FR as FreeRouting 2.5.0 (포터블 JRE 25)

    participant DRC as kicad-cli DRC

    AI->>KP: ExportSpecctraDSN(board, design.dsn)

    KP-->>AI: DSN 생성 (회로 연결 정보)

    AI->>FR: jdk-25\bin\java.exe -jar freerouting-2.5.0.jar -de design.dsn -do design.ses -mp 25 --gui.enabled=false

    Note over FR: 팬아웃 → 자동배선 → 최적화 (샘플보드: 약 3초)

    FR-->>AI: design.ses (배선 결과)

    AI->>KP: ImportSpecctraSES(board, design.ses)

    AI->>KP: 후처리: 규정폭 미만 트레이스 widen → 저장

    AI->>DRC: pcb drc --format json

    DRC-->>AI: 미배선 0, 위반 0

    AI->>AI: Top/Bottom/3D 렌더 재생성 → 모니터 갱신

```

**v2.5.0 실측 (2026-10-30, sample_board 미배선 사본):** 팬아웃 32/32 SMD · 배선 스코어 1000

(미배선 0·클리어런스 위반 0, 약 3초) → SES 역적용 85트랙 + 비아 3 → 후처리 후 **DRC 0**.

검증 산출물: `temp_fr250_test/`, 준비 스크립트: `.zcode/prep_fr250_test.py`.

2.5.0은 SMD 탈출에 비아를 쓸 수 있어 1.9.0(단면 무비아 84트랙)과 결과 형태가 다르다.

**⚠️ v2.5.0 넥다운 버그** (릴리스에 존재 — 업스트림 이슈 #978/#973, 2026-10-19 master에 수정 병합·

다음 릴리스에서 해소 예정): 넥다운이 규정폭 이하(6mil=0.15mm) 트레이스를 남기고, 꺼도 팬아웃 단계가

넥다운할 수 있다. **검증된 완화**: ① `--router.automatic_neckdown=false` (track_width 위반 8→4건)

② SES 적용 후 규정폭 미만 트레이스를 규정폭으로 widen하는 pcbnew 후처리 → **DRC 0**.

**폴백 (v1.9.0 + 시스템 Java 17):** `java -jar freerouting-1.9.0.jar -de in.dsn -do out.ses -quit -mp 25`.

v1.9.0에서 `-h`는 인식되지 않고 GUI가 뜨므로 사용하지 않는다. `-quit`는 v1.9.0 전용이며

**v2.x에서는 `--gui.enabled=false`가 공식 대체**다(공식 CLI 문서 확인).

---

## 8. 데이터시트·치수표 기반 커스텀 부품 생성

| 제공 자료 | 생성 결과 | 사용 도구 |

|---|---|---|

| 패키지 치수표 (랜드·피치·바디) | IPC-7351 표준 풋프린트 | `lib_generate_footprint_ipc7351` |

| 핀맵 표 (번호-이름-기능) | 회로도 심볼 | `lib_generate_symbol_from_pintable` |

| 보드 치수·구멍·커넥터 좌표 | 외곽선·마운팅홀·배치 반영 | pcbnew 스크립트 |

| 전기 사양 (전류·권장회로) | 디커플링/트레이스 폭 계산 | 설계 규칙 엔진 |

**절차(생략 금지):** ① 자료에서 치수·핀맵 추출 → ② **추출 결과 표를 사용자에게 확인받음** →

③ 생성·적용 → ④ 3D 재확인. 스캔 이미지 PDF는 비전 판독 오차 가능성을 안내합니다.

**준비 방법:** 데이터시트 PDF 또는 치수표(텍스트/엑셀)를 `D:\AICAD\` 아래에 넣고

세션에서 "이 데이터시트로 ○○ 부품 만들어줘"라고 요청.

---

## 9. 외부 포맷 가져오기 (OrCAD 등)

### 9.1 OrCAD 설계 가져오기

| 갖고 있는 파일 | 가져오기 | 설명 |

|---|---|---|

| OrCAD Capture **회로도** (.dsn/.opj) | ✅ **직접 변환 가능** (2026-10-29 실전 검증) | orcad2kicad v1.0.5 + KiCad 포터블 나이틀리 임포터 → 완전 무헤드 변환 |

| OrCAD/Allegro **PCB** (.brd) | ✅ 직접 지원 | KiCad 10 내장 "Cadence Allegro/OrCAD PCB Editor" 임포터 (GUI 메뉴 전용) |

| OrCAD **EDIF** (.edf) | ✅ 직접 변환 가능 | orcad2kicad 직접 판독, 나이틀리 불필요 — .DSN 실패 시 1차 대안 |

| Eagle, CADSTAR, EasyEDA, IPC-2581 등 | ✅ 지원 | KiCad 내장 임포터 |

가져오기 요청 시 AI가 먼저 파일을 무간섭으로 분석해 "직접 가져오기 가능/재작성 필요"를 판정합니다.

**공개용 안내문**: <https://www.wellcoms.co.kr/info/202/>

내부 절차 핵심 (세부는 `.zcode/split_boards.py` 헤더와 본문 주석 참조):

- 변환 명령: `tools/orcad2kicad/orcad2kicad-1.0.5-win64/orcad2kicad-cli.exe --dsn <원본.dsn> -o imports/<이름> --issues --explain`

  (환경변수 `O2K_KICAD_NIGHTLY=D:/AICAD/KICAD/tools/kicad-nightly/bin/kicad-cli.exe` 필요)

- **통합 DSN(보드 여러 종 수납)은 반드시 `.zcode/split_boards.py`로 보드별 분리** — 미분리 시 시트 간

  참조번호 충돌로 주석 오류·넷리스트 오염

- 임포터의 자동 넷명 라벨 `Net-(...)`은 가상 연결 역할 — **삭제 금지**, 별칭 복원은 이름 변경

  (별칭은 자동 라벨과 같은 행·왼쪽 ≤15mm, split_boards.py가 자동 처리)

- 검증 합격 기준: 넷리스트 내보내기 주석 오류 0 · ERC `lib_symbol_issues` 0 · 나머지 ERC는 무해 항목

- 워크시트: 분리 프로젝트에 `blank.kicad_wks` 누락 시 도곽 이중 표시 → 파일 복사 후 재오픈

### 9.2 Illustrator/AutoCAD 도면으로 PCB 아트워크 만들기 (외곽·실크·부품 배치)

**이 기능은?**

Illustrator(.ai)나 AutoCAD(.dwg)로 그린 **보드 외형, 실크 그래픽(로고·문구), 부품 배치 지시서**를

KiCad PCB에 자동으로 옮기는 기능입니다. 도면 하나로 외곽선 만들기 → 부품 배치 → 로고·문구 넣기 →

자동배선 → Gerber(아트워크) 출력까지 이어집니다.

#### 준비물

- Illustrator 또는 AutoCAD에서 그린 도면을 **DXF 형식(단위 mm)** 으로 내보낸 파일

  - Illustrator: 파일 → 내보내기 → DXF

  - AutoCAD: DWG를 DXF로 저장 (AutoCAD 또는 무료 ODA File Converter)

- 도면 안에서 **레이어를 용도별로 나누면** 정확도가 크게 올라갑니다:

| 도면 레이어 (예시 이름) | 담을 내용 |

|---|---|

| `OUTLINE` | 보드 외형, 컷아웃, 슬롯 (닫힌 선으로) |

| `SILK` | 실크에 인쇄할 로고·텍스트·주의문구 |

| `COMP` | 부품 배치 표시 — 부품명(refdes: R1, C2, U1…)을 배치할 위치에 표기 |

#### 도면이 PCB에 이식되는 방식

| 도면 레이어 | → KiCad 대상 | 결과 |

|---|---|---|

| `OUTLINE` | `Edge.Cuts` | 보드 외곽선 — 이 선이 기판의 잘리는 경계가 됨 |

| `SILK` | `F.Silkscreen` / `B.Silkscreen` | 로고·문구가 실크(부도체 인쇄)로 재현됨 |

| `COMP`의 refdes | 부품 배치 좌표 | 해당 위치에 **KiCad 표준 풋프린트가 자동 배치**됨 |

- 도면에 그려진 부품 외형 그림은 **위치 참고용**입니다. 실제 패드·핀 배열은 KiCad 표준 풋프린트로

  생성되고, 전기적 연결(넷)은 회로도에서 자동으로 연결됩니다.

- 도구 제약상 KiCad의 DXF 가져오기 메뉴·명령줄·API 어디로도 자동화가 안 되므로,

  본 시스템은 DXF를 직접 읽어 pcbnew 객체로 생성하는 **전용 변환 스크립트** 방식으로 처리합니다.

#### 사용 방법 (진행 흐름)

1. 도면을 **DXF(mm)로 내보내** 전달합니다.

2. 도면을 분석해 레이어별 구성(외곽/실크/부품 마커 수)을 확인합니다.

3. 보드 외곽선·실크 그래픽·텍스트·부품 배치를 PCB에 생성하고, 회로도와 넷을 연결합니다.

4. **3D 렌더로 배치를 눈으로 확인**합니다 — 부품 겹침·외곽 이탈은 DRC보다 여기서 잡습니다.

5. 자동배선(7장 FreeRouting 파이프라인)을 돌리고 **DRC 0**을 확인합니다.

6. Gerber·드릴 파일을 출력하면 아트워크 완성입니다 (제조 발주 전 사람 검토).

#### 주의할 점

- **단위는 mm로** 내보냅니다 — 인치로 저장되면 25.4배 크기 오류가 납니다.

- 도면과 보드의 **원점 기준**을 맞춥니다 (다르면 전체가 옆으로 밀립니다).

- 외곽선은 **닫힌 선(폐곡선)** 으로 그립니다 — 열려 있으면 3D·DRC·제조 경계가 깨집니다.

- 로고·문구는 반드시 실크 레이어로 — 동판(`F.Cu`)에 넣으면 DRC 클리어런스 위반입니다.

- 곡선·세부 도형이 많으면 변환 후 도형 수가 늘어납니다 — 불필요한 도면 레이어는 정리 후 전달합니다.

- 각 단계마다 3D 렌더와 DRC로 확인 후 다음 단계로 진행합니다.

---

## 10. 트러블슈팅 (실제 발생했던 문제들)

| 증상 | 원인 | 해결 |

|---|---|---|

| ERC: "심볼 라이브러리 'Device' 미포함" 경고 | KiCad 신규 설치 후 전역 라이브러리 테이블 비어 있음 | 템플릿 복사 (→ 3.5절) |

| MCP 쓰기 도구에서 "No schematic file configured" | 프로젝트 미지정 | `kicad_set_project` 호출 (sch/pcb/output 경로 포함) |

| MCP로 부품을 추가했는데 열린 KiCad 화면에 안 보임 | **정상 동작** (파일 직접 수정 방식) | 파일 → 되돌리기(Revert) 또는 창 재오픈 |

| IPC 관련 도구가 일부만 동작 | 열린 문서가 없음 (프로젝트 관리자만 열림) | 회로도/PCB 편집기에서 해당 문서를 열 것 |

| `sch_add_no_connect` 에러: x_mm/y_mm required | 핀 좌표 필요 | ERC 리포트의 위반 좌표(×100 = mm)를 사용 |

| 심볼 배치가 "OK"인데 실제로 없음 (ATtiny85-20SU) | 존재하지 않는 심볼 이름 | 라이브러리 파일에서 실제 이름 확인 (→ `ATtiny85-20S`) |

| FreeRouting 2.x JAR: UnsupportedClassVersionError (class 69) | v2.x는 Java 25 필요, 시스템 `java`는 17 | 포터블 JRE 25로 직접 호출: `tools\jdk-25.0.5+8-jre\bin\java.exe` (→ 3.6절) |

| 네이티브 CLI 2.5.0이 DSN 로드에서 즉시 크래시 | GraalVM native-image 직렬화 버그 (업스트림 결함) | **JAR(`-jar`) 경로만 사용** — 크래시 미재현 |

| v2.5.0 배선 후 DRC track_width 위반 (0.15mm < 0.2mm) | 넥다운 버그 (#978/#973 — 다음 릴리스에서 수정) | `--router.automatic_neckdown=false` + SES 적용 후 규정폭 미만 트레이스 widen 후처리 (→ 7장) |

| `java -jar freerouting-1.9.0.jar -h` → GUI 팝업 | `-h` 미지원 (v1.9.0) | `-de/-do/-quit` 조합으로만 실행 |

| KiCad 10 파이썬 `GetTrackCount()` AttributeError | API 변경 | `len(board.GetTracks())` 사용 |

| 모니터 접근 403 | (구버전 버그) 전체 경로에 토큰 검사 | 수정 완료 — 정적 파일은 공개, `/files`·`/open`만 토큰 |

| 웹에서 열기 버튼 무반응 | 모니터 서버 중지 | `python D:/AICAD/monitor/server.py` 재실행 |

| GUI 자동화(마우스/키보드)가 사용자 방해 | 포그라운드 독점 구조 | **원칙: 무간섭 백그라운드 방식 사용 (AGENTS.md 규칙)** |

| OrCAD 변환: ERC `lib_symbol_issues` 다발 / 도곽 이중 / 넷리스트 오염 / `Net-(...)` 라벨 충돌 | 임포터·변환기 특성 (각각 고유 원인) | **→ OrCAD_가져오기_가이드.md 7장 트러블슈팅 표 참조** |

---

## 11. 파일 위치 총정리

```

D:\AICAD\KICAD\                 ← KiCad AI 워크스페이스 (D:\AICAD 아래: FREECAD\, KICAD\)

├─ AGENTS.md                    ← AI 행동 규칙 (매 세션 자동 참조)

├─ 키캐드AI_설계시스템_종합가이드.md   ← 이 문서

├─ OrCAD_가져오기_가이드.md      ← OrCAD→KiCad 직접 변환 따라하기 안내문 (정보성 공개글,

│                                  게시 위치: https://www.wellcoms.co.kr/info/202/)

├─ .zcode\

│  ├─ config.json               ← ZCode MCP 등록 (kicad 서버)

│  ├─ skills\pcb-design\SKILL.md ← PCB 설계 규칙 스킬

│  ├─ test_mcp.py               ← MCP 연결/도구 목록 테스트

│  ├─ test_e2e.py               ← 미니 파이프라인 테스트

│  ├─ build_sample.py           ← sample_board 회로도 생성기

│  ├─ populate_pcb.py           ← PCB 풋프린트 배치 스크립트 ★

│  ├─ recenter_board.py         ← 보드 시트 중앙 이동

│  ├─ dsn_export.py / ses_import.py ← FreeRouting 연동

│  ├─ split_boards.py           ← OrCAD 통합 DSN → 보드별 독립 프로젝트 분리 ★

│  └─ kicad-mcp.log             ← MCP 서버 로그

├─ monitor\                     ← 웹 모니터 ★

│  ├─ server.py                 ← 서버 (포트 8765)

│  ├─ start_monitor.bat         ← 사용자용 서버 시작 배치

│  ├─ stop_monitor.bat          ← 서버 종료 배치

│  ├─ index.html                ← 모니터 페이지 (상단 프로젝트 탭)

│  ├─ state.json                ← 상태 (updated/active + projects.<프로젝트>)

│  ├─ token.txt                 ← 열기 버튼 토큰

│  └─ frames\<프로젝트>\         ← 프로젝트별 렌더 (sch.svg, pcb*.svg, board3d*.png)

├─ tools\jdk-25.0.5+8-jre\      ← 포터블 Temurin JRE 25 (시스템 무영향 — FreeRouting 2.5.0용, 3.6절)

├─ tools\freerouting-2.5.0.jar  ← 자동배선 엔진 (기본 — JRE 25 필수, 3.6·7장)

├─ tools\freerouting-1.9.0.jar  ← 폴백 엔진 (시스템 Java 17, -quit 방식)

├─ tools\freerouting-2.4.1.jar · temurin-25-jre.zip ← 보관 (이전 버전 / JRE 원본 zip)

├─ temp_fr250_test\             ← FreeRouting 2.5.0 end-to-end 검증 산출물 (2026-10-30)

├─ tools\orcad2kicad\           ← OrCAD 변환기 v1.0.5 (GUI+CLI, 9장)

├─ tools\kicad-nightly\         ← .DSN 파싱용 포터블 나이틀리 (설치 아님, 9장)

├─ imports\                     ← OrCAD 변환 결과 (보드별 독립 프로젝트 5개 + 통합본 참고용)

│  ├─ photo_v2.0 / swboard_v2.1 / remote_v1.0 / ext-sw / ext-button

│  └─ SWBOARD_kicad\            ← 통합 변환본 (참고용 — 넷리스트 오염으로 사용 비권장)

├─ sample_board\                ← 완성 샘플 (배선+제조파일)

│  ├─ sample_board.kicad_pro / .kicad_sch / .kicad_pcb

│  └─ output\ (netlist, erc/drc 리포트, bom.csv, pos.csv,

│             gerber\ 7종+드릴, sample_board_gerbers.zip)

└─ demo_led\                    ← 테스트용 빈 프로젝트 (회로도 파일 없음, 빈 PCB — 모니터 탭 테스트용)

C:\Users\js\AppData\Local\Programs\KiCad\10.0\   ← KiCad 본체

C:\Users\js\AppData\Roaming\kicad\10.0\          ← KiCad 설정 (IPC 스위치, 라이브러리 테이블)

C:\Users\js\AppData\Roaming\Python\Python311\Scripts\uvx.exe ← MCP 런처

```

---

## 부록 A: 자주 쓰는 명령어 모음

```powershell

# 모니터 서버 실행 (권장: 배치파일 — 이미 떠 있으면 '이미 실행 중' 안내)

D:\AICAD\KICAD\monitor\start_monitor.bat      # 시작 (최소화 창이 서버 본체 — 창을 닫으면 종료)

D:\AICAD\KICAD\monitor\stop_monitor.bat       # 종료 (포트 8765 프로세스만 정확히 종료)

python D:/AICAD/KICAD/monitor/server.py          # AI가 백그라운드로 직접 띄울 때

# ERC / DRC 검사

kicad-cli sch erc --output erc.json "D:\AICAD\KICAD\sample_board\sample_board.kicad_sch"

kicad-cli pcb drc --format json --output drc.json "D:\AICAD\KICAD\sample_board\sample_board.kicad_pcb"

# 렌더링

kicad-cli sch export svg --output <dir> <회로도.kicad_sch>

kicad-cli pcb export svg --mode-single --fit-page-to-board --layers "F.Cu,F.Mask,F.Silkscreen,Edge.Cuts" --out pcb_top.svg <보드.kicad_pcb>

kicad-cli pcb render --rotate '30,0,40' --output board3d.png <보드.kicad_pcb>

# 자동배선 3단계 (기본: v2.5.0 + 포터블 JRE 25)

<KiCad>\bin\python.exe dsn_export.py                       # 1) DSN

D:\AICAD\KICAD\tools\jdk-25.0.5+8-jre\bin\java.exe -jar D:\AICAD\KICAD\tools\freerouting-2.5.0.jar -de in.dsn -do out.ses -mp 25 --gui.enabled=false   # 2) 배선

<KiCad>\bin\python.exe ses_import.py                       # 3) SES 적용 + 규정폭 미만 트레이스 widen 후처리

# 자동배선 3단계 (폴백: v1.9.0 + 시스템 Java 17)

java -jar D:\AICAD\KICAD\tools\freerouting-1.9.0.jar -de in.dsn -do out.ses -quit -mp 25

```

## 부록 B: 검증 상태 요약 (2026-10-30 갱신)

| 항목 | 상태 |

|---|---|

| 버전 최신성 (2026-10-30) | ✅ KiCad 10.0.7 · kicad-mcp-pro 4.4.0 = PyPI 최신 · FreeRouting 2.5.0 = GitHub 최신 (→ 3.8절) |

| KiCad 10.0.7 + kicad-cli | ✅ 정상 (2026-10-30 10.0.6→10.0.7 업그레이드 — 경로·설정 불변) |

| MCP 서버 kicad-mcp-pro 4.4.0 (289 도구, write 모드) | ✅ 정상 (세션 시작 시 자동 연결) |

| **FreeRouting 2.5.0 자동배선 (포터블 JRE 25)** | ✅ **2026-10-30 end-to-end 검증** — 배선 스코어 1000·미배선 0·DRC 0 (→ 7장) |

| ERC | ✅ 0 오류 |

| 자동배선 | ✅ 84 트랙 / 비아 0 / 미배선 0 |

| DRC | ✅ 위반 1건(0.0018mm 미세, 제조 무영향) |

| 제조 파일 | ✅ Gerber+드릴+BOM+부착목록+zip |

| 웹 모니터 | ✅ :8765 구동 중 |

| IPC 읽기 / 무간섭 원칙 | ✅ AGENTS.md에 규칙 기록 |

---

## 부록 C: 작업 주체 구분 — AI가 한 것 vs 도구가 한 것

"AI가 설계했다"의 정확한 의미를 투명하게 기록한다. sample_board 전 과정을 기준으로 하며,

**설계 결정은 AI가 하고, 작도·계산·검증 실행은 도구가 담당**하는 구조이다

(사람 엔지니어가 CAD에 설계 결정을 입력하고 소프트웨어가 작도하는 것과 같은 분업).

### C-1. AI(에이전트)가 직접 수행한 것 — 설계 판단과 실행 지시

| 작업 | AI가 판단/결정한 내용 |

|---|---|

| 회로 구상 | 보호 순서(DC입력→퓨즈→쇼트키→AMS1117), MCU(ATtiny85) 선택, LED·스위치·확장헤더 구성 |

| 부품 값 산정 | 퓨즈 500mA, 풀업 10k, LED 저항 330R/1k, 디커플링 100nF, 쇼트키 SS34 |

| 연결 정의 | 39개 핀→넷 연결 전부 (VIN, +12V, +3V3, GND, RESET, PB0~2 등) |

| 회로도 배치 좌표 | 16개 심볼의 전원/MCU/출력 블록별 위치 (직접 계산한 좌표) |

| 풋프린트 선정 | 부품별 R_0603, SOT-223, SOIC-8, D_SMA, SW_PUSH_6mm 등 지정 |

| PCB 배치 좌표 | 보드 위 16개 부품 위치 — 배치 알고리즘이 아니라 **AI가 계산해 스크립트에 넣은 좌표** |

| 보드 사양 | 80×60mm 크기, 시트 중앙 배치 |

| 문제 해결 | 심볼 이름 불일치 발견(ATtiny85-20SU→20S), 라이브러리 테이블 복구, PWR_FLAG 추가, Java 버전 회피 등 |

| 웹 모니터 | 서버·페이지·렌더 파이프라인 전부 자체 제작 |

### C-2. 도구가 수행한 것 — AI는 실행자/해석자

| 작업 | 실제 실행 주체 | AI의 역할 |

|---|---|---|

| 배선 경로 84개 | FreeRouting 배선 알고리즘 | DSN 내보내기 → 실행 → SES 적용 → DRC 검증 |

| ERC/DRC 판정 | KiCad 검사 엔진 | 결과 해석 + 위반 원인 수정 |

| 파일 포맷 작성(S-expression) | MCP 도구, kicad-sch-api | 도구 호출 (명령) |

| 3D 렌더링 | kicad-cli render | 옵션 지정·실행 |

### C-3. 한계와 검토 책임 (정직한 기록)

1. **배선 품질의 보증 주체는 FreeRouting**이다. AI는 실행과 검증을 했을 뿐, 배선이 최적임을

   보장하지 않는다. 그래서 DRC 검증과 사람 검토 단계를 둔다.

2. 예제 회로는 AI 지식만으로 판단 가능한 수준이지만, **실제 제품 회로는** 데이터시트 확인·

   전원 무결성·EMC·발열 검토가 추가로 필요하다. → 최종 발주 전 **사람 검토**가 규칙(5.4절)이다.

3. 부품 값(500mA 퓨즈 등)은 예제용으로 AI가 판단한 값이며, 실제 제품에서는 소요 전류 계산과

   인증 규격 확인이 필요하다.